@osdlc/repo-cleaner 0.11.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @osdlc/repo-cleaner
 
+## 0.14.0
+
+### Minor Changes
+
+- cde983c: Pull request evidence now comes from a provider, and GitLab is one (prototype). `--provider auto|github|gitlab|none` on every sweeping command picks it; `auto`, the default, reads the remote's host, so a `gitlab` host asks `glab` for merge requests and any other host asks `gh` as before. `--no-gh` is `--provider none`. A plan records the choice for `apply`'s re-check. **Breaking (library):** `RepoInfo.provider` says which provider was asked and what its probe found, and replaces `hasGh` and `ghAuthenticated`. The `noGh` sweep and plan option is now `noProvider`. `fetchPrs` takes a provider (`githubProvider(gh)` for the old `Gh` form), and its third argument is an exact branch, not a prefix. The plan file keeps its `no_gh` field. Not yet done: Gitea, Forgejo, Bitbucket, a host-to-provider config, GitLab squash metadata, and GitLab installed under a sub-path. Without `--remotes` no provider is asked.
+
+## 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

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
@@ -39,7 +74,7 @@ Three signals settle most items. The first two are enough alone; the third needs
 
 | Signal | Source |
 | --- | --- |
-| A `MERGED` pull request from this repository, into the default branch, whose head commit is the branch tip | `gh pr list`, one listing per repository |
+| A `MERGED` pull request from this repository, into the default branch, whose head commit is the branch tip | `gh pr list` (or `glab` for GitLab), one listing per repository |
 | The branch tip is reachable from the default branch | `git merge-base --is-ancestor` |
 | The branch's changes are on the default branch under other commit ids (rebase merge, cherry-pick, squash merge) | `git cherry` plus `git merge-tree`, see [Patch equivalence](#patch-equivalence) |
 
@@ -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`:
 
@@ -180,8 +226,9 @@ table cannot be read the worktree is held back as `process-probe-failed`. A
 host or test supplies its own probe.
 Nothing is ever killed.
 
-Without `gh`, or without authentication, classification proceeds on git
-evidence alone and the report says so.
+Without the provider's CLI (`gh`, or `glab` for GitLab), or without
+authentication, classification proceeds on git evidence alone and the report
+says so. See [Providers (prototype)](#providers-prototype).
 
 Every branch delete names the full sha the sweep judged. `update-ref -d` and
 the pinned `--force-with-lease` push both refuse when the branch has moved
@@ -213,7 +260,7 @@ 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  prune  review   keep
   local branches      12       8       6      0       1      5
@@ -299,12 +346,14 @@ 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`) |
 | `--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` | Classify on git evidence alone |
-| `--no-fetch` | Skip the fetch; the header then says `not fetched` |
+| `--provider <name>` | With `--remotes`: where pull requests come from: `auto` (default, by the remote's host), `github`, `gitlab` or `none` |
+| `--no-gh` | With `--remotes`: classify on git evidence alone; the same as `--provider none`. Without `--remotes`, no provider is asked |
+| `--no-fetch` | With `--remotes`: skip the fetch; the header then says `not fetched`. Without `--remotes`, nothing is fetched |
 
 `status` also takes:
 
@@ -338,7 +387,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
@@ -383,7 +465,7 @@ that swept, or read its plan from stdin, writes a receipt only when
 ```ts
 import { sweepRepo, sweepRepos } from '@osdlc/repo-cleaner'
 
-const sweep = sweepRepo('/Users/me/work/api', { noGh: true })
+const sweep = sweepRepo('/Users/me/work/api', { noProvider: true })
 for (const item of sweep.items) {
   console.log(item.classification, item.id, item.reason)
 }
@@ -398,7 +480,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
 
@@ -417,10 +499,49 @@ or `needs-investigation`.
 An issue tracker's linkage, applied this way, is a host's own layer over the
 sweep and `applyPlan`.
 
+## Providers (prototype)
+
+Pull request evidence comes from a provider. Classification reads the same
+fields whichever one answered: number, state, head branch, head commit, target
+branch.
+
+| Provider | CLI | Listing |
+| --- | --- | --- |
+| `github` | `gh` | `gh pr list --state all`, up to 300 |
+| `gitlab` | `glab` | `glab api projects/<path>/merge_requests?state=all`, 100 a page, up to 300 |
+
+`--provider auto` (the default) reads the remote's host: a host with `gitlab`
+in its name is GitLab, any other is GitHub, which is what the tool did before
+providers existed. Name one with `--provider github|gitlab` for a host the
+name does not give away, or `--provider none` to skip pull requests. A plan
+records the choice, so `apply` re-checks with the same provider.
+
+GitLab maps onto the same evidence: `opened` and `locked` are `OPEN`, `merged`
+is `MERGED`, `closed` is `CLOSED`, `sha` is the head commit and `target_branch`
+the base. A merge request from a fork (source project is not the target
+project) is dropped, as a cross-repository PR is on GitHub. The project path is
+read off the remote URL with its groups (`group/sub/name`), and `glab` is asked
+for that host with `--hostname`.
+
+Not done yet:
+
+- Gitea, Forgejo and Bitbucket.
+- Mapping a self-hosted host to a provider in config; today it is the host
+  name or `--provider`.
+- Auth edge cases: tokens without API scope, `glab` signed in to a different
+  host than the remote, rate limits. Each reads as "no PR found".
+- Squash metadata. GitLab reports `squash_commit_sha`; it is not used, so a
+  squashed MR proves landing only by its head commit, as on GitHub.
+- GitLab under a sub-path (`https://host/gitlab/group/proj`). The URL does not
+  say where the install ends and the project begins, so the whole path is read
+  as the project, `glab` is asked for a project that does not exist, and the
+  listing fails. That reads as "no PR found": rows stay at `review`, nothing is
+  deleted on its account.
+
 ## Runtime dependencies
 
-`git` on `PATH`, and `gh` when PR state should count. Authentication is `gh`'s
-own — this package reads no token.
+`git` on `PATH`, and `gh` (or `glab` for GitLab) when PR state should count.
+Authentication is the CLI's own — this package reads no token.
 
 ## Running from a checkout
 

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';
@@ -26,9 +26,10 @@ export interface Grant {
     row: RowRef | null;
 }
 export interface ApplyOptions extends HostHooks {
-    /** Injected runners. Defaults spawn the real `git` and `gh`. */
+    /** Injected runners. Defaults spawn the real `git`, `gh` and `glab`. */
     git?: CommandRunner | undefined;
     gh?: CommandRunner | undefined;
+    glab?: CommandRunner | undefined;
     /**
      * Answers lock-owner and working-directory questions, for the re-sweep and
      * for the checks just before an unlock and a remove. Defaults to `ps` and
@@ -61,14 +62,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,19 +81,29 @@ 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];
     }
     const sweep = sweepRepo(repo.root, {
         remote: repo.remote,
-        noGh: repo.no_gh,
+        noProvider: repo.no_gh,
+        provider: repo.provider,
         branch: repo.branch ?? undefined,
+        fetch: opts.fetch ?? repo.fetch,
+        scope,
         cwd: opts.callerCwd,
         git: opts.git,
         gh: opts.gh,
+        glab: opts.glab,
         probe: opts.probe,
         onProgress: opts.onSweepProgress,
     });
@@ -99,11 +113,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 +174,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 +189,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 +224,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 +296,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 +362,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 +382,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 +430,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 +460,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 +485,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 +507,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/branches.d.ts

@@ -25,6 +25,8 @@ export declare function recordPr(facts: Record<string, unknown>, pr: PRInfo | un
     landed: boolean;
     gap: PrEvidenceGap | null;
 };
+/** Why a branch has no PR, naming where the sweep looked. */
+export declare function noPrSentence(repo: RepoInfo): string;
 /** One sentence on why a merged PR did not count, for `investigationParts`. */
 export declare function gapSentence(pr: PRInfo, gap: PrEvidenceGap, repo: RepoInfo): string;
 /**

package/dist/branches.js

@@ -53,6 +53,13 @@ export function recordPr(facts, pr, tip, repo) {
     out['evidence'] = verdict === true ? 'exact-head' : verdict;
     return verdict === true ? { landed: true, gap: null } : { landed: false, gap: verdict };
 }
+/** Why a branch has no PR, naming where the sweep looked. */
+export function noPrSentence(repo) {
+    const provider = repo.provider;
+    if (provider === null)
+        return 'No PR lookup (no provider).';
+    return `No ${provider.noun} found via \`${provider.listing}\`.`;
+}
 /** One sentence on why a merged PR did not count, for `investigationParts`. */
 export function gapSentence(pr, gap, repo) {
     return gap === 'other-base'
@@ -233,9 +240,7 @@ export function classifyLocalBranch(opts) {
         : `Branch \`${name}\` is not an ancestor of \`${compareRef}\`.`;
     const parts = [lead];
     parts.push(upstream ? `Tracks \`${upstream}\` (${track || 'in sync'}).` : 'Has no upstream.');
-    parts.push(pr
-        ? `Associated PR #${pr.number} is ${pr.state} (${pr.url}).`
-        : 'No PR found via `gh pr list`.');
+    parts.push(pr ? `Associated PR #${pr.number} is ${pr.state} (${pr.url}).` : noPrSentence(repo));
     if (pr && gap)
         parts.push(gapSentence(pr, gap, repo));
     const unmatched = patch === null ? null : unmatchedSentence(patch, repo);

package/dist/cli.d.ts

@@ -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;