@osdlc/repo-cleaner 0.6.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @osdlc/repo-cleaner
 
+## 0.9.0
+
+### Minor Changes
+
+- 43a4097: `pr-update dev` and `repo-cleaner dev` run the tool from a development checkout: `dev link <checkout>` makes the installed command run that checkout's source under Bun, `dev status` says which code runs, and `dev off` goes back. `PR_UPDATE_HOME` and `REPO_CLEANER_HOME` do the same for one run. `dev` is now a word for both tools: sweep a directory named `dev` with `repo-cleaner ./dev`, as with `apply`. The bin now loads `dist/bin.js`, built from the new `src/bin.ts`.
+
+### Patch Changes
+
+- Updated dependencies [43a4097]
+  - @osdlc/cli-tool@0.12.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 7fe7f51: Output change: a remote on a host other than github.com is now named `host/owner/name` in the report, read with typed-git's `parseRemoteRepo`. Before, typed-gh read `owner/name` from any host, so one `owner/name` on two hosts was reported as a duplicate checkout. The `slug` field of `--output json` changes with it.
+
+### Patch Changes
+
+- Updated dependencies [7fe7f51]
+  - @osdlc/typed-git@0.11.1
+
+## 0.7.0
+
+### Minor Changes
+
+- 82d9841: A branch landed by rebase merge, cherry-pick or squash merge is now recognised without pull request data, and needs no grant when the content check agrees.
+  
+  - A third landing signal, patch equivalence, runs when a PR at the exact tip and ancestry both fail. It compares by `git cherry` patch id: commit by commit (`per-commit`), the branch squashed into one change (`squashed`), and, for a branch that moved on after a merged PR's head, that head squashed plus each later commit (`head-moved`). It applies to local branches, remote branches and worktrees.
+  - A patch id is a heuristic, so a match alone still requires the `abandon-unmerged` authorization. A second check, `git merge-tree --write-tree` of the default branch and the tip (git 2.38 or later), must give the default branch's own tree to drop it; the outcome is in `facts.landing_content_confirmed` and the row's reason.
+  - The row records `facts.landing = 'patch-equivalent'` and `facts.landing_check`. A branch that is only partly on the default branch lists the commits that are not in `facts.unmatched_commits` and in the investigation text.
+  - It fails closed. A failing git call, unreadable output, a shallow clone, a missing merge base, an empty change, a merge commit in the range (for the commit-by-commit check), or any commit not on the default branch means the branch is not counted as landed.
+  - The squashed check writes one unreferenced commit object and no ref, needs no git identity, and ignores `git replace` refs.
+  - New exports: `assessLanding`, `patchEquivalent`, `Landing`, `LandingCheck`. Uses `cherry`, `commitTree` and `mergeTree` from `@osdlc/typed-git`.
+
+### Patch Changes
+
+- Updated dependencies [82d9841]
+- Updated dependencies [ebe0e0d]
+  - @osdlc/typed-git@0.11.0
+  - @osdlc/typed-gh@0.12.1
+
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies [a4ca07d]
+  - @osdlc/typed-gh@0.12.0
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -35,12 +35,13 @@ ESM only. Compiled JavaScript with type declarations, for Node 22 or newer.
 
 ## How it decides
 
-Two signals settle most items, and either alone is enough:
+Three signals settle most items. The first two are enough alone; the third needs a content check too (see [Patch equivalence](#patch-equivalence)):
 
 | 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 |
 | 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) |
 
 Ancestry is measured against `<remote>/<default>`, so work merged only into an
 unpushed local default branch does not count. Without a remote, the local
@@ -67,6 +68,65 @@ Some worktrees are held back whatever their branch says. Each lands in
 | `nested-repository` | An untracked or ignored directory holds a repository with its own history. |
 | `branch-in-other-worktree` | Another worktree has the same branch checked out (`facts.other_worktrees`). |
 
+### Patch equivalence
+
+A rebase merge, a cherry-pick and a squash merge put the work on the default
+branch under new commit ids, so the tip is not reachable from it and no PR
+head matches. The sweep then compares by patch id (`git cherry`), which ignores
+ids, messages and dates. It runs only when the first two signals do not
+settle the item, for local branches, remote branches and worktrees alike.
+
+A patch id is a heuristic, not proof, so a patch match alone does not make a
+branch as safe as an ancestor. A second, independent check must agree:
+`git merge-tree --write-tree <default> <tip>` must come out clean with exactly
+the default branch's tree, which shows the branch's content is already there. It
+needs git 2.38 or later; an older git, a conflict or any failure counts as not
+agreed. The row is `safe-to-delete` either way, but only an agreed check drops
+the `abandon-unmerged` authorization. Without it the row keeps requiring that
+grant, and a worktree with unpushed commits stays `needs-investigation`. The row
+carries three facts, and its reason says which case applied:
+
+| Fact | Value |
+| --- | --- |
+| `facts.landing` | `patch-equivalent` |
+| `facts.landing_check` | which check passed, below |
+| `facts.landing_content_confirmed` | `true` when the merge-tree check agreed, `false` otherwise |
+
+| `landing_check` | Meaning |
+| --- | --- |
+| `per-commit` | Every commit on the branch has a commit with the same patch id on the default branch. Covers rebase merges and cherry-picks. |
+| `squashed` | A commit holding the branch's combined change (its tree on the merge base) has a commit with the same patch id on the default branch. Covers squash merges. |
+| `head-moved` | A merged PR's head passes `squashed`, and every commit after that head passes `per-commit`. Covers a branch that moved on after its squash merge. |
+
+`squashed` accepts any one commit on the default branch with the same net
+patch, not necessarily one that came from this branch. That is acceptable only
+because the content check, or the grant, stands behind it.
+
+The squashed check builds one commit object with `git commit-tree` and no ref.
+It leaves the index, the working tree and every ref alone, and needs no git
+identity configured. Every git call of the check ignores `git replace` refs
+(`GIT_NO_REPLACE_OBJECTS=1`).
+
+The check decides what gets deleted, so a doubt is never evidence. None of
+these count as landed:
+
+- a commit that is not on the default branch, however many others are (the
+  commits that are missing are listed in `facts.unmatched_commits` and in the
+  investigation text when part of the work did land);
+- a git call that fails, or output that cannot be read;
+- a shallow clone, a missing merge base, a ref that does not resolve;
+- an empty change: an empty commit, or a branch whose commits cancel out;
+- any merge commit in the range, a plain merge of the default branch included,
+  for `per-commit` (neither `git cherry` nor `git log` shows its change); the
+  `squashed` check, which reads the combined change, can still pass;
+- a squash merge that was edited by hand, because the patch ids differ.
+
+A patch id says two changes are the same, not that they come from the same
+branch, and it ignores whitespace. A one-line change that the default branch
+also made independently, an indentation-only difference, or work that landed
+and was then reverted all match by patch id; the content check does not agree
+with them, so they keep needing the grant.
+
 ### Locks and running processes
 
 A crashed coding agent leaves its worktree locked. The sweep reads one generic
@@ -189,7 +249,8 @@ one that says which it could not find.
 | `--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`.
+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).
 
 ## Plan and apply
 
@@ -298,6 +359,22 @@ sweep and `applyPlan`.
 `git` on `PATH`, and `gh` when PR state should count. Authentication is `gh`'s
 own — this package reads no token.
 
+## Running from a checkout
+
+To try a change to repo-cleaner with the `repo-cleaner` already on your PATH, link a
+checkout of this package:
+
+```sh
+repo-cleaner dev link ~/src/osdlc/packages/ts/repo-cleaner   # every `repo-cleaner` now runs that checkout
+repo-cleaner dev status                             # which code runs, and why
+repo-cleaner dev off                                # back to the installed copy
+```
+
+`REPO_CLEANER_HOME=<checkout> repo-cleaner …` does the same for one run. The checkout runs
+from source under Bun, so it needs `bun` on PATH and the checkout's
+dependencies installed and built. The installed copy says which checkout it
+hands off to on stderr; `REPO_CLEANER_QUIET=1` silences that line.
+
 ## Licence
 
 `MIT OR Apache-2.0`, at your option. See [LICENSE-MIT](./LICENSE-MIT) and [LICENSE-APACHE](./LICENSE-APACHE).

package/bin/repo-cleaner.js

@@ -1,9 +1,5 @@
 #!/usr/bin/env node
 // The published entry point: `npx @osdlc/repo-cleaner …` and a plain
-// `node ./bin/repo-cleaner.js …` both land here. Requires the built dist/cli.js
-// (`pnpm run build`).
-import { runMain } from '@osdlc/cli-tool'
-import { main } from '../dist/cli.js'
-import { VERSION } from '../dist/version.generated.js'
-
-await runMain(main, { name: 'repo-cleaner', version: VERSION })
+// `node ./bin/repo-cleaner.js …` both land here. Requires the built dist/
+// (`pnpm run build`). See src/bin.ts.
+import '../dist/bin.js'

package/dist/bin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * What `repo-cleaner` runs: `bin/repo-cleaner.js` loads the built copy, and a development
+ * checkout that devlink selects runs this file under Bun.
+ */
+export {};

package/dist/bin.js

@@ -0,0 +1,10 @@
+/**
+ * What `repo-cleaner` runs: `bin/repo-cleaner.js` loads the built copy, and a development
+ * checkout that devlink selects runs this file under Bun.
+ */
+import { runMain } from '@osdlc/cli-tool';
+import { devlinkHook } from '@osdlc/cli-tool/devlink';
+import { main } from "./cli.js";
+import { DEVLINK_SPEC } from "./devlink.js";
+import { VERSION } from "./version.generated.js";
+await runMain(main, { name: 'repo-cleaner', version: VERSION, devlink: devlinkHook(DEVLINK_SPEC) });

package/dist/branches.d.ts

@@ -1,16 +1,16 @@
 /**
  * Local and remote branches: gather them, then decide what each one is.
  *
- * Two signals settle most branches. A merged pull request whose head commit is
+ * Three signals settle most branches. A merged pull request whose head commit is
  * the branch tip says the work landed. Ancestry says the same thing without
  * GitHub's help — if the branch tip is reachable from the default branch,
- * every commit on it is already there. Either one is enough to call a branch
- * spent; neither leaves the branch for a person to look at.
+ * every commit on it is already there. Patch equivalence covers rebase merges,
+ * cherry-picks and squash merges, where the work is on the default branch
+ * under other commit ids. Any one is enough to call a branch spent; none
+ * leaves the branch for a person to look at.
  */
 import { type Git } from '@osdlc/typed-git';
-import { type PRInfo, type RepoInfo, type SweepItem } from './types.ts';
-/** Why a merged PR does not prove that `tip` landed. */
-export type PrEvidenceGap = 'other-base' | 'head-moved';
+import { type PRInfo, type PrEvidenceGap, type RepoInfo, type SweepItem } from './types.ts';
 /**
  * True when merged `pr` proves `tip` landed: it targeted the default branch
  * and its head commit is `tip`. Fork PRs never reach here; `fetchPrs` drops

package/dist/branches.js

@@ -1,14 +1,17 @@
 /**
  * Local and remote branches: gather them, then decide what each one is.
  *
- * Two signals settle most branches. A merged pull request whose head commit is
+ * Three signals settle most branches. A merged pull request whose head commit is
  * the branch tip says the work landed. Ancestry says the same thing without
  * GitHub's help — if the branch tip is reachable from the default branch,
- * every commit on it is already there. Either one is enough to call a branch
- * spent; neither leaves the branch for a person to look at.
+ * every commit on it is already there. Patch equivalence covers rebase merges,
+ * cherry-picks and squash merges, where the work is on the default branch
+ * under other commit ids. Any one is enough to call a branch spent; none
+ * leaves the branch for a person to look at.
  */
 import { shellJoin } from '@osdlc/command-seam';
 import { forceWithLeaseArg } from '@osdlc/typed-git';
+import { confirmationNote, judgeLanding, landingConfirmed, recordLanding, unmatchedSentence, } from "./landing.js";
 import { authorizationsFor, landedRef, makeItem, } from "./types.js";
 /**
  * Five fields in one pass, so a repository costs one `for-each-ref`. The full
@@ -151,9 +154,16 @@ export function classifyLocalBranch(opts) {
     const isAncestor = ancestor === true;
     const pr = prs.get(name);
     const { landed, gap } = recordPr(facts, pr, sha, repo);
-    const unmerged = !landed && !isAncestor;
-    if (unmerged)
+    // Rebase merges, cherry-picks and squash merges leave the tip off the default
+    // branch; the patches say whether the work is there anyway.
+    const patch = landed || isAncestor ? null : judgeLanding(repo, sha, pr, gap, git);
+    if (patch !== null)
+        recordLanding(facts, patch);
+    const patchLanded = patch !== null && patch.check !== null;
+    const unmerged = !landed && !isAncestor && !landingConfirmed(patch);
+    if (!landed && !isAncestor) {
         facts['unique_commits'] = git.at(repo.root).aheadBehind(repo.mainBranch, sha).ahead;
+    }
     const requires = branchRequires(unmerged, pr);
     const deleteCmd = [localDeleteCommand(name, sha)];
     if (pr && landed) {
@@ -180,6 +190,18 @@ export function classifyLocalBranch(opts) {
             requires,
         });
     }
+    if (patchLanded) {
+        return makeItem({
+            category: 'local_branch',
+            id: name,
+            classification: 'safe-to-delete',
+            action: 'delete',
+            reason: `patch-equivalent to commits on ${compareRef} (${patch.check}); ${confirmationNote(patch)}`,
+            facts,
+            commands: deleteCmd,
+            requires,
+        });
+    }
     if (pr && pr.state === 'OPEN')
         return keep(`open PR #${pr.number}`, { requires });
     const lead = ancestor === null
@@ -192,6 +214,9 @@ export function classifyLocalBranch(opts) {
         : 'No PR found via `gh pr list`.');
     if (pr && gap)
         parts.push(gapSentence(pr, gap, repo));
+    const unmatched = patch === null ? null : unmatchedSentence(patch, repo);
+    if (unmatched !== null)
+        parts.push(unmatched);
     parts.push(`Last commit: ${lastCommit} (${sha}).`);
     return makeItem({
         category: 'local_branch',
@@ -251,8 +276,14 @@ export function classifyRemoteBranch(opts) {
     facts['ancestor_of_remote_main'] = isAncestor;
     const pr = prs.get(name);
     const { landed, gap } = recordPr(facts, pr, sha, repo);
-    const unmerged = !landed && !isAncestor;
-    if (unmerged) {
+    // `sha` came from `ls-remote` and may not be in this clone; the check then
+    // finds nothing and the branch stays unlanded.
+    const patch = landed || isAncestor ? null : judgeLanding(repo, sha, pr, gap, git);
+    if (patch !== null)
+        recordLanding(facts, patch);
+    const patchLanded = patch !== null && patch.check !== null;
+    const unmerged = !landed && !isAncestor && !landingConfirmed(patch);
+    if (!landed && !isAncestor) {
         // Unknown (null) when the clone lacks `sha` or `remoteMain`, as above.
         const counted = git.at(repo.root).try.aheadBehind(remoteMain, sha);
         facts['unique_commits'] = counted.ok ? counted.value.ahead : null;
@@ -283,12 +314,27 @@ export function classifyRemoteBranch(opts) {
             requires,
         });
     }
+    if (patchLanded) {
+        return makeItem({
+            category: 'remote_branch',
+            id,
+            classification: 'safe-to-delete',
+            action: 'delete',
+            reason: `patch-equivalent to commits on ${remoteMain} (${patch.check}); ${confirmationNote(patch)}`,
+            facts,
+            commands: deleteCmd,
+            requires,
+        });
+    }
     if (pr && pr.state === 'OPEN')
         return keep(`open PR #${pr.number}`, { requires });
     const parts = [`Remote branch \`${id}\` is not an ancestor of \`${remoteMain}\`.`];
     parts.push(pr ? `Associated PR #${pr.number} is ${pr.state}.` : 'No PR found.');
     if (pr && gap)
         parts.push(gapSentence(pr, gap, repo));
+    const unmatched = patch === null ? null : unmatchedSentence(patch, repo);
+    if (unmatched !== null)
+        parts.push(unmatched);
     parts.push('Decide whether to push more work, delete, or leave it as long-lived.');
     return makeItem({
         category: 'remote_branch',

package/dist/cli.js

@@ -86,8 +86,9 @@ const sweepCli = () => defineCli({
     },
     epilogue: `commands:
   repo-cleaner apply --help   delete the approved rows of a plan
+  repo-cleaner dev            run repo-cleaner from a development checkout
 
-A checkout directory named "apply" is swept as ./apply.
+A checkout directory named "apply" or "dev" is swept as ./apply or ./dev.
 
 config: ${configPath()}
 plans:  <durable home>/repo-cleaner/plans/ unless --plan-out`,

package/dist/devlink.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The devlink spec: how `repo-cleaner dev` recognises a repo-cleaner checkout and runs it.
+ *
+ * A checkout has `src/cli.ts` and a `package.json` named `@osdlc/repo-cleaner`; the
+ * installed package ships `dist/` alone, so it never counts. A selected
+ * checkout runs `src/bin.ts` under Bun. The cwd layer stays off: only
+ * `REPO_CLEANER_HOME` or `repo-cleaner dev link` hand off to a checkout.
+ */
+import { type ToolSpec } from '@osdlc/cli-tool/devlink';
+export declare const DEVLINK_SPEC: ToolSpec;

package/dist/devlink.js

@@ -0,0 +1,18 @@
+/**
+ * The devlink spec: how `repo-cleaner dev` recognises a repo-cleaner checkout and runs it.
+ *
+ * A checkout has `src/cli.ts` and a `package.json` named `@osdlc/repo-cleaner`; the
+ * installed package ships `dist/` alone, so it never counts. A selected
+ * checkout runs `src/bin.ts` under Bun. The cwd layer stays off: only
+ * `REPO_CLEANER_HOME` or `repo-cleaner dev link` hand off to a checkout.
+ */
+import { validateSpec } from '@osdlc/cli-tool/devlink';
+import { VENDOR_DIRS } from "./config.js";
+export const DEVLINK_SPEC = validateSpec({
+    name: 'repo-cleaner',
+    marker: 'src/cli.ts',
+    packageName: '@osdlc/repo-cleaner',
+    entry: 'src/bin.ts',
+    launcher: 'bin/repo-cleaner.js',
+    vendorDirs: VENDOR_DIRS,
+});

package/dist/discover.d.ts

@@ -3,8 +3,8 @@
  * where its main checkout is, what its default branch is called, which remote
  * to measure against, and whether `gh` can be asked about pull requests.
  */
-import type { Git } from '@osdlc/typed-git';
-import { type Gh } from '@osdlc/typed-gh';
+import { type Git } from '@osdlc/typed-git';
+import type { Gh } from '@osdlc/typed-gh';
 import type { RepoInfo } from './types.ts';
 /**
  * Thrown when a path names no repository, or names one whose default branch

package/dist/discover.js

@@ -3,7 +3,7 @@
  * where its main checkout is, what its default branch is called, which remote
  * to measure against, and whether `gh` can be asked about pull requests.
  */
-import { ownerRepoSlug } from '@osdlc/typed-gh';
+import { parseRemoteRepo } from '@osdlc/typed-git';
 /**
  * Thrown when a path names no repository, or names one whose default branch
  * cannot be determined. A single-repository caller lets it propagate; a
@@ -68,9 +68,9 @@ export function discoverRepo(hint, opts) {
     }
     if (!mainBranch)
         throw new DiscoveryFailed(`could not determine the default branch of ${root}`);
-    // `owner/name` for the report's header, so a fan-out over long paths stays
-    // readable. A remote that is not a recognisable host coordinate answers null.
-    const slug = remote === null ? null : ownerRepoSlugOf(git.at(root).try.remoteGetUrl(remote), gh, root);
+    // A short name for the report's header, so a fan-out over long paths stays
+    // readable. It also keys duplicate checkouts.
+    const slug = remote === null ? null : remoteSlugOf(git.at(root).try.remoteGetUrl(remote));
     const currentBranch = git.at(root).headRef() ?? '';
     // The two halves separately, not `ready()`: the report says "gh not
     // available" and "gh not authenticated" differently, because they send a
@@ -79,10 +79,17 @@ export function discoverRepo(hint, opts) {
     const ghAuthenticated = hasGh && gh.at(root).authenticated();
     return { root, slug, mainBranch, remote, currentBranch, hasGh, ghAuthenticated, fetched: false };
 }
-/** `owner/name` from a remote URL outcome, or null when it is not one. */
-function ownerRepoSlugOf(url, gh, root) {
+/**
+ * `owner/name` for a github.com remote, `host/owner/name` for any other, or
+ * null when the URL names no repository. The host keeps two hosts' `a/b`
+ * apart.
+ */
+function remoteSlugOf(url) {
     if (!url.ok || url.value === undefined || url.value === null)
         return null;
-    const coord = gh.at(root).ownerRepo(url.value);
-    return coord === null ? null : ownerRepoSlug(coord);
+    const remote = parseRemoteRepo(url.value);
+    if (remote === null)
+        return null;
+    const slug = `${remote.owner}/${remote.repo}`;
+    return remote.host === 'github.com' ? slug : `${remote.host}/${slug}`;
 }

package/dist/index.d.ts

@@ -17,6 +17,7 @@
 export { classifyLocalBranch, classifyRemoteBranch, gatherLocalBranches, gatherRemoteBranches, localDeleteCommand, remoteDeleteCommand, resolveBranch, } from './branches.ts';
 export { classifyWorktree, gatherWorktrees, hasBlockers, worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand, type WorktreeBlocker, } from './worktrees.ts';
 export { DiscoveryFailed, discoverRepo } from './discover.ts';
+export { assessLanding, patchEquivalent, type Landing, type LandingCheck } from './landing.ts';
 export { ApplyArgumentError, applyPlan, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
 export type { Annotate, HostHooks } from './hooks.ts';
 export { PLAN_VERSION, PlanReadError, planRepo, readPlan, stampedPath, writePlan, type Plan, type PlanRepo, type PlannableRow, } from './plan.ts';

package/dist/index.js

@@ -17,6 +17,7 @@
 export { classifyLocalBranch, classifyRemoteBranch, gatherLocalBranches, gatherRemoteBranches, localDeleteCommand, remoteDeleteCommand, resolveBranch, } from "./branches.js";
 export { classifyWorktree, gatherWorktrees, hasBlockers, worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand, } from "./worktrees.js";
 export { DiscoveryFailed, discoverRepo } from "./discover.js";
+export { assessLanding, patchEquivalent } from "./landing.js";
 export { ApplyArgumentError, applyPlan, parseGrant, parseRowRef, } from "./apply.js";
 export { PLAN_VERSION, PlanReadError, planRepo, readPlan, stampedPath, writePlan, } from "./plan.js";
 export { ReceiptSchema } from "./receipt.js";

package/dist/landing.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Patch equivalence: a third way to tell that a branch landed.
+ *
+ * A merge commit makes the branch tip reachable from the default branch, and a
+ * merged pull request at the tip says so too. A rebase merge, a cherry-pick
+ * and a squash merge do neither: the work is on the default branch under other
+ * commit ids. `git cherry` compares commits by patch id, which ignores the id,
+ * the message and the dates, so it can say "this commit's change is already
+ * there".
+ *
+ * A patch id is a heuristic, not proof. It reads only the changed lines, so an
+ * indentation-only change, a one-line edit that the landed ref also made
+ * independently, or a commit that landed and was later reverted can all look
+ * the same as work that landed. A patch-equivalent verdict therefore stands
+ * on its own only when a second, independent check agrees: merging the branch
+ * into the landed ref (`git merge-tree`) must change nothing, which shows the
+ * branch's content is already there. Without that, the verdict still names the
+ * check that passed, but `confirmed` is false and callers keep requiring the
+ * `abandon-unmerged` authorization.
+ *
+ * This code decides what gets deleted, so every doubt answers "not landed" or
+ * "not confirmed". A git call that fails, output that cannot be read, a
+ * shallow clone, a missing merge base, a commit that is not on the landed ref
+ * and a patch that is empty all end the same way: no evidence.
+ */
+import type { Git } from '@osdlc/typed-git';
+import { type PRInfo, type PrEvidenceGap, type RepoInfo } from './types.ts';
+/** Which check showed that the work is on the landed ref. */
+export type LandingCheck = 
+/** Every commit on the branch has a patch-equivalent commit on the landed ref (rebase merge, cherry-pick). */
+'per-commit'
+/** The branch's combined change equals one commit on the landed ref (squash merge). */
+ | 'squashed'
+/** A merged PR's head passes `squashed`, and every commit after it passes `per-commit`. */
+ | 'head-moved';
+/** The outcome of {@link assessLanding}. */
+export type Landing = {
+    check: LandingCheck;
+    /**
+     * True when `git merge-tree` of the landed ref and the tip gives exactly
+     * the landed ref's tree: the branch's content is already there. False
+     * when the merge changes something, conflicts, cannot run (git older
+     * than 2.38) or fails. Only a confirmed verdict drops `abandon-unmerged`.
+     */
+    confirmed: boolean;
+} | {
+    check: null;
+    /**
+     * Commits that have no patch-equivalent on the landed ref, as `<short sha> <subject>`.
+     * Filled only when the branch is partly on the landed ref, so a plain
+     * diverged branch does not list every commit it has.
+     */
+    unmatched: string[];
+};
+/**
+ * Whether the work on `tip` is already on the landed ref, judged by patch.
+ *
+ * Checked in order: every commit one by one (`per-commit`), the branch as one
+ * squashed change (`squashed`), and, with `prHead` set to the head of a merged
+ * pull request that is not `tip`, that head squashed plus each later commit
+ * one by one (`head-moved`). A branch with a commit that is not on the landed
+ * ref is never landed. A passing check also carries `confirmed`, the outcome
+ * of the content check ({@link contentConfirmed}).
+ *
+ * Reads only; it writes one unreferenced commit object and no ref. Any error
+ * returns `{ check: null, unmatched: [] }`: a check that cannot finish is not
+ * evidence.
+ */
+export declare function assessLanding(repo: RepoInfo, tip: string, git: Git, prHead?: string | null): Landing;
+/**
+ * The patch-equivalence verdict for a branch the first two signals did not
+ * settle. A merged PR at an earlier head lets the check trust that head's
+ * squash merge and look at the commits after it.
+ */
+export declare function judgeLanding(repo: RepoInfo, tip: string, pr: PRInfo | undefined, gap: PrEvidenceGap | null, git: Git): Landing;
+/** True when the verdict is a patch match that the content check agreed with, so no grant is needed. */
+export declare function landingConfirmed(landing: Landing | null): boolean;
+/** {@link assessLanding}, reduced to the check that passed, or null. */
+export declare function patchEquivalent(repo: RepoInfo, tip: string, git: Git, prHead?: string | null): LandingCheck | null;
+/** Write the landing evidence into a row's `facts`. */
+export declare function recordLanding(facts: Record<string, unknown>, landing: Landing): void;
+/**
+ * The part of a row's reason that says whether the content check agreed, for a
+ * patch-equivalent verdict.
+ */
+export declare function confirmationNote(landing: Extract<Landing, {
+    check: LandingCheck;
+}>): string;
+/** One sentence naming the commits that kept a partly landed branch from counting, or null. */
+export declare function unmatchedSentence(landing: Landing, repo: RepoInfo): string | null;

package/dist/landing.js

@@ -0,0 +1,265 @@
+/**
+ * Patch equivalence: a third way to tell that a branch landed.
+ *
+ * A merge commit makes the branch tip reachable from the default branch, and a
+ * merged pull request at the tip says so too. A rebase merge, a cherry-pick
+ * and a squash merge do neither: the work is on the default branch under other
+ * commit ids. `git cherry` compares commits by patch id, which ignores the id,
+ * the message and the dates, so it can say "this commit's change is already
+ * there".
+ *
+ * A patch id is a heuristic, not proof. It reads only the changed lines, so an
+ * indentation-only change, a one-line edit that the landed ref also made
+ * independently, or a commit that landed and was later reverted can all look
+ * the same as work that landed. A patch-equivalent verdict therefore stands
+ * on its own only when a second, independent check agrees: merging the branch
+ * into the landed ref (`git merge-tree`) must change nothing, which shows the
+ * branch's content is already there. Without that, the verdict still names the
+ * check that passed, but `confirmed` is false and callers keep requiring the
+ * `abandon-unmerged` authorization.
+ *
+ * This code decides what gets deleted, so every doubt answers "not landed" or
+ * "not confirmed". A git call that fails, output that cannot be read, a
+ * shallow clone, a missing merge base, a commit that is not on the landed ref
+ * and a patch that is empty all end the same way: no evidence.
+ */
+import { landedRef } from "./types.js";
+/** Cap on {@link Landing} `unmatched`. */
+const UNMATCHED_SHOWN = 10;
+/**
+ * `git replace` refs make git read one object as another, so a replaced commit
+ * could fake a merge base, a commit list or a patch. Every call of the check
+ * ignores them.
+ */
+const NO_REPLACE = { GIT_NO_REPLACE_OBJECTS: '1' };
+/** Call options of every git call the check makes. */
+const CALL = { env: NO_REPLACE };
+/**
+ * The identity of the throwaway commit the squashed check builds. Fixed, so
+ * the check needs no git identity to be configured, and the commit holds
+ * nothing that depends on who runs it.
+ */
+const PROBE_ENV = {
+    ...NO_REPLACE,
+    GIT_AUTHOR_NAME: 'repo-cleaner',
+    GIT_AUTHOR_EMAIL: 'repo-cleaner@localhost',
+    GIT_AUTHOR_DATE: '2000-01-01T00:00:00+0000',
+    GIT_COMMITTER_NAME: 'repo-cleaner',
+    GIT_COMMITTER_EMAIL: 'repo-cleaner@localhost',
+    GIT_COMMITTER_DATE: '2000-01-01T00:00:00+0000',
+};
+/**
+ * Compare every commit in `base..tip` with `landed` by patch id.
+ *
+ * `git cherry` leaves merge commits out, and `git log --name-status` shows no
+ * diff for them, so every merge commit in the range counts as unmatched, a
+ * plain merge of the default branch included. The range is listed separately
+ * and must be the same set of commits that `cherry` reported. A branch with a
+ * merge commit therefore never passes `per-commit`; the `squashed` check, which
+ * looks at the combined change, is the one that can still pass. An empty range
+ * is not a match: there is nothing to compare, and ancestry already covers it.
+ */
+function compareRange(at, landed, tip, base) {
+    const range = base === null ? `${landed}..${tip}` : `${base}..${tip}`;
+    const listed = at.logLines({ range, format: '%H', ...CALL });
+    const changing = commitsWithChanges(at, range);
+    const wanted = new Set(listed);
+    const seen = new Map();
+    for (const entry of at.cherry(landed, tip, CALL)) {
+        if (wanted.has(entry.sha))
+            seen.set(entry.sha, entry.equivalent);
+    }
+    // `git cherry` calls two empty commits equivalent, so an empty commit proves
+    // nothing and never counts.
+    const unmatched = listed.filter((sha) => seen.get(sha) !== true || !changing.has(sha));
+    const matched = listed.filter((sha) => seen.get(sha) === true && changing.has(sha)).length;
+    return { all: listed.length > 0 && unmatched.length === 0, matched, unmatched };
+}
+/** The commits in `range` whose own change touches at least one path. Merge commits show no diff and are never listed. */
+function commitsWithChanges(at, range) {
+    const marker = '\x1e';
+    const out = at.log({ range, format: 'format:%x1e%H', nameStatus: true, ...CALL });
+    const changing = new Set();
+    for (const record of out.split(marker)) {
+        const [sha, ...rest] = record.split('\n');
+        if (sha !== undefined && /^[0-9a-f]{40,64}$/.test(sha) && rest.some((l) => l.trim() !== '')) {
+            changing.add(sha);
+        }
+    }
+    return changing;
+}
+/**
+ * True when the combined change from the merge base to `commitish` equals the
+ * patch of one commit on `landed`.
+ *
+ * A commit with `commitish`'s tree on the merge base is built without moving
+ * any ref, and `git cherry` compares it with the landed commits. The patch
+ * must not be empty: an empty change has no patch id, and a tree equal to the
+ * merge base's is refused before the question is asked.
+ *
+ * Any one landed commit with the same net patch is enough, not necessarily a
+ * commit that came from this branch. That is why a `squashed` verdict is
+ * only a hint until {@link contentConfirmed} agrees.
+ */
+function squashedMatches(at, landed, commitish) {
+    const base = at.mergeBase(landed, commitish, CALL);
+    if (base === null)
+        return false;
+    const tree = at.resolveRef(`${commitish}^{tree}`, CALL);
+    const baseTree = at.resolveRef(`${base}^{tree}`, CALL);
+    if (tree === null || baseTree === null || tree === baseTree)
+        return false;
+    const probe = at.commitTree(tree, { parents: [base], message: 'repo-cleaner: patch equivalence probe' }, { env: PROBE_ENV });
+    const entries = at.cherry(landed, probe, CALL);
+    return entries.length === 1 && entries[0].sha === probe && entries[0].equivalent;
+}
+/** `<short sha> <subject>` for each of `shas` found in `base..tip`, capped. */
+function describeCommits(at, range, shas) {
+    const wanted = new Set(shas);
+    return at
+        .logLines({ range, format: '%H %h %s', ...CALL })
+        .map((line) => line.split(' '))
+        .filter(([sha]) => sha !== undefined && wanted.has(sha))
+        .map((parts) => parts.slice(1).join(' ').trim())
+        .slice(0, UNMATCHED_SHOWN);
+}
+function assess(repo, tip, git, prHead) {
+    const at = git.at(repo.root);
+    const none = { check: null, unmatched: [] };
+    // A shallow clone cuts history short, so the merge base and the commit list
+    // are not the real ones. Anything but a plain "false" is read as shallow.
+    if (at.revParse('--is-shallow-repository', CALL) !== 'false')
+        return none;
+    const landed = at.resolveRef(landedRef(repo), CALL);
+    const tipSha = at.resolveRef(`${tip}^{commit}`, CALL);
+    if (landed === null || tipSha === null)
+        return none;
+    const whole = compareRange(at, landed, tipSha, null);
+    if (whole.all)
+        return { check: 'per-commit' };
+    if (squashedMatches(at, landed, tipSha))
+        return { check: 'squashed' };
+    if (prHead !== null && prHead !== tipSha) {
+        const headSha = at.resolveRef(`${prHead}^{commit}`, CALL);
+        if (headSha !== null &&
+            at.isAncestor(headSha, tipSha, CALL) &&
+            squashedMatches(at, landed, headSha)) {
+            const after = compareRange(at, landed, tipSha, headSha);
+            if (after.all)
+                return { check: 'head-moved' };
+            // The squash merge is real, so the commits after it are what is left.
+            return {
+                check: null,
+                unmatched: describeCommits(at, `${headSha}..${tipSha}`, after.unmatched),
+            };
+        }
+    }
+    // Some commits are on the landed ref and some are not: name the rest.
+    if (whole.matched > 0 && whole.unmatched.length > 0) {
+        return {
+            check: null,
+            unmatched: describeCommits(at, `${landed}..${tipSha}`, whole.unmatched),
+        };
+    }
+    return none;
+}
+/**
+ * The second, independent check: merging `tip` into the landed ref changes
+ * nothing.
+ *
+ * `git merge-tree --write-tree <landed> <tip>` computes the merge in the object
+ * store. It must be clean and its tree must equal the landed ref's tree, which
+ * shows the branch's content is already there and not just a similar patch.
+ * Needs git 2.38 or later; an older git, a failure, a conflict or a tree that
+ * is not a sha all mean "not confirmed". A tip whose work was landed and later
+ * reverted on the default branch is not confirmed either: the merge brings the
+ * work back.
+ */
+function contentConfirmed(at, landed, tipSha) {
+    const merged = at.mergeTree(landed, tipSha, CALL);
+    if (merged.status !== 'clean' || !/^([0-9a-f]{40}|[0-9a-f]{64})$/.test(merged.tree))
+        return false;
+    const landedTree = at.resolveRef(`${landed}^{tree}`, CALL);
+    return landedTree !== null && landedTree === merged.tree;
+}
+/** {@link contentConfirmed} for `tip` against the landed ref; any error is false. */
+function confirm(repo, tip, git) {
+    try {
+        const at = git.at(repo.root);
+        const landed = at.resolveRef(landedRef(repo), CALL);
+        const tipSha = at.resolveRef(`${tip}^{commit}`, CALL);
+        return landed !== null && tipSha !== null && contentConfirmed(at, landed, tipSha);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether the work on `tip` is already on the landed ref, judged by patch.
+ *
+ * Checked in order: every commit one by one (`per-commit`), the branch as one
+ * squashed change (`squashed`), and, with `prHead` set to the head of a merged
+ * pull request that is not `tip`, that head squashed plus each later commit
+ * one by one (`head-moved`). A branch with a commit that is not on the landed
+ * ref is never landed. A passing check also carries `confirmed`, the outcome
+ * of the content check ({@link contentConfirmed}).
+ *
+ * Reads only; it writes one unreferenced commit object and no ref. Any error
+ * returns `{ check: null, unmatched: [] }`: a check that cannot finish is not
+ * evidence.
+ */
+export function assessLanding(repo, tip, git, prHead = null) {
+    let verdict;
+    try {
+        verdict = assess(repo, tip, git, prHead);
+    }
+    catch {
+        return { check: null, unmatched: [] };
+    }
+    if (verdict.check === null)
+        return verdict;
+    return { check: verdict.check, confirmed: confirm(repo, tip, git) };
+}
+/**
+ * The patch-equivalence verdict for a branch the first two signals did not
+ * settle. A merged PR at an earlier head lets the check trust that head's
+ * squash merge and look at the commits after it.
+ */
+export function judgeLanding(repo, tip, pr, gap, git) {
+    const prHead = pr !== undefined && gap === 'head-moved' ? pr.headOid : null;
+    return assessLanding(repo, tip, git, prHead);
+}
+/** True when the verdict is a patch match that the content check agreed with, so no grant is needed. */
+export function landingConfirmed(landing) {
+    return landing !== null && landing.check !== null && landing.confirmed;
+}
+/** {@link assessLanding}, reduced to the check that passed, or null. */
+export function patchEquivalent(repo, tip, git, prHead = null) {
+    return assessLanding(repo, tip, git, prHead).check;
+}
+/** Write the landing evidence into a row's `facts`. */
+export function recordLanding(facts, landing) {
+    if (landing.check !== null) {
+        facts['landing'] = 'patch-equivalent';
+        facts['landing_check'] = landing.check;
+        facts['landing_content_confirmed'] = landing.confirmed;
+    }
+    else if (landing.unmatched.length > 0) {
+        facts['unmatched_commits'] = landing.unmatched;
+    }
+}
+/**
+ * The part of a row's reason that says whether the content check agreed, for a
+ * patch-equivalent verdict.
+ */
+export function confirmationNote(landing) {
+    return landing.confirmed
+        ? 'content confirmed by merge-tree'
+        : 'content not confirmed by merge-tree, so abandon-unmerged is required';
+}
+/** One sentence naming the commits that kept a partly landed branch from counting, or null. */
+export function unmatchedSentence(landing, repo) {
+    if (landing.check !== null || landing.unmatched.length === 0)
+        return null;
+    return `Part of the work is on \`${landedRef(repo)}\`, but these commits are not (no patch-equivalent commit): ${landing.unmatched.join('; ')}.`;
+}

package/dist/types.d.ts

@@ -26,7 +26,10 @@ export declare function authorizationsFor(flags: Partial<Record<Authorization, b
 export interface RepoInfo {
     /** The main checkout's root, even when the sweep was pointed at a worktree. */
     root: string;
-    /** `owner/name` when the remote is a recognisable host coordinate. */
+    /**
+     * `owner/name` for a github.com remote, `host/owner/name` for one on another
+     * host, or null when the remote names no repository.
+     */
     slug: string | null;
     mainBranch: string;
     remote: string | null;
@@ -40,6 +43,8 @@ export interface RepoInfo {
 export declare function landedRef(repo: RepoInfo): string;
 /** True when the repository has a remote the sweep did not fetch, so its refs may be stale. */
 export declare function isUnfetched(repo: RepoInfo): boolean;
+/** Why a merged PR does not prove that a tip landed. */
+export type PrEvidenceGap = 'other-base' | 'head-moved';
 /** A pull request, reduced to what classification consults. */
 export interface PRInfo {
     number: number;

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, from its package.json when it was built. */
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.9.0";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 // Generated by cli-tool-stamp-version from package.json. Do not edit.
 /** This package's version, from its package.json when it was built. */
-export const VERSION = '0.6.0';
+export const VERSION = '0.9.0';

package/dist/worktrees.js

@@ -10,6 +10,7 @@ import { isAbsolute, join, sep } from 'node:path';
 import { shellJoin } from '@osdlc/command-seam';
 import { nodeGuard } from '@osdlc/path-guard/node';
 import { gapSentence, recordPr } from "./branches.js";
+import { confirmationNote, judgeLanding, landingConfirmed, recordLanding, unmatchedSentence, } from "./landing.js";
 import { busyHolders, isIdleHolder, parseLockOwner } from "./processes.js";
 import { authorizationsFor, landedRef, makeItem, } from "./types.js";
 /** The command line, not run, that removes the worktree at `path`. */
@@ -235,7 +236,14 @@ export function classifyWorktree(opts) {
         facts['unique_commits'] = unpushed.length;
     // A merged PR at HEAD lands every commit, even ones the fallback
     // `compare_against` (a squash merge, a deleted upstream) counts as ahead.
-    const unlanded = unpushed.length > 0 && !landed;
+    // A rebase merge, cherry-pick or squash merge leaves HEAD off the default
+    // branch; the patches say whether the work is there anyway. Judged from HEAD,
+    // so a dirty tree is still caught by the dirty-file check below.
+    const patch = landed || !onDisk || head === null ? null : judgeLanding(repo, head, pr, gap, git);
+    if (patch !== null)
+        recordLanding(facts, patch);
+    const patchLanded = patch !== null && patch.check !== null;
+    const unlanded = unpushed.length > 0 && !landed && !landingConfirmed(patch);
     const requires = authorizationsFor({
         'abandon-unmerged': unlanded,
         'discard-changes': dirtyFiles.length > 0,
@@ -289,6 +297,11 @@ export function classifyWorktree(opts) {
             investigationParts: [
                 `Worktree ${path} has uncommitted work or unpushed commits.`,
                 `Branch: ${branch || '(detached)'}.`,
+                ...(patchLanded && unlanded
+                    ? [
+                        `Its commits are patch-equivalent to commits on ${landedRef(repo)} (${patch.check}), but ${confirmationNote(patch)}.`,
+                    ]
+                    : []),
                 'Decide whether to preserve, push, or discard.',
             ],
         });
@@ -305,6 +318,18 @@ export function classifyWorktree(opts) {
             requires,
         });
     }
+    if (patchLanded) {
+        return makeItem({
+            category: 'worktree',
+            id: path,
+            classification: 'safe-to-delete',
+            action: 'remove',
+            reason: `clean; patch-equivalent to commits on ${landedRef(repo)} (${patch.check}); ${confirmationNote(patch)}`,
+            facts,
+            commands: safeRemove,
+            requires,
+        });
+    }
     if (branch && !branchExists) {
         return makeItem({
             category: 'worktree',
@@ -325,6 +350,9 @@ export function classifyWorktree(opts) {
     parts.push(pr ? `PR #${pr.number} is ${pr.state}.` : 'No associated PR.');
     if (pr && gap)
         parts.push(gapSentence(pr, gap, repo));
+    const unmatched = patch === null ? null : unmatchedSentence(patch, repo);
+    if (unmatched !== null)
+        parts.push(unmatched);
     return makeItem({
         category: 'worktree',
         id: path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/repo-cleaner",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "What has been merged into the default branch, and what can go away. Inventories local branches, worktrees and remote branches across one repository or many, classifying each with the evidence behind the verdict and the command that would act on it. Plans and applies approved deletes, compare-and-swap.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",
@@ -49,12 +49,12 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@osdlc/cli-tool": "^0.11.0",
+    "@osdlc/cli-tool": "^0.12.0",
     "@osdlc/command-seam": "^0.14.0",
     "@osdlc/config-layers": "^0.8.0",
     "@osdlc/path-guard": "^0.3.1",
-    "@osdlc/typed-gh": "^0.11.1",
-    "@osdlc/typed-git": "^0.10.0"
+    "@osdlc/typed-gh": "^0.12.1",
+    "@osdlc/typed-git": "^0.11.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",