@osdlc/repo-cleaner 0.9.2 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @osdlc/repo-cleaner
 
+## 0.10.1
+
+### Patch Changes
+
+- cde11b5: `apply` fixes:
+  
+  - The run a confirmation approves keeps the safe-to-delete guard: a row that turned into a review row between the preview and the yes is dropped as `needs-review`, not run.
+  - Two clones of one remote no longer delete its branches twice. The second row is dropped as the new reason `duplicate`, naming the clone that deletes it; before, the second push was rejected and the run stopped with exit 11. Remotes are compared by the push URLs git uses (`url.*.insteadOf` applied), a network URL in any form (`git@host:o/r`, `ssh://`, `https://`) as `host/path`, and a local path as written.
+  - A swept `apply` re-checks once before asking, from the sweep it just ran, instead of sweeping again; the run that deletes still sweeps afresh.
+  - A run that deletes without a receipt file says so on stderr.
+  - Every run ends with a summary: `deleted: 1 worktree, 3 local branches, 2 remote branches`, the dropped rows by reason, and how many rows a failed run did not reach. A preview says `would delete:`. `--output json` adds a `summary` object.
+  - The prompt's `Delete N items?` counts rows, not steps: a stale-locked worktree is one item, not two.
+  - `--repo-root` naming no repository in the plan exits 1 instead of reporting nothing to delete.
+  - An empty plan's JSON receipt says `complete`, not `dry-run`, unless the run was `--dry-run`.
+  
+  Library: `ApplyOptions.safeOnly` and `ApplyOptions.swept`, the `duplicate` drop reason, `RECEIPT_VERSION`, and `summarizeReceipt`, `renderApplySummary` and `ApplySummary`.
+
+## 0.10.0
+
+### Minor Changes
+
+- 6e4284b: **Breaking:** repo-cleaner no longer reads a config file. It sweeps the repository you are in, or the paths you pass, which can be directories holding checkouts. `--all` and `--config` are removed: pass the directories instead (`repo-cleaner ~/Developer ~/work`), or keep them in a shell alias. Removed from the library: `CONFIG_ENV`, `DEFAULT_CONFIG`, `RepoCleanerConfigSchema`, `TOOL`, `clearConfigCache`, `configPath`, `configuredRepos`, `loadConfig` and `RepoCleanerConfig`. `REPO_CLEANER_MACHINE_CONFIG` is no longer read. The package no longer depends on `@osdlc/config-layers`.
+- 6e4284b: A status line on stderr while a run works: which repository (`[2/5]` in a run of several), and which step — reading the repository, fetching, listing pull requests (gh), checking worktrees, local or remote branches with a count (`37/427`) — and, in `apply`, the re-check and each delete step. It is drawn only when stderr is a terminal, erased before any other output, and turned off with `--no-progress`.
+  
+  Library: `SweepOptions.onProgress` receives a `SweepProgress` before each step and each item; `ApplyOptions.onSweepProgress` and `onStep` do the same for `applyPlan`.
+- 6e4284b: New `repo-cleaner summary`: a table per repository counting local branches, worktrees and remote branches, with how many are merged into the default branch and how many the sweep would delete, review or keep. `--output json` gives the counts without the rows.
+  
+  Each row now records `facts.merged`: true when its work is on the default branch by ancestry, an exact-head merged PR or a patch match. A branch checked out in a worktree, or at HEAD, is judged by ancestry or PR alone. The default branch and the primary or current worktree carry none. `SummaryBucket` gains `merged`, so the JSON report's `summary` counts it too.
+- 6e4284b: **Breaking:** the CLI is three commands over one set of sweep options, and `apply` asks before it deletes.
+  
+  - `repo-cleaner [status]` is the report, as before.
+  - `repo-cleaner plan` writes the plan to stdout, or to a file with `-o <file>`. It replaces `--write-plan` and `--plan-out`. Plans no longer go to a hidden directory by default.
+  - `repo-cleaner apply` sweeps and plans in memory, or reads `--plan <file>` (`-` reads stdin). With no `--row` it applies every row the re-check judges `safe-to-delete`, and drops a row to review with the new reason `needs-review`; name a review row with `--row` to apply it. It re-checks each row, prints the steps and asks `Delete N items? [y/N]`. `--yes` (`-y`) skips the question. With no terminal and no `--yes` it refuses with exit 2. `--plan -` needs `--yes` or `--dry-run`. On yes it runs only the steps it showed.
+  - `--only worktrees,branches,remotes` replaces `--scope local-branches,worktrees,remote-branches`, and works on every command.
+  - `--allow <risk>[=<category>:<id>]` replaces `--authorize`.
+  - Receipts go beside a `--plan` file as `<plan>.receipt-<timestamp>.json`, or to `--receipt <file>`. `--receipt-dir` and the default receipts directory are removed. A run that swept, or read stdin, writes a receipt only with `--receipt`.
+  
+  Library: `applyPlan` with an empty row list selects every row of the plan and drops each one not judged `safe-to-delete` (`needs-review`), and `receiptPath` may be `null` to write no receipt. New `parsePlan(text, source)`. `stampedPath` is removed; use `fileStamp`.
+
+### Patch Changes
+
+- 6e4284b: A registered worktree whose directory still exists but whose `.git` is gone (git lists it as prunable) no longer makes the whole repository unreadable with `git status: This is not a git repository`. It is a `safe-to-delete` row whose command is `git worktree prune`, which drops the registration and leaves the directory; `facts.directory_left` is true.
+- 6e4284b: `apply` fixes: a branch name two repositories share applies in both instead of failing as ambiguous; a repository the sweep could not read (such as a failed fetch) is named on stderr and exits 1 instead of reading as "nothing to delete", and `plan` does the same; the receipt file records the rows the preview dropped; a worktree's fingerprint includes `on_disk`, so a prune row whose directory came back is dropped rather than removed. The status line strips terminal controls from paths and fits wide characters to the terminal's width. A worktree's `facts.merged` counts a patch match the same way a branch's does.
+  
+  Library: `applyPlan` takes `RowSelection` rows (a row with an optional `repo`) and `ApplyOptions.dropped`.
+
+## 0.9.3
+
+### Patch Changes
+
+- e0aaba5: A remote branch delete the remote refuses now fails its step with git's reason and what it means, such as `[remote rejected] (pre-receive hook declined): A hook on the remote refused the push.`, read from typed-git's per-ref push report instead of stderr.
+- Updated dependencies [e0aaba5]
+  - @osdlc/typed-git@0.12.0
+  - @osdlc/typed-gh@0.14.1
+
 ## 0.9.2
 
 ### Patch Changes

package/README.md

@@ -7,9 +7,9 @@ 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.
 
-The sweep never deletes anything. It emits commands, and can write the
-deletable rows as a plan. `repo-cleaner apply` deletes the plan rows you
-select, after checking each one again.
+`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.
 
 ```console
 $ repo-cleaner
@@ -201,13 +201,40 @@ approves them by name:
 A row kept for structure (default branch, current HEAD, a branch held by a
 worktree, the primary or caller's worktree) has `deletable: false`.
 
+## Commands
+
+```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 plan       # the deletable rows as a plan, to stdout or -o <file>
+repo-cleaner apply      # re-check, show the steps, ask, delete
+```
+
+All four take the same paths and sweep options.
+
+```console
+$ repo-cleaner summary
+/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
+
+38 to delete, 8 to review, across 1 repository.
+```
+
+`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
+primary worktree are counted in `total` but not judged. Each row's verdict is
+in its `facts.merged`.
+
 ## Scope is opt-in
 
 ```bash
 repo-cleaner                        # the repository you are standing in
 repo-cleaner ~/work/api ~/work/web  # named repositories
 repo-cleaner ~/Developer            # every checkout under it
-repo-cleaner --all                  # every repository in the config file
 ```
 
 A bare invocation never fans out. What an argument names is read off the disk
@@ -233,88 +260,88 @@ one that says which it could not find.
 
 ## Options
 
+Every command that sweeps takes these:
+
 | Flag | Effect |
 | --- | --- |
-| `--all` | Sweep the repositories named in the config file |
-| `--config <path>` | Config file to read |
-| `--scope <list>` | `local-branches`, `worktrees`, `remote-branches` |
+| `--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 |
 | `--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` |
+
+`status` also takes:
+
+| Flag | Effect |
+| --- | --- |
 | `--keep` | Include `safe-to-keep` rows in the report |
 | `--commands` | Print the proposed commands of rows that need no authorization, and nothing else |
 | `--output json` | The full inventory, facts included |
-| `--branch <name\|HEAD>` | Sweep one branch of this repository: its worktree, local and remote branch. Refuses the default branch |
-| `--write-plan` | Write the deletable rows as a plan for `apply` |
-| `--plan-out <path>` | Write the plan here; implies `--write-plan` |
-| `--version` | Print `repo-cleaner <version>` and exit; it must be the first argument |
 
-A checkout directory named `apply` is swept as `./apply`, and one named `dev` as
-`./dev`: `dev` runs the tool from a checkout (see Running from a checkout).
+`--version` prints `repo-cleaner <version>` and exits; it must be the first
+argument. A checkout directory named like a command (`status`, `summary`,
+`plan`, `apply`, `dev`) is swept as `./status` and so on: `dev` runs the tool from a
+checkout (see Running from a checkout).
 
 ## Plan and apply
 
 ```bash
-repo-cleaner --branch HEAD --plan-out plan.json
-repo-cleaner apply --plan plan.json --row worktree:/path/to/wt --row local_branch:feat/x
+repo-cleaner apply                          # sweep, show the steps, ask, delete
+repo-cleaner apply --only worktrees --yes   # no question
+repo-cleaner plan -o plan.json              # save the plan to review or edit
+repo-cleaner apply --plan plan.json --row local_branch:feat/x
+repo-cleaner plan | repo-cleaner apply --plan - --yes
 ```
 
 A plan holds each deletable row with a fingerprint of the facts behind its
-verdict. `apply` sweeps again and drops a selected row that is gone, no longer
-deletable, whose facts moved, or whose `requires` was not granted with
-`--authorize <name>` (every row) or `--authorize <name>=<category>:<id>` (one
-row). It then removes worktrees, deletes local branches, deletes remote
-branches and prunes, in that order. Branch deletes are compare-and-swap, every
-step is verified, and the first failure stops the run.
-
-A receipt records every step and is rewritten after each one. Plans and receipts go under
-`repo-cleaner/plans/` and `repo-cleaner/receipts/` in
-[`@osdlc/tiered-dirs`](https://www.npmjs.com/package/@osdlc/tiered-dirs)' standalone durable home
-(`repo-cleaner` directory, `REPO_CLEANER_*` override variables), unless `--plan-out` or `--receipt-dir` says
-otherwise. `--dry-run` checks again and prints the steps without writing anything.
+verdict. `apply` either sweeps and plans in memory, or reads a plan with
+`--plan <file>` (`-` reads stdin). With no `--row` it applies every row judged
+`safe-to-delete` and drops each row to review as `needs-review`. Name a row
+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]`.
+`--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
+stops.
+
+On yes it runs only the steps it showed: worktrees first, then local branches,
+remote branches and a prune, in that order. Branch deletes are
+compare-and-swap, every step is verified, and the first failure stops the run.
+
+Every run ends with what it did:
+
+```text
+deleted: 1 worktree, 3 local branches, 2 remote branches, 1 stale worktree pruned
+dropped 2: 1 needs-review, 1 duplicate
+status: complete
+```
+
+The preview says `would delete:`, and a run that stops at a failed step says
+how many rows it did not reach. `--output json` carries the same counts as
+`summary`. Two clones of one remote list the same remote branches; `apply`
+deletes each once and drops the other clone's row as `duplicate`. Remotes are
+compared by the push URL git uses, with `url.*.insteadOf` applied.
+
+A receipt records every step and is rewritten after each one. With
+`--plan plan.json` it goes beside the plan, as
+`plan.receipt-<timestamp>.json`. `--receipt <file>` puts it anywhere. A run
+that swept, or read its plan from stdin, writes a receipt only when
+`--receipt` names one; the printed steps are its record.
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
-| `0` | Swept; or every selected row was applied or dropped with a reason |
-| `1` | Failed against the state it found: a `{name}` token nothing defines, an unreadable plan, a row not in the plan |
-| `2` | Cannot run as typed: an unknown flag, a malformed `--row`, `--branch` with `--all` or a path |
+| `0` | Swept; or `apply` ran, was declined, or had nothing to run |
+| `1` | Failed against the state it found: an unreadable plan, a row not in the plan |
+| `2` | Cannot run as typed: an unknown flag, a malformed `--row`, `--branch` with a path, `apply` with nobody to ask and no `--yes` |
 | `10` | Nothing to sweep: no entry named a repository |
 | `11` | `apply` stopped at a failed step; the receipt says which |
 
-## Configuration
-
-Only the CLI reads a config file. The library takes repositories as an
-argument, so a host that already knows where its repositories are passes them
-in.
-
-```yaml
-paths:
-  dev: ~/Developer
-repos:
-  - '{dev}'
-  - ~/work/api
-```
-
-`paths:` names a directory once; any `repos:` entry then refers to it as
-`{name}`. A token nothing defines is an error, not an empty path.
-
-The file is [`@osdlc/config-layers`](https://www.npmjs.com/package/@osdlc/config-layers)'s machine config — `config.yaml` in the host
-OS's config home, resolved through
-[`@osdlc/tiered-dirs`](https://www.npmjs.com/package/@osdlc/tiered-dirs)' standalone tier (`repo-cleaner`
-directory, `REPO_CLEANER_*` override variables):
-
-| OS | Path |
-| --- | --- |
-| macOS | `~/Library/Application Support/repo-cleaner/config.yaml` |
-| Linux and other | `$XDG_CONFIG_HOME/repo-cleaner/config.yaml`, else `~/.config/repo-cleaner/config.yaml` |
-| Windows | `%APPDATA%\repo-cleaner\config.yaml` |
-
-`REPO_CLEANER_MACHINE_CONFIG`, or `--config <path>`, relocates it. A missing,
-unreadable or malformed file degrades to no repositories rather than failing
-the run.
-
 ## As a library
 
 ```ts

package/dist/apply.d.ts

@@ -18,8 +18,8 @@ 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';
-import type { Receipt, RowRef } from './receipt.ts';
-import { type Authorization } from './types.ts';
+import { type Dropped, type Receipt, type RowRef, type Step } from './receipt.ts';
+import { type Authorization, type SweepItem, type SweepProgress } from './types.ts';
 /** An authorization the caller gave, for one row or (`row: null`) for all. */
 export interface Grant {
     name: Authorization;
@@ -38,13 +38,33 @@ export interface ApplyOptions extends HostHooks {
     /** The caller's directory; the sweep never offers the worktree holding it. */
     callerCwd: string;
     dryRun: boolean;
-    /** Where the receipt goes. Unused under `dryRun`. */
-    receiptPath: string;
-    /** Shown in the receipt. */
+    /** Where the receipt is written after each step; null writes none. Unused under `dryRun`. */
+    receiptPath: string | null;
+    /** Where the plan came from, shown in the receipt. */
     planPath: string;
     /** Limit the run to the plan repository rooted here. */
     repoRoot?: string | undefined;
     now?: () => Date;
+    /**
+     * Drop each selected row the re-check does not judge `safe-to-delete`.
+     * Defaults to true when no rows are requested, so a row to review runs only
+     * when it is named. Pass it to keep that guard on a run whose rows came
+     * from such a selection, such as the run a preview confirmed.
+     */
+    safeOnly?: boolean | undefined;
+    /**
+     * Items to re-check against instead of sweeping again, keyed by repository
+     * root, already annotated: the hook is not applied to them again. For a
+     * preview straight after a sweep; the run that deletes should always sweep
+     * again.
+     */
+    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;
+    /** Passed to the re-sweep's `onProgress`, for a status line. */
+    onSweepProgress?: ((progress: SweepProgress) => 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;
 }
 /** A selection or grant the plan cannot satisfy. Nothing has been touched. */
 export declare class ApplyArgumentError extends Error {
@@ -54,9 +74,27 @@ export declare function parseRowRef(text: string): RowRef;
 /** `<name>` for every row, or `<name>=<category>:<id>` for one. */
 export declare function parseGrant(text: string): Grant;
 /**
- * Apply the `requested` rows of `plan` under `grants`. A row named twice runs once.
+ * A row to apply, optionally pinned to the plan repository rooted at `repo`.
+ * Without `repo`, a row id that two plan repositories share is ambiguous.
+ */
+export type RowSelection = RowRef & {
+    repo?: string;
+};
+/**
+ * A network URL as `host[:port]/path`, the same for `git@host:o/r.git`,
+ * `ssh://git@host/o/r` and `https://host/o/r/`; the whole path is kept, so
+ * nested groups stay apart. Null for a path on this machine, including
+ * `file://` and a Windows drive path.
+ */
+export declare function networkRemoteKey(url: string): string | null;
+/**
+ * Apply the `requested` rows of `plan` under `grants`. An empty `requested`
+ * selects every row of the plan (of `repoRoot`'s repository, when given) and
+ * then drops each one the re-sweep does not judge `safe-to-delete`: a row to
+ * review runs only when it is named. A row named twice runs once. A row whose
+ * `requires` was not granted is dropped, never run.
  *
  * @throws ApplyArgumentError before touching anything, when a row or grant does
  *   not fit the plan.
  */
-export declare function applyPlan(plan: Plan, requested: readonly RowRef[], grants: readonly Grant[], opts: ApplyOptions): Receipt;
+export declare function applyPlan(plan: Plan, requested: readonly RowSelection[], grants: readonly Grant[], opts: ApplyOptions): Receipt;

package/dist/apply.js

@@ -16,10 +16,11 @@
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { CommandFailed, Git } from '@osdlc/typed-git';
+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 { worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand } from "./worktrees.js";
@@ -53,6 +54,8 @@ function errorText(err) {
         return err.detail.trim() || err.message;
     return err instanceof Error ? err.message : String(err);
 }
+const sameSelection = (a, b) => sameRow(a, b) &&
+    (a.repo === undefined ? '' : resolve(a.repo)) === (b.repo === undefined ? '' : resolve(b.repo));
 /** Each selected row's plan repository. Unknown and ambiguous rows are errors. */
 function locate(plan, rows, repoRoot) {
     const repos = repoRoot === undefined
@@ -60,8 +63,9 @@ function locate(plan, rows, repoRoot) {
         : plan.repos.filter((r) => resolve(r.root) === resolve(repoRoot));
     if (repos.length === 0)
         throw new ApplyArgumentError(`no plan repository at ${repoRoot}`);
-    return rows.map((ref) => {
-        const hits = repos.filter((r) => r.rows.some((row) => sameRow(row, ref)));
+    return rows.map(({ repo, ...ref }) => {
+        const hits = repos.filter((r) => (repo === undefined || resolve(r.root) === resolve(repo)) &&
+            r.rows.some((row) => sameRow(row, ref)));
         if (hits.length === 0)
             throw new ApplyArgumentError(`row ${label(ref)} is not in the plan`);
         if (hits.length > 1) {
@@ -75,6 +79,10 @@ function granted(grants, ref, name) {
 }
 /** The plan repository's rows as they stand now, with the host's overlay applied. */
 function resweep(repo, 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,
@@ -83,6 +91,7 @@ function resweep(repo, opts) {
         git: opts.git,
         gh: opts.gh,
         probe: opts.probe,
+        onProgress: opts.onSweepProgress,
     });
     if (sweep.repo === null || sweep.error !== null) {
         throw new Error(sweep.error ?? `could not read repository: ${repo.root}`);
@@ -90,7 +99,7 @@ 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, opts) {
+function recheck(selected, grants, implicit, opts) {
     const swept = new Map();
     for (const { repo } of selected) {
         if (!swept.has(repo))
@@ -112,6 +121,10 @@ function recheck(selected, grants, opts) {
             drop('not-deletable', item.reason);
             continue;
         }
+        if (implicit && item.classification !== 'safe-to-delete') {
+            drop('needs-review', `${item.reason}; name it with --row to apply it`);
+            continue;
+        }
         const now = fingerprint(item);
         if (!sameFingerprint(planned.fingerprint, now)) {
             drop('facts-changed', `planned ${JSON.stringify(planned.fingerprint)}, now ${JSON.stringify(now)}`);
@@ -234,7 +247,14 @@ function execute(step, row, git, probe) {
         case 'delete-remote': {
             const remote = String(row.item.facts['remote']);
             const ref = `refs/heads/${String(row.item.facts['branch'])}`;
-            at.push(remote, `:${ref}`, { forceWithLease: { ref, expect: step.expected_sha } });
+            const report = at.push(remote, `:${ref}`, {
+                forceWithLease: { ref, expect: step.expected_sha },
+            });
+            const refused = report.refs.find((r) => r.flag === '!');
+            if (refused?.flag === '!') {
+                const why = refused.rawReason === null ? '' : ` (${refused.rawReason})`;
+                throw new Error(`${refused.summary}${why}: ${PUSH_REJECTIONS[refused.rejection].message}`);
+            }
             if (at.lsRemote(remote, ref).some((r) => r.ref === ref)) {
                 throw new Error(`ls-remote still lists ${ref}`);
             }
@@ -243,24 +263,102 @@ function execute(step, row, git, probe) {
     }
 }
 /**
- * Apply the `requested` rows of `plan` under `grants`. A row named twice runs once.
+ * A network URL as `host[:port]/path`, the same for `git@host:o/r.git`,
+ * `ssh://git@host/o/r` and `https://host/o/r/`; the whole path is kept, so
+ * nested groups stay apart. Null for a path on this machine, including
+ * `file://` and a Windows drive path.
+ */
+export function networkRemoteKey(url) {
+    const u = url.trim();
+    if (/^[a-z]:[\\/]/i.test(u) || /^file:/i.test(u))
+        return null;
+    const uri = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?([^/:]+)(?::(\d+))?(\/.*)?$/i.exec(u);
+    const scp = uri === null ? /^(?:[^@/:]+@)?([^/:]+):(?!\/\/)(.+)$/.exec(u) : null;
+    const host = uri?.[1] ?? scp?.[1];
+    if (host === undefined)
+        return null;
+    const port = uri?.[2] === undefined ? '' : `:${uri[2]}`;
+    const path = (uri?.[3] ?? scp?.[2] ?? '').replace(/^\/+|\/+$/g, '').replace(/\.git$/, '');
+    return `${host.toLowerCase()}${port}/${path}`;
+}
+/**
+ * One string per remote repository, so two clones that push to the same one
+ * agree. Built from the push URLs git would use (`remote get-url --push
+ * --all`, which applies `url.*.insteadOf` and `pushInsteadOf`): a network URL
+ * by {@link networkRemoteKey}, a local path resolved against the repository
+ * and kept as written, `.git` and all. Null when git reports no URL; such a
+ * row is never treated as a duplicate.
+ */
+function remoteKey(git, repo, remote) {
+    const urls = git.at(repo).try.remoteGetUrls(remote, { push: true });
+    if (!urls.ok || urls.value === null || urls.value.length === 0)
+        return null;
+    const keys = urls.value.map((url) => networkRemoteKey(url) ?? resolve(repo, url.trim().replace(/^file:\/\/(localhost)?/i, '')));
+    return [...new Set(keys)].sort().join('\n');
+}
+/**
+ * Keep the first row for each remote branch. Two clones of one remote each
+ * 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) {
+    const seen = new Map();
+    const kept = [];
+    const extra = [];
+    for (const row of accepted) {
+        if (row.item.category !== 'remote_branch') {
+            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 first = key === null ? undefined : seen.get(key);
+        if (first !== undefined) {
+            extra.push({
+                repo: row.repo,
+                category: row.item.category,
+                id: row.item.id,
+                reason: 'duplicate',
+                detail: `the same remote branch is deleted from ${first}`,
+            });
+            continue;
+        }
+        if (key !== null)
+            seen.set(key, row.repo);
+        kept.push(row);
+    }
+    return { accepted: kept, dropped: [...dropped, ...extra] };
+}
+/**
+ * Apply the `requested` rows of `plan` under `grants`. An empty `requested`
+ * selects every row of the plan (of `repoRoot`'s repository, when given) and
+ * then drops each one the re-sweep does not judge `safe-to-delete`: a row to
+ * review runs only when it is named. A row named twice runs once. A row whose
+ * `requires` was not granted is dropped, never run.
  *
  * @throws ApplyArgumentError before touching anything, when a row or grant does
  *   not fit the plan.
  */
 export function applyPlan(plan, requested, grants, opts) {
     const now = opts.now ?? (() => new Date());
-    const rows = requested.filter((row, i) => requested.findIndex((other) => sameRow(other, row)) === i);
+    // Every row of the plan keeps its repository, so a branch name two
+    // repositories share is two rows, not an ambiguity.
+    const wanted = requested.length > 0
+        ? requested
+        : 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);
     if (rows.length === 0)
-        throw new ApplyArgumentError('no rows selected');
+        throw new ApplyArgumentError('the plan has no rows to apply');
     const selected = locate(plan, rows, opts.repoRoot);
     for (const grant of grants) {
         if (grant.row !== null && !rows.some((r) => sameRow(r, grant.row))) {
-            throw new ApplyArgumentError(`--authorize names unselected row ${label(grant.row)}`);
+            throw new ApplyArgumentError(`--allow names unselected row ${label(grant.row)}`);
         }
     }
     const receipt = {
-        version: 1,
+        version: RECEIPT_VERSION,
         plan: opts.planPath,
         status: opts.dryRun ? 'dry-run' : 'applying',
         started_at: now().toISOString(),
@@ -268,8 +366,9 @@ export function applyPlan(plan, requested, grants, opts) {
         dropped: [],
         steps: [],
     };
-    const { accepted, dropped } = recheck(selected, grants, opts);
-    receipt.dropped = dropped;
+    const rechecked = recheck(selected, 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]));
     for (const repo of new Set(ordered.map((row) => row.repo))) {
@@ -282,14 +381,19 @@ export function applyPlan(plan, requested, grants, opts) {
         receipt.finished_at = now().toISOString();
         return receipt;
     }
-    const save = () => writeJsonAtomic(opts.receiptPath, receipt);
+    const receiptPath = opts.receiptPath;
+    const save = () => {
+        if (receiptPath !== null)
+            writeJsonAtomic(receiptPath, receipt);
+    };
     save();
     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`
     // verb, so a failed remove cannot put the lock back; the receipt says so.
     const unlocked = new Set();
-    for (const [step, row] of plannedSteps) {
+    for (const [i, [step, row]] of plannedSteps.entries()) {
+        opts.onStep?.(i, plannedSteps.length, step);
         try {
             step.verification = execute(step, row, git, probe);
             step.result = 'ok';

package/dist/branches.d.ts

@@ -27,6 +27,16 @@ export declare function recordPr(facts: Record<string, unknown>, pr: PRInfo | un
 };
 /** One sentence on why a merged PR did not count, for `investigationParts`. */
 export declare function gapSentence(pr: PRInfo, gap: PrEvidenceGap, repo: RepoInfo): string;
+/**
+ * `facts.merged`: the work is on the default branch, by an exact-head merged
+ * PR, by ancestry or by a patch match. Every category records it this way, so
+ * `summary` counts one definition.
+ */
+export declare function mergedFact(e: {
+    landed: boolean;
+    ancestor: boolean;
+    patchLanded: boolean;
+}): boolean;
 /** `HEAD` as the branch checked out at `git`'s directory; any other name as given. */
 export declare function resolveBranch(value: string, git: Git): string;
 /**
@@ -38,7 +48,7 @@ export declare function resolveBranch(value: string, git: Git): string;
 export declare function localDeleteCommand(name: string, sha: string): string;
 /** Delete `remote`'s branch `name` only while it still points at `sha`. */
 export declare function remoteDeleteCommand(remote: string, name: string, sha: string): string;
-export declare function gatherLocalBranches(repo: RepoInfo, prs: Map<string, PRInfo>, worktreeBranches: ReadonlySet<string>, git: Git, only?: string): SweepItem[];
+export declare function gatherLocalBranches(repo: RepoInfo, prs: Map<string, PRInfo>, worktreeBranches: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): SweepItem[];
 export declare function classifyLocalBranch(opts: {
     name: string;
     upstream: string;
@@ -50,7 +60,7 @@ export declare function classifyLocalBranch(opts: {
     worktreeBranches: ReadonlySet<string>;
     git: Git;
 }): SweepItem;
-export declare function gatherRemoteBranches(repo: RepoInfo, prs: Map<string, PRInfo>, localBranchNames: ReadonlySet<string>, git: Git, only?: string): SweepItem[];
+export declare function gatherRemoteBranches(repo: RepoInfo, prs: Map<string, PRInfo>, localBranchNames: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): SweepItem[];
 export declare function classifyRemoteBranch(opts: {
     name: string;
     sha: string;