@osdlc/repo-cleaner 0.10.1 → 0.13.0

package/dist/cli.js

@@ -4,7 +4,7 @@
  * Four verbs over one set of sweep filters:
  *
  *   status  (the default) inventory and classify; read-only but for the fetch
- *   summary the same sweep as counts: totals, merged, delete, review, keep
+ *   summary the same sweep as counts: totals, merged, delete, prune, review, keep
  *   plan    write the deletable rows as a plan, to stdout or a file
  *   apply   re-check, show the steps, ask, then delete
  *
@@ -21,17 +21,21 @@
  *   10  nothing to sweep: no entry named a repository
  *   11  apply stopped at a failed step; the receipt says which
  */
-import { readSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync, readSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { isatty } from 'node:tty';
-import { EXIT, askYesNo, canPrompt, defineCli } from '@osdlc/cli-tool';
+import { EXIT, askYesNo, canPrompt, defineCli, systemDirs } from '@osdlc/cli-tool';
 import { Git } from '@osdlc/typed-git';
+import { detectColorLevel } from '@osdlc/ux';
 import { resolveBranch } from "./branches.js";
+import { VENDOR_DIRS } from "./devlink.js";
+import { ensureMirror, mirrorProblem } from "./remote-mirror.js";
 import { ApplyArgumentError, applyPlan, parseGrant, parseRowRef } from "./apply.js";
 import { PLAN_VERSION, fileStamp, parsePlan, planRepo, readPlan, writePlan, } from "./plan.js";
 import { RECEIPT_VERSION } from "./receipt.js";
-import { proposedCommands, renderCountsJson, renderCountsText, renderJson, renderReceipt, renderSummary, renderText, rowsActedOn, summarizeReceipt, } from "./render.js";
+import { PLAIN, proposedCommands, renderCountsJson, renderCountsText, renderJson, renderPreview, renderPreviewDrops, renderReceipt, renderStepFailure, renderSummary, renderText, rowsActedOn, summarizeReceipt, TERMINAL_STYLE, } from "./render.js";
 import { NO_STATUS_LINE, describeStep, describeSweep, statusLine, } from "./status-line.js";
+import { stepBoard } from "./step-board.js";
 import { sweepRepos } from "./sweep.js";
 const EXIT_NOTHING_TO_SWEEP = 10;
 const EXIT_STEP_FAILED = 11;
@@ -47,23 +51,38 @@ const SWEEP_FLAGS = {
     only: {
         kind: 'list',
         valueName: 'list',
-        help: `comma-separated: ${Object.keys(ONLY).join(', ')} (default: all)`,
+        help: `comma-separated: ${Object.keys(ONLY).join(', ')} (default: worktrees, branches; remotes with --remotes)`,
+    },
+    remotes: {
+        kind: 'boolean',
+        help: 'also sweep remote branches, which is slower: each one is compared with the default branch',
     },
     branch: {
         kind: 'string',
         valueName: 'name|HEAD',
-        help: 'only this branch of this repository: its worktree, local and remote branch',
+        help: 'only this branch of this repository: its worktree and local branch, and its remote branch with --remotes',
     },
     remote: {
         kind: 'string',
         valueName: 'name',
         help: 'remote to measure against (default: origin)',
     },
-    gh: { kind: 'boolean', negatable: true, help: 'classify on git evidence alone' },
+    remoteUrl: {
+        kind: 'list',
+        valueName: 'url',
+        default: [],
+        commaSeparated: false,
+        help: 'sweep the branches of this remote with no checkout of your own, through a clone kept in the cache directory; repeatable',
+    },
+    gh: {
+        kind: 'boolean',
+        negatable: true,
+        help: 'with --remotes: classify on git evidence alone (without --remotes gh is never called)',
+    },
     fetch: {
         kind: 'boolean',
         negatable: true,
-        help: 'classify on the remote-tracking refs already on disk',
+        help: 'with --remotes: classify on the remote-tracking refs already on disk (without --remotes nothing is fetched)',
     },
     progress: {
         kind: 'boolean',
@@ -87,8 +106,9 @@ const OUTPUT = {
 };
 const statusCli = () => defineCli({
     name: NAME,
-    summary: 'Inventory branches, worktrees and remote branches, and say which have been merged into ' +
-        'the default branch. Fetches each remote first; deletes nothing.',
+    summary: 'Inventory local branches and worktrees (remote branches too with --remotes), and say ' +
+        'which have been merged into the default branch. Offline unless --remotes, which fetches ' +
+        'each remote first and asks gh about pull requests; deletes nothing.',
     positionals: PATHS,
     flags: {
         ...SWEEP_FLAGS,
@@ -98,7 +118,7 @@ const statusCli = () => defineCli({
     },
     epilogue: `commands:
   ${NAME} [status]   this report (the default)
-  ${NAME} summary    counts per repository: total, merged, delete, review, keep
+  ${NAME} summary    counts per repository: total, merged, delete, prune, review, keep
   ${NAME} plan       write the deletable rows as a plan
   ${NAME} apply      re-check, show the steps, ask, delete
   ${NAME} dev        run ${NAME} from a development checkout
@@ -108,8 +128,8 @@ swept as ./<name>.`,
 });
 const summaryCli = () => defineCli({
     name: `${NAME} summary`,
-    summary: 'Count local branches, worktrees and remote branches per repository: how many there are, ' +
-        'how many are merged into the default branch, and how many would be deleted, reviewed or kept.',
+    summary: 'Count local branches and worktrees (and remote branches with --remotes) per repository: how many there are, ' +
+        'how many are merged into the default branch, and how many would be deleted, pruned, reviewed or kept.',
     positionals: PATHS,
     flags: { ...SWEEP_FLAGS, output: OUTPUT },
     epilogue: 'merged: the work is on the default branch. Rows kept for structure (the default ' +
@@ -151,6 +171,13 @@ const applyCli = () => defineCli({
             commaSeparated: false,
             help: 'apply only this row, e.g. local_branch:feat/x; repeatable (default: every row)',
         },
+        keep: {
+            kind: 'list',
+            valueName: 'remote_branch:id',
+            default: [],
+            commaSeparated: false,
+            help: 'keep this remote branch, but refuse the run if its tip moved since the plan, e.g. remote_branch:origin/feat/x; repeatable',
+        },
         allow: {
             kind: 'list',
             valueName: 'risk[=category:id]',
@@ -209,6 +236,31 @@ function failure(ctx, err) {
     ctx.io.stderr(`${NAME}: ${err instanceof Error ? err.message : String(err)}\n`);
     return EXIT.error;
 }
+/** Color for a report on `stream`, when it is a terminal that takes color. */
+function styleFor(ctx, stream) {
+    const level = detectColorLevel({ env: ctx.env, isTTY: ctx.terminal?.[stream] === true });
+    return level === 'none' ? PLAIN : TERMINAL_STYLE;
+}
+/** The note under a text report that left remote branches out, or '' when it did not. */
+function remotesNote(swept, style) {
+    if (swept.kind !== 'ok' || swept.scope.includes('remote-branches'))
+        return '';
+    if (!swept.result.repos.some((r) => r.repo?.remote != null))
+        return '';
+    return (style.muted('Local only: nothing fetched, no gh, remote branches not checked; add --remotes for all three.') + '\n');
+}
+/** Where `--remote-url` keeps its clones. */
+function mirrorCache(ctx) {
+    return systemDirs(VENDOR_DIRS, { env: ctx.env }).standalone(NAME).cache().app('remotes').path;
+}
+/** Local work by default: remote branches only when asked for, with `--remotes` or `--only remotes`. */
+const LOCAL_SCOPE = ['worktrees', 'local-branches'];
+function sweepScope(only, remotes) {
+    const scope = only === undefined ? [...LOCAL_SCOPE] : only.map((s) => ONLY[s]);
+    if (remotes && !scope.includes('remote-branches'))
+        scope.push('remote-branches');
+    return scope;
+}
 /** Validate the sweep flags and run the sweep, or answer with the exit code. */
 function sweep(name, v, paths, ctx, status) {
     const only = v.only?.filter((s) => s !== '');
@@ -221,6 +273,26 @@ function sweep(name, v, paths, ctx, status) {
         const message = '--branch sweeps this repository only; drop the paths';
         return { kind: 'exit', code: usageError(ctx, name, message) };
     }
+    // An empty URL is refused, not dropped: `--remote-url "$UNSET"` must not
+    // fall back to sweeping the checkout you are standing in.
+    if (v.remoteUrl.some((u) => u.trim() === '')) {
+        return {
+            kind: 'exit',
+            code: usageError(ctx, name, '--remote-url needs a URL; got an empty one'),
+        };
+    }
+    const urls = v.remoteUrl;
+    if (urls.length > 0) {
+        const conflict = paths.length > 0
+            ? '--remote-url sweeps a remote, not a checkout; drop the paths'
+            : v.branch !== undefined
+                ? '--branch reads the checkout you are in; it does not combine with --remote-url'
+                : (only ?? []).some((s) => s !== 'remotes')
+                    ? '--remote-url has remote branches only; drop --only or pass --only remotes'
+                    : null;
+        if (conflict !== null)
+            return { kind: 'exit', code: usageError(ctx, name, conflict) };
+    }
     let branch;
     try {
         branch = v.branch === undefined ? undefined : resolveBranch(v.branch, new Git(ctx.cwd));
@@ -228,22 +300,40 @@ function sweep(name, v, paths, ctx, status) {
     catch (err) {
         return { kind: 'exit', code: failure(ctx, err) };
     }
+    const scope = urls.length > 0 ? ['remote-branches'] : sweepScope(only, v.remotes);
+    const online = scope.includes('remote-branches');
     const options = {
         baseDir: ctx.cwd,
         cwd: ctx.cwd,
-        noGh: !v.gh,
-        fetch: v.fetch,
+        // Local by default means offline: the fetch and gh go with remote branches.
+        noGh: !(online && v.gh),
+        fetch: online && v.fetch,
         branch,
         // Mid-walk, while the wait is happening — the summary comes too late to
         // explain why the tool appeared to hang.
         onWarn: (message) => ctx.io.stderr(`${NAME}: ${message}\n`),
         ...(v.progress ? { onProgress: (p) => status.update(describeSweep(p)) } : {}),
-        ...(only === undefined ? {} : { scope: only.map((s) => ONLY[s]) }),
+        scope,
         ...(v.remote === undefined ? {} : { remote: v.remote }),
     };
+    let entries = paths.length > 0 ? [...paths] : [ctx.cwd];
+    if (urls.length > 0) {
+        const cache = mirrorCache(ctx);
+        try {
+            entries = urls.map((url, i) => {
+                if (v.progress)
+                    status.update(`${NAME}: cloning remote ${i + 1}/${urls.length}`);
+                return ensureMirror(url, cache);
+            });
+        }
+        catch (err) {
+            status.clear();
+            return { kind: 'exit', code: failure(ctx, err) };
+        }
+    }
     if (v.progress)
         status.update(`${NAME}: finding repositories`);
-    const result = sweepRepos(paths.length > 0 ? paths : [ctx.cwd], options);
+    const result = sweepRepos(entries, options);
     status.clear();
     if (branch !== undefined && result.repos.length > 1) {
         const err = new Error(`--branch sweeps one repository; ${result.repos.length} found under ${ctx.cwd}`);
@@ -254,7 +344,7 @@ function sweep(name, v, paths, ctx, status) {
         return { kind: 'exit', code: failure(ctx, new Error(refused)) };
     if (result.repos.length === 0)
         return { kind: 'nothing', result };
-    return { kind: 'ok', result, branch, values: v };
+    return { kind: 'ok', result, branch, values: v, scope, noGh: options.noGh === true };
 }
 /**
  * Name each repository the sweep could not read, on stderr. True when there
@@ -270,13 +360,13 @@ function reportUnreadable(ctx, name, result) {
 function planOf(swept, now) {
     const opts = {
         remote: swept.values.remote ?? null,
-        noGh: !swept.values.gh,
+        noGh: swept.noGh,
         branch: swept.branch ?? null,
     };
     return {
         version: PLAN_VERSION,
         created_at: now.toISOString(),
-        repos: swept.result.repos.flatMap((s) => s.repo === null ? [] : [planRepo(s.repo.root, opts, s.items)]),
+        repos: swept.result.repos.flatMap((s) => s.repo === null ? [] : [planRepo(s.repo.root, { ...opts, fetch: s.repo.fetched }, s.items)]),
     };
 }
 function runStatus(argv, ctx, status) {
@@ -286,7 +376,8 @@ function runStatus(argv, ctx, status) {
     if (parsed.status === 'error')
         return usageError(ctx, NAME, parsed.message);
     const v = parsed.values;
-    const render = (r) => v.output === 'json' ? renderJson(r) : renderText(r, { keep: v.keep });
+    const style = styleFor(ctx, 'stdout');
+    const render = (r) => v.output === 'json' ? renderJson(r) : renderText(r, { keep: v.keep, style });
     const swept = sweep(NAME, v, parsed.positionals, ctx, status);
     if (swept.kind === 'exit')
         return swept.code;
@@ -301,6 +392,8 @@ function runStatus(argv, ctx, status) {
     }
     else {
         ctx.io.stdout(render(swept.result));
+        if (v.output === 'text')
+            ctx.io.stdout(remotesNote(swept, style));
     }
     return EXIT.ok;
 }
@@ -312,11 +405,14 @@ function runSummary(argv, ctx, status) {
     if (parsed.status === 'error')
         return usageError(ctx, name, parsed.message);
     const v = parsed.values;
-    const render = (r) => v.output === 'json' ? renderCountsJson(r) : renderCountsText(r);
+    const style = styleFor(ctx, 'stdout');
+    const render = (r) => v.output === 'json' ? renderCountsJson(r) : renderCountsText(r, style);
     const swept = sweep(name, v, parsed.positionals, ctx, status);
     if (swept.kind === 'exit')
         return swept.code;
     ctx.io.stdout(render(swept.result));
+    if (v.output === 'text')
+        ctx.io.stdout(remotesNote(swept, style));
     return swept.kind === 'nothing' ? EXIT_NOTHING_TO_SWEEP : EXIT.ok;
 }
 function runPlan(argv, ctx, status) {
@@ -337,7 +433,8 @@ function runPlan(argv, ctx, status) {
     }
     const plan = planOf(swept, new Date());
     const unreadable = reportUnreadable(ctx, name, swept.result);
-    ctx.io.stderr(renderSummary(swept.result) + '\n');
+    const style = styleFor(ctx, 'stderr');
+    ctx.io.stderr(renderSummary(swept.result, style) + '\n' + remotesNote(swept, style));
     if (v.out === '-') {
         ctx.io.stdout(`${JSON.stringify(plan, null, 2)}\n`);
     }
@@ -353,6 +450,7 @@ function receiptBeside(planPath, now) {
     const stem = basename(planPath).replace(/\.json$/i, '');
     return join(dirname(planPath), `${stem}.receipt-${fileStamp(now)}.json`);
 }
+const dropKey = (d) => JSON.stringify([d.repo, d.category, d.id]);
 /** Rows the run would delete or prune: one each, however many steps (an unlock, a remove) it takes. */
 function wouldRun(receipt) {
     return rowsActedOn(summarizeReceipt(receipt));
@@ -407,6 +505,7 @@ function applyConflict(v, paths) {
             v.only !== undefined ? '--only' : null,
             v.branch !== undefined ? '--branch' : null,
             v.remote !== undefined ? '--remote' : null,
+            v.remoteUrl.length > 0 ? '--remote-url' : null,
         ].filter((f) => f !== null);
         if (sweepFlags.length > 0)
             return `--plan fixes what is swept; drop ${sweepFlags.join(', ')}`;
@@ -426,9 +525,11 @@ function runApply(argv, ctx, deps, status) {
     const v = parsed.values;
     const paths = parsed.positionals;
     let rows;
+    let keep;
     let grants;
     try {
         rows = v.row.map(parseRowRef);
+        keep = v.keep.map(parseRowRef);
         grants = v.allow.map(parseGrant);
     }
     catch (err) {
@@ -444,12 +545,27 @@ function runApply(argv, ctx, deps, status) {
     if (typeof loaded === 'number')
         return loaded;
     const { plan, source, receiptPath } = loaded;
+    // A plan from `--remote-url` names a clone in the cache. Its deletes are
+    // pushed from there, so the clone must still push only where it fetches from.
+    const cacheDir = mirrorCache(ctx);
+    const cache = (existsSync(cacheDir) ? realpathSync(cacheDir) : cacheDir) + sep;
+    for (const repo of plan.repos) {
+        if (!repo.root.startsWith(cache))
+            continue;
+        const problem = mirrorProblem(repo.root);
+        if (problem !== null)
+            return failure(ctx, new Error(`${problem}; refusing to apply`));
+    }
     const ok = () => (loaded.unreadable ? EXIT.error : EXIT.ok);
     const repoRoot = v.repoRoot === undefined ? undefined : resolve(ctx.cwd, v.repoRoot);
-    const print = (receipt, shownPath) => {
+    // On a terminal the run is shown live: every step first, then each one
+    // checked off as it finishes, with a bar on the status line.
+    const live = v.output === 'text' && ctx.terminal?.stdout === true;
+    const style = styleFor(ctx, 'stdout');
+    const print = (receipt, shownPath, steps = true) => {
         ctx.io.stdout(v.output === 'json'
             ? `${JSON.stringify({ receiptPath: shownPath, summary: summarizeReceipt(receipt), receipt }, null, 2)}\n`
-            : renderReceipt(receipt, shownPath));
+            : renderReceipt(receipt, shownPath, style, { steps }));
     };
     const planned = plan.repos.filter((r) => repoRoot === undefined || resolve(r.root) === resolve(repoRoot));
     if (repoRoot !== undefined && planned.length === 0) {
@@ -466,6 +582,7 @@ function runApply(argv, ctx, deps, status) {
         callerCwd: ctx.cwd,
         planPath: source,
         repoRoot,
+        keep,
         // An implicit selection runs only safe-to-delete rows, in the preview and
         // in the run it confirms, whose rows are passed explicitly.
         safeOnly: rows.length === 0,
@@ -487,11 +604,16 @@ function runApply(argv, ctx, deps, status) {
         });
     }
     catch (err) {
+        if (err instanceof ApplyArgumentError)
+            return usageError(ctx, name, err.message);
         return failure(ctx, err);
     }
     const count = wouldRun(preview);
     if (v.dryRun || count === 0) {
-        print(preview, null);
+        if (live)
+            ctx.io.stdout(renderPreview(preview, style));
+        else
+            print(preview, null);
         return ok();
     }
     if (!v.yes) {
@@ -499,10 +621,22 @@ function runApply(argv, ctx, deps, status) {
         if (declined !== null)
             return declined;
     }
+    else if (live) {
+        ctx.io.stdout(renderPreview(preview, style));
+    }
+    if (live)
+        ctx.io.stdout('\n');
     // Only what the preview showed: rows it dropped stay dropped.
     // Pinned to their repositories: a branch name two repositories share stays two rows.
-    const approved = preview.steps.flatMap((s) => s.row === null ? [] : [{ ...s.row, repo: s.repo }]);
+    // A kept row's tip check is not a selection; `keep` carries it again.
+    const approved = preview.steps.flatMap((s) => s.row === null || s.action === 'verify-remote' ? [] : [{ ...s.row, repo: s.repo }]);
     const approvedGrants = grants.filter((g) => g.row === null || approved.some((r) => r.category === g.row.category && r.id === g.row.id));
+    const size = deps.terminalSize ??
+        (() => ({
+            width: ctx.terminal?.columns || process.stdout.columns || 80,
+            height: process.stdout.rows || 24,
+        }));
+    let board;
     let receipt;
     try {
         receipt = applyPlan(plan, approved, approvedGrants, {
@@ -510,12 +644,40 @@ function runApply(argv, ctx, deps, status) {
             dryRun: false,
             receiptPath,
             dropped: preview.dropped,
+            ...(live
+                ? {
+                    // The board carries the run's progress; the status line stays clear.
+                    onStart: (steps) => {
+                        board = stepBoard(ctx.io.stdout, steps, size, style);
+                        board.draw(null);
+                    },
+                    onStep: (i) => board?.draw(i),
+                    onStepDone: (_i, _total, step) => {
+                        board?.draw(null);
+                        // Here rather than after the run: a receipt that then cannot be
+                        // saved must not take the step's own error with it.
+                        if (step.result === 'failed') {
+                            ctx.io.stdout(`\n${renderStepFailure(step, style)}\n`);
+                        }
+                    },
+                }
+                : {}),
         });
     }
     catch (err) {
         return failure(ctx, err);
     }
-    print(receipt, receiptPath);
+    status.clear();
+    if (live) {
+        // The run's own re-check can drop a row the preview showed, if it moved
+        // while the question was open: say which, since it gets no tick.
+        const seen = new Set(preview.dropped.map(dropKey));
+        const late = receipt.dropped.filter((d) => !seen.has(dropKey(d)));
+        if (late.length > 0)
+            ctx.io.stdout(`\n${renderPreviewDrops(late, style)}`);
+        ctx.io.stdout('\n');
+    }
+    print(receipt, receiptPath, !live);
     if (receiptPath === null) {
         ctx.io.stderr(`${name}: no receipt written; pass --receipt <file> to keep one\n`);
     }
@@ -528,7 +690,7 @@ function runApply(argv, ctx, deps, status) {
 function confirm(ctx, name, preview, count, json, deps) {
     // The preview is for the person answering, so it goes where the question does.
     const show = json ? ctx.io.stderr : ctx.io.stdout;
-    show(renderReceipt(preview, null));
+    show(renderPreview(preview, styleFor(ctx, json ? 'stderr' : 'stdout')));
     const answer = (deps.confirm ?? terminalConfirm)(`Delete ${count} item${count === 1 ? '' : 's'}?`);
     if (answer === null) {
         return usageError(ctx, name, 'refusing to delete without a terminal to ask; pass --yes');

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export { classifyLocalBranch, classifyRemoteBranch, gatherLocalBranches, gatherR
 export { classifyWorktree, gatherWorktrees, hasBlockers, worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand, type WorktreeBlocker, } from './worktrees.ts';
 export { DiscoveryFailed, discoverRepo } from './discover.ts';
 export { assessLanding, patchEquivalent, type Landing, type LandingCheck } from './landing.ts';
-export { ApplyArgumentError, applyPlan, type RowSelection, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
+export { ApplyArgumentError, ApplyRefused, applyPlan, type RowSelection, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
 export type { Annotate, HostHooks } from './hooks.ts';
 export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, type Plan, type PlanRepo, type PlannableRow, } from './plan.ts';
 export { RECEIPT_VERSION, ReceiptSchema, type Dropped, type Receipt, type RowRef, type Step, } from './receipt.ts';

package/dist/index.js

@@ -18,7 +18,7 @@ export { classifyLocalBranch, classifyRemoteBranch, gatherLocalBranches, gatherR
 export { classifyWorktree, gatherWorktrees, hasBlockers, worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand, } from "./worktrees.js";
 export { DiscoveryFailed, discoverRepo } from "./discover.js";
 export { assessLanding, patchEquivalent } from "./landing.js";
-export { ApplyArgumentError, applyPlan, parseGrant, parseRowRef, } from "./apply.js";
+export { ApplyArgumentError, ApplyRefused, applyPlan, parseGrant, parseRowRef, } from "./apply.js";
 export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, } from "./plan.js";
 export { RECEIPT_VERSION, ReceiptSchema, } from "./receipt.js";
 export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, } from "./processes.js";

package/dist/plan.d.ts

@@ -29,6 +29,7 @@ export declare const PlanRepoSchema: z.ZodObject<{
     remote: z.ZodNullable<z.ZodString>;
     no_gh: z.ZodBoolean;
     branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    fetch: z.ZodDefault<z.ZodBoolean>;
     rows: z.ZodArray<z.ZodObject<{
         category: z.ZodEnum<{
             local_branch: "local_branch";
@@ -53,6 +54,7 @@ export declare const PlanSchema: z.ZodObject<{
         remote: z.ZodNullable<z.ZodString>;
         no_gh: z.ZodBoolean;
         branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        fetch: z.ZodDefault<z.ZodBoolean>;
         rows: z.ZodArray<z.ZodObject<{
             category: z.ZodEnum<{
                 local_branch: "local_branch";
@@ -89,6 +91,7 @@ export declare function planRepo(root: string, opts: {
     remote: string | null;
     noGh: boolean;
     branch?: string | null;
+    fetch?: boolean;
 }, items: readonly PlannableRow[]): PlanRepo;
 /** A UTC timestamp safe in a file name, e.g. `2026-10-04T12-30-05-123Z`. */
 export declare function fileStamp(d: Date): string;

package/dist/plan.js

@@ -23,6 +23,12 @@ export const PlanRepoSchema = z.object({
     no_gh: z.boolean(),
     /** The `branch` the sweep was narrowed to; the re-sweep uses the same. */
     branch: z.string().nullable().default(null),
+    /**
+     * Whether the sweep fetched before classifying. The re-sweep fetches too, so
+     * it judges against the remote's current default branch, as the sweep did.
+     * A plan written before this field reads as not fetched.
+     */
+    fetch: z.boolean().default(false),
     rows: z.array(PlanRowSchema),
 });
 export const PlanSchema = z.object({
@@ -78,7 +84,14 @@ export function planRepo(root, opts, items) {
             fingerprint: fingerprint(item),
         });
     }
-    return { root, remote: opts.remote, no_gh: opts.noGh, branch: opts.branch ?? null, rows };
+    return {
+        root,
+        remote: opts.remote,
+        no_gh: opts.noGh,
+        branch: opts.branch ?? null,
+        fetch: opts.fetch ?? false,
+        rows,
+    };
 }
 /** A UTC timestamp safe in a file name, e.g. `2026-10-04T12-30-05-123Z`. */
 export function fileStamp(d) {

package/dist/receipt.d.ts

@@ -26,6 +26,7 @@ export declare const DroppedSchema: z.ZodObject<{
         "facts-changed": "facts-changed";
         "not-authorized": "not-authorized";
         duplicate: "duplicate";
+        kept: "kept";
     }>;
     detail: z.ZodString;
 }, z.core.$strip>;
@@ -41,6 +42,7 @@ export declare const StepSchema: z.ZodObject<{
         id: z.ZodString;
     }, z.core.$strip>>;
     action: z.ZodEnum<{
+        "verify-remote": "verify-remote";
         "unlock-worktree": "unlock-worktree";
         "remove-worktree": "remove-worktree";
         "delete-local": "delete-local";
@@ -85,6 +87,7 @@ export declare const ReceiptSchema: z.ZodObject<{
             "facts-changed": "facts-changed";
             "not-authorized": "not-authorized";
             duplicate: "duplicate";
+            kept: "kept";
         }>;
         detail: z.ZodString;
     }, z.core.$strip>>;
@@ -99,6 +102,7 @@ export declare const ReceiptSchema: z.ZodObject<{
             id: z.ZodString;
         }, z.core.$strip>>;
         action: z.ZodEnum<{
+            "verify-remote": "verify-remote";
             "unlock-worktree": "unlock-worktree";
             "remove-worktree": "remove-worktree";
             "delete-local": "delete-local";

package/dist/receipt.js

@@ -13,6 +13,7 @@ export const DroppedSchema = RowRefSchema.extend({
         'facts-changed',
         'not-authorized',
         'duplicate',
+        'kept',
     ]),
     detail: z.string(),
 });
@@ -21,6 +22,7 @@ export const StepSchema = z.object({
     /** Null for the closing prune, which belongs to no row. */
     row: RowRefSchema.nullable(),
     action: z.enum([
+        'verify-remote',
         'unlock-worktree',
         'remove-worktree',
         'delete-local',

package/dist/remote-mirror.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Sweep a remote with no checkout of your own: a clone of it, kept in
+ * repo-cleaner's cache directory, stands in for the checkout.
+ *
+ * The clone is `--no-checkout`, so no files are written outside `.git`. It is
+ * not a partial (`--filter=blob:none`) clone: the patch comparison that
+ * finds squash-merged branches reads file contents, and a partial clone
+ * 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
+ * from there. A later run reuses it, and the sweep's fetch brings it up to
+ * date.
+ */
+import type { CommandRunner } from '@osdlc/command-seam';
+/** A remote URL that cannot be mirrored, or a mirror that cannot be made or reused. */
+export declare class RemoteMirrorError extends Error {
+    constructor(message: string);
+}
+/**
+ * `text` with every URL's credentials removed: the user-info before `@` in a
+ * `scheme://` URL, and any query string or fragment. For a message or a name
+ * that must not carry a token.
+ */
+export declare function redactUrl(text: string): string;
+/**
+ * The directory name for `url`'s mirror: readable `host-owner-repo`, then a
+ * hash of the whole URL so two URLs never share a mirror. The readable part
+ * is read from the URL with its credentials, query and fragment removed, so a
+ * token never reaches the name.
+ */
+export declare function mirrorName(url: string): string;
+/**
+ * Why `dir` is not a mirror of `url` — or of whatever it was cloned from, when
+ * `url` is omitted — or null when it is. A mirror's `origin` has one fetch URL
+ * and pushes to that URL alone, so a delete cannot be sent elsewhere.
+ */
+export declare function mirrorProblem(dir: string, url?: string, opts?: {
+    git?: CommandRunner | undefined;
+}): string | null;
+/**
+ * The directory of `url`'s mirror under `cacheDir`, cloned on first use. An
+ * existing mirror is reused as it is, once {@link mirrorProblem} finds
+ * nothing wrong with it; the sweep's own fetch brings it up to date. A first
+ * clone goes to a sibling directory and is renamed into place, so a clone
+ * that fails leaves nothing behind, and a run that loses a race to clone the
+ * same URL uses the winner's clone. Messages carry the URL with its
+ * credentials removed.
+ *
+ * @throws RemoteMirrorError when `url` is empty or looks like an option, when
+ *   the clone fails, or when the directory is not a mirror of `url`.
+ */
+export declare function ensureMirror(url: string, cacheDir: string, opts?: {
+    git?: CommandRunner | undefined;
+}): string;