@osdlc/repo-cleaner 0.10.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @osdlc/repo-cleaner
 
+## 0.13.0
+
+### Minor Changes
+
+- 3005587: A clean worktree merged into the default branch by ancestry alone is now `safe-to-delete` when its branch shows it was worked on: its reflog records a commit, cherry-pick, `am`, or a merge or pull that made a merge commit, or it tracks a branch on a remote other than the default branch. The sign is in the new `facts.branch_used` (`commits`, `upstream` or `null`). A worktree that looks freshly made from the default branch stays `needs-investigation`, as before. (#582)
+  
+  A plan now records, per repository, whether its sweep fetched (`fetch`, default `false` for older plans), and `applyPlan` fetches before its re-check when it did, so the re-check judges against the same current default branch. `ApplyOptions.fetch` overrides it. A failed fetch fails the run before any step. (#584)
+  
+  New `ApplyOptions.keep` and `apply --keep remote_branch:<remote>/<branch>`: keep a remote branch while its other rows are applied, and refuse the run if its tip moved. The re-check throws the new `ApplyRefused` when a kept branch is gone or moved since the plan, and a `verify-remote` step, run before any delete, checks the tip again with `ls-remote`. Only the tip is compared, so PR facts that changed do not refuse it, and another clone of the same remote drops its row for the kept branch with the new reason `kept`. The receipt's step `action` gains `verify-remote`, and `dropped[].reason` gains `kept`. (#583)
+
+### Patch Changes
+
+- 9948d90: In a project that has this tool in its `node_modules`, the global command now runs the project's copy, unless a `dev link` or `<NAME>_HOME` checkout is set. Set `<NAME>_PROJECT=0` to keep the global copy.
+- 79407f5: Depend on `zod` `^4.6.6` instead of exactly `4.4.3`. 4.4.3 is covered by GHSA-mrhx-c7xc-m3w5 (memory exhaustion validating an oversized constrained collection; fixed in 4.6.6), and the exact pin made a consumer that already had a fixed `zod` install a second, vulnerable copy.
+- Updated dependencies [9948d90]
+  - @osdlc/cli-tool@0.14.0
+
+## 0.12.0
+
+### Minor Changes
+
+- 8c832df: **Breaking:** a sweep is local and offline by default. Every sweeping command now reads worktrees and local branches only, fetches nothing and never calls `gh`, which is much faster. `--remotes` (or `--only remotes`, or `--remote-url`) turns on all three: the fetch, the `gh` pull-request lookup and remote branches. `--no-fetch` and `--no-gh` still turn one off again. A local text report ends with a line saying what it left out. A plan written from a local sweep records `no_gh`, so `apply` does not call `gh` either. `--branch` follows the same rule: its remote branch is included only with `--remotes`.
+  
+  `apply` re-checks only the categories its selected rows are in, so applying local rows from a plan no longer compares every remote branch again.
+  
+  On a terminal, the report, the counts and the apply preview are colored: red for delete, blue for prune, yellow for review and skipped rows, green for keep. `NO_COLOR` turns it off; a pipe or file gets none unless `FORCE_COLOR` asks for it. The preview shown before `Delete N items?` now lists, per repository, each row to delete or prune with its command beneath, each skipped row with its reason, and the counts, with terminal controls stripped from paths, names and commands.
+  
+  On a terminal, a long sweep step draws a progress bar on the status line. `apply` draws its steps as a vertical list redrawn in place: each row has its own bar, empty while waiting, half full while running, full with `✓` or `✗` when done, plus a bar for the whole run; a list taller than the terminal keeps the running step in view, and a failed step's error follows in full. It does not list the steps again under the counts. `ApplyOptions.onStart` (the planned steps, updated in place as they run) and `ApplyOptions.onStepDone` (each step after it finishes) are new.
+
+## 0.11.0
+
+### Minor Changes
+
+- 14d4351: A worktree row whose directory is gone, or is no longer a checkout, now reads `prune` instead of `delete` in the report, and `summary` counts those rows in a `prune` column (and a `prune` count in each JSON bucket, a part of `safe-to-delete`). The row's `action` is `prune`.
+  
+  New `--remote-url <url>` on every sweeping command: sweep a remote's branches with no checkout of your own. The URL is cloned once (`--no-checkout`) under the cache directory and reused; deletes are pushed from that clone, so a plan written with `--remote-url` can be applied later from anywhere.
+
+### Patch Changes
+
+- Updated dependencies [14d4351]
+- Updated dependencies [dd2265e]
+  - @osdlc/cli-tool@0.13.0
+
 ## 0.10.1
 
 ### Patch Changes

package/README.md

@@ -2,17 +2,52 @@
 
 What has been merged into the default branch, and what can go away.
 
-Point it at a repository and it inventories the local branches, worktrees and
-remote branches, classifying each as `safe-to-delete`, `safe-to-keep` or
-`needs-investigation` — with the evidence behind the verdict and the literal
-command that would act on it.
+Point it at a repository and it inventories the local branches and
+worktrees, and with `--remotes` the remote branches too, classifying each
+as `safe-to-delete`, `safe-to-keep` or `needs-investigation` — with the
+evidence behind the verdict and the literal command that would act on it.
 
 `repo-cleaner` (or `repo-cleaner status`) never deletes anything. It prints
 the commands that would. `repo-cleaner apply` deletes: it checks each row
-again, shows you the steps and asks before it runs them.
+again, shows you what it will delete and skip, and asks before it runs.
+
+By default it works on your own machine only: worktrees and local branches,
+nothing fetched and no `gh` call, compared with the `origin/<default>` you
+last fetched (the header says `not fetched`). `--remotes` (or `--only
+remotes`, or `--remote-url`) turns on all three things that need the
+network: it fetches each remote first, asks `gh` about pull requests, and
+sweeps remote branches. Remote branches are shared, often number in the
+hundreds, and each one is compared with the default branch, so they make a
+sweep much slower. A local report ends with a line saying what it left out.
+
+Without `gh`, a squash-merged branch is still found by comparing patches,
+and a clean worktree merged by ancestry is `delete` once its branch shows
+it was worked on (see [How it decides](#how-it-decides)); one that looks
+freshly made stays `review`.
+
+On a terminal, a long sweep step draws a progress bar on stderr, and
+`apply` draws its steps as a list that updates in place: each row has its
+own bar, empty while it waits, half full while it runs and full with a `✓`
+(or `✗`) when it is done, with a bar for the whole run underneath:
+
+```text
+  ██████████ ✓ delete  local_branch  feat/a
+  █████░░░░░ › delete  local_branch  feat/b
+  ░░░░░░░░░░   delete  remote_branch  origin/feat/b
+  ░░░░░░░░░░   prune
+  ████████░░░░░░░░░░░░░░░░░░░░░░ 1/4
+```
+
+A list taller than the terminal scrolls to keep the running step in view.
+A failed step's error is printed in full under the list.
+
+On a terminal, the report and the apply preview are colored: red for a
+delete, blue for a prune, yellow for a review or a skipped row, green for a
+keep. `NO_COLOR` turns this off. A pipe or a file gets no color unless
+`FORCE_COLOR` asks for it.
 
 ```console
-$ repo-cleaner
+$ repo-cleaner --remotes
 /Users/me/work/api  (acme/api, default main, origin)
   local_branch   fix/login-redirect   delete  PR #412 merged
                  git update-ref -d refs/heads/fix/login-redirect 3f9c2e1d8b7a6c5d4e3f2a1b0c9d8e7f6a5b4c3d
@@ -56,6 +91,17 @@ holding uncommitted or unpushed work is never proposed for removal whatever
 else is true of it — losing an hour of someone's work costs more than any
 amount of clutter.
 
+A clean worktree whose HEAD is merged by ancestry alone, with no merged PR
+or patch match, needs one more sign, because a worktree that `git worktree
+add -b` just made from the default branch is merged that way too, and
+removing it would lose the ignored files of work about to start. The sign is
+in `facts.branch_used`: `commits` when the branch's reflog records a commit,
+cherry-pick, `am`, or a merge or pull that made a merge commit (a
+fast-forward only moves the branch), and `upstream` when the branch
+tracks a branch on a remote, other than the default branch (a branch made
+with `--track` from `main` or `origin/main` does not count). With either, the worktree
+is `safe-to-delete`; with neither (`null`) it stays `needs-investigation`.
+
 Some worktrees are held back whatever their branch says. Each lands in
 `facts.blockers`, and the row carries no command and has `deletable: false`:
 
@@ -205,7 +251,7 @@ worktree, the primary or caller's worktree) has `deletable: false`.
 
 ```bash
 repo-cleaner [status]   # the report: what is merged, what can go (the default)
-repo-cleaner summary    # counts per repository: total, merged, delete, review, keep
+repo-cleaner summary    # counts per repository: total, merged, delete, prune, review, keep
 repo-cleaner plan       # the deletable rows as a plan, to stdout or -o <file>
 repo-cleaner apply      # re-check, show the steps, ask, delete
 ```
@@ -213,16 +259,23 @@ repo-cleaner apply      # re-check, show the steps, ask, delete
 All four take the same paths and sweep options.
 
 ```console
-$ repo-cleaner summary
+$ repo-cleaner summary --remotes
 /Users/me/work/api  (acme/api, default main, origin)
-                   total  merged  delete  review   keep
-  local branches      12       8       6       1      5
-  worktrees            4       3       2       1      1
-  remote branches     40      31      30       6      4
+                   total  merged  delete  prune  review   keep
+  local branches      12       8       6      0       1      5
+  worktrees            4       3       1      1       1      1
+  remote branches     40      31      30      0       6      4
 
-38 to delete, 8 to review, across 1 repository.
+37 to delete, 1 to prune, 8 to review, across 1 repository.
 ```
 
+`prune` counts worktree rows whose directory is gone, or is no longer a
+checkout: deleting one runs `git worktree prune` to drop the stale link, and
+a directory that is still there stays. The report labels those rows `prune`
+rather than `delete`. In `--output json` they are `safe-to-delete` with
+`action: "prune"`, and each summary bucket has a `prune` count, a part of its
+`safe-to-delete` count.
+
 `merged` counts rows whose work is on the default branch: by ancestry, by a
 merged PR at the branch's head, or by a patch match. A branch checked out in a
 worktree counts as merged by ancestry or PR alone. The default branch and the
@@ -258,17 +311,47 @@ An entry that resolves to nothing is reported rather than dropped. A worklist
 that silently sweeps four of the five repositories it was given is worse than
 one that says which it could not find.
 
+### A remote with no checkout
+
+```bash
+repo-cleaner --remote-url git@github.com:acme/api.git
+repo-cleaner apply --remote-url git@github.com:acme/api.git
+```
+
+`--remote-url <url>` sweeps a remote's branches when you have no checkout of
+it. It clones the URL once, with `--no-checkout`, into
+`repo-cleaner/remotes/` under the cache directory (`~/Library/Caches` on
+macOS, `$XDG_CACHE_HOME` or `~/.cache` on Linux, `REPO_CLEANER_CACHE_DIR`
+to move it), and sweeps that clone. Later runs reuse the clone and fetch. Only remote branches
+are swept: the clone's own branches and worktree are not yours. Deletes are
+pushed to the URL from the clone, compare-and-swap as always.
+
+The clone is kept, not deleted after the run, so a plan written with
+`--remote-url` can be applied later from anywhere: the plan names the clone's
+directory. Remove the directory to drop it. The clone is a full one, not
+`--filter=blob:none`: the patch check reads file contents, and a partial
+clone fetches them one branch at a time.
+
+The flag repeats for several remotes. It does not combine with paths,
+`--branch` or `--plan`, `--only` may only name `remotes`, and an empty URL is
+refused. A clone is reused only while its `origin` fetches from that URL and
+pushes to it alone; `apply --plan` checks the same of a plan's clone before
+deleting. The clone's directory name and every message carry the URL with
+its credentials, query and fragment removed.
+
 ## Options
 
 Every command that sweeps takes these:
 
 | Flag | Effect |
 | --- | --- |
-| `--only <list>` | `worktrees`, `branches`, `remotes` (default: all three) |
-| `--branch <name\|HEAD>` | One branch of this repository: its worktree, local and remote branch. Refuses the default branch |
+| `--only <list>` | `worktrees`, `branches`, `remotes` (default: `worktrees,branches`) |
+| `--remotes` | Also sweep remote branches. Slower: each one is compared with the default branch |
+| `--branch <name\|HEAD>` | One branch of this repository: its worktree and local branch, and its remote branch with `--remotes`. Refuses the default branch |
 | `--remote <name>` | Remote to measure against (default `origin`) |
-| `--no-gh` | Classify on git evidence alone |
-| `--no-fetch` | Skip the fetch; the header then says `not fetched` |
+| `--remote-url <url>` | Sweep this remote's branches with no checkout of your own (see [A remote with no checkout](#a-remote-with-no-checkout)); repeatable |
+| `--no-gh` | With `--remotes`: classify on git evidence alone. Without `--remotes`, `gh` is never called |
+| `--no-fetch` | With `--remotes`: skip the fetch; the header then says `not fetched`. Without `--remotes`, nothing is fetched |
 
 `status` also takes:
 
@@ -302,7 +385,40 @@ with `--row <category>:<id>` to apply it, review rows included.
 Before it deletes anything, `apply` sweeps again and drops a row that is gone,
 no longer deletable, whose facts moved, or that carries a risk you did not
 accept with `--allow <risk>` (every row) or `--allow <risk>=<category>:<id>`
-(one row). It prints the steps it would run and asks `Delete N items? [y/N]`.
+(one row). It then shows, per repository, each row it will delete or prune
+with the command under it, each row it will skip and why, and the counts, and
+asks `Delete N items? [y/N]`:
+
+```text
+/Users/me/work/api
+  delete  local_branch   fix/login-redirect
+          git update-ref -d refs/heads/fix/login-redirect 3f9c2e1d…
+  prune
+          git -C /Users/me/work/api worktree prune
+  skip    worktree       /Users/me/work/api/wt/spike
+          needs-review: clean but no clear disposability signal; name it with --row to apply it
+
+would delete: 1 local branch
+dropped 1: 1 needs-review
+Delete 2 items? [y/N]
+```
+
+The re-check reads only the categories the selected rows are in, so applying
+a plan of local rows does not compare every remote branch again. A plan
+records in each repository's `fetch` whether its sweep fetched; the re-check
+fetches too when it did, so it judges against the same, current default
+branch. A plan written before that field re-checks without fetching.
+
+`--keep remote_branch:<remote>/<branch>` keeps a remote branch while the
+rest of its rows go: say, delete the worktree and local branch but leave
+the branch on the remote. A kept row is checked, not skipped. The re-check
+refuses the run if the branch is gone or its tip moved since the plan, and
+the run's first step checks the tip again with `git ls-remote`, so one that
+moves after the re-check stops the run before anything is deleted. Only the
+tip counts: a PR that closed since the plan does not refuse it. Another
+clone of the same remote does not delete a kept branch either; its row is
+dropped as `kept`. The row id is the one the plan lists,
+`<remote>/<branch>`, e.g. `origin/feat/x`.
 `--yes` skips the question. With no terminal to ask on and no `--yes`, it
 refuses with exit 2 rather than deleting. `--plan -` needs `--yes` or
 `--dry-run`, because stdin carries the plan. `--dry-run` prints the steps and
@@ -362,7 +478,7 @@ back as `error`, because a fan-out must not end on its first bad entry.
 before classifying, so ancestry is read against fresh remote-tracking refs.
 That fetch is the only write. A repository whose fetch fails comes back with `error` starting
 `fetch failed:` and no items. `repo.fetched` says which case applied. The
-library default is off; the CLI fetches unless given `--no-fetch`.
+library default is off; the CLI fetches with `--remotes`, unless given `--no-fetch`.
 
 ### Adding knowledge the library does not have
 

package/dist/apply.d.ts

@@ -14,7 +14,7 @@
  * Branch deletes are compare-and-swap on the planned sha. Every step is
  * verified, and the receipt is rewritten after each.
  */
-import type { CommandRunner } from '@osdlc/command-seam';
+import { type CommandRunner } from '@osdlc/command-seam';
 import type { HostHooks } from './hooks.ts';
 import { type ProcessProbe } from './processes.ts';
 import { type Plan } from './plan.ts';
@@ -61,14 +61,43 @@ export interface ApplyOptions extends HostHooks {
     swept?: ReadonlyMap<string, readonly SweepItem[]> | undefined;
     /** Rows dropped before this run, such as by a preview; recorded first in the receipt. */
     dropped?: readonly Dropped[] | undefined;
+    /**
+     * Remote branch rows to keep: not deleted, but checked. Each must be a
+     * `remote_branch` row of the plan; its id is `<remote>/<branch>`, as in the
+     * plan, e.g. `origin/topic`. The re-check refuses the run with
+     * {@link ApplyRefused} when a kept branch is gone or its tip is not the
+     * planned one, and the run's first steps check each tip again with
+     * `ls-remote`, so a branch that moves after the re-check stops the run
+     * before anything is deleted. A kept row cannot also be selected.
+     */
+    keep?: readonly RowSelection[] | undefined;
+    /**
+     * Fetch each repository's remote before the re-sweep. Defaults to what the
+     * plan repository records in `fetch`: a plan swept after a fetch is
+     * re-checked after one. Remote branch tips are read live either way; the
+     * fetch moves the default branch those tips and the local refs are judged
+     * against. A failed fetch fails the run before any step.
+     */
+    fetch?: boolean | undefined;
     /** Passed to the re-sweep's `onProgress`, for a status line. */
     onSweepProgress?: ((progress: SweepProgress) => void) | undefined;
+    /**
+     * Told once the steps are planned, before the first runs, with the list
+     * itself: each step's `result` is updated in place as the run goes. Not
+     * called under `dryRun`.
+     */
+    onStart?: ((steps: readonly Step[]) => void) | undefined;
     /** Told before each step runs: its 0-based index, the step count and the step. Not called under `dryRun`. */
     onStep?: ((index: number, total: number, step: Step) => void) | undefined;
+    /** Told after each step, with its `result` set (`ok`, or `failed` and the run stops), before the receipt is saved. Not called under `dryRun`. */
+    onStepDone?: ((index: number, total: number, step: Step) => void) | undefined;
 }
 /** A selection or grant the plan cannot satisfy. Nothing has been touched. */
 export declare class ApplyArgumentError extends Error {
 }
+/** A kept row is gone or moved since the plan, so the run refuses. Nothing has been touched. */
+export declare class ApplyRefused extends Error {
+}
 /** `<category>:<id>`, split at the first colon. */
 export declare function parseRowRef(text: string): RowRef;
 /** `<name>` for every row, or `<name>=<category>:<id>` for one. */

package/dist/apply.js

@@ -16,18 +16,22 @@
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { shellJoin } from '@osdlc/command-seam';
 import { CommandFailed, Git, PUSH_REJECTIONS } from '@osdlc/typed-git';
 import { localDeleteCommand, remoteDeleteCommand } from "./branches.js";
 import { busyHolders, defaultProcessProbe, parseLockOwner } from "./processes.js";
 import { PLAN_CATEGORIES, fingerprint, isPlanCategory, sameFingerprint, } from "./plan.js";
 import { RECEIPT_VERSION } from "./receipt.js";
 import { sweepRepo } from "./sweep.js";
-import { AUTHORIZATIONS } from "./types.js";
+import { AUTHORIZATIONS, } from "./types.js";
 import { worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand } from "./worktrees.js";
 import { writeJsonAtomic } from "./write-json.js";
 /** A selection or grant the plan cannot satisfy. Nothing has been touched. */
 export class ApplyArgumentError extends Error {
 }
+/** A kept row is gone or moved since the plan, so the run refuses. Nothing has been touched. */
+export class ApplyRefused extends Error {
+}
 /** `<category>:<id>`, split at the first colon. */
 export function parseRowRef(text) {
     const colon = text.indexOf(':');
@@ -77,8 +81,14 @@ function locate(plan, rows, repoRoot) {
 function granted(grants, ref, name) {
     return grants.some((g) => g.name === name && (g.row === null || sameRow(g.row, ref)));
 }
+/** The sweep scope that gathers each row category. */
+const SCOPE_OF = {
+    worktree: 'worktrees',
+    local_branch: 'local-branches',
+    remote_branch: 'remote-branches',
+};
 /** The plan repository's rows as they stand now, with the host's overlay applied. */
-function resweep(repo, opts) {
+function resweep(repo, scope, opts) {
     const given = opts.swept?.get(repo.root);
     if (given !== undefined) {
         return [...given];
@@ -87,6 +97,8 @@ function resweep(repo, opts) {
         remote: repo.remote,
         noGh: repo.no_gh,
         branch: repo.branch ?? undefined,
+        fetch: opts.fetch ?? repo.fetch,
+        scope,
         cwd: opts.callerCwd,
         git: opts.git,
         gh: opts.gh,
@@ -99,11 +111,34 @@ function resweep(repo, opts) {
     return opts.annotate === undefined ? sweep.items : opts.annotate(sweep.repo, sweep.items);
 }
 /** Re-sweep, then split the selection into rows to run and rows dropped. */
-function recheck(selected, grants, implicit, opts) {
+function recheck(selected, kept, grants, implicit, opts) {
     const swept = new Map();
-    for (const { repo } of selected) {
-        if (!swept.has(repo))
-            swept.set(repo, resweep(repo, opts));
+    const all = [...selected, ...kept];
+    for (const { repo } of all) {
+        if (swept.has(repo))
+            continue;
+        // Only the categories the selection is in: a plan of local rows need not
+        // compare every remote branch again.
+        const scope = new Set(all.filter((s) => s.repo === repo).map((s) => SCOPE_OF[s.ref.category]));
+        swept.set(repo, resweep(repo, [...scope], opts));
+    }
+    // A kept branch is checked, not dropped: one that moved refuses the run.
+    const verified = [];
+    for (const { repo, ref } of kept) {
+        const planned = repo.rows.find((row) => sameRow(row, ref));
+        const item = swept.get(repo).find((it) => sameRow(it, ref));
+        if (item === undefined) {
+            throw new ApplyRefused(`kept ${label(ref)} is no longer in the sweep; refusing to apply`);
+        }
+        // The tip alone: a PR that closed since the plan does not move the branch.
+        const plannedSha = planned.fingerprint['sha'];
+        if (typeof plannedSha !== 'string' || shaOf(item) === null) {
+            throw new ApplyRefused(`kept ${label(ref)} has no tip to check; refusing to apply`);
+        }
+        if (shaOf(item) !== plannedSha) {
+            throw new ApplyRefused(`kept ${label(ref)} moved since the plan (planned ${String(plannedSha)}, now ${String(item.facts['sha'])}); refusing to apply`);
+        }
+        verified.push({ repo: repo.root, item, force: false });
     }
     const accepted = [];
     const dropped = [];
@@ -137,7 +172,7 @@ function recheck(selected, grants, implicit, opts) {
         }
         accepted.push({ repo: repo.root, item, force: granted(grants, ref, 'discard-changes') });
     }
-    return { accepted, dropped };
+    return { accepted, dropped, verified };
 }
 function pending(repo, row, action, command, expectedSha = null) {
     return {
@@ -152,9 +187,24 @@ function pending(repo, row, action, command, expectedSha = null) {
     };
 }
 const pruneStep = (repo, row) => pending(repo, row, 'prune-worktrees', worktreePruneCommand(repo));
+/** A row's sha fact, or null when it has none. */
+function shaOf(item) {
+    return typeof item.facts['sha'] === 'string' ? item.facts['sha'] : null;
+}
+/** A remote branch row's remote, its full ref on that remote, and its branch name. */
+function remoteRefOf(item) {
+    const branch = String(item.facts['branch']);
+    return { remote: String(item.facts['remote']), ref: `refs/heads/${branch}`, branch };
+}
+/** The step that checks a kept remote branch's tip, just before anything is deleted. */
+function verifyStep({ repo, item }) {
+    const sha = shaOf(item);
+    const { remote, ref } = remoteRefOf(item);
+    return pending(repo, { category: item.category, id: item.id }, 'verify-remote', shellJoin(['git', 'ls-remote', remote, ref]), sha);
+}
 function stepsFor({ repo, item, force }) {
     const ref = { category: item.category, id: item.id };
-    const sha = typeof item.facts['sha'] === 'string' ? item.facts['sha'] : null;
+    const sha = shaOf(item);
     switch (item.category) {
         case 'worktree': {
             // Remove and prune both skip a locked worktree, so a stale lock goes first.
@@ -172,7 +222,7 @@ function stepsFor({ repo, item, force }) {
             return [pending(repo, ref, 'delete-local', localDeleteCommand(item.id, sha ?? ''), sha)];
         case 'remote_branch':
             return [
-                pending(repo, ref, 'delete-remote', remoteDeleteCommand(String(item.facts['remote']), String(item.facts['branch']), sha ?? ''), sha),
+                pending(repo, ref, 'delete-remote', remoteDeleteCommand(remoteRefOf(item).remote, remoteRefOf(item).branch, sha ?? ''), sha),
             ];
     }
 }
@@ -244,9 +294,18 @@ function execute(step, row, git, probe) {
                 throw new Error('ref still resolves');
             return 'ref does not resolve';
         }
+        case 'verify-remote': {
+            const { remote, ref } = remoteRefOf(row.item);
+            const tip = at.lsRemote(remote, ref).find((r) => r.ref === ref);
+            if (tip === undefined)
+                throw new Error(`refused: kept ${ref} is gone from ${remote}`);
+            if (tip.sha !== step.expected_sha) {
+                throw new Error(`refused: kept ${ref} moved to ${tip.sha}, planned ${step.expected_sha}`);
+            }
+            return 'tip unchanged; kept';
+        }
         case 'delete-remote': {
-            const remote = String(row.item.facts['remote']);
-            const ref = `refs/heads/${String(row.item.facts['branch'])}`;
+            const { remote, ref } = remoteRefOf(row.item);
             const report = at.push(remote, `:${ref}`, {
                 forceWithLease: { ref, expect: step.expected_sha },
             });
@@ -301,7 +360,18 @@ function remoteKey(git, repo, remote) {
  * list its branches; deleting one twice fails the second push and stops the
  * run, so the later row is dropped as `duplicate`.
  */
-function onePerRemoteBranch({ accepted, dropped }, git) {
+function onePerRemoteBranch({ accepted, dropped, verified, }, git) {
+    const keyOf = (row) => {
+        const remote = remoteKey(git, row.repo, String(row.item.facts['remote']));
+        return remote === null ? null : `${remote}\0${remoteRefOf(row.item).branch}`;
+    };
+    // A branch kept through one clone stays, whichever clone lists it.
+    const keptAt = new Map();
+    for (const row of verified) {
+        const key = keyOf(row);
+        if (key !== null)
+            keptAt.set(key, row.repo);
+    }
     const seen = new Map();
     const kept = [];
     const extra = [];
@@ -310,8 +380,18 @@ function onePerRemoteBranch({ accepted, dropped }, git) {
             kept.push(row);
             continue;
         }
-        const remote = remoteKey(git, row.repo, String(row.item.facts['remote']));
-        const key = remote === null ? null : `${remote}\0${String(row.item.facts['branch'])}`;
+        const key = keyOf(row);
+        const keeper = key === null ? undefined : keptAt.get(key);
+        if (keeper !== undefined) {
+            extra.push({
+                repo: row.repo,
+                category: row.item.category,
+                id: row.item.id,
+                reason: 'kept',
+                detail: `the same remote branch is kept through ${keeper}`,
+            });
+            continue;
+        }
         const first = key === null ? undefined : seen.get(key);
         if (first !== undefined) {
             extra.push({
@@ -348,7 +428,19 @@ export function applyPlan(plan, requested, grants, opts) {
         : plan.repos
             .filter((r) => opts.repoRoot === undefined || resolve(r.root) === resolve(opts.repoRoot))
             .flatMap((r) => r.rows.map((row) => ({ category: row.category, id: row.id, repo: r.root })));
-    const rows = wanted.filter((row, i) => wanted.findIndex((other) => sameSelection(other, row)) === i);
+    const kept = locate(plan, opts.keep ?? [], opts.repoRoot);
+    for (const k of kept) {
+        if (k.ref.category !== 'remote_branch') {
+            throw new ApplyArgumentError(`--keep takes a remote_branch row, not ${label(k.ref)}`);
+        }
+    }
+    const isKept = (row) => kept.some((k) => sameRow(k.ref, row) &&
+        (row.repo === undefined || resolve(row.repo) === resolve(k.repo.root)));
+    for (const row of requested) {
+        if (isKept(row))
+            throw new ApplyArgumentError(`row ${label(row)} is both selected and kept`);
+    }
+    const rows = wanted.filter((row, i) => wanted.findIndex((other) => sameSelection(other, row)) === i && !isKept(row));
     if (rows.length === 0)
         throw new ApplyArgumentError('the plan has no rows to apply');
     const selected = locate(plan, rows, opts.repoRoot);
@@ -366,11 +458,15 @@ export function applyPlan(plan, requested, grants, opts) {
         dropped: [],
         steps: [],
     };
-    const rechecked = recheck(selected, grants, opts.safeOnly ?? requested.length === 0, opts);
+    const rechecked = recheck(selected, kept, grants, opts.safeOnly ?? requested.length === 0, opts);
     const { accepted, dropped } = onePerRemoteBranch(rechecked, new Git(opts.callerCwd, { runner: opts.git }));
     receipt.dropped = [...(opts.dropped ?? []), ...dropped];
     const ordered = PLAN_CATEGORIES.flatMap((category) => accepted.filter((row) => row.item.category === category));
-    const plannedSteps = ordered.flatMap((row) => stepsFor(row).map((step) => [step, row]));
+    const plannedSteps = [
+        // Kept tips first: one that moved stops the run before anything is deleted.
+        ...rechecked.verified.map((row) => [verifyStep(row), row]),
+        ...ordered.flatMap((row) => stepsFor(row).map((step) => [step, row])),
+    ];
     for (const repo of new Set(ordered.map((row) => row.repo))) {
         plannedSteps.push([pruneStep(repo, null), null]);
     }
@@ -387,6 +483,7 @@ export function applyPlan(plan, requested, grants, opts) {
             writeJsonAtomic(receiptPath, receipt);
     };
     save();
+    opts.onStart?.(receipt.steps);
     const git = new Git(opts.callerCwd, { runner: opts.git });
     const probe = opts.probe ?? defaultProcessProbe();
     // Worktrees whose lock this run cleared. typed-git has no `worktree lock`
@@ -408,9 +505,13 @@ export function applyPlan(plan, requested, grants, opts) {
             }
             receipt.status = 'failed';
             receipt.finished_at = now().toISOString();
+            // Told before the save, so a receipt that cannot be written still
+            // leaves the step's outcome on screen.
+            opts.onStepDone?.(i, plannedSteps.length, step);
             save();
             return receipt;
         }
+        opts.onStepDone?.(i, plannedSteps.length, step);
         save();
     }
     receipt.status = 'complete';

package/dist/cli.d.ts

@@ -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
  *
@@ -33,6 +33,11 @@ export interface MainDeps {
     readStdin?: () => string;
     /** Whether stderr is a terminal, so a status line may be drawn. Defaults to `isatty(2)`. */
     stderrIsTerminal?: boolean;
+    /** The terminal's size, for the live step board. Defaults to stdout's columns and rows. */
+    terminalSize?: () => {
+        width: number;
+        height: number;
+    };
 }
 /** `main(argv, ctx)`: returns an exit code, never exits. */
 export declare function main(argv: readonly string[], ctx: CliContext, deps?: MainDeps): number;