@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/src/lib/worktree/finish-backup.js

@@ -0,0 +1,739 @@
+/**
+ * finish-backup.js — the backups `finish` and `worktree remove` leave under
+ * `.git/morph-spec/finish-backup/`: how one is written, how they are listed,
+ * and how long each one lives.
+ *
+ * A backup exists so that removing a worktree (or shedding the root-side
+ * scaffold) never destroys the only exemplar of a file. That is a reason to keep
+ * the last ones, not all of them, and a worktree's `.env.e2e` — the e2e stack's
+ * credentials — has no business living inside `.git/` indefinitely. So every
+ * backup is subject to a retention policy, on by default:
+ *
+ *   maxCount          — the newest this many backups per namespace always stay
+ *   maxAgeDays        — no age cut unless configured: a quiet month must never
+ *                       empty the backups of the last features closed
+ *   secretMaxAgeDays  — `.env*` files inside a backup go away after this
+ *
+ * `config.json → finishBackup.retention` can change the numbers or turn the
+ * whole thing off (`false`); a project without the key gets the defaults, and a
+ * value that cannot be read skips the prune for that run.
+ *
+ * A backup without its manifest was written before this retention existed. The
+ * automatic prune (end of `finish`, end of `worktree remove`) never deletes it,
+ * never strips its `.env*` and does not count it against the budget — it only
+ * reports how many wait (`legacyPending`). The first prune of those is the
+ * explicit `doctor --worktrees --prune`, which ranks them with the rest and
+ * gives each one it keeps a manifest, so from then on they are ordinary backups.
+ *
+ * Layout, and what counts as ONE backup:
+ *
+ *   {feature}-{stamp}/                     the feature scope the shed discards
+ *   {feature}-{stamp}-worktree-ignored/    the worktree's exclusive gitignored
+ *   {folder}.manifest.json                 sidecar: what was copied, the secrets
+ *   task/{name}-{stamp}-worktree-ignored/  a namespace (task isolation trees)
+ *
+ * One finish writes both folders with the SAME stamp, so they are one backup —
+ * the unit the count applies to; a folder with no same-stamp sibling counts
+ * alone. The `task/` namespace has its own budget: a fan-out of twenty
+ * sub-agent worktrees must not evict the backup of the feature finished a
+ * minute earlier. The backup the calling run just wrote is never pruned by it.
+ *
+ * Deletion is PROVE-or-DECLINE, as everywhere else near a worktree: a backup
+ * holding a reparse point is never removed, links are never descended, and
+ * nothing outside the backup directory is touched. Not because `rmSync` would
+ * follow a junction — it unlinks the link itself; what once emptied a primary
+ * root was `git worktree remove` — but because a link inside a backup is not
+ * something this code put there. A first-level entry that is neither a backup
+ * nor `task/` is left alone, even empty — it is not ours to judge.
+ */
+
+import {
+  cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync,
+  rmdirSync, rmSync, unlinkSync,
+} from 'fs';
+import { dirname, join, relative, isAbsolute } from 'path';
+import { isDisposableBuildArtifact } from './ignored-triage.js';
+import { atomicWriteJson, CONFIG_FILE_NAME } from '../../core/state/state-manager.js';
+import { scanForBlockers } from '../../../framework/hooks/shared/reparse-scan.js';
+
+export const FINISH_BACKUP_RETENTION_DEFAULTS = Object.freeze({
+  maxCount: 20,
+  maxAgeDays: null,
+  secretMaxAgeDays: 7,
+});
+
+/** The keys whose `null` means "no limit" rather than an invalid value. */
+const NULLABLE_RETENTION_KEYS = new Set(['maxAgeDays']);
+
+const DAY_MS = 86_400_000;
+const WORKTREE_IGNORED_SUFFIX = '-worktree-ignored';
+const MANIFEST_SUFFIX = '.manifest.json';
+const NAME_RE = /^(.+)-(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z(-worktree-ignored)?$/;
+/** How many names a payload carries; the counts are always complete. */
+const SAMPLE = 5;
+
+/** @param {string} root - the primary root */
+export function morphSpecStoreDir(root) {
+  return join(root, '.git', 'morph-spec');
+}
+
+/** @param {string} root - the primary root */
+export function finishBackupDir(root) {
+  return join(morphSpecStoreDir(root), 'finish-backup');
+}
+
+/** The stamp in a backup's name — filesystem-safe ISO-8601. */
+export function newBackupStamp(date = new Date()) {
+  return date.toISOString().replace(/[:.]/g, '-');
+}
+
+/** `.env`, `.env.e2e`, `.env.local`… — the files that hold a stack's secrets. */
+export function isSecretFileName(name) {
+  return name.startsWith('.env');
+}
+
+/**
+ * @param {string} name - one directory name under finish-backup/ (or under a namespace)
+ * @returns {{ base: string, feature: string, stamp: string,
+ *   kind: 'feature-scope'|'worktree-ignored', createdAt: number }|null}
+ */
+export function parseBackupName(name) {
+  const m = NAME_RE.exec(name);
+  if (!m) return null;
+  const [, feature, date, hh, mm, ss, ms, suffix] = m;
+  const createdAt = Date.parse(`${date}T${hh}:${mm}:${ss}.${ms}Z`);
+  if (Number.isNaN(createdAt)) return null;
+  return {
+    base: suffix ? name.slice(0, -WORKTREE_IGNORED_SUFFIX.length) : name,
+    feature,
+    stamp: `${date}T${hh}-${mm}-${ss}-${ms}Z`,
+    kind: suffix ? 'worktree-ignored' : 'feature-scope',
+    createdAt,
+  };
+}
+
+function stampToIso(stamp) {
+  const parsed = parseBackupName(`x-${stamp}`);
+  return new Date(parsed ? parsed.createdAt : Date.now()).toISOString();
+}
+
+const RETENTION_KEYS = Object.keys(FINISH_BACKUP_RETENTION_DEFAULTS);
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const shown = (v) => JSON.stringify(v) ?? String(v);
+const skippedPolicy = (reason) => ({ enabled: false, skipped: reason, ...FINISH_BACKUP_RETENTION_DEFAULTS });
+
+/**
+ * The policy in force, from a parsed config.json. A config without the key
+ * gets the defaults (retention on) and an explicit `false` turns it off. What
+ * this cannot recognise SKIPS the prune for the run instead: the operation
+ * deletes, and a value nobody can read — `{ enabled: false }`, `"false"`, a
+ * `maxCount` of `0` — may well have been meant as "keep everything".
+ *
+ * @param {object|null} config - null when there is no config.json at all
+ * @returns {{ enabled: boolean, skipped?: string, maxCount: number, maxAgeDays: number|null, secretMaxAgeDays: number }}
+ */
+export function resolveBackupRetention(config) {
+  const d = FINISH_BACKUP_RETENTION_DEFAULTS;
+  const skip = skippedPolicy;
+  const section = config?.finishBackup;
+  if (section === undefined) return { enabled: true, ...d };
+  if (!isPlainObject(section)) return skip(`finishBackup não é um objeto (${shown(section)})`);
+  const raw = section.retention;
+  if (raw === undefined) return { enabled: true, ...d };
+  if (raw === false) return { enabled: false, ...d };
+  if (!isPlainObject(raw)) {
+    return skip(`finishBackup.retention não reconhecida (${shown(raw)}) — use false ou { ${RETENTION_KEYS.join(', ')} }`);
+  }
+  const policy = { enabled: true, ...d };
+  for (const [key, value] of Object.entries(raw)) {
+    if (!RETENTION_KEYS.includes(key)) return skip(`finishBackup.retention.${key} não existe — as chaves são ${RETENTION_KEYS.join(', ')}`);
+    if (value === null && NULLABLE_RETENTION_KEYS.has(key)) { policy[key] = null; continue; }
+    if (!Number.isInteger(value) || value < 1) {
+      return skip(`finishBackup.retention.${key} inválido (${shown(value)}) — inteiro ≥ 1${NULLABLE_RETENTION_KEYS.has(key) ? ' ou null (sem limite)' : ''}`);
+    }
+    policy[key] = value;
+  }
+  return policy;
+}
+
+/**
+ * Unlike `readMorphConfig`, a config.json that exists and does not parse is
+ * not "no config": the defaults would turn on a prune its author may have
+ * switched off in the part that failed to parse.
+ *
+ * @param {string} root
+ */
+export function readBackupRetention(root) {
+  const path = join(root, CONFIG_FILE_NAME);
+  if (!existsSync(path)) return resolveBackupRetention(null);
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, ''));
+  } catch (err) {
+    return skippedPolicy(`config.json ilegível (${String(err?.message || err).slice(0, 80)})`);
+  }
+  return resolveBackupRetention(config);
+}
+
+function isRealDir(path) {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isRealFile(path) {
+  try {
+    return lstatSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isStrictlyInside(parent, child) {
+  const rel = relative(parent, child);
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+/**
+ * Every `.env*` REAL file under `dir`, relative to it. Links are neither
+ * followed nor reported: a link is not bytes this backup holds.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function secretFilesIn(dir) {
+  const out = [];
+  const stack = [''];
+  while (stack.length) {
+    const rel = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(join(dir, rel), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) stack.push(childRel);
+      else if (e.isFile() && isSecretFileName(e.name)) out.push(childRel);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Bytes and files under `dir`, by lstat — a link counts as itself, never as
+ * what it points at. `null` when the walk could not start.
+ *
+ * @param {string} dir
+ * @returns {{ bytes: number, files: number }|null}
+ */
+export function measureDir(dir) {
+  if (!isRealDir(dir)) return null;
+  let bytes = 0;
+  let files = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const p = join(current, e.name);
+      if (e.isDirectory() && !e.isSymbolicLink()) { stack.push(p); continue; }
+      try { bytes += lstatSync(p).size; files += 1; } catch { /* vanished */ }
+    }
+  }
+  return { bytes, files };
+}
+
+export function manifestPathFor(backupPath) {
+  return `${backupPath}${MANIFEST_SUFFIX}`;
+}
+
+function readManifest(backupPath) {
+  try {
+    return JSON.parse(readFileSync(manifestPathFor(backupPath), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Bookkeeping, never a precondition: a backup whose bytes are on disk is a
+ * backup, with or without its manifest. One whose manifest failed to be written
+ * reads as legacy, which is the safe side — the automatic prune leaves it alone.
+ */
+function writeManifest(backupPath, manifest) {
+  try {
+    atomicWriteJson(manifestPathFor(backupPath), { version: 1, ...manifest });
+  } catch { /* fail-open */ }
+}
+
+/**
+ * Copy the worktree's exclusive gitignored leftovers out before the removal
+ * deletes them. Caches are excluded at every depth, not only as top-level
+ * entries: git reports an ignored directory as ONE entry when the directory
+ * itself matches a pattern, so an exclusive `apps/x/` would otherwise drag its
+ * `node_modules/` and `.next/` along. They are regenerable, and the removal
+ * deletes them either way.
+ *
+ * @param {{ worktreePath: string, root: string, feature: string, rels: string[], stamp?: string }} args
+ * @returns {string|null} the backup path, or null if ANY copy failed (the caller
+ *   must then decline the removal — a partial backup authorizes nothing) or if
+ *   none of `rels` exists anymore
+ */
+export function writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels, stamp = newBackupStamp() }) {
+  const dest = join(finishBackupDir(root), `${feature}-${stamp}${WORKTREE_IGNORED_SUFFIX}`);
+  const copied = [];
+  const excludedCaches = [];
+  const relOf = (abs) => relative(worktreePath, abs).replace(/\\/g, '/');
+  try {
+    for (const rel of rels) {
+      const src = join(worktreePath, rel);
+      if (!existsSync(src)) continue; // a directory entry already covered by its children
+      if (isDisposableBuildArtifact(relOf(src))) {
+        excludedCaches.push(relOf(src));
+        continue;
+      }
+      const target = join(dest, rel);
+      mkdirSync(dirname(target), { recursive: true });
+      cpSync(src, target, {
+        recursive: true,
+        filter: (from) => {
+          const r = relOf(from);
+          if (!isDisposableBuildArtifact(r)) return true;
+          excludedCaches.push(r);
+          return false;
+        },
+      });
+      copied.push(rel);
+    }
+    if (!copied.length && !excludedCaches.length) return null;
+    mkdirSync(dest, { recursive: true });
+  } catch {
+    return null;
+  }
+  writeManifest(dest, {
+    kind: 'worktree-ignored',
+    feature,
+    createdAt: stampToIso(stamp),
+    source: worktreePath.replace(/\\/g, '/'),
+    copied,
+    excludedCaches,
+    secrets: secretFilesIn(dest),
+  });
+  return dest;
+}
+
+/**
+ * Copy the feature's root-side scope to a backup OUTSIDE the working tree, so
+ * the shed can never be the reason something is lost.
+ *
+ * Lives under `.git/` on purpose: it is not a working-tree path, so it can never
+ * dirty `git status` (which the very next validation reads) and is never merged,
+ * committed, or cleaned by `git clean`.
+ *
+ * @param {{ root: string, feature: string, stamp?: string }} args
+ * @returns {string|null} absolute backup path, or null if the copy failed
+ */
+export function writeFeatureScopeBackup({ root, feature, stamp = newBackupStamp() }) {
+  const src = join(root, '.morph', 'features', feature);
+  if (!existsSync(src)) return null;
+  const dest = join(finishBackupDir(root), `${feature}-${stamp}`);
+  try {
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest, { recursive: true });
+  } catch {
+    return null; // caller MUST treat this as "do not shed"
+  }
+  writeManifest(dest, {
+    kind: 'feature-scope',
+    feature,
+    createdAt: stampToIso(stamp),
+    source: src.replace(/\\/g, '/'),
+    secrets: secretFilesIn(dest),
+  });
+  return dest;
+}
+
+/**
+ * The first-level directories that hold backups instead of being one: `task/`
+ * is where the `task/{name}` key of a task isolation tree (see
+ * `envKeyForWorktree` in worktree.js) lands. Any other first-level directory
+ * that is not a backup was put there by someone else — never listed, never
+ * removed, not even empty.
+ */
+const BACKUP_NAMESPACES = new Set(['task']);
+
+/**
+ * Every backup folder on disk: the first level, plus one level down inside a
+ * namespace of BACKUP_NAMESPACES. A link is never descended, at either level.
+ *
+ * @param {string} root
+ * `managed` is whether the folder has its manifest — the one criterion that
+ * tells a backup of this retention from one written before it.
+ *
+ * @returns {Array<{ name: string, path: string, namespace: string, set: string,
+ *   feature: string, stamp: string, kind: string, createdAt: number, managed: boolean }>}
+ */
+export function listFinishBackups(root) {
+  const base = finishBackupDir(root);
+  if (!isRealDir(base)) return [];
+  const out = [];
+  const visit = (dir, namespace) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const path = join(dir, e.name);
+      if (!isRealDir(path)) continue; // manifests, temp files and links
+      const parsed = parseBackupName(e.name);
+      if (parsed) {
+        const prefix = namespace ? `${namespace}/` : '';
+        out.push({
+          name: `${prefix}${e.name}`,
+          path,
+          namespace,
+          set: `${prefix}${parsed.base}`,
+          feature: `${prefix}${parsed.feature}`,
+          stamp: parsed.stamp,
+          kind: parsed.kind,
+          createdAt: parsed.createdAt,
+          managed: isRealFile(manifestPathFor(path)),
+        });
+      } else if (!namespace && BACKUP_NAMESPACES.has(e.name)) {
+        visit(path, e.name);
+      }
+    }
+  };
+  visit(base, '');
+  return out;
+}
+
+/**
+ * Which backups the policy removes, and which it keeps but strips of `.env*`.
+ * Pure: the caller supplies the listing and the clock.
+ *
+ * Two kinds of set are never removed. The ones stamped with `protectStamps` —
+ * the backup the calling run just wrote: a retention that runs after a backup
+ * exists to make room for it, not to take it. And the ones stamped AFTER `now`
+ * (a clock that ran ahead and was corrected): their age is unknowable, so they
+ * stay and do not take a place in the count — otherwise a handful of them
+ * would push every new backup out the moment it is written.
+ *
+ * A set is legacy unless EVERY folder in it has its manifest. Without
+ * `includeLegacy` (the automatic prune) legacy sets are out of the plan
+ * altogether — no removal, no strip, no place in the count — and only counted
+ * in `legacy`. With it (the explicit prune) they are ranked like the rest, and
+ * the ones kept are listed in `adopt`.
+ *
+ * @param {ReturnType<typeof listFinishBackups>} backups
+ * @param {ReturnType<typeof resolveBackupRetention>} retention
+ * @param {number} now - epoch ms
+ * @param {{ protectStamps?: string[], includeLegacy?: boolean }} [opts]
+ * @returns {{ sets: number, legacy: number, remove: object[], stripSecrets: object[], adopt: object[] }}
+ *   each entry a `{ set, namespace, stamp, createdAt, managed, members }`
+ */
+export function planBackupRetention(backups, retention, now, { protectStamps = [], includeLegacy = false } = {}) {
+  const sets = new Map();
+  for (const b of backups) {
+    const s = sets.get(b.set) ?? { set: b.set, namespace: b.namespace, stamp: b.stamp, createdAt: b.createdAt, managed: true, members: [] };
+    s.createdAt = Math.min(s.createdAt, b.createdAt);
+    s.managed = s.managed && b.managed;
+    s.members.push(b);
+    sets.set(b.set, s);
+  }
+  const all = [...sets.values()];
+  const plan = { sets: sets.size, legacy: all.filter((s) => !s.managed).length, remove: [], stripSecrets: [], adopt: [] };
+  if (!retention.enabled) return plan;
+
+  const isProtected = (s) => protectStamps.includes(s.stamp);
+  const byNamespace = new Map();
+  for (const s of all) {
+    if (!s.managed && !includeLegacy) continue;
+    if (s.createdAt > now) {
+      if (!s.managed) plan.adopt.push(s);
+      continue;
+    }
+    const list = byNamespace.get(s.namespace) ?? [];
+    list.push(s);
+    byNamespace.set(s.namespace, list);
+  }
+  const maxAgeMs = retention.maxAgeDays == null ? Infinity : retention.maxAgeDays * DAY_MS;
+  for (const list of byNamespace.values()) {
+    list.sort((a, b) => b.createdAt - a.createdAt || (a.set < b.set ? 1 : -1));
+    list.forEach((s, index) => {
+      const age = now - s.createdAt;
+      const dropped = index >= retention.maxCount || age > maxAgeMs;
+      if (dropped && !isProtected(s)) {
+        plan.remove.push(s);
+        return;
+      }
+      if (age > retention.secretMaxAgeDays * DAY_MS) plan.stripSecrets.push(s);
+      if (!s.managed) plan.adopt.push(s);
+    });
+  }
+  return plan;
+}
+
+/**
+ * Apply the policy: remove what it drops, strip `.env*` from what it keeps past
+ * the short retention, and record the stripped names in the manifest. A backup
+ * whose removal is declined (a reparse point inside, a locked file) is stripped
+ * instead: the policy wanted it gone, and its secrets are the part that must not
+ * linger. A policy that could not be read (`skipped`) prunes nothing. Never
+ * throws — a retention that fails must never be the reason a `finish` fails.
+ *
+ * Legacy backups (no manifest) are touched only with `includeLegacy` — the
+ * explicit `doctor --worktrees --prune`; otherwise they are counted in
+ * `legacyPending`. The explicit prune writes a manifest into every legacy
+ * backup it keeps (`adopted`), which makes it an ordinary backup from then on.
+ *
+ * @param {string} root
+ * @param {{ now?: number, retention?: ReturnType<typeof resolveBackupRetention>,
+ *   protectStamps?: string[], includeLegacy?: boolean }} [opts]
+ *   `protectStamps`: the stamp(s) the calling run wrote its backup under
+ * @returns {{ enabled: boolean, skipped?: string, removed: string[],
+ *   secretsStripped: Array<{ backup: string, files: string[] }>, declined: Array<{ backup: string, reason: string }>,
+ *   legacyPending: number, adopted: string[] }}
+ */
+export function applyBackupRetention(root, { now = Date.now(), retention, protectStamps = [], includeLegacy = false } = {}) {
+  const result = { enabled: true, removed: [], secretsStripped: [], declined: [], legacyPending: 0, adopted: [] };
+  try {
+    const policy = retention ?? readBackupRetention(root);
+    result.enabled = policy.enabled;
+    if (policy.skipped) result.skipped = policy.skipped;
+    if (!policy.enabled) return result;
+    const base = finishBackupDir(root);
+    if (!isRealDir(base)) return result;
+    const plan = planBackupRetention(listFinishBackups(root), policy, now, { protectStamps, includeLegacy });
+    if (!includeLegacy) result.legacyPending = plan.legacy;
+    const toStrip = plan.stripSecrets.flatMap((s) => s.members);
+
+    for (const s of plan.remove) {
+      for (const m of s.members) {
+        if (!isStrictlyInside(base, m.path)) {
+          result.declined.push({ backup: m.name, reason: 'outside-backup-dir' });
+          continue;
+        }
+        const scan = scanForBlockers(m.path);
+        if (!scan.safe) {
+          result.declined.push({ backup: m.name, reason: `reparse-point: ${scan.blockers.slice(0, SAMPLE).join(', ')}` });
+          toStrip.push(m);
+          continue;
+        }
+        try {
+          rmSync(m.path, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+        } catch (err) {
+          result.declined.push({ backup: m.name, reason: (err?.code || err?.message || 'rm-failed').toString().slice(0, 120) });
+          toStrip.push(m);
+          continue;
+        }
+        try { rmSync(manifestPathFor(m.path), { force: true }); } catch { /* the sidecar is bookkeeping */ }
+        result.removed.push(m.name);
+      }
+    }
+
+    for (const m of toStrip) {
+      const stripped = [];
+      for (const rel of secretFilesIn(m.path)) {
+        try {
+          unlinkSync(join(m.path, rel));
+          stripped.push(rel);
+        } catch { /* locked — the next run tries again */ }
+      }
+      if (!stripped.length) continue;
+      const manifest = readManifest(m.path) ?? { kind: m.kind, feature: m.feature, createdAt: new Date(m.createdAt).toISOString() };
+      const secrets = [...new Set([...(manifest.secrets || []), ...stripped])].sort();
+      writeManifest(m.path, { ...manifest, secrets, secretsStrippedAt: new Date(now).toISOString() });
+      result.secretsStripped.push({ backup: m.name, files: stripped });
+    }
+
+    for (const m of plan.adopt.flatMap((s) => s.members)) {
+      if (m.managed) continue;
+      const manifest = readManifest(m.path)
+        ?? { kind: m.kind, feature: m.feature, createdAt: new Date(m.createdAt).toISOString(), secrets: secretFilesIn(m.path) };
+      writeManifest(m.path, { ...manifest, legacy: true, adoptedAt: new Date(now).toISOString() });
+      result.adopted.push(m.name);
+    }
+
+    // A namespace emptied by the removals goes too; rmdir refuses anything else.
+    for (const name of BACKUP_NAMESPACES) {
+      const p = join(base, name);
+      if (isRealDir(p)) {
+        try { rmdirSync(p); } catch { /* not empty */ }
+      }
+    }
+  } catch { /* fail-open */ }
+  return result;
+}
+
+/**
+ * What a prune WOULD do now, without doing it. `includeLegacy` picks which
+ * prune: without it, the automatic one (what `finish --dry-run` announces);
+ * with it, the explicit `doctor --worktrees --prune` (what the doctor reports).
+ *
+ * @param {string} root
+ * @param {{ now?: number, retention?: ReturnType<typeof resolveBackupRetention>, includeLegacy?: boolean }} [opts]
+ * @returns {{ policy: object, sets: number, folders: number, legacy: number,
+ *   outsideRetention: number, overdueSecrets: string[] }}
+ */
+export function inspectFinishBackups(root, { now = Date.now(), retention, includeLegacy = false } = {}) {
+  const policy = retention ?? readBackupRetention(root);
+  const backups = listFinishBackups(root);
+  const plan = planBackupRetention(backups, policy, now, { includeLegacy });
+  const overdueSecrets = plan.stripSecrets.flatMap((s) => s.members.flatMap((m) => secretFilesIn(m.path).map((f) => `${m.name}/${f}`)));
+  return {
+    policy,
+    sets: plan.sets,
+    folders: backups.length,
+    legacy: plan.legacy,
+    outsideRetention: plan.remove.length,
+    overdueSecrets,
+  };
+}
+
+/** The sentence both the audit and the store line say about what `--prune` would do. */
+function pendingParts(report, { long = false } = {}) {
+  const { maxCount, maxAgeDays, secretMaxAgeDays } = report.policy;
+  const parts = [];
+  if (report.legacy) {
+    parts.push(long
+      ? `${report.legacy} backup(s) sem manifesto (anteriores à retenção) — a poda automática não os toca`
+      : `${report.legacy} sem manifesto aguardando --prune`);
+  }
+  if (report.outsideRetention) {
+    const age = maxAgeDays == null ? '' : ` ou com mais de ${maxAgeDays} dias`;
+    parts.push(long
+      ? `--prune apagaria ${report.outsideRetention} backup(s) fora do teto de ${maxCount} por namespace${age}`
+      : `${report.outsideRetention} fora da retenção`);
+  }
+  if (report.overdueSecrets.length) {
+    parts.push(long
+      ? `${report.overdueSecrets.length} arquivo(s) .env* com mais de ${secretMaxAgeDays} dias (${report.overdueSecrets.slice(0, SAMPLE).join(', ')})`
+      : `${report.overdueSecrets.length} .env* com mais de ${secretMaxAgeDays} dias`);
+  }
+  return parts;
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/**
+ * The default `doctor`'s line about `.git/morph-spec/`: its size and the
+ * backups in it, in the check shape the doctor renders. The size rides in the
+ * NAME because an `ok` line prints only its name. `ok` or `warn`, never a
+ * failure; `null` — no line — when nothing was ever stored there.
+ *
+ * @param {string} root - the primary root
+ * @param {{ now?: number }} [opts]
+ * @returns {{ name: string, status: 'ok'|'warn', msg?: string }|null}
+ */
+export function morphStoreCheck(root, { now = Date.now() } = {}) {
+  let store;
+  let report;
+  try {
+    store = measureDir(morphSpecStoreDir(root));
+    if (!store) return null;
+    report = inspectFinishBackups(root, { now, includeLegacy: true });
+  } catch {
+    return null;
+  }
+  const name = `.git/morph-spec (${formatSize(store.bytes)} · ${report.sets} backup(s) do finish)`;
+  if (report.policy.skipped) return { name, status: 'warn', msg: `retenção pulada: ${report.policy.skipped}` };
+  const pending = pendingParts(report);
+  if (!report.policy.enabled || !pending.length) return { name, status: 'ok' };
+  return { name, status: 'warn', msg: `${pending.join(', ')} — rode morph-spec doctor --worktrees --prune` };
+}
+
+/**
+ * The retention as an audit finding, in the shape `auditWorktrees` returns:
+ * what the explicit `--prune` would do, including the legacy backups only it
+ * prunes. `warn`, never a failure — backups waiting for a prune are
+ * housekeeping. A policy that could not be read is a finding too: until it is
+ * fixed, nothing is ever pruned.
+ *
+ * @param {string} root
+ * @param {{ now?: number }} [opts]
+ * @returns {Array<{ type: string, severity: string, detail: string, fix: string }>}
+ */
+export function auditFinishBackups(root, opts = {}) {
+  let report;
+  try {
+    report = inspectFinishBackups(root, { ...opts, includeLegacy: true });
+  } catch {
+    return [];
+  }
+  const detailOf = (text) => `${finishBackupDir(root).replace(/\\/g, '/')}: ${text}`;
+  if (report.policy.skipped) {
+    if (!report.folders) return [];
+    return [{
+      type: 'finish-backup-retention',
+      severity: 'warn',
+      detail: detailOf(`retenção pulada — ${report.policy.skipped}`),
+      fix: 'corrija `finishBackup.retention` no config.json (false desliga; { maxCount, maxAgeDays, secretMaxAgeDays } ajusta)',
+    }];
+  }
+  const parts = report.policy.enabled ? pendingParts(report, { long: true }) : [];
+  if (!parts.length) return [];
+  return [{
+    type: 'finish-backup-retention',
+    severity: 'warn',
+    detail: detailOf(parts.join('; ')),
+    fix: 'rode `morph-spec doctor --worktrees --prune` — a única via que poda os backups sem manifesto; os com manifesto o próximo `finish` já poda',
+  }];
+}
+
+/**
+ * A payload-sized account of one retention run: complete counts, a short
+ * sample of names; `{ skipped }` when the policy could not be read. `null` when
+ * the run changed nothing and nothing waits for the explicit prune.
+ *
+ * @param {ReturnType<typeof applyBackupRetention>} result
+ * @returns {object|null}
+ */
+export function summarizeRetention(result) {
+  if (!result) return null;
+  if (result.skipped) return { skipped: result.skipped };
+  const files = result.secretsStripped.reduce((n, s) => n + s.files.length, 0);
+  const out = {
+    ...(result.removed.length ? { removed: result.removed.length, removedSample: result.removed.slice(0, SAMPLE) } : {}),
+    ...(files ? { secretsStripped: files } : {}),
+    ...(result.declined.length ? { declined: result.declined.slice(0, SAMPLE) } : {}),
+    ...(result.adopted?.length ? { adopted: result.adopted.length } : {}),
+    ...(result.legacyPending
+      ? { legacyPending: result.legacyPending, legacyHint: 'backups sem manifesto (anteriores à retenção) só são podados por `morph-spec doctor --worktrees --prune`' }
+      : {}),
+  };
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * The retention step every writer of backups runs after its own backup:
+ * apply + summarize, fail-open. `protectStamps` is the stamp that backup was
+ * written under — never pruned by this run.
+ *
+ * @param {string} root
+ * @param {{ protectStamps?: string[] }} [opts]
+ * @returns {object|null}
+ */
+export function enforceBackupRetention(root, { protectStamps = [] } = {}) {
+  try {
+    return summarizeRetention(applyBackupRetention(root, { protectStamps }));
+  } catch {
+    return null;
+  }
+}