@cohortapp/agent-sdk 2.5.0 → 2.6.0

package/lib/backup/policy.mjs

@@ -0,0 +1,710 @@
+/**
+ * lib/backup/policy.mjs — what a fleet machine backs up, where, and what it
+ * must NEVER touch.
+ *
+ * ── The decision this module encodes ────────────────────────────────────────
+ *
+ * `maestro doctor` used to FAIL every agent on earth with "No backup target
+ * configured", and the only remedy on offer was an interactive wizard that
+ * wrote `enabled: false` and demanded a GCS/S3 bucket plus cloud credentials
+ * the machine did not have. So every agent was born red, the check was learned
+ * as noise, and the actual DR posture stayed exactly where it was: nothing.
+ *
+ * The posture implemented here is **restore points first, offsite second**:
+ *
+ *   Tier 1 — LOCAL RESTORE POINTS (on by default, zero configuration).
+ *     A nightly tarball written OUTSIDE the agent repo, to
+ *     `~/Library/Application Support/Maestro/backups/<prefix>/`. It costs
+ *     nothing, needs no credentials, and covers the failure that actually
+ *     happens week to week: a corrupted queue, a bad state write, a botched
+ *     checkout, an `rm -rf` of the repo. Living outside the repo is the whole
+ *     point — a backup inside the tree it protects is not a backup.
+ *
+ *   Tier 2 — OFFSITE COPY (opt-in, one config block).
+ *     The same tarball pushed to gcs/s3/rsync. This is the only tier that
+ *     survives machine loss, so an agent WITHOUT it is not silently green:
+ *     doctor WARNs, naming the residual risk in words ("local restore points
+ *     only — a dead machine loses everything since enrolment").
+ *
+ * Why not just demand offsite and stay red until someone configures it? Because
+ * a check that is red on every machine for months is a check nobody reads, and
+ * because "no restore point at all" and "restore points that would not survive
+ * a house fire" are genuinely different severities. Doctor now says which one
+ * you have. FAIL-OPEN IS FINE; SILENT IS NOT.
+ *
+ * ── What is NEVER backed up ─────────────────────────────────────────────────
+ *
+ * `DENY_PATTERNS` is a HARD deny-list enforced in code, not a YAML default a
+ * config edit can undo. `.env` and `.cohort-key.json` are LIVE credentials:
+ * `.env` carries COHORT_API_KEY (authenticates as this member) and
+ * `.cohort-key.json` is the device identity. Shipping either to a bucket turns
+ * a backup into a credential-exfiltration channel, and the failure would be
+ * invisible — the tarball uploads fine. So the deny-list is applied twice:
+ * as tar `--exclude` patterns AND as a pre-flight filter that DROPS any
+ * configured include path that resolves to a denied file, reporting the drop
+ * as a violation rather than quietly obeying it.
+ *
+ * A restore never wants these anyway: `scripts/restore-from-backup.sh`
+ * deliberately re-pairs for a FRESH device token instead of restoring the dead
+ * machine's identity, and secrets come back via `maestro secrets sync`.
+ *
+ * Pure + injectable (fs, env, homedir). Never throws — a DR helper that can
+ * crash the thing observing it is worse than one that says "assume bad".
+ *
+ * @module lib/backup/policy
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, isAbsolute, normalize } from "node:path";
+import yaml from "js-yaml";
+
+/** Config file, relative to the agent root. */
+export const CONFIG_REL = ".maestro/backup-config.yaml";
+/** Success marker the runner stamps, relative to the agent root. */
+export const MARKER_REL = ".maestro/last-backup.json";
+
+/**
+ * Paths that must NEVER enter a backup archive, whatever the config says.
+ *
+ * Each entry is matched against a repo-relative POSIX path, as a path prefix
+ * (`state/tmp` matches `state/tmp/anything`) or, when it contains `*`, as a
+ * glob over a single path segment. Order is irrelevant; any match denies.
+ *
+ * Rationale per group:
+ *   - live credentials  — `.env*`, `.cohort-key.json`, keychains, private keys.
+ *                          A restore re-pairs; it never restores an identity.
+ *   - Claude Code auth  — `.claude/.credentials.json` is an OAuth token.
+ *   - reconstructables  — node_modules, .git, RAG index binaries: huge, and a
+ *                          restore rebuilds them faster than it downloads them.
+ *   - hot files         — sqlite WAL/SHM and state/tmp are mid-write by
+ *                          definition; archiving them yields torn data.
+ */
+export const DENY_PATTERNS = Object.freeze([
+  // ── Live credentials: the whole reason this list is code, not config ──
+  ".env",
+  ".env.*",
+  "*.env",
+  ".cohort-key.json",
+  ".neolith-key.json",
+  ".claude/.credentials.json",
+  "config/secrets.local.yaml",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "id_rsa*",
+  "id_ed25519*",
+  ".ssh",
+  ".npmrc",
+  ".gnupg",
+  // ── Reconstructable bulk ──
+  "node_modules",
+  ".git",
+  "state/rag/index",
+  // ── Hot / torn-by-definition ──
+  "state/tmp",
+  "*.sqlite-wal",
+  "*.sqlite-shm",
+  "*.db-wal",
+  "*.db-shm",
+  ".DS_Store",
+]);
+
+/**
+ * Credential shapes that must never be INSIDE an archived file.
+ *
+ * ── why a path deny-list is not enough ──────────────────────────────────────
+ * Every enforcement point in this module used to match path NAMES only, so
+ * `.env` was correctly excluded while `state/setup/progress.json` — a 0644 file
+ * inside the default `state` include — carried `"orgToken":"nlk_…"`, the exact
+ * bytes of that agent's `COHORT_API_KEY`. The runner then listed the archive,
+ * found no denied paths, and logged "archive verified clean". Set
+ * `offsite.provider` and it uploads nightly. That is the credential-exfiltration
+ * channel the module doc warns about, arriving through the one door nobody was
+ * watching.
+ *
+ * A file whose CONTENT matches is dropped from the archive and reported as a
+ * violation. Dropped, not fatal: these patterns will occasionally hit a test
+ * fixture, and the cost of a false positive must be one missing file in a
+ * restore point — never "this machine has no DR posture".
+ *
+ * Deliberately high-signal only. This is not a general secret scanner; it is the
+ * set of things that authenticate AS this agent or its operator.
+ */
+export const SECRET_CONTENT_PATTERNS = Object.freeze([
+  { id: "cohort-api-key", re: /\bnlk_[A-Za-z0-9]{16,}/ },
+  { id: "anthropic-key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
+  { id: "openai-key", re: /\bsk-(?:proj-)?[A-Za-z0-9]{32,}/ },
+  { id: "github-token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/ },
+  { id: "slack-token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/ },
+  { id: "aws-access-key", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  { id: "google-api-key", re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { id: "private-key-block", re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----/ },
+]);
+
+/** Files larger than this are not content-scanned (and not skipped — see scanFileForSecrets). */
+export const CONTENT_SCAN_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Which credential shapes appear in this text? Pure; never throws.
+ * @param {string} text
+ * @returns {string[]} matching pattern ids
+ */
+export function scanTextForSecrets(text) {
+  if (typeof text !== "string" || !text) return [];
+  const hits = [];
+  for (const p of SECRET_CONTENT_PATTERNS) {
+    if (p.re.test(text)) hits.push(p.id);
+  }
+  return hits;
+}
+
+/**
+ * Content-scan one file. Binary files (a NUL byte in the first 8 KiB) are
+ * skipped — a credential is text by construction and scanning compiled blobs
+ * would only manufacture false positives.
+ *
+ * A file too large to scan is reported as `{ oversize:true }` rather than
+ * silently passed: the caller decides, and it says so either way.
+ *
+ * @param {string} absPath
+ * @param {object} [deps] injectable {statSync, readFileSync}
+ * @returns {{hits:string[], scanned:boolean, oversize:boolean, binary:boolean, error:string|null}}
+ */
+export function scanFileForSecrets(absPath, deps = {}) {
+  const _stat = deps.statSync || statSync;
+  const _read = deps.readFileSync || readFileSync;
+  const out = { hits: [], scanned: false, oversize: false, binary: false, error: null };
+  let size = 0;
+  try {
+    size = _stat(absPath).size;
+  } catch (err) {
+    out.error = err && err.message ? err.message : String(err);
+    return out;
+  }
+  if (size > CONTENT_SCAN_MAX_BYTES) {
+    out.oversize = true;
+    return out;
+  }
+  let buf;
+  try {
+    buf = _read(absPath);
+  } catch (err) {
+    out.error = err && err.message ? err.message : String(err);
+    return out;
+  }
+  const probe = buf.subarray ? buf.subarray(0, 8192) : Buffer.from(String(buf)).subarray(0, 8192);
+  if (probe.includes ? probe.includes(0) : false) {
+    out.binary = true;
+    return out;
+  }
+  out.scanned = true;
+  out.hits = scanTextForSecrets(buf.toString("utf-8"));
+  return out;
+}
+
+/**
+ * Default include set. Durable, hand-authored, or expensive-to-recompute state
+ * only. `logs/` is deliberately ABSENT from the default: it is the largest and
+ * least valuable tree, and the audit trail that matters is already mirrored to
+ * the org event ledger. An operator who wants logs adds them explicitly.
+ */
+export const DEFAULT_INCLUDE = Object.freeze([
+  "state",
+  "knowledge",
+  "memory",
+  "outputs",
+  "config",
+  ".maestro",
+]);
+
+/** Nightly, 03:10 local — quiet hours, and ahead of nightly-cost-reconcile. */
+export const DEFAULT_SCHEDULE = Object.freeze({ hour: 3, minute: 10 });
+
+/** Two weeks of local restore points: long enough to notice a slow corruption. */
+export const DEFAULT_RETENTION_DAYS = 14;
+
+/** Providers the runner knows how to push to. `local` needs no credentials. */
+export const OFFSITE_PROVIDERS = Object.freeze(["gcs", "s3", "rsync"]);
+
+/**
+ * Where Tier-1 snapshots live. Outside the agent repo on purpose (see module
+ * doc) and inside the user's own Library so no sudo, no shared paths, and
+ * per-user permissions apply.
+ *
+ * @param {object} [deps]
+ * @param {string} [deps.home] injectable home dir (tests)
+ * @param {object} [deps.env]  injectable env (MAESTRO_BACKUP_DIR override)
+ * @returns {string}
+ */
+export function defaultLocalRoot(deps = {}) {
+  const env = deps.env || process.env;
+  if (env.MAESTRO_BACKUP_DIR) return resolve(String(env.MAESTRO_BACKUP_DIR));
+  const home = deps.home || env.HOME || homedir();
+  return join(home, "Library", "Application Support", "Maestro", "backups");
+}
+
+/**
+ * The config a brand-new agent is born with: Tier 1 on, Tier 2 declared but
+ * empty, exclusions documented so the operator can see what is protected.
+ *
+ * Emitted verbatim by scripts/setup/init-backup.mjs. Kept as a template string
+ * (not a `yaml.dump`) so the COMMENTS ship — they are the only place an
+ * operator reads why `.env` is not in the archive.
+ *
+ * @param {object} [o]
+ * @param {string} [o.prefix] archive prefix (typically the repo slug)
+ * @returns {string} YAML document
+ */
+export function defaultConfigYaml(o = {}) {
+  const prefix = sanitisePrefix(o.prefix || "agent");
+  return `# .maestro/backup-config.yaml — this agent's disaster-recovery posture.
+#
+# TIER 1 (below, on by default): nightly local restore points written OUTSIDE
+# this repo, to ~/Library/Application Support/Maestro/backups/${prefix}/.
+# Zero credentials, survives a bad checkout / corrupted queue / rm -rf of the
+# repo. Does NOT survive machine loss.
+#
+# TIER 2 (offsite, below): the same archive pushed off the machine. This is the
+# only tier that survives a dead Mac mini, so \`maestro doctor\` WARNS until it
+# is set. Fill in provider + bucket and the nightly-backup cadence picks it up
+# on the next run — no restart needed.
+#
+# NEVER ARCHIVED, and not negotiable from this file: .env, .cohort-key.json,
+# private keys, .claude/.credentials.json, node_modules, .git, state/tmp and
+# the RAG index. Those are live credentials or reconstructable bulk; the
+# deny-list lives in lib/backup/policy.mjs (DENY_PATTERNS) and is enforced in
+# code precisely so a config edit cannot ship a credential to a bucket.
+# A restore re-pairs for a FRESH token — it never restores a dead identity.
+
+enabled: true
+prefix: ${prefix}
+
+# Tier 1 — local restore points.
+local:
+  enabled: true
+  # dir: ~/Library/Application Support/Maestro/backups   # override if you must
+  retention_days: ${DEFAULT_RETENTION_DAYS}
+
+# Tier 2 — off-machine copy. THE one that survives losing the box.
+# retention_days is enforced for gcs and s3 (the runner prunes its own
+# <bucket>/<prefix>/ key space after each successful upload). For rsync it is
+# NOT enforced — maestro will not run a remote delete over ssh against a path
+# from a config file — and the runner says so in the log every night.
+offsite:
+  provider: ""        # gcs | s3 | rsync   (empty = not configured)
+  bucket: ""          # gs://bucket, s3 bucket name, or user@host:/path for rsync
+  retention_days: 30
+
+# Nightly at 03:10 local, via the \`nightly-backup\` cadence. Change the cadence
+# in lib/cadences.mjs, not here — this value is documentation.
+schedule: "${DEFAULT_SCHEDULE.minute} ${DEFAULT_SCHEDULE.hour} * * *"
+
+include:
+${DEFAULT_INCLUDE.map((p) => `  - ${p}`).join("\n")}
+
+# Extra excludes on top of the hard-coded deny-list (repo-relative).
+exclude: []
+`;
+}
+
+/**
+ * Archive prefixes end up in file names AND bucket keys, so they get the
+ * boring treatment: lowercase, `[a-z0-9._-]` only, no leading dots or dashes
+ * (a `..`-prefixed key is a path-traversal invitation on the restore side).
+ */
+export function sanitisePrefix(raw) {
+  const s = String(raw || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[.\-]+/, "")
+    .replace(/[.\-]+$/, "");
+  return s || "agent";
+}
+
+/**
+ * Parse the config YAML. Never throws: a malformed document degrades to
+ * `null`, which callers report as "unreadable" rather than as "absent" (those
+ * are different problems and the operator needs to know which one they have).
+ *
+ * @param {string} text
+ * @returns {object|null}
+ */
+export function parseBackupConfig(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  try {
+    const doc = yaml.load(text);
+    if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+/** Normalise a repo-relative path for matching: POSIX separators, no `./`. */
+function relKey(p) {
+  return String(p)
+    .replace(/\\/g, "/")
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "");
+}
+
+/**
+ * Does `rel` (a repo-relative path) hit the hard deny-list?
+ *
+ * Matches on any path SEGMENT so a deny of `node_modules` also denies
+ * `state/x/node_modules`, and on the full path so `config/secrets.local.yaml`
+ * denies exactly that file. Glob support is deliberately one segment wide
+ * (`*.pem`, `.env.*`) — enough for the credential shapes we care about, small
+ * enough to reason about.
+ *
+ * @param {string} rel
+ * @param {string[]} [patterns]
+ * @returns {string|null} the pattern that denied it, or null
+ */
+export function denyMatch(rel, patterns = DENY_PATTERNS) {
+  const key = relKey(rel);
+  if (!key) return null;
+  const segments = key.split("/");
+  for (const pattern of patterns) {
+    const pat = relKey(pattern);
+    if (!pat) continue;
+    if (pat.includes("*")) {
+      const re = new RegExp(
+        `^${pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")}$`
+      );
+      if (segments.some((seg) => re.test(seg))) return pattern;
+      if (re.test(key)) return pattern;
+      continue;
+    }
+    if (key === pat) return pattern;
+    if (key.startsWith(`${pat}/`)) return pattern;
+    // Bare segment denies (node_modules, .git) apply at any depth.
+    if (!pat.includes("/") && segments.includes(pat)) return pattern;
+  }
+  return null;
+}
+
+/**
+ * Resolve the effective backup plan for an agent root.
+ *
+ * The single source of truth for the runner, the doctor check and the cadence
+ * handler — three call sites that used to each re-derive their own idea of
+ * what "configured" meant (and disagreed).
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot
+ * @param {object} [o.fs]   injectable {existsSync, readFileSync} (tests)
+ * @param {object} [o.env]  injectable env
+ * @param {string} [o.home] injectable home dir
+ * @returns {{
+ *   present: boolean,
+ *   readable: boolean,
+ *   enabled: boolean,
+ *   prefix: string,
+ *   local: {enabled: boolean, dir: string, retentionDays: number},
+ *   offsite: {configured: boolean, provider: string, bucket: string, retentionDays: number},
+ *   include: string[],
+ *   exclude: string[],
+ *   violations: Array<{path: string, pattern: string}>,
+ *   tier: "none"|"unreadable"|"disabled"|"local"|"offsite",
+ * }}
+ */
+export function resolveBackupPlan(o = {}) {
+  const _fs = o.fs || { existsSync, readFileSync };
+  const agentRoot = resolve(o.agentRoot || process.cwd());
+  const path = join(agentRoot, CONFIG_REL);
+
+  const base = {
+    present: false,
+    readable: false,
+    enabled: false,
+    prefix: sanitisePrefix(agentRoot.split("/").pop()),
+    local: { enabled: false, dir: "", retentionDays: DEFAULT_RETENTION_DAYS },
+    offsite: { configured: false, provider: "", bucket: "", retentionDays: 30 },
+    include: [...DEFAULT_INCLUDE],
+    exclude: [],
+    violations: [],
+    tier: "none",
+  };
+
+  let raw;
+  try {
+    if (!_fs.existsSync(path)) return base;
+    raw = _fs.readFileSync(path, "utf-8");
+  } catch {
+    return { ...base, present: true, tier: "unreadable" };
+  }
+
+  const doc = parseBackupConfig(raw);
+  if (!doc) return { ...base, present: true, tier: "unreadable" };
+
+  const enabled = doc.enabled === true;
+  const prefix = sanitisePrefix(doc.prefix || base.prefix);
+
+  const localCfg = doc.local && typeof doc.local === "object" ? doc.local : {};
+  // Tier 1 is on unless explicitly switched off — the default posture.
+  const localEnabled = localCfg.enabled !== false;
+  const localDir = localCfg.dir
+    ? resolve(expandHome(String(localCfg.dir), o))
+    : join(defaultLocalRoot(o), prefix);
+
+  const offCfg = doc.offsite && typeof doc.offsite === "object" ? doc.offsite : {};
+  const provider = String(offCfg.provider || "").trim().toLowerCase();
+  const bucket = String(offCfg.bucket || "").trim();
+  const offsiteConfigured = OFFSITE_PROVIDERS.includes(provider) && bucket !== "";
+
+  // Include list: config wins, defaults otherwise; deny-list violations are
+  // DROPPED and reported. A typo'd `- .env` never reaches tar.
+  const rawInclude = Array.isArray(doc.include) && doc.include.length ? doc.include : [...DEFAULT_INCLUDE];
+  const include = [];
+  const violations = [];
+  for (const entry of rawInclude) {
+    const rel = relKey(entry);
+    if (!rel) continue;
+    if (isAbsolute(rel) || normalize(rel).startsWith("..")) {
+      violations.push({ path: rel, pattern: "outside-agent-root" });
+      continue;
+    }
+    const hit = denyMatch(rel);
+    if (hit) {
+      violations.push({ path: rel, pattern: hit });
+      continue;
+    }
+    if (!include.includes(rel)) include.push(rel);
+  }
+
+  const exclude = (Array.isArray(doc.exclude) ? doc.exclude : [])
+    .map(relKey)
+    .filter(Boolean);
+
+  let tier = "disabled";
+  if (enabled && offsiteConfigured) tier = "offsite";
+  else if (enabled && localEnabled) tier = "local";
+
+  return {
+    present: true,
+    readable: true,
+    enabled,
+    prefix,
+    local: {
+      enabled: localEnabled,
+      dir: localDir,
+      retentionDays: posInt(localCfg.retention_days, DEFAULT_RETENTION_DAYS),
+    },
+    offsite: {
+      configured: offsiteConfigured,
+      provider,
+      bucket,
+      retentionDays: posInt(offCfg.retention_days, 30),
+    },
+    include,
+    exclude,
+    violations,
+    tier,
+  };
+}
+
+/** `~`-relative paths in config resolve against the real home dir. */
+function expandHome(p, deps = {}) {
+  if (!p.startsWith("~")) return p;
+  const env = deps.env || process.env;
+  const home = deps.home || env.HOME || homedir();
+  return join(home, p.slice(1));
+}
+
+function posInt(v, fallback) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+
+/**
+ * tar `--exclude` arguments for a plan: the hard deny-list first (so it cannot
+ * be reordered away), then the operator's extras.
+ *
+ * @param {object} plan
+ * @returns {string[]}
+ */
+export function tarExcludeArgs(plan) {
+  const pats = [...DENY_PATTERNS, ...((plan && plan.exclude) || [])];
+  const args = [];
+  for (const p of pats) {
+    args.push(`--exclude=${p}`);
+    // bsdtar/gnutar match --exclude against the stored path; a bare segment
+    // deny needs the `*/seg` form to hit nested copies too.
+    if (!p.includes("/") && !p.includes("*")) args.push(`--exclude=*/${p}`);
+  }
+  return args;
+}
+
+/**
+ * Walk a plan's include trees and find every file whose CONTENT carries a
+ * credential. The pre-flight half of the content deny-list: its output becomes
+ * `--exclude` arguments, so the bytes never enter the archive at all.
+ *
+ * Path-denied entries are skipped as we walk (no point scanning `node_modules`),
+ * which also keeps this cheap: the observed real agent is ~4,800 files / 4 MB.
+ *
+ * NEVER THROWS. An unreadable directory is reported in `errors[]` and the walk
+ * continues — a DR helper that can crash the backup is worse than one that
+ * reports partial coverage. `truncated` is set when the file budget is hit, so a
+ * caller can refuse rather than believe a partial scan.
+ *
+ * @param {object} plan  from resolveBackupPlan
+ * @param {string} agentRoot
+ * @param {object} [deps] { readdirSync, statSync, readFileSync, maxFiles }
+ * @returns {{ leaks:Array<{path:string,patterns:string[]}>, scanned:number,
+ *             skippedBinary:number, oversize:string[], errors:string[],
+ *             truncated:boolean }}
+ */
+export function scanIncludesForSecrets(plan, agentRoot, deps = {}) {
+  const _readdir = deps.readdirSync || readdirSync;
+  const _stat = deps.statSync || statSync;
+  const maxFiles = Number.isFinite(deps.maxFiles) ? deps.maxFiles : 50_000;
+  const root = resolve(agentRoot || process.cwd());
+
+  const leaks = [];
+  const oversize = [];
+  const errors = [];
+  let scanned = 0;
+  let skippedBinary = 0;
+  let seen = 0;
+  let truncated = false;
+
+  const walk = (rel) => {
+    if (truncated) return;
+    if (denyMatch(rel)) return;
+    const abs = join(root, rel);
+    let st;
+    try {
+      st = _stat(abs);
+    } catch (err) {
+      errors.push(`${rel}: ${err && err.message ? err.message : err}`);
+      return;
+    }
+    if (st.isDirectory && st.isDirectory()) {
+      let entries = [];
+      try {
+        entries = _readdir(abs);
+      } catch (err) {
+        errors.push(`${rel}: ${err && err.message ? err.message : err}`);
+        return;
+      }
+      for (const name of entries) walk(`${rel}/${name}`);
+      return;
+    }
+    if (++seen > maxFiles) {
+      truncated = true;
+      return;
+    }
+    const r = scanFileForSecrets(abs, deps);
+    if (r.error) errors.push(`${rel}: ${r.error}`);
+    if (r.oversize) oversize.push(rel);
+    if (r.binary) skippedBinary += 1;
+    if (r.scanned) scanned += 1;
+    if (r.hits.length) leaks.push({ path: rel, patterns: r.hits });
+  };
+
+  for (const inc of (plan && plan.include) || []) walk(relKey(inc));
+  return { leaks, scanned, skippedBinary, oversize, errors, truncated };
+}
+
+/**
+ * Human-readable one-liner for doctor/alerts, given a plan + freshness verdict.
+ * Returns the level AND the sentence so both consumers stay in lockstep.
+ *
+ * Severity ladder (the decision in one place):
+ *   fail — no config, unreadable config, disabled, or every include denied.
+ *   fail — Tier 1 on but no successful run has EVER happened.
+ *   warn — restore points exist but are stale, or are local-only.
+ *   ok   — offsite tier, fresh.
+ *
+ * @param {object} plan     from resolveBackupPlan
+ * @param {object} fresh    {configured, lastBackupAt, ageHours, stale}
+ * @returns {{level:"ok"|"warn"|"fail", msg:string, fix?:string}}
+ */
+export function backupVerdict(plan, fresh = {}) {
+  if (!plan || !plan.present) {
+    return {
+      level: "fail",
+      msg: "No DR posture at all — .maestro/backup-config.yaml is missing, so nothing on this machine is recoverable.",
+      fix: "maestro init backup-replication --apply   (writes the default: nightly LOCAL restore points outside the repo, no credentials needed)",
+    };
+  }
+  if (!plan.readable) {
+    return {
+      level: "fail",
+      msg: ".maestro/backup-config.yaml is present but unparseable — the nightly backup cannot run.",
+      fix: "fix the YAML, or delete it and re-run: maestro init backup-replication --apply",
+    };
+  }
+  if (!plan.enabled) {
+    return {
+      level: "fail",
+      msg: "Backup is configured but switched OFF (.maestro/backup-config.yaml: enabled is not true) — this machine has no restore points.",
+      fix: "set enabled: true in .maestro/backup-config.yaml",
+    };
+  }
+  if (!plan.include.length) {
+    return {
+      level: "fail",
+      msg: `Backup enabled but every include path was rejected (${plan.violations.map((v) => `${v.path} → ${v.pattern}`).join(", ") || "empty include list"}) — the archive would be empty.`,
+      fix: "restore the include list in .maestro/backup-config.yaml (state, knowledge, memory, outputs, config, .maestro)",
+    };
+  }
+
+  const where = plan.tier === "offsite" ? `${plan.offsite.provider}://${plan.offsite.bucket}` : plan.local.dir;
+  const age = Number.isFinite(fresh.ageHours) ? `${Math.round(fresh.ageHours)}h ago` : "never";
+
+  if (!fresh.lastBackupAt) {
+    return {
+      level: "fail",
+      msg: `Backup enabled but has NEVER completed a run — there is no restore point (target ${where}).`,
+      fix: "run it once now: node scripts/maintenance/backup-run.mjs   (then the nightly-backup cadence keeps it current)",
+    };
+  }
+  if (fresh.stale) {
+    return {
+      level: "warn",
+      msg: `Last backup ${age} — stale (target ${where}). Check logs/maintenance/backup.log.`,
+      fix: "node scripts/maintenance/backup-run.mjs",
+    };
+  }
+  if (plan.tier !== "offsite") {
+    return {
+      level: "warn",
+      msg: `Restore points are LOCAL-ONLY: fresh (${age}) at ${where}, but nothing is off this machine — losing the box loses everything since enrolment.`,
+      fix: "set offsite.provider (gcs|s3|rsync) + offsite.bucket in .maestro/backup-config.yaml",
+    };
+  }
+  return {
+    level: "ok",
+    msg: `Backup fresh + off-machine: last run ${age} → ${where} (local copy at ${plan.local.dir})`,
+  };
+}
+
+export default {
+  CONFIG_REL,
+  MARKER_REL,
+  DENY_PATTERNS,
+  DEFAULT_INCLUDE,
+  DEFAULT_RETENTION_DAYS,
+  OFFSITE_PROVIDERS,
+  defaultLocalRoot,
+  defaultConfigYaml,
+  sanitisePrefix,
+  parseBackupConfig,
+  denyMatch,
+  resolveBackupPlan,
+  tarExcludeArgs,
+  backupVerdict,
+  SECRET_CONTENT_PATTERNS,
+  CONTENT_SCAN_MAX_BYTES,
+  scanTextForSecrets,
+  scanFileForSecrets,
+  scanIncludesForSecrets,
+};