@osdlc/repo-cleaner 0.18.0 → 0.19.0

package/dist/prs.js

@@ -6,37 +6,70 @@
  * one listing covers. Which forge answers is the provider's business; see
  * `providers/`.
  */
+import { errorText } from "./util.js";
+/**
+ * Why open pull requests cannot be ruled out for this repository, or null
+ * when the provider answered. A missing or signed-out CLI was never asked, and
+ * a failed listing answered nothing; either way a remote branch with no known
+ * PR may still have an open one. Every sentence about a lookup that did not
+ * answer is built from this one answer.
+ */
+export function prsUnchecked(status) {
+    if (!status.available)
+        return { kind: 'not-installed', why: `\`${status.tool}\` is not installed` };
+    if (!status.authenticated) {
+        return { kind: 'not-signed-in', why: `\`${status.tool}\` is not signed in` };
+    }
+    if (status.listError !== undefined) {
+        return { kind: 'list-failed', why: `\`${status.listing}\` failed` };
+    }
+    return null;
+}
 /** Open outranks merged outranks closed, and a newer PR outranks an older. */
 function priority(state) {
     return { OPEN: 3, MERGED: 2, CLOSED: 1 }[state] ?? 0;
 }
 /**
- * Every same-repository pull request, keyed by head branch. Fork PRs are
- * dropped by the provider: a fork branch that shares a name proves nothing
- * about ours.
+ * Every same-repository pull request, keyed by head branch, and why there are
+ * none when the listing failed. Fork PRs are dropped by the provider: a fork
+ * branch that shares a name proves nothing about ours.
  *
  * A branch can carry several PRs over its life. The one that decides a
  * verdict is the most live: an open PR means keep whatever else happened, and
  * a merged one means the work landed. Ties go to the higher number, so two
  * runs over unchanged state agree.
  *
- * An empty map is the honest answer when the provider's CLI is missing,
- * unauthenticated or failing, or when there is no provider. Classification
- * degrades to git evidence and the report says so.
+ * The map is empty when the provider's CLI is missing or unauthenticated, when
+ * there is no provider, and when the listing fails. A provider that answers
+ * null or throws has failed (a repository the signed-in account cannot see, a
+ * forge that is down, output that cannot be read), and `error` says why.
+ * Classification then degrades to git evidence, and the sweep notes it rather
+ * than losing every row to one listing.
  *
  * @param provider The provider to ask. It is asked only when it is the one
  *   `repo.provider` names and that probe found it signed in.
  * @param branch Ask only for PRs whose head is exactly this branch; rows
  *   for any other head are dropped here too.
  */
-export function fetchPrs(repo, provider, branch) {
+export function lookupPrs(repo, provider, branch) {
     const byHead = new Map();
     const status = repo.provider;
-    if (status === null || status.name !== provider.name || !status.authenticated)
-        return byHead;
-    const rows = provider.listPrs(repo.root, status, branch);
+    if (status === null || status.name !== provider.name || !status.authenticated) {
+        return { prs: byHead, error: null };
+    }
+    let rows;
+    try {
+        rows = provider.listPrs(repo.root, status, branch);
+    }
+    catch (err) {
+        // A bug in the provider is not a listing that failed: let it fail loudly,
+        // as an error on the repository, rather than gate every remote branch.
+        if (err instanceof TypeError || err instanceof ReferenceError)
+            throw err;
+        return { prs: byHead, error: errorText(err) };
+    }
     if (rows === null)
-        return byHead;
+        return { prs: byHead, error: 'the provider gave no reason' };
     for (const info of rows) {
         const head = info.headRef;
         if (!head)
@@ -54,5 +87,5 @@ export function fetchPrs(repo, provider, branch) {
             byHead.set(head, info);
         }
     }
-    return byHead;
+    return { prs: byHead, error: null };
 }

package/dist/receipt.d.ts

@@ -56,6 +56,7 @@ export declare const StepSchema: z.ZodObject<{
     }>;
     error: z.ZodNullable<z.ZodString>;
     verification: z.ZodNullable<z.ZodString>;
+    gone: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 export type Step = z.infer<typeof StepSchema>;
 export declare const ReceiptSchema: z.ZodObject<{
@@ -106,6 +107,7 @@ export declare const ReceiptSchema: z.ZodObject<{
         }>;
         error: z.ZodNullable<z.ZodString>;
         verification: z.ZodNullable<z.ZodString>;
+        gone: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Receipt = z.infer<typeof ReceiptSchema>;

package/dist/receipt.js

@@ -51,6 +51,12 @@ export const StepSchema = z.object({
     result: z.enum(['pending', 'would-run', 'ok', 'failed']),
     error: z.string().nullable(),
     verification: z.string().nullable(),
+    /**
+     * The remote no longer listed the branch when the step ran: someone deleted
+     * it after the run's re-check. A `delete-remote` step so marked deleted
+     * nothing, and the run summary counts it apart. Absent otherwise.
+     */
+    gone: z.literal(true).optional(),
 });
 export const ReceiptSchema = z.object({
     version: z.literal(RECEIPT_VERSION),

package/dist/reference.js

@@ -9,14 +9,17 @@ const TARGETS = `Targets
     a directory           every checkout found under it, three levels deep at most
     a remote URL          its remote branches only, through a clone kept in the cache
                           directory (https://, ssh://, file://, or user@host:path)
-  No target sweeps the checkout you are in. A target never fans out further than
-  it says.`;
+  No target sweeps the directory you are in, read the same way.`;
 const SWEEP = `Sweep options (the report, plan and clean)
   --remote                Also judge remote branches. Turns on the network: fetches
                           each remote first and asks GitHub or GitLab about pull
                           requests. Slower.
   --offline               With --remote: do not fetch; judge against the
-                          remote-tracking refs already on disk.
+                          remote-tracking refs already on disk, remote branches
+                          included, so judging does not contact the remote. Tips can
+                          be stale; clean asks the remote before deleting on it.
+                          Pull requests are still looked up; add --provider none
+                          to judge with no network at all.
   --only <kinds>          Only these kinds of row: worktree, branch, remote,
                           comma-separated. Default: worktree,branch, plus remote with
                           --remote. Naming remote implies --remote.
@@ -54,8 +57,8 @@ const CLEAN = `repo-cleaner clean [target...]
                           Repeatable.
   --spare <row>           Leave this row alone, and make sure it is what you saw. A
                           spared row is not deleted, even if it is judged delete. A
-                          spared remote branch is still checked: if it is gone or its
-                          tip moved since the plan, the run stops before deleting
+                          spared remote branch is still checked: if its tip moved or
+                          it is gone since the plan, the run stops before deleting
                           anything. Sparing a worktree also spares its branch.
                           Repeatable.
   --allow <risk>          Accept this risk for every row that carries it.
@@ -98,8 +101,9 @@ Risks (approve each by name with --allow)
                      (or its submodules') commits and stashes that no remote has.
   discard-changes    Uncommitted or untracked files in the worktree or any of its
                      submodules.
-  confirm-open-pr    The branch has an open pull request; deleting the remote branch
-                     closes it.
+  confirm-open-pr    The branch has an open pull request, or open pull requests could
+                     not be checked (the CLI is missing or signed out, or the listing
+                     failed); deleting the remote branch closes it.
   A worktree's submodules are part of it: one --allow on the worktree row covers
   the same risk in every submodule.`;
 const CONFLICTS = `Refused before anything is deleted (exit 2)
@@ -125,7 +129,7 @@ const CONFLICTS = `Refused before anything is deleted (exit 2)
 Refused after the sweep, before deleting (exit 1)
     a picked, spared or allowed row the plan does not have
     a row name that matches rows in more than one repository
-    a spared remote branch that is gone or moved since the plan
+    a spared remote branch that moved since the plan, or that the re-check no longer finds
 
 Allowed, because nothing contradicts
     the same row picked twice: it runs once

package/dist/remote-mirror.d.ts

@@ -8,7 +8,7 @@
  * fetches them over the network one comparison at a time, which made a sweep
  * of a few hundred branches take minutes instead of seconds. It is kept
  * rather than thrown away so a plan written from it can be applied later: the
- * plan names the clone's directory, and `apply` re-sweeps and pushes deletes
+ * plan names the clone's directory, and `clean` re-sweeps and pushes deletes
  * from there. A later run reuses it, and the sweep's fetch brings it up to
  * date.
  */

package/dist/remote-mirror.js

@@ -8,7 +8,7 @@
  * fetches them over the network one comparison at a time, which made a sweep
  * of a few hundred branches take minutes instead of seconds. It is kept
  * rather than thrown away so a plan written from it can be applied later: the
- * plan names the clone's directory, and `apply` re-sweeps and pushes deletes
+ * plan names the clone's directory, and `clean` re-sweeps and pushes deletes
  * from there. A later run reuses it, and the sweep's fetch brings it up to
  * date.
  */

package/dist/render.d.ts

@@ -61,8 +61,13 @@ export declare function renderJson(sweep: Sweep, extra?: Record<string, unknown>
 export declare function renderCommands(sweep: Sweep): string[];
 /** What a run did, or would do, counted by kind. */
 export interface RunSummary {
-    /** Rows deleted (or, in a preview, that would be), by kind. Pruned worktrees are counted apart. */
+    /**
+     * Rows deleted (or, in a preview, that would be), by kind. Pruned worktrees,
+     * and remote branches a delete step found already gone, are counted apart.
+     */
     deleted: Record<Kind, number>;
+    /** Remote branches a delete step found the remote had already deleted. */
+    gone: number;
     /** Worktrees whose stale record was pruned; their directories were gone or left alone. */
     pruned: number;
     /** Dropped rows by reason. */

package/dist/render.js

@@ -71,6 +71,10 @@ function repoHeader(sweep) {
     ];
     return `${name}  (${bits.filter((b) => b !== null).join(', ')})`;
 }
+/** A repository's notes on what the sweep judged without, one line each under its header. */
+function noteLines(sweep, style) {
+    return sweep.notes.map((note) => `  ${style.review('note')}: ${stripControls(note)}`);
+}
 /** The word a report shows for a row: its verdict, or `prune` for a `delete` that only prunes. */
 function verdictWord(row) {
     return isPrune(row) ? 'prune' : row.verdict;
@@ -88,7 +92,7 @@ function wordStyle(style, word) {
 /** One repository's rows, indented under its header. `all` shows `keep` rows too. */
 export function renderRepo(sweep, opts = {}) {
     const style = opts.style ?? PLAIN;
-    const lines = [style.strong(repoHeader(sweep))];
+    const lines = [style.strong(repoHeader(sweep)), ...noteLines(sweep, style)];
     if (sweep.error !== null) {
         lines.push(`  ${style.delete('error')}: ${sweep.error}`);
         return lines.join('\n');
@@ -190,7 +194,7 @@ function report(blocks, sweep, style) {
 /** The sweep as counts (`--format summary`): a table per repository, then the totals line. */
 export function renderSummary(sweep, style = PLAIN) {
     const blocks = sweep.repos.map((r) => {
-        const lines = [repoHeader(r)];
+        const lines = [repoHeader(r), ...noteLines(r, style)];
         if (r.error !== null) {
             lines.push(`  error: ${r.error}`);
             return lines.join('\n');
@@ -256,6 +260,7 @@ export function renderCommands(sweep) {
 export function summarizeRun(r) {
     const out = {
         deleted: { worktree: 0, branch: 0, remote: 0 },
+        gone: 0,
         pruned: 0,
         dropped: {},
         failed: 0,
@@ -275,6 +280,10 @@ export function summarizeRun(r) {
         }
         if (s.result !== 'ok' && s.result !== 'would-run')
             continue;
+        if (s.action === 'delete-remote' && s.gone === true) {
+            out.gone += 1;
+            continue;
+        }
         if (s.action === 'remove-worktree')
             out.deleted.worktree += 1;
         else if (s.action === 'prune-worktrees')
@@ -316,6 +325,7 @@ export function renderRunSummary(r, opts = {}) {
         s.deleted.branch > 0 ? plural(s.deleted.branch, 'local branch', 'local branches') : null,
         s.deleted.remote > 0 ? plural(s.deleted.remote, 'remote branch', 'remote branches') : null,
         s.pruned > 0 ? `${plural(s.pruned, 'stale worktree', 'stale worktrees')} pruned` : null,
+        s.gone > 0 ? `${plural(s.gone, 'remote branch', 'remote branches')} already gone` : null,
     ].filter((p) => p !== null);
     const lines = [
         `${opts.preview === true ? 'would delete' : 'deleted'}: ${parts.length > 0 ? parts.join(', ') : 'nothing'}`,

package/dist/resolve.d.ts

@@ -8,9 +8,9 @@
  * covers everything under it — including a per-owner or per-client
  * directory — without listing any of them.
  *
- * Nothing here fans out on its own. A caller that passes no entries gets no
- * repositories, and the CLI's bare invocation sweeps the checkout it is
- * standing in.
+ * A caller that passes no entries gets no repositories. The CLI's bare
+ * invocation passes the directory it stands in, which resolves like any
+ * other entry.
  */
 import { type Git } from '@osdlc/typed-git';
 import { type ScanStats, type UnresolvedEntry } from './types.ts';

package/dist/resolve.js

@@ -8,9 +8,9 @@
  * covers everything under it — including a per-owner or per-client
  * directory — without listing any of them.
  *
- * Nothing here fans out on its own. A caller that passes no entries gets no
- * repositories, and the CLI's bare invocation sweeps the checkout it is
- * standing in.
+ * A caller that passes no entries gets no repositories. The CLI's bare
+ * invocation passes the directory it stands in, which resolves like any
+ * other entry.
  */
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve as resolvePath } from 'node:path';

package/dist/sweep.d.ts

@@ -67,7 +67,7 @@ export declare function sweptWith(targets: readonly string[], opts: Omit<SweepOp
 /**
  * Sweep `targets`: checkouts, directories to search for checkouts, or remote
  * URLs (swept through a clone kept in `cacheDir`, remote branches only). No
- * target sweeps the checkout at `cwd`.
+ * targets means `[cwd]`, resolved the same way.
  *
  * Never throws for a repository it cannot read: that one comes back with
  * `error` set, because a fan-out must not end on its first bad entry. Throws a
@@ -81,6 +81,13 @@ interface RepoSweepOptions extends Runners {
     against?: string | undefined;
     provider: ProviderChoice;
     fetch: boolean;
+    /**
+     * Read remote tips with `ls-remote` even without a fetch: `clean`'s
+     * re-check, which must not delete on the strength of a stale tracking ref.
+     * Without a fetch, a failed `ls-remote` then fails the repository rather
+     * than fall back to those refs.
+     */
+    liveRemoteTips?: boolean | undefined;
     branch?: string | undefined;
     /** Only the worktree at this path; for {@link inspectWorktree}. */
     worktree?: string | undefined;
@@ -97,6 +104,12 @@ interface RepoSweepOptions extends Runners {
  * {@link sweep} does for each. The engine `check` and `run` re-sweep with.
  * Never throws for a repository it cannot read; throws a `conflict` for a
  * `branch` that is the default branch.
+ *
+ * A failed fetch fails the repository. A lookup that only adds evidence does
+ * not: a remote whose branches `ls-remote` cannot list is read from the
+ * remote-tracking refs the fetch just wrote, and a provider whose listing
+ * fails leaves no pull request evidence. Each is a sentence in `notes`, and
+ * every row is judged on the evidence that is left.
  */
 export declare function sweepRepo(path: string, opts: RepoSweepOptions): RepoSweep;
 /**

package/dist/sweep.js

@@ -13,11 +13,12 @@ import { Gh } from '@osdlc/typed-gh';
 import { HELD_BY_WORKTREE, gatherLocalBranches, gatherRemoteBranches, resolveBranch, } from "./branches.js";
 import { discoverRepo } from "./discover.js";
 import { defaultProcessProbe } from "./processes.js";
-import { fetchPrs } from "./prs.js";
+import { lookupPrs, prsUnchecked } from "./prs.js";
 import { PROVIDER_CHOICES, providers } from "./providers/index.js";
 import { defaultCacheDir, ensureMirror, isRemoteUrl, redactUrl } from "./remote-mirror.js";
 import { expandTilde, resolveEntries } from "./resolve.js";
 import { KINDS, RepoCleanerError, countRows, emptyScan, findDuplicateCheckouts, } from "./types.js";
+import { errorText } from "./util.js";
 import { gatherWorktrees } from "./worktrees.js";
 const LOCAL = ['worktree', 'branch'];
 /**
@@ -105,7 +106,7 @@ export function sweptWith(targets, opts) {
 /**
  * Sweep `targets`: checkouts, directories to search for checkouts, or remote
  * URLs (swept through a clone kept in `cacheDir`, remote branches only). No
- * target sweeps the checkout at `cwd`.
+ * targets means `[cwd]`, resolved the same way.
  *
  * Never throws for a repository it cannot read: that one comes back with
  * `error` set, because a fan-out must not end on its first bad entry. Throws a
@@ -163,12 +164,43 @@ export function sweep(targets, opts = {}) {
         options,
     };
 }
+/**
+ * The repository's note about its pull request lookup, or null when the
+ * provider answered or nothing hangs on it. A failed listing is always noted;
+ * a CLI that is missing or signed out only when a remote branch could be
+ * deleted on its account, which then needs confirm-open-pr.
+ */
+function providerNote(repo, kinds, choice) {
+    const status = repo.provider;
+    const unchecked = status === null ? null : prsUnchecked(status);
+    // With no remote there is no remote branch to gate and no forge to point
+    // at; the local rows already say the lookup failed.
+    if (status === null || unchecked === null || repo.remote === null)
+        return null;
+    // A local remote names no forge, and `auto` asks GitHub for any host that
+    // is not GitLab's, so a host that is not a forge lands here too. github.com
+    // is a forge: there the cause is access, not the provider.
+    const hint = status.host === null ||
+        (choice === 'auto' && status.name === 'github' && status.host !== 'github.com')
+        ? ' Pass `--provider none` if this remote has no forge.'
+        : '';
+    if (unchecked.kind === 'list-failed') {
+        return `Listing ${status.noun}s with \`${status.listing}\` failed (${status.listError}); judged on git evidence alone.${hint}`;
+    }
+    if (!kinds.has('remote'))
+        return null;
+    const fix = unchecked.kind === 'not-installed'
+        ? `Install \`${status.tool}\``
+        : `Sign in to \`${status.tool}\``;
+    return `Could not check for open ${status.noun}s: ${unchecked.why}, so deleting a remote branch needs confirm-open-pr. ${fix}, or pass \`--allow confirm-open-pr\` once you have checked.${hint}`;
+}
 function errorSweep(path, err) {
     return {
         path,
         repo: null,
         rows: [],
         counts: countRows([]),
+        notes: [],
         error: err instanceof Error ? err.message : String(err),
     };
 }
@@ -177,6 +209,12 @@ function errorSweep(path, err) {
  * {@link sweep} does for each. The engine `check` and `run` re-sweep with.
  * Never throws for a repository it cannot read; throws a `conflict` for a
  * `branch` that is the default branch.
+ *
+ * A failed fetch fails the repository. A lookup that only adds evidence does
+ * not: a remote whose branches `ls-remote` cannot list is read from the
+ * remote-tracking refs the fetch just wrote, and a provider whose listing
+ * fails leaves no pull request evidence. Each is a sentence in `notes`, and
+ * every row is judged on the evidence that is left.
  */
 export function sweepRepo(path, opts) {
     const kinds = new Set(opts.only);
@@ -219,19 +257,33 @@ export function sweepRepo(path, opts) {
         const fetched = git
             .at(repo.root)
             .try.fetch(repo.remote, undefined, { prune: true, quiet: true, noWriteFetchHead: true });
+        // Unlike the lookups below, a failed fetch fails the repository: every
+        // row, local ones included, would be judged against a default branch
+        // older than the one asked for.
         if (!fetched.ok) {
             return {
-                ...errorSweep(path, new Error(`fetch failed: ${fetched.error.detail || fetched.error.message}`)),
+                ...errorSweep(path, new Error(`fetch failed: ${errorText(fetched.error)}`)),
                 repo,
             };
         }
         repo = { ...repo, fetched: true };
     }
+    const notes = [];
     try {
         const status = repo.provider ?? null;
         if (status?.authenticated === true)
             report('prs', undefined, undefined, status.tool);
-        const prs = status === null ? new Map() : fetchPrs(repo, known[status.name], only);
+        let prs = new Map();
+        if (status !== null) {
+            const looked = lookupPrs(repo, known[status.name], only);
+            prs = looked.prs;
+            if (looked.error !== null) {
+                repo = { ...repo, provider: { ...status, listError: looked.error } };
+            }
+            const note = providerNote(repo, kinds, opts.provider);
+            if (note !== null)
+                notes.push(note);
+        }
         const rows = [];
         // Worktrees are gathered whenever local branches are, even if they are not
         // reported: a branch checked out in one must not be judged on its own.
@@ -268,17 +320,25 @@ export function sweepRepo(path, opts) {
                 rows.push(...localRows);
         }
         if (kinds.has('remote')) {
-            rows.push(...gatherRemoteBranches(repo, prs, localBranchNames, git, only, ticker('remote')));
+            const remote = gatherRemoteBranches(repo, prs, localBranchNames, git, {
+                live: repo.fetched || opts.liveRemoteTips === true,
+                strict: opts.liveRemoteTips === true && !repo.fetched,
+                only,
+                tick: ticker('remote'),
+            });
+            rows.push(...remote.rows);
+            if (remote.note !== null)
+                notes.push(remote.note);
         }
         const annotated = opts.annotate === undefined
             ? rows
             : holdFreedBranches(opts.annotate(repo, rows).map(blockedHasNoAction), only !== undefined);
-        return { path, repo, rows: annotated, counts: countRows(annotated), error: null };
+        return { path, repo, rows: annotated, counts: countRows(annotated), notes, error: null };
     }
     catch (err) {
         if (err instanceof RepoCleanerError)
             throw err;
-        return { ...errorSweep(path, err), repo };
+        return { ...errorSweep(path, err), repo, notes };
     }
 }
 /**

package/dist/types.d.ts

@@ -55,8 +55,10 @@ export type Action = (typeof ACTIONS)[number];
  *                       (or its submodules') commits and stashes no remote has
  *   `discard-changes`   drops modified, staged or untracked files in a worktree
  *                       or any of its submodules
- *   `confirm-open-pr`   the branch has an open pull request; deleting the remote
- *                       branch closes it
+ *   `confirm-open-pr`   the branch has an open pull request, or open pull
+ *                       requests could not be checked (the CLI is missing or
+ *                       signed out, or the listing failed) so one cannot be
+ *                       ruled out; deleting the remote branch closes it
  */
 export declare const RISKS: readonly ["abandon-unmerged", "discard-changes", "confirm-open-pr"];
 export type Risk = (typeof RISKS)[number];
@@ -265,9 +267,25 @@ export interface RepoSweep {
     repo: RepoInfo | null;
     rows: Row[];
     counts: Counts;
+    /**
+     * What the sweep could not look up for this repository and judged without,
+     * one sentence each: a remote branch listing or a pull request listing that
+     * failed, a pull request lookup the provider's CLI could not make (missing
+     * or signed out), or, offline, a remote with no tracking refs on disk. The
+     * rows stand on the evidence that was left.
+     * Empty when nothing was missing.
+     */
+    notes: string[];
     /** Why this repository produced no rows. Null on success. */
     error: string | null;
 }
+/** One of a repository's `notes`, with the repository's root. */
+export interface RepoNote {
+    repo: string;
+    note: string;
+}
+/** Every repository's `notes` in `sweep`, each with its repository. */
+export declare function sweepNotes(sweep: Pick<Sweep, 'repos'>): RepoNote[];
 /** A target that named no repository. */
 export interface UnresolvedEntry {
     entry: string;

package/dist/types.js

@@ -49,8 +49,10 @@ export const ACTIONS = ['remove', 'prune', 'delete'];
  *                       (or its submodules') commits and stashes no remote has
  *   `discard-changes`   drops modified, staged or untracked files in a worktree
  *                       or any of its submodules
- *   `confirm-open-pr`   the branch has an open pull request; deleting the remote
- *                       branch closes it
+ *   `confirm-open-pr`   the branch has an open pull request, or open pull
+ *                       requests could not be checked (the CLI is missing or
+ *                       signed out, or the listing failed) so one cannot be
+ *                       ruled out; deleting the remote branch closes it
  */
 export const RISKS = ['abandon-unmerged', 'discard-changes', 'confirm-open-pr'];
 /** The risks whose flag is set, in canonical order. */
@@ -107,6 +109,10 @@ export function totalOf(counts) {
     }
     return out;
 }
+/** Every repository's `notes` in `sweep`, each with its repository. */
+export function sweepNotes(sweep) {
+    return sweep.repos.flatMap((r) => r.notes.map((note) => ({ repo: r.repo?.root ?? r.path, note })));
+}
 /**
  * Slugs shared by two or more of `repos`, roots sorted. A null entry or a
  * repository without a slug is left out.

package/dist/util.d.ts

@@ -1,7 +1,13 @@
 /** Small helpers every module of the package shares. */
 /** True when `path` is a directory; false for anything else, or when it cannot be read. */
 export declare function isDir(path: string): boolean;
-/** An error as one line for a person: a failed git call's own output, or the message. */
+/**
+ * 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 declare function errorText(err: unknown): string;
 /** `1 commit`, `3 commits`. */
 export declare const plural: (n: number, one: string, many: string) => string;

package/dist/util.js

@@ -1,5 +1,6 @@
 /** 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) {
@@ -10,11 +11,26 @@ export function isDir(path) {
         return false;
     }
 }
-/** An error as one line for a person: a failed git call's own output, or the message. */
+/**
+ * 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;
-    return err instanceof Error ? err.message : String(err);
+    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.18.0";
+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.18.0';
+export const VERSION = '0.19.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/repo-cleaner",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "What has been merged into the default branch, and what can go away. Inventories local branches, worktrees and remote branches across one repository or many, classifying each with the evidence behind the verdict and the command that would act on it. Plans and applies approved deletes, compare-and-swap.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",
@@ -49,12 +49,12 @@
   },
   "dependencies": {
     "zod": "^4.6.6",
-    "@osdlc/command-seam": "^0.14.0",
     "@osdlc/cli-tool": "^0.17.0",
     "@osdlc/path-guard": "^0.3.1",
     "@osdlc/typed-gh": "^0.16.1",
-    "@osdlc/typed-git": "^0.13.0",
-    "@osdlc/ux": "^0.1.1"
+    "@osdlc/command-seam": "^0.14.0",
+    "@osdlc/ux": "^0.1.1",
+    "@osdlc/typed-git": "^0.13.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",