@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/util.js

@@ -0,0 +1,36 @@
+/** Small helpers every module of the package shares. */
+import { statSync } from 'node:fs';
+import { failureOf } from '@osdlc/cli-tool';
+import { CommandFailed } from '@osdlc/typed-git';
+/** True when `path` is a directory; false for anything else, or when it cannot be read. */
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * An error as one line for a person: a failed git call's own output, or the
+ * message. Takes a thrown error or a `try` door's failure, which is a
+ * `Failure` rather than an `Error`; a failure's classified message reads
+ * better than the raw output it was classified from. The text goes into
+ * notes and report lines, so line breaks are folded into spaces.
+ */
+export function errorText(err) {
+    return oneLine(rawErrorText(err));
+}
+function rawErrorText(err) {
+    if (err instanceof CommandFailed)
+        return err.detail.trim() || err.message;
+    if (err instanceof Error)
+        return err.message;
+    const failure = failureOf(err);
+    if (failure !== null)
+        return failure.message || failure.detail?.trim() || '';
+    return String(err);
+}
+const oneLine = (text) => text.replace(/\s*\n\s*/g, ' ').trim();
+/** `1 commit`, `3 commits`. */
+export const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, from its package.json when it was built. */
-export declare const VERSION = "0.17.2";
+export declare const VERSION = "0.19.0";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 // Generated by cli-tool-stamp-version from package.json. Do not edit.
 /** This package's version, from its package.json when it was built. */
-export const VERSION = '0.17.2';
+export const VERSION = '0.19.0';

package/dist/worktrees.d.ts

@@ -7,7 +7,7 @@
  */
 import type { Git } from '@osdlc/typed-git';
 import { type ProcessProbe } from './processes.ts';
-import { type PRInfo, type RepoInfo, type SweepItem } from './types.ts';
+import { type PRInfo, type RepoInfo, type WorktreeEvidence, type WorktreeRow } from './types.ts';
 /** The command line, not run, that removes the worktree at `path`. */
 export declare function worktreeRemoveCommand(root: string, path: string, opts?: {
     force?: boolean;
@@ -16,45 +16,29 @@ export declare function worktreeRemoveCommand(root: string, path: string, opts?:
 export declare function worktreeUnlockCommand(root: string, path: string): string;
 /** The command line, not run, that drops registrations of worktrees whose directories are gone. */
 export declare function worktreePruneCommand(root: string): string;
-/** A condition that rules out removing a worktree, whatever its branch says. */
-export type WorktreeBlocker = 'locked-worktree' | 'live-process' | 'process-probe-failed' | 'hidden-index-flags' | 'nested-repository' | 'branch-in-other-worktree';
-/** True for a worktree row held back by `facts.blockers`. */
-export declare function hasBlockers(item: Pick<SweepItem, 'facts'>): boolean;
+/**
+ * Whether removing this worktree takes `git worktree remove --force`: its
+ * submodules make plain remove refuse, it has modified or untracked files
+ * (which only `discard-changes` lets go), or its branch is gone. The force
+ * skips git's own cleanliness check, so a run checks again itself first.
+ */
+export declare function removeIsForced(e: WorktreeEvidence): boolean;
+/**
+ * The commands that carry out `action` on the worktree whose evidence is `e`:
+ * an unlock first for a stale lock. A prune of a worktree whose directory is
+ * gone removes that worktree's record alone (`git worktree remove` takes a
+ * missing directory); one whose directory is left without its `.git` needs
+ * the repository-wide `git worktree prune`, which `git worktree remove`
+ * refuses to stand in for.
+ */
+export declare function worktreeCommands(root: string, e: WorktreeEvidence, action: 'remove' | 'prune'): string[];
 /**
  * Every worktree of `repo`, and the set of branches they hold.
  *
  * The branch set is returned because a local branch checked out in a worktree
  * must not be judged on its own: the worktree is what a person would act on.
  */
-export declare function gatherWorktrees(repo: RepoInfo, prs: Map<string, PRInfo>, cwd: string, git: Git, only: string | undefined, probe: ProcessProbe, tick?: (done: number, total: number) => void): [SweepItem[], Set<string>];
-export declare function classifyWorktree(opts: {
-    path: string;
-    branch: string;
-    /** The worktree's HEAD commit; null when git reported none. */
-    head: string | null;
-    isBare: boolean;
-    isDetached: boolean;
-    isPrimary: boolean;
-    locked: boolean;
-    lockReason: string | null;
-    /** Other worktrees with the same branch checked out. */
-    otherWorktrees: string[];
-    repo: RepoInfo;
-    prs: Map<string, PRInfo>;
-    cwd: string;
-    git: Git;
-    /** Answers lock-owner and working-directory questions. One per sweep: it caches the process table. */
-    probe: ProcessProbe;
-}): SweepItem;
-/** How a branch shows it was worked on, for a worktree merged by ancestry alone. */
-export type BranchUse = 'commits' | 'upstream';
-/**
- * The sign that `branch` was worked on, or null for a branch that looks
- * freshly made. `commits`: its reflog records work (see {@link isWorkEntry}). `upstream`: it tracks a branch on a remote, and not
- * the default branch (`mainBranch`) of any remote, so someone pushed it as
- * its own branch. A branch with neither, such as one `git worktree add -b`
- * just made from the default branch, with or without `--track`, reads as
- * null: removing its worktree could lose ignored files from work about to
- * start.
- */
-export declare function branchUse(git: Git, branch: string, mainBranch: string): BranchUse | null;
+export declare function gatherWorktrees(repo: RepoInfo, prs: Map<string, PRInfo>, cwd: string, git: Git, only: {
+    branch?: string | undefined;
+    path?: string | undefined;
+}, probe: ProcessProbe, tick?: (done: number, total: number) => void): [WorktreeRow[], Set<string>];

package/dist/worktrees.js

@@ -5,14 +5,16 @@
  * than a branch. Anything uncommitted or unpushed stops the verdict cold —
  * losing an hour of someone's work costs more than any amount of clutter.
  */
-import { existsSync, statSync } from 'node:fs';
-import { isAbsolute, join, sep } from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
 import { shellJoin } from '@osdlc/command-seam';
 import { nodeGuard } from '@osdlc/path-guard/node';
 import { gapSentence, mergedFact, recordPr } from "./branches.js";
 import { confirmationNote, judgeLanding, landingConfirmed, recordLanding, unmatchedSentence, } from "./landing.js";
 import { busyHolders, isIdleHolder, parseLockOwner } from "./processes.js";
-import { authorizationsFor, landedRef, makeItem, } from "./types.js";
+import { inspectSubmodules, readIndexHazards, submoduleFacts, unpushedPhrase, unreadablePhrase, worktreeGitDirs, } from "./submodules.js";
+import { landedRef, makeRow, risksFor, } from "./types.js";
+import { isDir } from "./util.js";
 /** The command line, not run, that removes the worktree at `path`. */
 export function worktreeRemoveCommand(root, path, opts = {}) {
     return shellJoin([
@@ -33,36 +35,57 @@ export function worktreeUnlockCommand(root, path) {
 export function worktreePruneCommand(root) {
     return shellJoin(['git', '-C', root, 'worktree', 'prune']);
 }
-function isDir(path) {
-    try {
-        return statSync(path).isDirectory();
-    }
-    catch {
-        return false;
-    }
+/**
+ * Whether removing this worktree takes `git worktree remove --force`: its
+ * submodules make plain remove refuse, it has modified or untracked files
+ * (which only `discard-changes` lets go), or its branch is gone. The force
+ * skips git's own cleanliness check, so a run checks again itself first.
+ */
+export function removeIsForced(e) {
+    return (e.forcedForSubmodules === true ||
+        (e.dirtyFiles ?? 0) > 0 ||
+        (e.submoduleDirtyFiles ?? 0) > 0 ||
+        (e.branch !== null && e.branchExists === false));
 }
-/** True for a worktree row held back by `facts.blockers`. */
-export function hasBlockers(item) {
-    const blockers = item.facts['blockers'];
-    return Array.isArray(blockers) && blockers.length > 0;
+/**
+ * The commands that carry out `action` on the worktree whose evidence is `e`:
+ * an unlock first for a stale lock. A prune of a worktree whose directory is
+ * gone removes that worktree's record alone (`git worktree remove` takes a
+ * missing directory); one whose directory is left without its `.git` needs
+ * the repository-wide `git worktree prune`, which `git worktree remove`
+ * refuses to stand in for.
+ */
+export function worktreeCommands(root, e, action) {
+    // `git worktree remove` and `prune` both skip a locked worktree, so a stale
+    // lock is cleared first.
+    const unlock = e.staleLock === true ? [worktreeUnlockCommand(root, e.path)] : [];
+    return [
+        ...unlock,
+        action === 'remove'
+            ? worktreeRemoveCommand(root, e.path, { force: removeIsForced(e) })
+            : e.directoryLeft === true
+                ? worktreePruneCommand(root)
+                : worktreeRemoveCommand(root, e.path),
+    ];
 }
-/** Cap on `facts.hidden_index_paths`; `facts.hidden_index_flags` is the full count. */
+/** Cap on `evidence.hiddenIndexPaths`; `evidence.hiddenIndexFlags` is the full count. */
 const HIDDEN_PATHS_SHOWN = 10;
 /**
  * The blockers on one worktree, each with the sentence telling a person what
- * to do about it. Writes the evidence for each into `facts`.
+ * to do about it. Writes the evidence for each into `evidence`.
  */
 function readBlockers(opts) {
-    const { path, branch, onDisk, locked, lockReason, otherWorktrees, facts, git, probe } = opts;
+    const { path, branch, onDisk, locked, lockReason, otherWorktrees, evidence, git, probe } = opts;
+    const { submodules } = opts;
     const out = [];
     if (locked) {
-        facts['lock_reason'] = lockReason;
+        evidence.lockReason = lockReason;
         // A lock whose owner is dead holds nothing. A lock that names no owner, or
         // one that cannot be ruled out, stays a blocker.
         const owner = parseLockOwner(lockReason);
         if (owner !== null && !probe.alive(owner.pid, owner.startedAt)) {
-            facts['stale_lock'] = true;
-            facts['lock_owner'] = { pid: owner.pid, started_at: owner.startedAt ?? null };
+            evidence.staleLock = true;
+            evidence.lockOwner = { pid: owner.pid, startedAt: owner.startedAt ?? null };
         }
         else {
             out.push([
@@ -80,9 +103,9 @@ function readBlockers(opts) {
             const shells = live.filter(isIdleHolder);
             const busy = busyHolders(live);
             if (shells.length > 0)
-                facts['idle_shells'] = shells;
+                evidence.idleShells = shells;
             if (busy.length > 0) {
-                facts['live_processes'] = busy;
+                evidence.liveProcesses = busy;
                 out.push([
                     'live-process',
                     `Running in the worktree: ${busy.map((h) => `${h.command} (pid ${h.pid})`).join(', ')}; stop them or wait for them to finish.`,
@@ -93,41 +116,43 @@ function readBlockers(opts) {
             // No process table to read (a host without `lsof`, a timeout): nobody
             // can say the directory is idle, so the worktree is held back.
             const message = err instanceof Error ? err.message : String(err);
-            facts['process_probe_error'] = message;
+            evidence.processProbeError = message;
             out.push([
                 'process-probe-failed',
                 `Could not tell whether a process is running in the worktree (${message}); check by hand, or fix the probe and sweep again.`,
             ]);
         }
-        const at = git.at(path);
-        // Status hides edits to these files, so "clean" cannot be trusted.
-        const hidden = at
-            .lsFilesTagged()
-            .filter((row) => row.tag === 'S' || row.tag !== row.tag.toUpperCase())
-            .map((row) => row.path);
+        // Status hides edits to flagged files, so "clean" cannot be trusted, and a
+        // nested repository has its own history. A submodule's count too: `--force`
+        // removes its files with the rest.
+        const own = readIndexHazards(git.at(path), path);
+        const inSubmodules = (pick) => submodules.submodules.flatMap((s) => pick(s).map((p) => `${s.path}/${p}`));
+        const hidden = [...own.hiddenIndexPaths, ...inSubmodules((s) => s.hiddenIndexPaths)];
         if (hidden.length > 0) {
-            facts['hidden_index_flags'] = hidden.length;
-            facts['hidden_index_paths'] = hidden.slice(0, HIDDEN_PATHS_SHOWN);
+            evidence.hiddenIndexFlags = hidden.length;
+            evidence.hiddenIndexPaths = hidden.slice(0, HIDDEN_PATHS_SHOWN);
             out.push([
                 'hidden-index-flags',
                 `${hidden.length} file(s) are marked skip-worktree or assume-unchanged, so status may hide edits; clear the flags with \`git update-index --no-skip-worktree --no-assume-unchanged <path>\` and check again.`,
             ]);
         }
-        // No `excludeStandard`: an ignored directory can hold a repository too.
-        // Only the top of each listed directory is checked.
-        const nested = at
-            .lsFiles({ others: true, directory: true })
-            .filter((entry) => entry.endsWith('/') && existsSync(join(path, entry, '.git')));
+        const nested = [...own.nestedRepositories, ...inSubmodules((s) => s.nestedRepositories)];
         if (nested.length > 0) {
-            facts['nested_repositories'] = nested;
+            evidence.nestedRepositories = nested;
             out.push([
                 'nested-repository',
                 `Nested repositories (${nested.join(', ')}) have their own history; move them out before removing the worktree.`,
             ]);
         }
     }
+    if (submodules.unreadable.length > 0) {
+        out.push([
+            'submodule-unreadable',
+            `Could not read ${unreadablePhrase(submodules.unreadable)}; check them by hand, then sweep again.`,
+        ]);
+    }
     if (otherWorktrees.length > 0) {
-        facts['other_worktrees'] = otherWorktrees;
+        evidence.otherWorktrees = otherWorktrees;
         out.push([
             'branch-in-other-worktree',
             `Branch \`${branch}\` is also checked out at ${otherWorktrees.join(', ')}; deleting the branch along with this worktree would pull it from under the other.`,
@@ -149,7 +174,22 @@ export function gatherWorktrees(repo, prs, cwd, git, only, probe, tick) {
             pathsByBranch.set(entry.branch, [...(pathsByBranch.get(entry.branch) ?? []), entry.path]);
         }
     }
-    const entries = only === undefined ? all : all.filter((entry) => entry.branch === only);
+    // A path matches however git spelled it: as listed, resolved, or through symlinks.
+    const samePath = (listed, wanted) => listed === wanted ||
+        resolve(listed) === wanted ||
+        (existsSync(listed) && realpathSync(listed) === wanted);
+    const entries = all.filter((entry) => (only.branch === undefined || entry.branch === only.branch) &&
+        (only.path === undefined || samePath(entry.path, only.path)));
+    // Read once, and only when a worktree is gone: its git dir may still hold
+    // submodule history that the prune would delete.
+    let gitDirs;
+    const gitDirOf = (path) => {
+        if (gitDirs === undefined) {
+            const common = git.at(repo.root).soft.gitCommonDir();
+            gitDirs = common === null ? new Map() : worktreeGitDirs(common);
+        }
+        return gitDirs.get(resolve(path)) ?? null;
+    };
     const items = [];
     for (const [i, entry] of entries.entries()) {
         tick?.(i, entries.length);
@@ -169,13 +209,14 @@ export function gatherWorktrees(repo, prs, cwd, git, only, probe, tick) {
             cwd,
             git,
             probe,
+            gitDirOf,
         }));
     }
     return [items, new Set(pathsByBranch.keys())];
 }
-export function classifyWorktree(opts) {
+function classifyWorktree(opts) {
     const { path, branch, head, isBare, isDetached, isPrimary, repo, prs, cwd, git } = opts;
-    const facts = {
+    const evidence = {
         path,
         branch: branch || null,
         head,
@@ -183,16 +224,8 @@ export function classifyWorktree(opts) {
         detached: isDetached,
         primary: isPrimary,
     };
-    const keep = (reason, extra = {}) => makeItem({
-        category: 'worktree',
-        id: path,
-        classification: 'safe-to-keep',
-        action: 'keep',
-        reason,
-        facts,
-        ...extra,
-    });
-    const pinned = (reason) => keep(reason, { deletable: false });
+    const row = (r) => makeRow({ kind: 'worktree', name: path, evidence, ...r });
+    const pinned = (why) => row({ verdict: 'keep', action: null, why });
     if (isPrimary)
         return pinned('primary worktree (repo root)');
     // The caller is standing in this worktree. Proposing its removal would
@@ -208,8 +241,23 @@ export function classifyWorktree(opts) {
     // that drops its registration leaves the directory alone.
     const dirPresent = isDir(path);
     const onDisk = dirPresent && existsSync(join(path, '.git'));
-    facts['on_disk'] = onDisk;
-    facts['directory_left'] = dirPresent && !onDisk;
+    evidence.onDisk = onDisk;
+    evidence.directoryLeft = dirPresent && !onDisk;
+    // The worktree's git dir from the map read once per repository; a gone
+    // worktree has no checkout to ask, and its git dir may still hold
+    // submodule history that removing it would delete.
+    const submodules = inspectSubmodules(git, path, { gitDir: opts.gitDirOf(path) });
+    const submoduleDirty = submodules.dirty.reduce((n, s) => n + s.dirtyFiles, 0);
+    if (submodules.submodules.length > 0) {
+        evidence.submodules = submoduleFacts(submodules);
+        evidence.submoduleDirtyFiles = submoduleDirty;
+    }
+    // Plain `worktree remove` refuses a worktree with submodules whatever their
+    // state, so the remove is forced. The force also skips git's own check for
+    // modified and untracked files, which the sweep makes below and `run`
+    // makes again just before it removes.
+    if (onDisk && submodules.forceRequired)
+        evidence.forcedForSubmodules = true;
     let dirtyFiles = [];
     let unpushed = [];
     if (onDisk) {
@@ -230,89 +278,105 @@ export function classifyWorktree(opts) {
         const range = git.at(path).try.logLines({ range: `${compareAgainst}..HEAD`, format: '%h %s' });
         if (range.ok)
             unpushed = range.value;
-        facts['compare_against'] = compareAgainst;
+        evidence.compareAgainst = compareAgainst;
     }
-    facts['dirty_files'] = dirtyFiles.length;
-    facts['unpushed_commits'] = unpushed.length;
+    evidence.dirtyFiles = dirtyFiles.length;
+    evidence.unpushedCommits = unpushed.length;
     const branchExists = !!branch && git.at(repo.root).resolveRef(branch) !== null;
-    facts['branch_exists'] = branchExists;
+    evidence.branchExists = branchExists;
     const pr = branch ? prs.get(branch) : undefined;
-    const { landed, gap } = recordPr(facts, pr, head ?? '', repo);
+    const { landed, gap } = recordPr(evidence, pr, head ?? '', repo);
     if (unpushed.length > 0)
-        facts['unique_commits'] = unpushed.length;
+        evidence.uniqueCommits = unpushed.length;
     // A merged PR at HEAD lands every commit, even ones the fallback
-    // `compare_against` (a squash merge, a deleted upstream) counts as ahead.
+    // `compareAgainst` (a squash merge, a deleted upstream) counts as ahead.
     // A rebase merge, cherry-pick or squash merge leaves HEAD off the default
     // branch; the patches say whether the work is there anyway. Judged from HEAD,
     // so a dirty tree is still caught by the dirty-file check below.
     const patch = landed || !onDisk || head === null ? null : judgeLanding(repo, head, pr, gap, git);
     if (patch !== null)
-        recordLanding(facts, patch);
+        recordLanding(evidence, patch);
     const patchLanded = patch !== null && patch.check !== null;
     const unlanded = unpushed.length > 0 && !landed && !landingConfirmed(patch);
     if (onDisk && head !== null) {
         // `soft`: a missing default ref reads as not merged.
-        facts['merged'] = mergedFact({
+        evidence.merged = mergedFact({
             landed,
             patchLanded,
             ancestor: git.at(repo.root).soft.isAncestor(head, landedRef(repo)),
         });
     }
-    const requires = authorizationsFor({
-        'abandon-unmerged': unlanded,
-        'discard-changes': dirtyFiles.length > 0,
+    const dirty = dirtyFiles.length > 0 || submoduleDirty > 0;
+    // A submodule's git dir lives in the worktree's own git dir, so removing
+    // the worktree, or pruning it once its directory is gone, deletes the
+    // submodule's commits and stashes with it. The same risk as the worktree's
+    // own unpushed commits covers them.
+    const submoduleWork = submodules.unpushed.length > 0;
+    const submoduleWorkText = submoduleWork ? unpushedPhrase(submodules.unpushed) : '';
+    const risks = risksFor({
+        'abandon-unmerged': unlanded || submoduleWork,
+        'discard-changes': dirty,
         'confirm-open-pr': pr?.state === 'OPEN',
     });
-    const blockers = readBlockers({
-        ...opts,
-        onDisk,
-        facts,
-    });
-    const kinds = blockers.map(([kind]) => kind);
-    // `git worktree remove` and `prune` both skip a locked worktree, so a stale
-    // lock is cleared first.
-    const unlock = facts['stale_lock'] === true ? [worktreeUnlockCommand(repo.root, path)] : [];
-    const safeRemove = [...unlock, worktreeRemoveCommand(repo.root, path)];
-    const forceRemove = [...unlock, worktreeRemoveCommand(repo.root, path, { force: true })];
-    const pruneOnly = [...unlock, worktreePruneCommand(repo.root)];
-    facts['blockers'] = kinds;
-    if (kinds.length > 0) {
-        return makeItem({
-            category: 'worktree',
-            id: path,
-            classification: 'needs-investigation',
-            action: 'review',
-            reason: `blocked: ${kinds.join(', ')}`,
-            facts,
-            investigationParts: blockers.map(([, advice]) => advice),
-            deletable: false,
+    const blockers = readBlockers({ ...opts, onDisk, evidence, submodules });
+    const removes = worktreeCommands(repo.root, evidence, 'remove');
+    const pruneOnly = worktreeCommands(repo.root, evidence, 'prune');
+    // Said in the reason of a row whose remove is forced for its submodules.
+    const forced = evidence.forcedForSubmodules === true
+        ? '; its submodules are clean and pushed, so the remove is forced'
+        : '';
+    if (blockers.length > 0) {
+        const kinds = blockers.map(([kind]) => kind);
+        return row({
+            verdict: 'blocked',
+            action: null,
+            why: `blocked: ${kinds.join(', ')}`,
+            blockers: kinds,
+            notes: blockers.map(([, advice]) => advice),
+        });
+    }
+    if (!onDisk && submoduleWork) {
+        return row({
+            verdict: 'review',
+            action: 'prune',
+            why: `directory gone, but its git dir keeps work no remote has in ${submoduleWorkText}`,
+            commands: pruneOnly,
+            risks,
+            notes: [
+                `Worktree ${path} is gone, but its git dir keeps ${submoduleWorkText}; pruning it deletes them.`,
+                'Push the work from that git dir, or allow abandon-unmerged to prune it anyway.',
+            ],
         });
     }
     if (!onDisk) {
-        return makeItem({
-            category: 'worktree',
-            id: path,
-            classification: 'safe-to-delete',
+        return row({
+            verdict: 'delete',
             action: 'prune',
-            reason: dirPresent
-                ? 'directory is no longer a checkout (no .git); prune the stale link, the directory stays'
-                : 'worktree directory no longer on disk; prune the stale link',
-            facts,
+            why: dirPresent
+                ? 'directory is no longer a checkout (no .git); prune the stale record, the directory stays'
+                : 'worktree directory no longer on disk; prune the stale record',
             commands: pruneOnly,
         });
     }
-    if (dirtyFiles.length > 0 || unlanded) {
-        return makeItem({
-            category: 'worktree',
-            id: path,
-            classification: 'needs-investigation',
-            action: 'review',
-            reason: `${dirtyFiles.length} dirty file(s), ${unpushed.length} commit(s) ahead of ${facts['compare_against']}`,
-            facts,
-            requires,
-            investigationParts: [
+    if (dirty || unlanded || submoduleWork) {
+        const inSubmodules = submoduleDirty > 0
+            ? `, ${submoduleDirty} in submodule(s) ${submodules.dirty.map((s) => s.path).join(', ')}`
+            : '';
+        const workInSubmodules = submoduleWork ? `; unpushed work in ${submoduleWorkText}` : '';
+        return row({
+            verdict: 'review',
+            action: 'remove',
+            why: `${dirtyFiles.length} dirty file(s)${inSubmodules}, ${unpushed.length} commit(s) ahead of ${evidence.compareAgainst}${workInSubmodules}`,
+            commands: removes,
+            risks,
+            notes: [
                 `Worktree ${path} has uncommitted work or unpushed commits.`,
                 `Branch: ${branch || '(detached)'}.`,
+                ...(submoduleWork
+                    ? [
+                        `Removing it also deletes the work in ${submoduleWorkText}, whose git dirs live in the worktree's own.`,
+                    ]
+                    : []),
                 ...(patchLanded && unlanded
                     ? [
                         `Its commits are patch-equivalent to commits on ${landedRef(repo)} (${patch.check}), but ${confirmationNote(patch)}.`,
@@ -322,80 +386,49 @@ export function classifyWorktree(opts) {
             ],
         });
     }
-    if (pr && landed) {
-        return makeItem({
-            category: 'worktree',
-            id: path,
-            classification: 'safe-to-delete',
-            action: 'remove',
-            reason: `clean; PR #${pr.number} merged`,
-            facts,
-            commands: safeRemove,
-            requires,
-        });
-    }
+    const deletes = (why) => row({ verdict: 'delete', action: 'remove', why, commands: removes, risks });
+    if (pr && landed)
+        return deletes(`clean; PR #${pr.number} merged${forced}`);
     if (patchLanded) {
-        return makeItem({
-            category: 'worktree',
-            id: path,
-            classification: 'safe-to-delete',
-            action: 'remove',
-            reason: `clean; patch-equivalent to commits on ${landedRef(repo)} (${patch.check}); ${confirmationNote(patch)}`,
-            facts,
-            commands: safeRemove,
-            requires,
-        });
+        return deletes(`clean; patch-equivalent to commits on ${landedRef(repo)} (${patch.check}); ${confirmationNote(patch)}${forced}`);
     }
     if (branch && !branchExists) {
-        return makeItem({
-            category: 'worktree',
-            id: path,
-            classification: 'safe-to-delete',
+        return deletes(`branch \`${branch}\` no longer exists${forced}`);
+    }
+    if (pr && pr.state === 'OPEN') {
+        return row({
+            verdict: 'keep',
             action: 'remove',
-            reason: `branch \`${branch}\` no longer exists`,
-            facts,
-            commands: forceRemove,
-            requires,
+            why: `open PR #${pr.number}`,
+            commands: removes,
+            risks,
         });
     }
-    if (pr && pr.state === 'OPEN')
-        return keep(`open PR #${pr.number}`, { requires });
     // Merged by ancestry alone: a worktree just made from the default branch is
     // merged that way too, so ancestry needs a sign the branch was worked on.
-    if (facts['merged'] === true && branch && head !== null) {
+    if (evidence.merged === true && branch && head !== null) {
         const used = branchUse(git.at(repo.root), branch, repo.mainBranch);
-        facts['branch_used'] = used;
+        evidence.branchUsed = used;
         if (used !== null) {
-            return makeItem({
-                category: 'worktree',
-                id: path,
-                classification: 'safe-to-delete',
-                action: 'remove',
-                reason: `clean; merged into ${landedRef(repo)}, and ${USE_REASON[used]}`,
-                facts,
-                commands: safeRemove,
-                requires,
-            });
+            return deletes(`clean; merged into ${landedRef(repo)}, and ${USE_REASON[used]}${forced}`);
         }
     }
-    const parts = [`Worktree \`${path}\` is clean.`];
+    const notes = [`Worktree \`${path}\` is clean.`];
     if (branch)
-        parts.push(`Branch: \`${branch}\`.`);
-    parts.push(pr ? `PR #${pr.number} is ${pr.state}.` : 'No associated PR.');
+        notes.push(`Branch: \`${branch}\`.`);
+    notes.push(pr ? `PR #${pr.number} is ${pr.state}.` : 'No associated PR.');
     if (pr && gap)
-        parts.push(gapSentence(pr, gap, repo));
+        notes.push(gapSentence(pr, gap, repo));
     const unmatched = patch === null ? null : unmatchedSentence(patch, repo);
     if (unmatched !== null)
-        parts.push(unmatched);
-    return makeItem({
-        category: 'worktree',
-        id: path,
-        classification: 'needs-investigation',
-        action: 'review',
-        reason: 'clean but no clear disposability signal',
-        facts,
-        investigationParts: parts,
-        requires,
+        notes.push(unmatched);
+    return row({
+        verdict: 'review',
+        action: 'remove',
+        why: 'clean but no clear disposability signal',
+        commands: removes,
+        notes,
+        risks,
     });
 }
 const USE_REASON = {
@@ -422,7 +455,7 @@ function isWorkEntry(entry) {
  * null: removing its worktree could lose ignored files from work about to
  * start.
  */
-export function branchUse(git, branch, mainBranch) {
+function branchUse(git, branch, mainBranch) {
     // `raw`: a branch with no reflog (core.logAllRefUpdates off) exits non-zero.
     const reflog = git.raw(['reflog', 'show', '--format=%gs', `refs/heads/${branch}`, '--']);
     if (reflog.exitCode === 0 && reflog.stdout.split('\n').some(isWorkEntry)) {