@osdlc/repo-cleaner 0.17.2 → 0.19.0

package/dist/hooks.d.ts

@@ -1,18 +1,14 @@
 /**
  * What a host may supply that this package cannot know for itself.
  *
- * A standalone run passes none; a host passes `annotate` so its verdicts
- * survive `applyPlan`'s re-sweep.
+ * A standalone run passes none; a host passes `annotate` so its verdicts are
+ * in the sweep, the plan, and the re-check `check` and `run` make.
  */
-import type { RepoInfo, SweepItem } from './types.ts';
+import type { RepoInfo, Row } from './types.ts';
 /**
- * Re-rank a repository's swept rows with what the host knows. Runs after the
- * sweep, on its output; it never reaches into classification. A host that
- * holds back or demotes a worktree passes its own annotated rows through
- * `holdFreedBranches`, as `applyPlan` does, so that worktree's branch is kept
- * too.
+ * Re-rank a repository's swept rows with what the host knows: change a
+ * verdict, add a note, drop a row. Runs after classification, on its output;
+ * it never reaches into it. A worktree the host holds back keeps its branch
+ * too: the sweep applies that rule after the hook.
  */
-export type Annotate = (repo: RepoInfo, items: SweepItem[]) => SweepItem[];
-export interface HostHooks {
-    annotate?: Annotate | undefined;
-}
+export type Annotate = (repo: RepoInfo, rows: Row[]) => Row[];

package/dist/hooks.js

@@ -1,7 +1,7 @@
 /**
  * What a host may supply that this package cannot know for itself.
  *
- * A standalone run passes none; a host passes `annotate` so its verdicts
- * survive `applyPlan`'s re-sweep.
+ * A standalone run passes none; a host passes `annotate` so its verdicts are
+ * in the sweep, the plan, and the re-check `check` and `run` make.
  */
 export {};

package/dist/index.d.ts

@@ -2,30 +2,23 @@
  * `@osdlc/repo-cleaner` — 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. The sweep never deletes anything; `applyPlan`
- * deletes the rows of a plan a person approved.
+ * `sweep` inventories worktrees, local branches and remote branches across
+ * one repository or many, and judges each row: `delete`, `review`, `keep` or
+ * `blocked`, with the risks its deletion carries and the evidence behind it.
+ * The sweep deletes nothing. `plan` saves the rows and their evidence;
+ * `check` resolves a person's approval against a plan and shows the steps a
+ * run would take; `run` takes them, compare-and-swap, verifying each.
  *
- * Two signals settle most items — a merged pull request, and ancestry of the
- * default branch — and either alone is enough. A host that knows more than
- * git does (an issue tracker, say) re-ranks the returned rows
- * rather than reaching into classification, which is why every row carries
- * its facts and why `investigationParts` is a list rather than a sentence.
+ * A host that knows more than git does (an issue tracker, say) passes
+ * `annotate` to re-rank the rows, rather than reaching into classification,
+ * which is why every row carries its evidence and why `notes` is a list.
  */
-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, ApplyRefused, applyPlan, type RowSelection, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
-export type { Annotate, HostHooks } from './hooks.ts';
-export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, type Plan, type PlanRepo, type PlannableRow, } from './plan.ts';
-export { RECEIPT_VERSION, ReceiptSchema, type Dropped, type Receipt, type RowRef, type Step, } from './receipt.ts';
-export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, type DefaultProbeOptions, type LockOwner, type ProcessHolder, type ProcessProbe, } from './processes.ts';
-export { fetchPrs } from './prs.ts';
-export { PROVIDER_CHOICES, PROVIDER_NAMES, chooseProvider, forgeTarget, githubProvider, gitlabProvider, probeProvider, providers, type ForgeTarget, type PrProvider, type ProviderChoice, type ProviderName, type ProviderStatus, } from './providers/index.ts';
-export { expandTilde, isCheckoutRoot, resolveEntries, type Resolution, type ResolveOptions, } from './resolve.ts';
-export { holdFreedBranches, sweepRepo, sweepRepos, type SweepOptions, type SweepReposOptions, } from './sweep.ts';
-export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, type ApplySummary, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from './render.ts';
-export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, type Authorization, type Category, type Classification, type DuplicateCheckout, type PRInfo, type RepoInfo, type RepoSweep, type ScanStats, type Scope, type SummaryBucket, type SweepItem, type SweepProgress, type SweepResult, type UnresolvedEntry, } from './types.ts';
+export { sweep, inspectWorktree, type Runners, type SweepOptions } from './sweep.ts';
+export { PLAN_VERSION, plan, readPlan, writePlan, type Plan, type PlanRepo, type PlanRow, } from './plan.ts';
+export { check, run, type Allow, type Approval, type CheckOptions, type Preview, type ResolvedApproval, type Resolved, type RunOptions, } from './clean.ts';
+export { RECEIPT_VERSION, ReceiptSchema, type DropReason, type Dropped, type Receipt, type Step, } from './receipt.ts';
+export { render, type RunSummary, type Style } from './render.ts';
+export { defaultProcessProbe, type ProcessHolder, type ProcessProbe } from './processes.ts';
+export { providers, type PrProvider, type ProviderChoice } from './providers/index.ts';
+export type { Annotate } from './hooks.ts';
+export { KINDS, RISKS, RepoCleanerError, type Action, type Blocker, type BranchEvidence, type BranchRow, type Bucket, type Counts, type ErrorCode, type Kind, type LandingEvidence, type PrEvidence, type RemoteEvidence, type RemoteRow, type RepoInfo, type RepoNote, type RepoSweep, type Risk, type Row, type RowId, type SubmoduleEvidence, type Sweep, type SweepProgress, type SweptWith, type Verdict, type WorktreeEvidence, type WorktreeRow, } from './types.ts';

package/dist/index.js

@@ -2,29 +2,22 @@
  * `@osdlc/repo-cleaner` — 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. The sweep never deletes anything; `applyPlan`
- * deletes the rows of a plan a person approved.
+ * `sweep` inventories worktrees, local branches and remote branches across
+ * one repository or many, and judges each row: `delete`, `review`, `keep` or
+ * `blocked`, with the risks its deletion carries and the evidence behind it.
+ * The sweep deletes nothing. `plan` saves the rows and their evidence;
+ * `check` resolves a person's approval against a plan and shows the steps a
+ * run would take; `run` takes them, compare-and-swap, verifying each.
  *
- * Two signals settle most items — a merged pull request, and ancestry of the
- * default branch — and either alone is enough. A host that knows more than
- * git does (an issue tracker, say) re-ranks the returned rows
- * rather than reaching into classification, which is why every row carries
- * its facts and why `investigationParts` is a list rather than a sentence.
+ * A host that knows more than git does (an issue tracker, say) passes
+ * `annotate` to re-rank the rows, rather than reaching into classification,
+ * which is why every row carries its evidence and why `notes` is a list.
  */
-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, ApplyRefused, applyPlan, parseGrant, parseRowRef, } from "./apply.js";
-export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, } from "./plan.js";
+export { sweep, inspectWorktree } from "./sweep.js";
+export { PLAN_VERSION, plan, readPlan, writePlan, } from "./plan.js";
+export { check, run, } from "./clean.js";
 export { RECEIPT_VERSION, ReceiptSchema, } from "./receipt.js";
-export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, } from "./processes.js";
-export { fetchPrs } from "./prs.js";
-export { PROVIDER_CHOICES, PROVIDER_NAMES, chooseProvider, forgeTarget, githubProvider, gitlabProvider, probeProvider, providers, } from "./providers/index.js";
-export { expandTilde, isCheckoutRoot, resolveEntries, } from "./resolve.js";
-export { holdFreedBranches, sweepRepo, sweepRepos, } from "./sweep.js";
-export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from "./render.js";
-export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, } from "./types.js";
+export { render } from "./render.js";
+export { defaultProcessProbe } from "./processes.js";
+export { providers } from "./providers/index.js";
+export { KINDS, RISKS, RepoCleanerError, } from "./types.js";

package/dist/landing.d.ts

@@ -24,7 +24,7 @@
  * 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';
+import { type LandingEvidence, 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). */
@@ -77,8 +77,8 @@ export declare function judgeLanding(repo: RepoInfo, tip: string, pr: PRInfo | u
 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;
+/** Write the landing evidence into a row's evidence. */
+export declare function recordLanding(evidence: LandingEvidence, landing: Landing): void;
 /**
  * The part of a row's reason that says whether the content check agreed, for a
  * patch-equivalent verdict.

package/dist/landing.js

@@ -23,7 +23,7 @@
  * 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";
+import { landedRef, } from "./types.js";
 /** Cap on {@link Landing} `unmatched`. */
 const UNMATCHED_SHOWN = 10;
 /**
@@ -237,15 +237,15 @@ export function landingConfirmed(landing) {
 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) {
+/** Write the landing evidence into a row's evidence. */
+export function recordLanding(evidence, landing) {
     if (landing.check !== null) {
-        facts['landing'] = 'patch-equivalent';
-        facts['landing_check'] = landing.check;
-        facts['landing_content_confirmed'] = landing.confirmed;
+        evidence.landing = 'patch-equivalent';
+        evidence.landingCheck = landing.check;
+        evidence.landingContentConfirmed = landing.confirmed;
     }
     else if (landing.unmatched.length > 0) {
-        facts['unmatched_commits'] = landing.unmatched;
+        evidence.unmatchedCommits = landing.unmatched;
     }
 }
 /**

package/dist/plan.d.ts

@@ -1,23 +1,27 @@
 /**
- * The cleanup plan: the deletable rows of a sweep, each with a fingerprint of
- * the facts its verdict rests on. `applyPlan` re-sweeps and drops any row
- * whose fingerprint no longer matches.
+ * The plan: a sweep's deletable rows, each with a fingerprint of the evidence
+ * its verdict rests on, and the options the sweep ran with. `check` sweeps
+ * again with the same options and drops any row whose fingerprint moved.
  */
 import { z } from 'zod';
-import { type ProviderChoice } from './providers/types.ts';
-import { type SweepItem } from './types.ts';
-export declare const PLAN_VERSION = 1;
-/** The categories a plan can hold, in the order apply runs them. */
-export declare const PLAN_CATEGORIES: readonly ["worktree", "local_branch", "remote_branch"];
-export type PlanCategory = (typeof PLAN_CATEGORIES)[number];
+import { type Row, type Sweep } from './types.ts';
+export declare const PLAN_VERSION = 2;
+/** A row id, `<kind>:<name>` with a name; shared by the plan and the receipt. */
+export declare const RowIdSchema: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
 export declare const PlanRowSchema: z.ZodObject<{
-    category: z.ZodEnum<{
-        local_branch: "local_branch";
-        worktree: "worktree";
-        remote_branch: "remote_branch";
+    id: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
+    verdict: z.ZodEnum<{
+        delete: "delete";
+        review: "review";
+        keep: "keep";
+        blocked: "blocked";
     }>;
-    id: z.ZodString;
-    requires: z.ZodArray<z.ZodEnum<{
+    action: z.ZodNullable<z.ZodEnum<{
+        delete: "delete";
+        remove: "remove";
+        prune: "prune";
+    }>>;
+    risks: z.ZodArray<z.ZodEnum<{
         "abandon-unmerged": "abandon-unmerged";
         "discard-changes": "discard-changes";
         "confirm-open-pr": "confirm-open-pr";
@@ -27,24 +31,21 @@ export declare const PlanRowSchema: z.ZodObject<{
 export type PlanRow = z.infer<typeof PlanRowSchema>;
 export declare const PlanRepoSchema: z.ZodObject<{
     root: z.ZodString;
-    remote: z.ZodNullable<z.ZodString>;
-    no_gh: z.ZodBoolean;
-    provider: z.ZodOptional<z.ZodEnum<{
-        github: "github";
-        gitlab: "gitlab";
-        auto: "auto";
-        none: "none";
-    }>>;
-    branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    fetch: z.ZodDefault<z.ZodBoolean>;
+    fetched: z.ZodBoolean;
     rows: z.ZodArray<z.ZodObject<{
-        category: z.ZodEnum<{
-            local_branch: "local_branch";
-            worktree: "worktree";
-            remote_branch: "remote_branch";
+        id: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
+        verdict: z.ZodEnum<{
+            delete: "delete";
+            review: "review";
+            keep: "keep";
+            blocked: "blocked";
         }>;
-        id: z.ZodString;
-        requires: z.ZodArray<z.ZodEnum<{
+        action: z.ZodNullable<z.ZodEnum<{
+            delete: "delete";
+            remove: "remove";
+            prune: "prune";
+        }>>;
+        risks: z.ZodArray<z.ZodEnum<{
             "abandon-unmerged": "abandon-unmerged";
             "discard-changes": "discard-changes";
             "confirm-open-pr": "confirm-open-pr";
@@ -54,28 +55,42 @@ export declare const PlanRepoSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type PlanRepo = z.infer<typeof PlanRepoSchema>;
 export declare const PlanSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    created_at: z.ZodString;
-    repos: z.ZodArray<z.ZodObject<{
-        root: z.ZodString;
-        remote: z.ZodNullable<z.ZodString>;
-        no_gh: z.ZodBoolean;
-        provider: z.ZodOptional<z.ZodEnum<{
+    version: z.ZodLiteral<2>;
+    createdAt: z.ZodString;
+    options: z.ZodObject<{
+        only: z.ZodArray<z.ZodEnum<{
+            worktree: "worktree";
+            branch: "branch";
+            remote: "remote";
+        }>>;
+        remote: z.ZodBoolean;
+        offline: z.ZodBoolean;
+        against: z.ZodNullable<z.ZodString>;
+        provider: z.ZodEnum<{
             github: "github";
             gitlab: "gitlab";
             auto: "auto";
             none: "none";
-        }>>;
-        branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-        fetch: z.ZodDefault<z.ZodBoolean>;
+        }>;
+        branch: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    repos: z.ZodArray<z.ZodObject<{
+        root: z.ZodString;
+        fetched: z.ZodBoolean;
         rows: z.ZodArray<z.ZodObject<{
-            category: z.ZodEnum<{
-                local_branch: "local_branch";
-                worktree: "worktree";
-                remote_branch: "remote_branch";
+            id: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
+            verdict: z.ZodEnum<{
+                delete: "delete";
+                review: "review";
+                keep: "keep";
+                blocked: "blocked";
             }>;
-            id: z.ZodString;
-            requires: z.ZodArray<z.ZodEnum<{
+            action: z.ZodNullable<z.ZodEnum<{
+                delete: "delete";
+                remove: "remove";
+                prune: "prune";
+            }>>;
+            risks: z.ZodArray<z.ZodEnum<{
                 "abandon-unmerged": "abandon-unmerged";
                 "discard-changes": "discard-changes";
                 "confirm-open-pr": "confirm-open-pr";
@@ -85,38 +100,29 @@ export declare const PlanSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Plan = z.infer<typeof PlanSchema>;
-/** What planning reads off a row. A host's own row type plans the same way. */
-export type PlannableRow = Pick<SweepItem, 'id' | 'facts' | 'requires' | 'deletable'> & {
-    category: string;
-};
-export declare function isPlanCategory(category: string): category is PlanCategory;
 /**
- * The facts a row's verdict rests on. A branch: its sha and its PR's number
- * and state. A worktree: HEAD, branch, how much unlanded work it holds and
- * whether its lock was stale and whether it is on disk, so a lock taken or
- * revived after planning, or a directory that came back, drops the row.
+ * The evidence a row's verdict rests on. A branch: its sha and its PR's number
+ * and state. A worktree: HEAD, branch, how much unlanded work it holds, whether
+ * its lock was stale, whether it is on disk, and each submodule's state, so a
+ * lock taken or revived after planning, a directory that came back, or a
+ * submodule that changed, drops the row.
  */
-export declare function fingerprint(item: PlannableRow): Record<string, unknown>;
+export declare function fingerprint(row: Row): Record<string, unknown>;
 /** Equal fingerprints, treating a missing key as null. */
 export declare function sameFingerprint(a: Record<string, unknown>, b: Record<string, unknown>): boolean;
-/** One repository's plan entry: its deletable rows. */
-export declare function planRepo(root: string, opts: {
-    remote: string | null;
-    noProvider: boolean;
-    branch?: string | null;
-    fetch?: boolean;
-    provider?: ProviderChoice | undefined;
-}, items: readonly PlannableRow[]): PlanRepo;
+/** True when `row` could run without being picked by name: it has an action and is not blocked. */
+export declare function runnable(row: Pick<PlanRow, 'action' | 'verdict'>): boolean;
+/** A plan of `sweep`: every row, in every repository it read. */
+export declare function plan(sweep: Sweep, now?: Date): Plan;
 /** A UTC timestamp safe in a file name, e.g. `2026-10-04T12-30-05-123Z`. */
 export declare function fileStamp(d: Date): string;
 export declare function writePlan(path: string, plan: Plan): void;
-/** A plan file that cannot be read or does not match {@link PlanSchema}. */
-export declare class PlanReadError extends Error {
-}
 /**
  * Parse a plan's JSON text. `source` names where it came from, for the error.
- * @throws PlanReadError
+ * A plan of another version is refused, not translated: sweep again.
+ *
+ * @throws RepoCleanerError (`bad-plan`)
  */
 export declare function parsePlan(text: string, source: string): Plan;
-/** @throws PlanReadError */
+/** @throws RepoCleanerError (`bad-plan`) */
 export declare function readPlan(path: string): Plan;

package/dist/plan.js

@@ -1,74 +1,69 @@
 /**
- * The cleanup plan: the deletable rows of a sweep, each with a fingerprint of
- * the facts its verdict rests on. `applyPlan` re-sweeps and drops any row
- * whose fingerprint no longer matches.
+ * The plan: a sweep's deletable rows, each with a fingerprint of the evidence
+ * its verdict rests on, and the options the sweep ran with. `check` sweeps
+ * again with the same options and drops any row whose fingerprint moved.
  */
 import { readFileSync } from 'node:fs';
 import { z } from 'zod';
 import { PROVIDER_CHOICES } from "./providers/types.js";
-import { AUTHORIZATIONS } from "./types.js";
+import { ACTIONS, KINDS, RISKS, RepoCleanerError, VERDICTS, parseRowId, } from "./types.js";
 import { writeJsonAtomic } from "./write-json.js";
-export const PLAN_VERSION = 1;
-/** The categories a plan can hold, in the order apply runs them. */
-export const PLAN_CATEGORIES = ['worktree', 'local_branch', 'remote_branch'];
+export const PLAN_VERSION = 2;
+/** A row id, `<kind>:<name>` with a name; shared by the plan and the receipt. */
+export const RowIdSchema = z.custom((v) => typeof v === 'string' && (parseRowId(v)?.name ?? '') !== '', { message: 'expected <kind>:<name>' });
 export const PlanRowSchema = z.object({
-    category: z.enum(PLAN_CATEGORIES),
-    id: z.string(),
-    requires: z.array(z.enum(AUTHORIZATIONS)),
+    id: RowIdSchema,
+    /** The sweep's verdict when the plan was made. Without a pick, only `delete` rows run. */
+    verdict: z.enum(VERDICTS),
+    /** What deleting it does; null for a row that can never be deleted, kept so a pick of it is skipped with its reason. */
+    action: z.enum(ACTIONS).nullable(),
+    risks: z.array(z.enum(RISKS)),
     fingerprint: z.record(z.string(), z.unknown()),
 });
 export const PlanRepoSchema = z.object({
     root: z.string(),
-    /** The `remote` the sweep ran with; the re-sweep uses the same. */
-    remote: z.string().nullable(),
-    /**
-     * True when the sweep asked no provider for pull requests. The name is the
-     * plan format's, from when GitHub was the only provider; renaming it would
-     * break every plan already written.
-     */
-    no_gh: z.boolean(),
-    /** The provider choice the sweep ran with; absent is `auto`. `no_gh` wins over it. */
-    provider: z.enum(PROVIDER_CHOICES).optional(),
-    /** The `branch` the sweep was narrowed to; the re-sweep uses the same. */
-    branch: z.string().nullable().default(null),
-    /**
-     * Whether the sweep fetched before classifying. The re-sweep fetches too, so
-     * it judges against the remote's current default branch, as the sweep did.
-     * A plan written before this field reads as not fetched.
-     */
-    fetch: z.boolean().default(false),
+    /** Whether this repository's sweep fetched; the re-check fetches too, so it judges against the same default branch. */
+    fetched: z.boolean(),
     rows: z.array(PlanRowSchema),
 });
 export const PlanSchema = z.object({
     version: z.literal(PLAN_VERSION),
-    created_at: z.string(),
+    createdAt: z.string(),
+    /** What was swept; the re-check sweeps the same. `SweptWith` is this object's type. */
+    options: z.object({
+        only: z.array(z.enum(KINDS)),
+        remote: z.boolean(),
+        offline: z.boolean(),
+        against: z.string().nullable(),
+        provider: z.enum(PROVIDER_CHOICES),
+        branch: z.string().nullable(),
+    }),
     repos: z.array(PlanRepoSchema),
 });
-export function isPlanCategory(category) {
-    return PLAN_CATEGORIES.includes(category);
-}
 /**
- * The facts a row's verdict rests on. A branch: its sha and its PR's number
- * and state. A worktree: HEAD, branch, how much unlanded work it holds and
- * whether its lock was stale and whether it is on disk, so a lock taken or
- * revived after planning, or a directory that came back, drops the row.
+ * The evidence a row's verdict rests on. A branch: its sha and its PR's number
+ * and state. A worktree: HEAD, branch, how much unlanded work it holds, whether
+ * its lock was stale, whether it is on disk, and each submodule's state, so a
+ * lock taken or revived after planning, a directory that came back, or a
+ * submodule that changed, drops the row.
  */
-export function fingerprint(item) {
-    const f = item.facts;
-    if (item.category === 'worktree') {
+export function fingerprint(row) {
+    if (row.kind === 'worktree') {
+        const e = row.evidence;
         return {
-            head: f['head'] ?? null,
-            branch: f['branch'] ?? null,
-            dirty_files: f['dirty_files'] ?? null,
-            unpushed_commits: f['unpushed_commits'] ?? null,
-            stale_lock: f['stale_lock'] ?? null,
-            // Prune or remove: a directory that came back between plan and apply
+            head: e.head,
+            branch: e.branch,
+            dirtyFiles: e.dirtyFiles ?? null,
+            unpushedCommits: e.unpushedCommits ?? null,
+            staleLock: e.staleLock ?? null,
+            // Prune or remove: a directory that came back between plan and run
             // must not turn a prune into a remove.
-            on_disk: f['on_disk'] ?? null,
+            onDisk: e.onDisk ?? null,
+            submodules: e.submodules ?? null,
         };
     }
-    const pr = f['pr'];
-    return { sha: f['sha'] ?? null, pr_number: pr?.number ?? null, pr_state: pr?.state ?? null };
+    const pr = row.evidence.pr;
+    return { sha: row.evidence.sha, prNumber: pr?.number ?? null, prState: pr?.state ?? null };
 }
 /** Equal fingerprints, treating a missing key as null. */
 export function sameFingerprint(a, b) {
@@ -79,27 +74,33 @@ export function sameFingerprint(a, b) {
     }
     return true;
 }
-/** One repository's plan entry: its deletable rows. */
-export function planRepo(root, opts, items) {
-    const rows = [];
-    for (const item of items) {
-        if (!item.deletable || !isPlanCategory(item.category))
-            continue;
-        rows.push({
-            category: item.category,
-            id: item.id,
-            requires: item.requires,
-            fingerprint: fingerprint(item),
-        });
-    }
+/**
+ * The rows of `rows` as a plan holds them: every one. Without a pick only those
+ * with an action run; the rest are there so a pick of one is skipped with its
+ * reason rather than refused as unknown.
+ */
+function planRows(rows) {
+    return rows.map((row) => ({
+        id: row.id,
+        verdict: row.verdict,
+        action: row.action,
+        risks: row.risks,
+        fingerprint: fingerprint(row),
+    }));
+}
+/** True when `row` could run without being picked by name: it has an action and is not blocked. */
+export function runnable(row) {
+    return row.action !== null && row.verdict !== 'blocked';
+}
+/** A plan of `sweep`: every row, in every repository it read. */
+export function plan(sweep, now = new Date()) {
     return {
-        root,
-        remote: opts.remote,
-        no_gh: opts.noProvider,
-        ...(opts.provider === undefined || opts.provider === 'auto' ? {} : { provider: opts.provider }),
-        branch: opts.branch ?? null,
-        fetch: opts.fetch ?? false,
-        rows,
+        version: PLAN_VERSION,
+        createdAt: now.toISOString(),
+        options: { ...sweep.options },
+        repos: sweep.repos.flatMap((s) => s.repo === null
+            ? []
+            : [{ root: s.repo.root, fetched: s.repo.fetched, rows: planRows(s.rows) }]),
     };
 }
 /** A UTC timestamp safe in a file name, e.g. `2026-10-04T12-30-05-123Z`. */
@@ -109,12 +110,11 @@ export function fileStamp(d) {
 export function writePlan(path, plan) {
     writeJsonAtomic(path, plan);
 }
-/** A plan file that cannot be read or does not match {@link PlanSchema}. */
-export class PlanReadError extends Error {
-}
 /**
  * Parse a plan's JSON text. `source` names where it came from, for the error.
- * @throws PlanReadError
+ * A plan of another version is refused, not translated: sweep again.
+ *
+ * @throws RepoCleanerError (`bad-plan`)
  */
 export function parsePlan(text, source) {
     let raw;
@@ -122,21 +122,26 @@ export function parsePlan(text, source) {
         raw = JSON.parse(text);
     }
     catch (err) {
-        throw new PlanReadError(`cannot read plan ${source}: ${err instanceof Error ? err.message : String(err)}`);
+        throw new RepoCleanerError('bad-plan', `cannot read plan ${source}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const version = raw?.version;
+    if (version !== PLAN_VERSION) {
+        throw new RepoCleanerError('bad-plan', `plan ${source} is version ${JSON.stringify(version ?? null)}; this repo-cleaner reads version ${PLAN_VERSION}. Sweep again to make a new plan`);
     }
     const parsed = PlanSchema.safeParse(raw);
-    if (!parsed.success)
-        throw new PlanReadError(`bad plan ${source}: ${parsed.error.message}`);
+    if (!parsed.success) {
+        throw new RepoCleanerError('bad-plan', `bad plan ${source}: ${parsed.error.message}`);
+    }
     return parsed.data;
 }
-/** @throws PlanReadError */
+/** @throws RepoCleanerError (`bad-plan`) */
 export function readPlan(path) {
     let text;
     try {
         text = readFileSync(path, 'utf-8');
     }
     catch (err) {
-        throw new PlanReadError(`cannot read plan ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        throw new RepoCleanerError('bad-plan', `cannot read plan ${path}: ${err instanceof Error ? err.message : String(err)}`);
     }
     return parsePlan(text, path);
 }

package/dist/providers/github.d.ts

@@ -5,6 +5,7 @@ import type { PrProvider } from './types.ts';
 export declare const PR_LIMIT = 300;
 /**
  * A provider over `gh pr list`. `gh` picks the repository from the checkout's
- * remotes, so `target` is not consulted.
+ * remotes, so `target` is not consulted. A listing `gh` fails, such as one for
+ * a repository the signed-in account cannot see, throws with `gh`'s reason.
  */
 export declare function githubProvider(gh: Gh): PrProvider;

package/dist/providers/github.js

@@ -15,7 +15,8 @@ const FIELDS = [
 export const PR_LIMIT = 300;
 /**
  * A provider over `gh pr list`. `gh` picks the repository from the checkout's
- * remotes, so `target` is not consulted.
+ * remotes, so `target` is not consulted. A listing `gh` fails, such as one for
+ * a repository the signed-in account cannot see, throws with `gh`'s reason.
  */
 export function githubProvider(gh) {
     return {