@osdlc/repo-cleaner 0.18.0 → 0.19.0

package/dist/clean.d.ts

@@ -27,7 +27,7 @@ import type { Annotate } from './hooks.ts';
 import { type Plan } from './plan.ts';
 import { type Dropped, type Receipt, type Step } from './receipt.ts';
 import { type Runners } from './sweep.ts';
-import { type Kind, type Risk, type RowId, type Sweep, type SweepProgress, type SweptWith } from './types.ts';
+import { type Kind, type Risk, type RowId, type Sweep, type SweepProgress, type SweptWith, type RepoNote } from './types.ts';
 /** A risk allowed for every row (`row` absent), or for one row. */
 export interface Allow {
     risk: Risk;
@@ -41,7 +41,7 @@ export interface Allow {
  *   `pick`   work on exactly these rows; a `review` row, or a `keep` row with
  *            an action, runs only when picked. Default: every `delete` row.
  *   `spare`  leave these rows alone; a spared remote branch is still checked,
- *            and the run stops if it is gone or moved since the plan.
+ *            and the run stops if it moved or is gone since the plan.
  *   `allow`  the risks a row's action may carry.
  */
 export interface Approval {
@@ -74,7 +74,9 @@ interface Shared extends Runners {
 export interface CheckOptions extends Shared {
     /**
      * A sweep made just now, used as the re-check instead of sweeping again: for
-     * a preview straight after a sweep. `run` always sweeps again.
+     * a preview straight after a sweep. A repository whose remote rows it read
+     * from disk (offline) is swept again, asking the remote. `run` always sweeps
+     * again.
      */
     sweep?: Sweep | undefined;
     /** Where remote URL clones are kept; a plan repository there must still push only where it fetches from. */
@@ -92,6 +94,12 @@ export interface RunOptions extends Shared {
     onStep?: ((index: number, total: number, step: Step) => void) | undefined;
     /** Told after each step, with its `result` set, before the receipt is saved. */
     onStepDone?: ((index: number, total: number, step: Step) => void) | undefined;
+    /**
+     * Told the run's own re-check's notes, before the first step: what it judged
+     * without. The re-check may differ from the preview's, for example when a
+     * listing fails only at the run.
+     */
+    onNotes?: ((notes: RepoNote[]) => void) | undefined;
 }
 /** What a run would do, for a person to approve: the steps, and the rows dropped and why. */
 export interface Preview {
@@ -105,6 +113,12 @@ export interface Preview {
         risk: Risk;
         row: RowId | null;
     }[];
+    /**
+     * `RepoSweep.notes`, with each repository's root: what the re-check judged
+     * without. With a sweep passed in (`CheckOptions.sweep`), every repository
+     * of that sweep; otherwise each plan repository the re-check swept again.
+     */
+    notes: RepoNote[];
 }
 /** A row reference as typed: a kind and a name, or a bare name (`kind: null`). */
 export interface RowRef {
@@ -146,7 +160,9 @@ export declare function networkRemoteKey(url: string): string | null;
  *
  * @throws RepoCleanerError for an approval that contradicts itself, names a
  *   row the plan does not have or names one ambiguously, or spares a remote
- *   branch that moved. Nothing has been touched.
+ *   branch that moved. A plain `Error`, naming the repository, when the
+ *   re-check cannot read one: a failed fetch, or a remote `ls-remote` cannot
+ *   reach. Nothing has been touched.
  */
 export declare function check(plan: Plan, approval: Approval, opts?: CheckOptions): Preview;
 /**
@@ -156,7 +172,8 @@ export declare function check(plan: Plan, approval: Approval, opts?: CheckOption
  * row it dropped stays dropped.
  *
  * @throws RepoCleanerError (`spared-changed`) when a spared remote branch moved
- *   since the preview. Nothing has been touched.
+ *   since the preview, and a plain `Error` when the re-check cannot read a
+ *   repository, as {@link check} does. Nothing has been touched.
  */
 export declare function run(preview: Preview, opts?: RunOptions): Receipt;
 export {};

package/dist/clean.js

@@ -35,7 +35,7 @@ import { RECEIPT_VERSION } from "./receipt.js";
 import { defaultCacheDir, mirrorProblem } from "./remote-mirror.js";
 import { inspectSubmodules, submoduleHazards } from "./submodules.js";
 import { holdFreedBranches, sweepRepo } from "./sweep.js";
-import { KINDS, RISKS, RepoCleanerError, parseRowId, } from "./types.js";
+import { KINDS, RISKS, RepoCleanerError, parseRowId, sweepNotes, } from "./types.js";
 import { errorText } from "./util.js";
 import { removeIsForced, worktreeCommands } from "./worktrees.js";
 import { writeJsonAtomic } from "./write-json.js";
@@ -184,12 +184,21 @@ export function resolveApproval(plan, approval, cwd) {
 function allowed(allow, at, risk) {
     return allow.some((a) => a.risk === risk && (a.row === null || same(a.row, at)));
 }
-/** The plan repository's rows as they stand now, annotated as the sweep annotated them. */
+/**
+ * The plan repository's rows as they stand now, annotated as the sweep
+ * annotated them, and, when it had to sweep again, that sweep's notes on what
+ * it judged without. A sweep passed in reports its notes whole, in `recheck`.
+ */
 function resweep(repo, plan, kinds, opts) {
     const branchScoped = plan.options.branch !== null;
     const given = opts.sweep?.repos.find((r) => r.repo?.root === repo.root);
-    if (given !== undefined && given.error === null) {
-        return holdFreedBranches([...given.rows], branchScoped);
+    // An offline sweep read remote tips from disk, so it cannot stand in for
+    // the re-check of remote rows: sweep again and ask the remote, so the
+    // preview shows what the run will do.
+    const readFromDisk = kinds.includes('remote') && given?.repo?.fetched !== true;
+    if (given !== undefined && given.error === null && !readFromDisk) {
+        // Its notes are reported with the rest of that sweep's, by `recheck`.
+        return { rows: holdFreedBranches([...given.rows], branchScoped), notes: [] };
     }
     const swept = sweepRepo(repo.root, {
         ...opts,
@@ -197,13 +206,16 @@ function resweep(repo, plan, kinds, opts) {
         against: plan.options.against ?? undefined,
         provider: plan.options.provider,
         fetch: repo.fetched,
+        // Offline, the plan read tracking refs that can be stale; before anything
+        // is deleted on the remote, ask the remote itself.
+        liveRemoteTips: kinds.includes('remote'),
         branch: plan.options.branch ?? undefined,
         cwd: opts.cwd ?? process.cwd(),
     });
     if (swept.repo === null || swept.error !== null) {
-        throw new Error(swept.error ?? `could not read repository: ${repo.root}`);
+        throw new Error(`${repo.root}: ${swept.error ?? 'could not read the repository'}`);
     }
-    return swept.rows;
+    return { rows: swept.rows, notes: swept.notes };
 }
 /**
  * Re-sweep, then split the selection into rows to run and rows dropped. With
@@ -229,6 +241,7 @@ function recheck(plan, approval, opts, safeOnly) {
         kindsIn.set(s.repo, kinds);
     }
     const currentRows = new Map();
+    const notes = [];
     for (const [root, wanted] of kindsIn) {
         const repo = plan.repos.find((r) => r.root === root);
         // Only the kinds the selection is in: a plan of local rows need not
@@ -236,12 +249,19 @@ function recheck(plan, approval, opts, safeOnly) {
         // decide whether it is free to go or held.
         if (wanted.has('branch') && plan.options.only.includes('worktree'))
             wanted.add('worktree');
-        for (const row of resweep(repo, plan, KINDS.filter((k) => wanted.has(k)), opts)) {
+        const now = resweep(repo, plan, KINDS.filter((k) => wanted.has(k)), opts);
+        for (const row of now.rows)
             currentRows.set(keyOf({ repo: root, id: row.id }), row);
-        }
+        for (const note of now.notes)
+            notes.push({ repo: root, note });
     }
     const planned = (s) => plannedRows.get(keyOf(s));
     const current = (s) => currentRows.get(keyOf(s));
+    // A refusal ends the check before its notes are shown, so it carries them.
+    const alsoNoted = (root) => {
+        const said = notes.filter((n) => n.repo === root).map((n) => n.note);
+        return said.length === 0 ? '' : ` (${said.join(' ')})`;
+    };
     // A spared remote branch is checked, not dropped: one that moved refuses the run.
     const verified = [];
     for (const s of approval.spare) {
@@ -250,7 +270,7 @@ function recheck(plan, approval, opts, safeOnly) {
         const row = current(s);
         const plannedSha = planned(s).fingerprint['sha'];
         if (row === undefined || row.kind !== 'remote') {
-            throw new RepoCleanerError('spared-changed', `spared ${s.id} is no longer on the remote; refusing to run`);
+            throw new RepoCleanerError('spared-changed', `spared ${s.id} is no longer on the remote; refusing to run${alsoNoted(s.repo)}`);
         }
         if (typeof plannedSha !== 'string' || row.evidence.sha !== plannedSha) {
             throw new RepoCleanerError('spared-changed', `spared ${s.id} moved since the plan (planned ${String(plannedSha)}, now ${row.evidence.sha}); refusing to run`);
@@ -310,7 +330,25 @@ function recheck(plan, approval, opts, safeOnly) {
             detail: `checked out in ${worktree}, which this run does not remove`,
         });
     }
-    return { accepted: kept, dropped, verified };
+    // A sweep passed in speaks for every repository it read, selected or not: a
+    // repository with nothing to run is where a missing listing matters most.
+    return {
+        accepted: kept,
+        dropped,
+        verified,
+        notes: opts.sweep === undefined ? notes : uniqueNotes([...sweepNotes(opts.sweep), ...notes]),
+    };
+}
+/** Notes once each: a repository the given sweep read offline is swept again, and can repeat one. */
+function uniqueNotes(notes) {
+    const seen = new Set();
+    return notes.filter((n) => {
+        const key = `${n.repo}\0${n.note}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
 }
 // ── one row per remote branch ──────────────────────────────────────────────
 /**
@@ -476,7 +514,7 @@ function planSteps(plan, approval, opts, safeOnly) {
         ...rechecked.verified.map((a) => [verifyStep(a), a]),
         ...ordered.flatMap((a) => stepsFor(a).map((step) => [step, a])),
     ];
-    return { steps, dropped, accepted: ordered, removedHere };
+    return { steps, dropped, accepted: ordered, removedHere, notes: rechecked.notes };
 }
 /** A worktree row whose deletion takes the repository-wide prune: its directory is left without its `.git`. */
 function prunesAll(row) {
@@ -510,20 +548,22 @@ function checkMirrors(plan, cacheDir) {
  *
  * @throws RepoCleanerError for an approval that contradicts itself, names a
  *   row the plan does not have or names one ambiguously, or spares a remote
- *   branch that moved. Nothing has been touched.
+ *   branch that moved. A plain `Error`, naming the repository, when the
+ *   re-check cannot read one: a failed fetch, or a remote `ls-remote` cannot
+ *   reach. Nothing has been touched.
  */
 export function check(plan, approval, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     checkMirrors(plan, opts.cacheDir ?? defaultCacheDir());
     const resolved = resolveApproval(plan, approval, cwd);
-    const { steps, dropped, accepted } = planSteps(plan, resolved, opts, resolved.pick.length === 0);
+    const { steps, dropped, accepted, notes } = planSteps(plan, resolved, opts, resolved.pick.length === 0);
     for (const [step] of steps)
         step.result = 'would-run';
     const unusedAllows = resolved.allow
         .filter((a) => !accepted.some((row) => row.row.risks.includes(a.risk) &&
         (a.row === null || same(a.row, { repo: row.repo, id: row.row.id }))))
         .map((a) => ({ risk: a.risk, row: a.row?.id ?? null }));
-    return { plan, approval: resolved, steps: steps.map(([s]) => s), dropped, unusedAllows };
+    return { plan, approval: resolved, steps: steps.map(([s]) => s), dropped, unusedAllows, notes };
 }
 // ── the run ────────────────────────────────────────────────────────────────
 /**
@@ -562,9 +602,19 @@ function assertSafeToForce(path, git, a) {
     if (reasons.length > 0)
         throw new Error(`refused: ${reasons.join('; ')}`);
 }
-/** Run one step, then confirm it took. Throws with the reason on failure. */
+/** A remote step that found the branch already gone: its verification, marked so. */
+class Gone {
+    verification;
+    constructor(verification) {
+        this.verification = verification;
+    }
+}
+/**
+ * Run one step, then confirm it took. Throws with the reason on failure.
+ */
 function execute(step, a, git, probe, removedHere) {
     const at = git.at(step.repo);
+    const remoteTip = (remote, ref) => at.lsRemote(remote, ref).find((r) => r.ref === ref);
     const registered = (path) => at.worktrees().some((w) => resolve(w.path) === resolve(path));
     const row = a?.row;
     switch (step.action) {
@@ -641,7 +691,7 @@ function execute(step, a, git, probe, removedHere) {
             if (row?.kind !== 'remote')
                 throw new Error('verify-remote without a remote branch');
             const ref = `refs/heads/${row.evidence.branch}`;
-            const tip = at.lsRemote(row.evidence.remote, ref).find((r) => r.ref === ref);
+            const tip = remoteTip(row.evidence.remote, ref);
             if (tip === undefined)
                 throw new Error(`refused: spared ${ref} is gone from ${row.evidence.remote}`);
             if (tip.sha !== step.expectedSha) {
@@ -659,10 +709,20 @@ function execute(step, a, git, probe, removedHere) {
             });
             const refused = report.refs.find((r) => r.flag === '!');
             if (refused?.flag === '!') {
+                // Someone deleted the branch between the re-check and this push, so
+                // the lease refuses; a ref the remote no longer lists is done. Drop
+                // the tracking ref, as a delete push would have.
+                if (remoteTip(remote, ref) === undefined) {
+                    // Compare-and-swap: a tracking ref that moved since is left alone.
+                    at.try.deleteRef(`refs/remotes/${remote}/${row.evidence.branch}`, {
+                        expected: step.expectedSha,
+                    });
+                    return new Gone(`already gone from ${remote}`);
+                }
                 const why = refused.rawReason === null ? '' : ` (${refused.rawReason})`;
                 throw new Error(`${refused.summary}${why}: ${PUSH_REJECTIONS[refused.rejection].message}`);
             }
-            if (at.lsRemote(remote, ref).some((r) => r.ref === ref))
+            if (remoteTip(remote, ref) !== undefined)
                 throw new Error(`ls-remote still lists ${ref}`);
             return 'ls-remote lists nothing';
         }
@@ -675,7 +735,8 @@ function execute(step, a, git, probe, removedHere) {
  * row it dropped stays dropped.
  *
  * @throws RepoCleanerError (`spared-changed`) when a spared remote branch moved
- *   since the preview. Nothing has been touched.
+ *   since the preview, and a plain `Error` when the re-check cannot read a
+ *   repository, as {@link check} does. Nothing has been touched.
  */
 export function run(preview, opts = {}) {
     const now = opts.now ?? (() => new Date());
@@ -714,6 +775,7 @@ export function run(preview, opts = {}) {
     // so a row the re-check now judges `review` drops rather than runs.
     const safeOnly = preview.approval.pick.length === 0;
     const planned = planSteps(preview.plan, approval, { ...opts, sweep: undefined }, safeOnly);
+    opts.onNotes?.(planned.notes);
     const known = new Set(receipt.dropped.map((d) => `${d.repo}\0${d.row}`));
     for (const d of planned.dropped) {
         if (!known.has(`${d.repo}\0${d.row}`))
@@ -732,7 +794,14 @@ export function run(preview, opts = {}) {
     for (const [i, [step, a]] of plannedSteps.entries()) {
         opts.onStep?.(i, plannedSteps.length, step);
         try {
-            step.verification = execute(step, a, git, probe, removedHere);
+            const done = execute(step, a, git, probe, removedHere);
+            if (done instanceof Gone) {
+                step.verification = done.verification;
+                step.gone = true;
+            }
+            else {
+                step.verification = done;
+            }
             step.result = 'ok';
             if (step.action === 'unlock-worktree')
                 unlocked.add(a.row.name);

package/dist/cli.js

@@ -22,7 +22,7 @@
 import { readSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { isatty } from 'node:tty';
-import { EXIT, askYesNo, canPrompt, defineCli, } from '@osdlc/cli-tool';
+import { EXIT, askYesNo, canPrompt, defineCli, renderError, } from '@osdlc/cli-tool';
 import { detectColorLevel, stripControls } from '@osdlc/ux';
 import { check, checkApproval, parseAllow, run } from "./clean.js";
 import { fileStamp, parsePlan, plan as planOf, readPlan, writePlan } from "./plan.js";
@@ -33,7 +33,7 @@ import { PLAIN, TERMINAL_STYLE, renderCommands, renderJson, renderLateDrops, ren
 import { NO_STATUS_LINE, describeStep, describeSweep, statusLine, } from "./status-line.js";
 import { stepBoard } from "./step-board.js";
 import { sweep as sweepTargets, sweptWith } from "./sweep.js";
-import { KINDS, RISKS, RepoCleanerError } from "./types.js";
+import { KINDS, RISKS, RepoCleanerError, sweepNotes, } from "./types.js";
 const EXIT_NOTHING_TO_SWEEP = 10;
 const EXIT_STEP_FAILED = 11;
 const NAME = 'repo-cleaner';
@@ -84,7 +84,7 @@ const TARGETS = [
     {
         name: 'target',
         variadic: true,
-        help: 'a checkout, a directory of checkouts, or a remote URL (default: the checkout you are in)',
+        help: 'a checkout, a directory of checkouts, or a remote URL (default: the directory you are in)',
     },
 ];
 const MORE = `Run with --help --extended for the full reference: what every option means, the words the report uses, and which combinations are refused.`;
@@ -324,6 +324,15 @@ function reportUnreadable(ctx, name, s) {
         ctx.io.stderr(`${name}: ${r.repo?.root ?? r.path}: ${r.error}\n`);
     return failed.length > 0;
 }
+/** Each repository's `RepoSweep.notes`, on stderr, for the outputs that do not carry them. */
+function reportNotes(ctx, name, s) {
+    writeNotes(ctx, name, sweepNotes(s));
+}
+/** Notes as `<name>: <repo>: <note>` lines on stderr. A note quotes git's and the provider's output, so it goes out as an error line does, controls removed. */
+function writeNotes(ctx, name, notes) {
+    for (const { repo, note } of notes)
+        ctx.io.stderr(renderError(`${repo}: ${note}`, name));
+}
 function runReport(argv, ctx, status) {
     const parsed = parseWith(reportCli(), NAME, argv, ctx);
     if (parsed.status === 'done')
@@ -342,6 +351,7 @@ function runReport(argv, ctx, status) {
     else if (v.format === 'summary')
         ctx.io.stdout(renderSummary(s, style) + remoteNote(s, style));
     else if (v.format === 'commands') {
+        reportNotes(ctx, NAME, s);
         const commands = renderCommands(s);
         if (commands.length > 0)
             ctx.io.stdout(commands.join('\n') + '\n');
@@ -366,6 +376,7 @@ function runPlan(argv, ctx, status) {
         return EXIT_NOTHING_TO_SWEEP;
     }
     const plan = planOf(swept.sweep);
+    reportNotes(ctx, name, swept.sweep);
     const unreadable = reportUnreadable(ctx, name, swept.sweep);
     const style = styleFor(ctx, 'stderr');
     ctx.io.stderr(renderTotals(swept.sweep, style) + '\n' + remoteNote(swept.sweep, style));
@@ -504,9 +515,21 @@ function runClean(argv, ctx, deps, status) {
         return refusal(ctx, name, err);
     }
     status.clear();
+    // The re-check's notes: from the sweep just made, or from sweeping a saved
+    // plan's repositories again. The run re-checks once more; only a note that
+    // is new by then is printed again.
+    const noted = new Set();
+    const notesOnce = (notes) => writeNotes(ctx, name, notes.filter(({ repo, note }) => {
+        const key = `${repo}\0${note}`;
+        if (noted.has(key))
+            return false;
+        noted.add(key);
+        return true;
+    }));
+    notesOnce(preview.notes);
     const showPreview = () => {
         if (v.format === 'json') {
-            ctx.io.stdout(`${JSON.stringify({ dryRun: v.dryRun, summary: summarizeRun(preview), steps: preview.steps, dropped: preview.dropped, unusedAllows: preview.unusedAllows }, null, 2)}\n`);
+            ctx.io.stdout(`${JSON.stringify({ dryRun: v.dryRun, summary: summarizeRun(preview), steps: preview.steps, dropped: preview.dropped, unusedAllows: preview.unusedAllows, notes: preview.notes }, null, 2)}\n`);
         }
         else {
             ctx.io.stdout(renderPreview(preview, style));
@@ -540,6 +563,11 @@ function runClean(argv, ctx, deps, status) {
             source,
             receiptPath,
             now: () => new Date(),
+            onNotes: (notes) => {
+                // The run's re-check draws its progress on the status line.
+                status.clear();
+                notesOnce(notes);
+            },
             ...(live
                 ? {
                     // The board carries the run's progress; the status line stays clear.

package/dist/index.d.ts

@@ -21,4 +21,4 @@ export { render, type RunSummary, type Style } from './render.ts';
 export { defaultProcessProbe, type ProcessHolder, type ProcessProbe } from './processes.ts';
 export { providers, type PrProvider, type ProviderChoice } from './providers/index.ts';
 export type { Annotate } from './hooks.ts';
-export { KINDS, RISKS, RepoCleanerError, type Action, type Blocker, type BranchEvidence, type BranchRow, type Bucket, type Counts, type ErrorCode, type Kind, type LandingEvidence, type PrEvidence, type RemoteEvidence, type RemoteRow, type RepoInfo, type RepoSweep, type Risk, type Row, type RowId, type SubmoduleEvidence, type Sweep, type SweepProgress, type SweptWith, type Verdict, type WorktreeEvidence, type WorktreeRow, } from './types.ts';
+export { KINDS, RISKS, RepoCleanerError, type Action, type Blocker, type BranchEvidence, type BranchRow, type Bucket, type Counts, type ErrorCode, type Kind, type LandingEvidence, type PrEvidence, type RemoteEvidence, type RemoteRow, type RepoInfo, type RepoNote, type RepoSweep, type Risk, type Row, type RowId, type SubmoduleEvidence, type Sweep, type SweepProgress, type SweptWith, type Verdict, type WorktreeEvidence, type WorktreeRow, } from './types.ts';

package/dist/providers/github.d.ts

@@ -5,6 +5,7 @@ import type { PrProvider } from './types.ts';
 export declare const PR_LIMIT = 300;
 /**
  * A provider over `gh pr list`. `gh` picks the repository from the checkout's
- * remotes, so `target` is not consulted.
+ * remotes, so `target` is not consulted. A listing `gh` fails, such as one for
+ * a repository the signed-in account cannot see, throws with `gh`'s reason.
  */
 export declare function githubProvider(gh: Gh): PrProvider;

package/dist/providers/github.js

@@ -15,7 +15,8 @@ const FIELDS = [
 export const PR_LIMIT = 300;
 /**
  * A provider over `gh pr list`. `gh` picks the repository from the checkout's
- * remotes, so `target` is not consulted.
+ * remotes, so `target` is not consulted. A listing `gh` fails, such as one for
+ * a repository the signed-in account cannot see, throws with `gh`'s reason.
  */
 export function githubProvider(gh) {
     return {

package/dist/providers/gitlab.d.ts

@@ -25,8 +25,9 @@ interface MergeRequest {
 /** One merge request as a {@link PRInfo}, or null for a fork's or an unknown state's. */
 export declare function mergeRequestToPr(mr: MergeRequest): PRInfo | null;
 /**
- * A provider over `glab`. It needs `target.project`: without one there is
- * nothing to ask, and the listing answers null.
+ * A provider over `glab`. It needs `target.project`. A listing it cannot
+ * make or read throws with the reason: no project in the remote URL, `glab`'s
+ * own error, or a page that cannot be read.
  */
 export declare function gitlabProvider(glab: CommandRunner): PrProvider;
 export {};

package/dist/providers/gitlab.js

@@ -6,7 +6,7 @@
  * an explicit host and project, so a checkout with several remotes is read
  * against the one the sweep measures.
  */
-import { parseJsonResult, runFailed, } from '@osdlc/command-seam';
+import { parseJsonResult, runFailed, stderrOrError, } from '@osdlc/command-seam';
 import { PR_LIMIT } from "./github.js";
 const PER_PAGE = 100;
 /** GitLab's states, as the GitHub names classification reads. A locked MR is an open one mid-update. */
@@ -59,8 +59,9 @@ function succeeded(result) {
     return !runFailed(result);
 }
 /**
- * A provider over `glab`. It needs `target.project`: without one there is
- * nothing to ask, and the listing answers null.
+ * A provider over `glab`. It needs `target.project`. A listing it cannot
+ * make or read throws with the reason: no project in the remote URL, `glab`'s
+ * own error, or a page that cannot be read.
  */
 export function gitlabProvider(glab) {
     const run = (root, argv) => glab.run(argv, { cwd: root });
@@ -75,7 +76,7 @@ export function gitlabProvider(glab) {
         },
         listPrs(root, target, branch) {
             if (target.project === null)
-                return null;
+                throw new Error('the remote URL names no GitLab project');
             const project = encodeURIComponent(target.project);
             const prs = [];
             for (let page = 1; (page - 1) * PER_PAGE < PR_LIMIT; page++) {
@@ -95,11 +96,16 @@ export function gitlabProvider(glab) {
                 ]);
                 // A failed, cut-short or unreadable page fails the listing: a missing
                 // open MR would read as no MR.
-                if (!succeeded(result))
-                    return null;
+                if (!succeeded(result)) {
+                    // Not stdout: a page cut short is half a JSON listing, not a reason.
+                    throw new Error(result.outputIncomplete === true
+                        ? `page ${page} was cut short`
+                        : stderrOrError(result) || `glab exited ${String(result.exitCode)}`);
+                }
                 const listed = parseJsonResult(result);
-                if (!listed.ok || !Array.isArray(listed.value))
-                    return null;
+                if (!listed.ok || !Array.isArray(listed.value)) {
+                    throw new Error(`page ${page} is not a merge request list`);
+                }
                 const rows = listed.value;
                 for (const row of rows) {
                     if (!isMergeRequest(row))

package/dist/providers/index.d.ts

@@ -20,10 +20,11 @@ export declare function providers(clients: {
  */
 export declare function forgeTarget(url: string | null): ForgeTarget;
 /**
- * The provider `choice` names for `target`. `auto` reads the host: one with
- * `gitlab` in its name is GitLab, any other is GitHub, which is what the sweep
- * did before providers existed (`gh` answers nothing for a host it does not
- * know). `none` is no provider.
+ * The provider `choice` names for `target`. `auto` reads the host: none, for
+ * a remote that names no host (a local path or `file://`), which cannot have
+ * pull requests; one with `gitlab` in its name is GitLab; any other is
+ * GitHub, which is what the sweep did before providers existed (`gh` answers
+ * nothing for a host it does not know). `none` is no provider.
  */
 export declare function chooseProvider(choice: ProviderChoice, target: ForgeTarget): ProviderName | null;
 /** The chosen provider for a repository, probed; null for none. */

package/dist/providers/index.js

@@ -41,17 +41,20 @@ export function forgeTarget(url) {
     return { host: match[1].toLowerCase(), project: parts.join('/') };
 }
 /**
- * The provider `choice` names for `target`. `auto` reads the host: one with
- * `gitlab` in its name is GitLab, any other is GitHub, which is what the sweep
- * did before providers existed (`gh` answers nothing for a host it does not
- * know). `none` is no provider.
+ * The provider `choice` names for `target`. `auto` reads the host: none, for
+ * a remote that names no host (a local path or `file://`), which cannot have
+ * pull requests; one with `gitlab` in its name is GitLab; any other is
+ * GitHub, which is what the sweep did before providers existed (`gh` answers
+ * nothing for a host it does not know). `none` is no provider.
  */
 export function chooseProvider(choice, target) {
     if (choice === 'none')
         return null;
     if (choice !== 'auto')
         return choice;
-    return target.host !== null && target.host.includes('gitlab') ? 'gitlab' : 'github';
+    if (target.host === null)
+        return null;
+    return target.host.includes('gitlab') ? 'gitlab' : 'github';
 }
 /** The chosen provider for a repository, probed; null for none. */
 export function probeProvider(choice, root, target, all) {

package/dist/providers/types.d.ts

@@ -34,6 +34,11 @@ export interface ProviderStatus extends ForgeTarget, ProviderWords {
     available: boolean;
     /** The CLI has credentials for `host`. */
     authenticated: boolean;
+    /**
+     * Set by the sweep when the provider was asked and its listing failed: why,
+     * in the provider's words. Absent when it answered or was not asked.
+     */
+    listError?: string | undefined;
 }
 /** One source of pull request evidence. */
 export interface PrProvider {
@@ -46,8 +51,9 @@ export interface PrProvider {
     };
     /**
      * The repository's pull requests, fork PRs already dropped, in any order;
-     * null when the listing failed. A failure is not "no PRs": the caller
-     * classifies on git evidence alone.
+     * null, or a throw whose message says why, when the listing failed. A
+     * failure is not "no PRs": the caller classifies on git evidence alone and
+     * notes the failure on the repository.
      *
      * @param branch Narrow the listing to this exact head branch. The caller
      *   checks the head again, so a provider that cannot narrow may list all.

package/dist/prs.d.ts

@@ -7,24 +7,52 @@
  * `providers/`.
  */
 import type { PrProvider } from './providers/index.ts';
+import type { ProviderStatus } from './providers/types.ts';
 import type { PRInfo, RepoInfo } from './types.ts';
+/** Why the provider did not answer, and the words for it. */
+export interface PrsUnchecked {
+    kind: 'not-installed' | 'not-signed-in' | 'list-failed';
+    /** For a sentence: "`gh` is not installed", "`gh pr list` failed". */
+    why: string;
+}
 /**
- * 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.
+ * 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 declare function prsUnchecked(status: ProviderStatus): PrsUnchecked | null;
+/** A provider's answer for one repository: its pull requests, or why there are none to read. */
+export interface PrLookup {
+    /** Pull requests keyed by head branch; empty when the lookup failed or was not made. */
+    prs: Map<string, PRInfo>;
+    /**
+     * Why the listing failed, in the provider's own words where it gave any;
+     * null when it answered, or when it was not asked at all.
+     */
+    error: string | null;
+}
+/**
+ * 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 declare function fetchPrs(repo: RepoInfo, provider: PrProvider, branch?: string): Map<string, PRInfo>;
+export declare function lookupPrs(repo: RepoInfo, provider: PrProvider, branch?: string): PrLookup;