@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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

@@ -1,52 +1,6 @@
-/**
- * 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.
- */
-
+// Folders with the SAME stamp are one backup; `task/` has its own count budget.
+// A backup without manifest predates retention: only the explicit `--prune` touches it.
+// Deletion is prove-or-decline: a backup holding a reparse point is never removed.
 import {
   cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync,
   rmdirSync, rmSync, unlinkSync,
@@ -62,41 +16,30 @@ export const FINISH_BACKUP_RETENTION_DEFAULTS = Object.freeze({
   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;
@@ -122,16 +65,8 @@ const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArr
 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 }}
- */
+// A value this cannot recognise SKIPS the prune instead of falling back to the
+// defaults: the operation deletes, and `"false"` or `maxCount: 0` may mean "keep all".
 export function resolveBackupRetention(config) {
   const d = FINISH_BACKUP_RETENTION_DEFAULTS;
   const skip = skippedPolicy;
@@ -156,13 +91,8 @@ export function resolveBackupRetention(config) {
   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
- */
+// Unlike `readMorphConfig`, an unparseable config.json is not "no config": the
+// defaults would turn on a prune its author may have switched off.
 export function readBackupRetention(root) {
   const path = join(root, CONFIG_FILE_NAME);
   if (!existsSync(path)) return resolveBackupRetention(null);
@@ -196,13 +126,6 @@ function isStrictlyInside(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 = [''];
@@ -224,13 +147,7 @@ export function secretFilesIn(dir) {
   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}
- */
+/** By lstat: a link counts as itself. `null` when the walk could not start. */
 export function measureDir(dir) {
   if (!isRealDir(dir)) return null;
   let bytes = 0;
@@ -247,7 +164,7 @@ export function measureDir(dir) {
     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 */ }
+      try { bytes += lstatSync(p).size; files += 1; } catch {}
     }
   }
   return { bytes, files };
@@ -265,30 +182,16 @@ function readManifest(backupPath) {
   }
 }
 
-/**
- * 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.
- */
+// Fail-open: a backup whose manifest failed reads as legacy, the safe side.
 function writeManifest(backupPath, manifest) {
   try {
     atomicWriteJson(manifestPathFor(backupPath), { version: 1, ...manifest });
-  } catch { /* fail-open */ }
+  } catch {}
 }
 
-/**
- * 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
- */
+// Caches are excluded at every depth: git reports an ignored dir as ONE entry,
+// so `apps/x/` would drag its `node_modules/` along.
+/** `null` if ANY copy failed — the caller must then decline the removal. */
 export function writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels, stamp = newBackupStamp() }) {
   const dest = join(finishBackupDir(root), `${feature}-${stamp}${WORKTREE_IGNORED_SUFFIX}`);
   const copied = [];
@@ -297,7 +200,7 @@ export function writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels,
   try {
     for (const rel of rels) {
       const src = join(worktreePath, rel);
-      if (!existsSync(src)) continue; // a directory entry already covered by its children
+      if (!existsSync(src)) continue;
       if (isDisposableBuildArtifact(relOf(src))) {
         excludedCaches.push(relOf(src));
         continue;
@@ -332,17 +235,8 @@ export function writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels,
   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
- */
+// Under `.git/` so it never dirties the `git status` the next validation reads.
+/** `null` if the copy failed: the caller must not shed. */
 export function writeFeatureScopeBackup({ root, feature, stamp = newBackupStamp() }) {
   const src = join(root, '.morph', 'features', feature);
   if (!existsSync(src)) return null;
@@ -351,7 +245,7 @@ export function writeFeatureScopeBackup({ root, feature, stamp = newBackupStamp(
     mkdirSync(dirname(dest), { recursive: true });
     cpSync(src, dest, { recursive: true });
   } catch {
-    return null; // caller MUST treat this as "do not shed"
+    return null;
   }
   writeManifest(dest, {
     kind: 'feature-scope',
@@ -363,26 +257,10 @@ export function writeFeatureScopeBackup({ root, feature, stamp = newBackupStamp(
   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.
- */
+// Any other first-level directory that is not a backup is not ours: never removed.
 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 }>}
- */
+/** `managed` = has its manifest; without one the backup predates retention. */
 export function listFinishBackups(root) {
   const base = finishBackupDir(root);
   if (!isRealDir(base)) return [];
@@ -396,7 +274,7 @@ export function listFinishBackups(root) {
     }
     for (const e of entries) {
       const path = join(dir, e.name);
-      if (!isRealDir(path)) continue; // manifests, temp files and links
+      if (!isRealDir(path)) continue;
       const parsed = parseBackupName(e.name);
       if (parsed) {
         const prefix = namespace ? `${namespace}/` : '';
@@ -420,30 +298,8 @@ export function listFinishBackups(root) {
   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 }`
- */
+// Sets stamped after `now` (clock ran ahead) stay and take no place in the count,
+// or a handful of them would evict every new backup the moment it is written.
 export function planBackupRetention(backups, retention, now, { protectStamps = [], includeLegacy = false } = {}) {
   const sets = new Map();
   for (const b of backups) {
@@ -486,27 +342,8 @@ export function planBackupRetention(backups, retention, now, { protectStamps = [
   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[] }}
- */
+// A backup whose removal is declined still loses its `.env*`. Never throws:
+// a failed retention must never be the reason a `finish` fails.
 export function applyBackupRetention(root, { now = Date.now(), retention, protectStamps = [], includeLegacy = false } = {}) {
   const result = { enabled: true, removed: [], secretsStripped: [], declined: [], legacyPending: 0, adopted: [] };
   try {
@@ -539,7 +376,7 @@ export function applyBackupRetention(root, { now = Date.now(), retention, protec
           toStrip.push(m);
           continue;
         }
-        try { rmSync(manifestPathFor(m.path), { force: true }); } catch { /* the sidecar is bookkeeping */ }
+        try { rmSync(manifestPathFor(m.path), { force: true }); } catch {}
         result.removed.push(m.name);
       }
     }
@@ -550,7 +387,7 @@ export function applyBackupRetention(root, { now = Date.now(), retention, protec
         try {
           unlinkSync(join(m.path, rel));
           stripped.push(rel);
-        } catch { /* locked — the next run tries again */ }
+        } catch {}
       }
       if (!stripped.length) continue;
       const manifest = readManifest(m.path) ?? { kind: m.kind, feature: m.feature, createdAt: new Date(m.createdAt).toISOString() };
@@ -567,27 +404,16 @@ export function applyBackupRetention(root, { now = Date.now(), retention, protec
       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 */ }
+        try { rmdirSync(p); } catch {}
       }
     }
-  } catch { /* fail-open */ }
+  } catch {}
   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);
@@ -603,7 +429,6 @@ export function inspectFinishBackups(root, { now = Date.now(), retention, includ
   };
 }
 
-/** 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 = [];
@@ -632,16 +457,7 @@ function formatSize(bytes) {
   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}
- */
+// The size rides in the NAME because the doctor prints only the name of an `ok` line.
 export function morphStoreCheck(root, { now = Date.now() } = {}) {
   let store;
   let report;
@@ -659,17 +475,6 @@ export function morphStoreCheck(root, { now = Date.now() } = {}) {
   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 {
@@ -697,14 +502,7 @@ export function auditFinishBackups(root, opts = {}) {
   }];
 }
 
-/**
- * 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}
- */
+/** `null` when the run changed nothing and nothing waits for the explicit prune. */
 export function summarizeRetention(result) {
   if (!result) return null;
   if (result.skipped) return { skipped: result.skipped };
@@ -721,15 +519,7 @@ export function summarizeRetention(result) {
   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}
- */
+/** `protectStamps`: the stamp the caller just wrote its backup under, never pruned by this run. */
 export function enforceBackupRetention(root, { protectStamps = [] } = {}) {
   try {
     return summarizeRetention(applyBackupRetention(root, { protectStamps }));

package/src/lib/worktree/fleet-scanner.js

@@ -1,17 +1,4 @@
-/**
- * fleet-scanner.js — aggregate view of every active feature across the fleet.
- *
- * A fleet is N Claude Code instances, one per feature worktree, plus whatever
- * is active in the primary root. Each instance only sees its own cwd; the
- * operator loses track of "what is each session doing, what is waiting on me".
- * This scanner answers that from the primary root's vantage point: one entry
- * per active feature, worktree or root-resident, with the operational facts
- * (phase, pending gates, slice counts, port block, handoff freshness, last
- * commit, dirtiness) resolved per entry.
- *
- * Read-only and fail-open per FIELD: a corrupt feature.json or a git hiccup
- * nulls that field, never the scan.
- */
+// Fail-open per FIELD: a corrupt feature.json or a git hiccup nulls that field, never the scan.
 
 import { execSync, execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync } from 'fs';
@@ -35,15 +22,7 @@ import { sliceProgress, sliceProgressFrom } from '../../../framework/hooks/share
 
 const counts = (progress) => (progress ? { done: progress.done, total: progress.total } : null);
 
-/**
- * Slice progress for one feature, read from the copy that holds the work: a
- * root-resident feature's plan checks and reports are committed on its own
- * `morph/{f}` branch, while the root working tree only holds the checked-out
- * branch's (pre-work) copy.
- *
- * @param {string} featureDir - the feature dir inside `path`
- * @param {{ root: string, feature: string, featureBranch: string|null }} ctx
- */
+// A root-resident feature's reports live on `morph/{f}`; the root tree only has the pre-work copy.
 function sliceCounts(featureDir, { root, feature, featureBranch } = {}) {
   if (featureBranch && root && feature) {
     const show = (rel) => {
@@ -88,20 +67,7 @@ function dirtyCount(worktreePath) {
   }
 }
 
-/**
- * One `git ls-remote --heads origin` for the WHOLE scan → Map<branch, sha>.
- *
- * The fleet used to read only local state, so a feature whose branch (and PR)
- * already lived on origin still showed up as "pending, nothing pushed" — that
- * reading is what made a second session redo finished work. Resolved once per
- * scan, never per entry.
- *
- * Returns `null` when there is no origin, or the probe fails/times out: the
- * entries then carry `remote: null` ("unknown"), never a false `pushed: false`.
- *
- * @param {string} root
- * @returns {Map<string,string>|null}
- */
+// null = unknown (no origin, or the probe failed): entries get `remote: null`, never a false `pushed: false`.
 function remoteHeads(root) {
   if (!hasOriginRemote(root)) return null;
   try {
@@ -119,28 +85,11 @@ function remoteHeads(root) {
   }
 }
 
-/**
- * One `gh pr list` for the whole scan → Map<headRefName, {number, state}>.
- *
- * Delegates to the shared `buildPrIndex` so `fleet`, `branch prune` and
- * `doctor --worktrees` cannot answer "does this branch have a PR" differently
- * — the destructive two read it to decide what NOT to delete.
- *
- * Fail-open: `null` (no `gh`, not authenticated, not GitHub, timeout) just
- * leaves the PR half of the column empty while `pushed` still works.
- *
- * @param {string} root
- * @returns {Map<string,{number:number,state:string}>|null}
- */
 function remotePrs(root) {
   return buildPrIndex(root, { limit: 100 });
 }
 
-/**
- * The remote fact for one feature. Worktree entries know their real branch
- * (which may carry a `--fresh` date suffix); root-resident features fall back
- * to the canonical `morph/{feature}` every feature is born on.
- */
+// A worktree's real branch may carry a `--fresh` date suffix; only root entries fall back to `morph/{f}`.
 function buildRemote(feature, branch, heads, prs) {
   if (!heads) return null;
   const remoteBranch = branch || `morph/${feature}`;
@@ -154,15 +103,9 @@ function buildEntry(feature, { location, path, branch, root, allocations, blockS
   let phase = 'plan';
   let pendingGates = [];
 
-  // Resolved once and shared with sliceCounts — see branchToReadFrom.
   const featureBranch = branchToReadFrom(root, feature, location, branch);
 
   try {
-    // B3b: phase and gates suffered the same branch-staleness B3 fixed for
-    // progress. They read `.morph/features/{f}/` through the working tree, so a
-    // root parked on the default reported the PRE-WORK phase for a feature
-    // whose branch was already at implement — and re-asked for a gate the
-    // feature branch had already approved.
     const view = featureBranch ? branchView(root, feature, featureBranch) : null;
     if (view) {
       workType = view.fj?.workType || null;
@@ -176,7 +119,7 @@ function buildEntry(feature, { location, path, branch, root, allocations, blockS
       phase = derivePhaseForFeature(feature, path);
       pendingGates = getPendingGates(feature, path);
     }
-  } catch { /* field-level fail-open */ }
+  } catch { /* fail-open */ }
 
   const featureDir = join(path, '.morph', 'features', feature);
   const alloc = allocations[feature];
@@ -197,20 +140,11 @@ function buildEntry(feature, { location, path, branch, root, allocations, blockS
     lastCommit: location === 'worktree' && branch ? lastCommitRelative(root, branch) : null,
     dirty: location === 'worktree' ? dirtyCount(path) : null,
     remote: buildRemote(feature, branch, heads, prs),
-    // Advisory ownership (B1): which session is on this feature right now.
-    // `live` is what matters for the operator — a stale claim is reported as
-    // stale rather than hidden, so "nobody is here" and "somebody died here"
-    // stay distinguishable.
+    // A stale claim is reported, not hidden: "nobody is here" ≠ "somebody died here".
     claim: claims?.[feature] || null,
   };
 }
 
-/**
- * Scan the fleet from anywhere inside the repo.
- *
- * @param {string} [cwd]
- * @returns {{ root: string, entries: object[] }}
- */
 export function scanFleet(cwd = process.cwd()) {
   if (!isGitRepo(cwd)) {
     return { root: resolve(cwd).replace(/\\/g, '/'), entries: [] };
@@ -226,13 +160,12 @@ export function scanFleet(cwd = process.cwd()) {
       try {
         const reg = JSON.parse(readFileSync(registryPath(gitCommonDir), 'utf8'));
         if (reg && typeof reg.allocations === 'object' && reg.allocations !== null) allocations = reg.allocations;
-      } catch { /* no env registry yet — env stays null per entry */ }
+      } catch { /* env stays null per entry */ }
       for (const c of listClaims(gitCommonDir)) claims[c.feature] = c;
     }
-  } catch { /* no common dir — env and claim both stay null per entry */ }
+  } catch { /* env and claim stay null per entry */ }
   const { blockSize } = resolveFleetConfig(root);
 
-  // Remote awareness, resolved ONCE for the whole scan (see remoteHeads/remotePrs).
   const heads = remoteHeads(root);
   const prs = heads ? remotePrs(root) : null;
 
@@ -241,7 +174,7 @@ export function scanFleet(cwd = process.cwd()) {
 
   for (const e of parseWorktreeList(root)) {
     const m = e.branch && e.branch.match(/^refs\/heads\/morph\/(.+)$/);
-    if (!m) continue; // primary root entry and non-morph worktrees
+    if (!m) continue;
     inWorktree.add(m[1]);
     entries.push(buildEntry(m[1], {
       location: 'worktree',
@@ -256,7 +189,6 @@ export function scanFleet(cwd = process.cwd()) {
     }));
   }
 
-  // Root-resident features (no live worktree): whatever has a feature.json.
   try {
     const featuresDir = join(root, '.morph', 'features');
     if (existsSync(featuresDir)) {
@@ -272,23 +204,9 @@ export function scanFleet(cwd = process.cwd()) {
     }
   } catch { /* fail-open */ }
 
-  // Features that exist ONLY as an open PR: no registered worktree, no
-  // `.morph/features/*` folder in this tree. This is exactly what
-  // `finish --pr` leaves behind — and without this pass `fleet` would say
-  // "nothing in flight" about work that is under review on GitHub.
-  //
-  // `prs` was attempted above whenever `heads` is truthy (`remotePrs` runs —
-  // see `const prs = heads ? remotePrs(root) : null;` — regardless of
-  // whether that `gh` call itself succeeded). Gate on the SAME condition
-  // `remotePrs` used, not on `prs !== null`: `remotePrs`/`buildPrIndex` can
-  // fail (timeout, not authenticated, malformed JSON) and legitimately
-  // return `null` even after really invoking `gh`. Passing that `null`
-  // through lets `pendingPrFeatures` short-circuit on its own documented
-  // contract (explicit `null` index = known unknown, never a fallback build)
-  // instead of retrying `gh` a second time in the same scan. Only when
-  // `remotePrs` was never attempted at all (`heads` falsy) does
-  // `pendingPrFeatures` get no index, so it makes the first (and only) `gh`
-  // call itself.
+  // Features that exist only as an open PR (what `finish --pr` leaves). Gate on `heads`, not
+  // `prs !== null`: a `gh` that already ran and failed passes an explicit `null` index, so
+  // `pendingPrFeatures` does not call `gh` a second time.
   try {
     const seen = new Set(entries.map((e) => e.feature));
     const pendOpts = heads ? { index: prs } : {};
@@ -312,7 +230,7 @@ export function scanFleet(cwd = process.cwd()) {
         claim: null,
       });
     }
-  } catch { /* fail-open — a pendency not listed must never take down the scan */ }
+  } catch { /* fail-open */ }
 
   return { root, entries };
 }