@codyswann/lisa 4.10.15 → 4.11.1

package/dist/cli/stash-prune-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stash-prune-policy.d.ts","sourceRoot":"","sources":["../../src/cli/stash-prune-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,oCAAoC;AACpC,MAAM,MAAM,YAAY,GACpB,wBAAwB,GACxB,YAAY,GACZ,YAAY,CAAC;AAEjB,0CAA0C;AAC1C,MAAM,MAAM,eAAe,GAAG,qBAAqB,GAAG,gBAAgB,CAAC;AAEvE,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED,yEAAyE;AACzE,eAAO,MAAM,8BAA8B,QAAe,CAAC;AAW3D,sDAAsD;AACtD,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAO5B,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,gBAAgB,GACvB,YAAY,CA6Bd"}

package/dist/cli/stash-prune-policy.js

@@ -0,0 +1,90 @@
+/**
+ * The entitlement rule for dropping a stash entry.
+ *
+ * Stashes are harder to own than worktrees: `refs/stash` is a single reflog
+ * shared by every worktree of a repository, so an entry an agent finds may have
+ * been pushed a minute ago by a sibling working three directories away. There
+ * is no path, no branch, and no author to scope by. The only defensible
+ * entitlement is therefore not "mine" but **provably redundant** — an entry
+ * whose content is already preserved somewhere else, or machine-generated
+ * debris whose producing run is provably long dead.
+ *
+ * Everything else is kept and reported. A stash that cannot be proven redundant
+ * is precisely the case the standing block on `git stash drop` exists for.
+ * @module cli/stash-prune-policy
+ */
+/** Default debris age: a lint-staged run that old is not coming back. */
+export const DEFAULT_MIN_DEBRIS_AGE_SECONDS = 24 * 60 * 60;
+/**
+ * The exact message lint-staged gives its automatic backup stash.
+ *
+ * Matched exactly, and with the `On <branch>: ` prefix git adds when the entry
+ * is stored through `git stash push`, because a substring match would sweep a
+ * human stash whose message merely mentions lint-staged.
+ */
+const LINT_STAGED_BACKUP = /^(?:On [^:]+: )?lint-staged automatic backup$/;
+/** Operator-readable explanation for each blocker. */
+export const STASH_BLOCKER_EXPLANATIONS = Object.freeze({
+    "not-provably-redundant": "its content is not provably preserved anywhere else, so dropping it could destroy the only copy",
+    "too-recent": "it is machine-generated backup debris, but recent enough that the run which created it may still be alive",
+    unreadable: "git could not report on it, so nothing about it was proven",
+});
+/**
+ * Report whether a reflog subject is lint-staged's automatic backup.
+ * @param subject - Reflog subject of the stash entry
+ * @returns True when the entry is machine-generated backup debris
+ */
+export function isLintStagedBackup(subject) {
+    return LINT_STAGED_BACKUP.test(subject.trim());
+}
+/**
+ * Decide whether one stash entry may be dropped, and say why not when it may not.
+ * @param facts - Gathered facts about the entry
+ * @param policy - Tunable thresholds
+ * @returns Verdict with the reason it may be dropped, or every reason it may not
+ */
+export function classifyStash(facts, policy) {
+    if (!facts.readable) {
+        return {
+            index: facts.index,
+            sha: facts.sha,
+            eligible: false,
+            blockers: ["unreadable"],
+        };
+    }
+    const redundancy = findRedundancy(facts, policy);
+    if (redundancy !== undefined) {
+        return {
+            index: facts.index,
+            sha: facts.sha,
+            eligible: true,
+            redundancy,
+            blockers: [],
+        };
+    }
+    return {
+        index: facts.index,
+        sha: facts.sha,
+        eligible: false,
+        blockers: [
+            isLintStagedBackup(facts.subject)
+                ? "too-recent"
+                : "not-provably-redundant",
+        ],
+    };
+}
+/**
+ * Identify which redundancy proof, if any, one entry satisfies.
+ * @param facts - Gathered facts about the entry
+ * @param policy - Tunable thresholds
+ * @returns The satisfied proof, or undefined when none is
+ */
+function findRedundancy(facts, policy) {
+    if (facts.recordsNoChange && facts.baseOnRemote)
+        return "empty-and-published";
+    return isLintStagedBackup(facts.subject) &&
+        facts.ageSeconds >= policy.minDebrisAgeSeconds
+        ? "machine-debris"
+        : undefined;
+}
+//# sourceMappingURL=stash-prune-policy.js.map

package/dist/cli/stash-prune-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stash-prune-policy.js","sourceRoot":"","sources":["../../src/cli/stash-prune-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiDH,yEAAyE;AACzE,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,+CAA+C,CAAC;AAE3E,sDAAsD;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAEnC,MAAM,CAAC,MAAM,CAAC;IAChB,wBAAwB,EACtB,iGAAiG;IACnG,YAAY,EACV,2GAA2G;IAC7G,UAAU,EAAE,4DAA4D;CACzE,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAiB,EACjB,MAAwB;IAExB,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,QAAQ,EAAE,KAAK;YACf,QAAQ,EAAE,CAAC,YAAY,CAAC;SACzB,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,QAAQ,EAAE,IAAI;YACd,UAAU;YACV,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE;YACR,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC;gBAC/B,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,wBAAwB;SAC7B;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CACrB,KAAiB,EACjB,MAAwB;IAExB,IAAI,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO,qBAAqB,CAAC;IAC9E,OAAO,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC;QACtC,KAAK,CAAC,UAAU,IAAI,MAAM,CAAC,mBAAmB;QAC9C,CAAC,CAAC,gBAAgB;QAClB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist/cli/stash-prune.d.ts

@@ -0,0 +1,104 @@
+/**
+ * `lisa stash prune` — the vetted verb for clearing redundant stash entries.
+ *
+ * The guard blocks `git stash drop` and `git stash clear` because they destroy
+ * stashed work. That block stays. This command answers it rather than relaxing
+ * it: every entry it drops is first re-anchored under
+ * `refs/lisa/pruned-stashes/`, so the stash commit — trees, index state, and
+ * the untracked-files parent alike — stays in the object database and is
+ * recoverable with a single `git stash apply <ref>`. Nothing is destroyed; the
+ * reflog entry is what goes away.
+ *
+ * Dropping is index-shifting on a ref that every worktree of the repository
+ * shares, so entries are addressed by commit id and re-located immediately
+ * before each drop. An entry whose id no longer sits where it was is skipped,
+ * never dropped by position — that is the difference between a cleaner and a
+ * race that eats a sibling's stash.
+ * @module cli/stash-prune
+ */
+import { type StashFacts, type StashVerdict } from "./stash-prune-policy.js";
+/** Namespace the preserved stash commits are anchored under. */
+export declare const PRESERVED_STASH_REF_PREFIX = "refs/lisa/pruned-stashes";
+/** Command-line options for the stash prune verb. */
+export interface StashPruneOptions {
+    /** Perform the drops instead of reporting them. */
+    readonly apply?: boolean;
+    /** Age in hours a machine backup must reach before it counts as debris. */
+    readonly olderThanHours?: string;
+    /** Emit machine-readable output. */
+    readonly json?: boolean;
+}
+/** One entry as the listing reports it. */
+export interface StashRecord {
+    /** Commit id of the entry. */
+    readonly sha: string;
+    /** Reflog subject. */
+    readonly subject: string;
+    /** Commit timestamp in epoch seconds. */
+    readonly timestamp: number;
+}
+/** What one run decided, before anything is dropped. */
+export interface StashPrunePlan {
+    /** Repository the plan was computed for. */
+    readonly repoPath: string;
+    /** Verdict for every stash entry. */
+    readonly verdicts: readonly StashVerdict[];
+    /** Facts behind each verdict, in the same order. */
+    readonly facts: readonly StashFacts[];
+}
+/** Outcome of dropping one stash entry. */
+export interface StashDropOutcome {
+    /** Commit id of the entry. */
+    readonly sha: string;
+    /** Whether the entry was dropped. */
+    readonly dropped: boolean;
+    /** Ref the stash commit was anchored under before the drop. */
+    readonly preservedRef?: string;
+    /** Why the drop did not happen. */
+    readonly error?: string;
+}
+/**
+ * Resolve the debris age threshold from the command line.
+ * @param olderThanHours - Raw `--older-than-hours` value
+ * @returns Threshold in seconds
+ */
+export declare function resolveMinDebrisAgeSeconds(olderThanHours: string | undefined): number;
+/**
+ * Parse the formatted stash listing into its raw fields.
+ * @param stdout - Output of the formatted `git stash list`
+ * @returns One record per entry, in list order
+ */
+export declare function parseStashList(stdout: string): readonly StashRecord[];
+/**
+ * The ref one stash commit is preserved under.
+ * @param sha - Commit id of the stash entry
+ * @returns Fully-qualified ref name
+ */
+export declare function preservedStashRef(sha: string): string;
+/**
+ * Compute what a run would do, without dropping anything.
+ * @param repoPath - Any path inside the repository
+ * @param options - Command-line options
+ * @param now - Clock in epoch milliseconds
+ * @returns The plan
+ */
+export declare function planStashPrune(repoPath: string, options: StashPruneOptions, now?: () => number): Promise<StashPrunePlan>;
+/**
+ * Locate a stash entry by commit id, as `git stash list` currently numbers it.
+ *
+ * Re-derived immediately before every drop. Positions shift under a concurrent
+ * push or drop from any worktree of the repository, and a stale position is how
+ * a cleaner destroys the entry after the one it meant to.
+ * @param repoPath - Any path inside the repository
+ * @param sha - Commit id of the entry
+ * @returns Current `stash@{n}` reference, or undefined when the entry is gone
+ */
+export declare function locateStash(repoPath: string, sha: string): Promise<string | undefined>;
+/**
+ * Preserve and drop every eligible stash entry in a plan.
+ * @param plan - Plan produced by {@link planStashPrune}
+ * @param index - Index of the eligible entry to drop next
+ * @returns One outcome per eligible entry
+ */
+export declare function applyStashPrune(plan: StashPrunePlan, index?: number): Promise<readonly StashDropOutcome[]>;
+//# sourceMappingURL=stash-prune.d.ts.map

package/dist/cli/stash-prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stash-prune.d.ts","sourceRoot":"","sources":["../../src/cli/stash-prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AASjC,gEAAgE;AAChE,eAAO,MAAM,0BAA0B,6BAA6B,CAAC;AAErE,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAOR;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAWrE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAkFD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,iBAAiB,EAC1B,GAAG,GAAE,MAAM,MAAyB,GACnC,OAAO,CAAC,cAAc,CAAC,CAkBzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B;AA+CD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,cAAc,EACpB,KAAK,SAAI,GACR,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAQtC"}

package/dist/cli/stash-prune.js

@@ -0,0 +1,206 @@
+/**
+ * `lisa stash prune` — the vetted verb for clearing redundant stash entries.
+ *
+ * The guard blocks `git stash drop` and `git stash clear` because they destroy
+ * stashed work. That block stays. This command answers it rather than relaxing
+ * it: every entry it drops is first re-anchored under
+ * `refs/lisa/pruned-stashes/`, so the stash commit — trees, index state, and
+ * the untracked-files parent alike — stays in the object database and is
+ * recoverable with a single `git stash apply <ref>`. Nothing is destroyed; the
+ * reflog entry is what goes away.
+ *
+ * Dropping is index-shifting on a ref that every worktree of the repository
+ * shares, so entries are addressed by commit id and re-located immediately
+ * before each drop. An entry whose id no longer sits where it was is skipped,
+ * never dropped by position — that is the difference between a cleaner and a
+ * race that eats a sibling's stash.
+ * @module cli/stash-prune
+ */
+import { classifyStash, DEFAULT_MIN_DEBRIS_AGE_SECONDS, } from "./stash-prune-policy.js";
+import { git } from "./worktree-inventory.js";
+/** Unit-separator field delimiter, matching the `%x1f` in the list format. */
+const FIELD = "\u001F";
+/** Format that makes `git stash list` machine-readable. */
+const STASH_LIST_FORMAT = "--format=%H%x1f%gs%x1f%ct";
+/** Namespace the preserved stash commits are anchored under. */
+export const PRESERVED_STASH_REF_PREFIX = "refs/lisa/pruned-stashes";
+/**
+ * Resolve the debris age threshold from the command line.
+ * @param olderThanHours - Raw `--older-than-hours` value
+ * @returns Threshold in seconds
+ */
+export function resolveMinDebrisAgeSeconds(olderThanHours) {
+    if (olderThanHours === undefined)
+        return DEFAULT_MIN_DEBRIS_AGE_SECONDS;
+    const parsed = Number.parseFloat(olderThanHours);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error("--older-than-hours must be a non-negative number");
+    }
+    return Math.floor(parsed * 3600);
+}
+/**
+ * Parse the formatted stash listing into its raw fields.
+ * @param stdout - Output of the formatted `git stash list`
+ * @returns One record per entry, in list order
+ */
+export function parseStashList(stdout) {
+    return stdout
+        .split("\n")
+        .filter(line => line.includes(FIELD))
+        .map(line => line.split(FIELD))
+        .map(fields => ({
+        sha: (fields[0] ?? "").trim(),
+        subject: fields[1] ?? "",
+        timestamp: Number.parseInt(fields[2] ?? "", 10) || 0,
+    }))
+        .filter(record => record.sha !== "");
+}
+/**
+ * The ref one stash commit is preserved under.
+ * @param sha - Commit id of the stash entry
+ * @returns Fully-qualified ref name
+ */
+export function preservedStashRef(sha) {
+    return `${PRESERVED_STASH_REF_PREFIX}/${sha}`;
+}
+/**
+ * Report whether two revisions have an identical tree.
+ * @param repoPath - Any path inside the repository
+ * @param left - First revision
+ * @param right - Second revision
+ * @returns True when the revisions differ in nothing
+ */
+async function isSameTree(repoPath, left, right) {
+    const [leftTree, rightTree] = await Promise.all([
+        git(["rev-parse", `${left}^{tree}`], repoPath).then(out => out.trim()),
+        git(["rev-parse", `${right}^{tree}`], repoPath).then(out => out.trim()),
+    ]);
+    return leftTree !== "" && leftTree === rightTree;
+}
+/**
+ * Establish whether one entry holds anything, and whether its base is published.
+ *
+ * A stash created with `--include-untracked` carries a third parent holding
+ * those files. Its presence alone means the entry holds content no comparison
+ * against the first two parents would reveal, so it is treated as non-empty
+ * without further inspection.
+ * @param repoPath - Any path inside the repository
+ * @param sha - Commit id of the stash entry
+ * @returns Content and publication facts
+ */
+async function probeStashContent(repoPath, sha) {
+    const hasUntrackedParent = await git(["rev-parse", "--verify", "--quiet", `${sha}^3`], repoPath).then(() => true, () => false);
+    const [sameWorktree, sameIndex, unpublished] = await Promise.all([
+        isSameTree(repoPath, `${sha}^`, sha),
+        isSameTree(repoPath, `${sha}^`, `${sha}^2`),
+        git(["rev-list", "--count", `${sha}^`, "--not", "--remotes"], repoPath),
+    ]);
+    return {
+        recordsNoChange: !hasUntrackedParent && sameWorktree && sameIndex,
+        baseOnRemote: (Number.parseInt(unpublished.trim(), 10) || 0) === 0,
+    };
+}
+/**
+ * Gather every fact the entitlement rule may consider for one entry.
+ * @param repoPath - Any path inside the repository
+ * @param record - Raw listing fields
+ * @param index - Position in the listing
+ * @param nowSeconds - Clock in epoch seconds
+ * @returns Facts for the entitlement rule
+ */
+async function gatherStashFacts(repoPath, record, index, nowSeconds) {
+    const shell = {
+        index,
+        sha: record.sha,
+        subject: record.subject,
+        ageSeconds: Math.max(0, nowSeconds - record.timestamp),
+    };
+    const probed = await probeStashContent(repoPath, record.sha).catch(() => undefined);
+    return probed === undefined
+        ? { ...shell, readable: false, recordsNoChange: false, baseOnRemote: false }
+        : { ...shell, readable: true, ...probed };
+}
+/**
+ * Compute what a run would do, without dropping anything.
+ * @param repoPath - Any path inside the repository
+ * @param options - Command-line options
+ * @param now - Clock in epoch milliseconds
+ * @returns The plan
+ */
+export async function planStashPrune(repoPath, options, now = () => Date.now()) {
+    const minDebrisAgeSeconds = resolveMinDebrisAgeSeconds(options.olderThanHours);
+    const listed = parseStashList(await git(["stash", "list", STASH_LIST_FORMAT], repoPath).catch(() => ""));
+    const nowSeconds = Math.floor(now() / 1000);
+    const facts = await Promise.all(listed.map((record, index) => gatherStashFacts(repoPath, record, index, nowSeconds)));
+    return {
+        repoPath,
+        facts,
+        verdicts: facts.map(fact => classifyStash(fact, { minDebrisAgeSeconds })),
+    };
+}
+/**
+ * Locate a stash entry by commit id, as `git stash list` currently numbers it.
+ *
+ * Re-derived immediately before every drop. Positions shift under a concurrent
+ * push or drop from any worktree of the repository, and a stale position is how
+ * a cleaner destroys the entry after the one it meant to.
+ * @param repoPath - Any path inside the repository
+ * @param sha - Commit id of the entry
+ * @returns Current `stash@{n}` reference, or undefined when the entry is gone
+ */
+export async function locateStash(repoPath, sha) {
+    const listed = parseStashList(await git(["stash", "list", STASH_LIST_FORMAT], repoPath));
+    const position = listed.findIndex(record => record.sha === sha);
+    return position === -1 ? undefined : `stash@{${position}}`;
+}
+/**
+ * Preserve one stash commit under a ref, verify it, then drop the entry.
+ * @param repoPath - Any path inside the repository
+ * @param sha - Commit id of the entry
+ * @returns Outcome for the entry
+ */
+async function dropOne(repoPath, sha) {
+    const ref = preservedStashRef(sha);
+    const preserved = await git(["update-ref", ref, sha], repoPath).then(() => git(["rev-parse", "--verify", ref], repoPath), () => "");
+    if (preserved.trim() !== sha) {
+        return {
+            sha,
+            dropped: false,
+            error: "could not preserve the stash commit, so it was not dropped",
+        };
+    }
+    const located = await locateStash(repoPath, sha);
+    if (located === undefined) {
+        return {
+            sha,
+            dropped: false,
+            preservedRef: ref,
+            error: "entry moved or was dropped elsewhere before this drop",
+        };
+    }
+    return git(["stash", "drop", located], repoPath).then(() => ({ sha, dropped: true, preservedRef: ref }), (error) => ({
+        sha,
+        dropped: false,
+        preservedRef: ref,
+        error: error instanceof Error
+            ? (error.message.split("\n")[0] ?? "unknown")
+            : "unknown",
+    }));
+}
+/**
+ * Preserve and drop every eligible stash entry in a plan.
+ * @param plan - Plan produced by {@link planStashPrune}
+ * @param index - Index of the eligible entry to drop next
+ * @returns One outcome per eligible entry
+ */
+export async function applyStashPrune(plan, index = 0) {
+    const eligible = plan.verdicts.filter(verdict => verdict.eligible);
+    if (index >= eligible.length)
+        return [];
+    const target = eligible[index];
+    return [
+        await dropOne(plan.repoPath, target.sha),
+        ...(await applyStashPrune(plan, index + 1)),
+    ];
+}
+//# sourceMappingURL=stash-prune.js.map

package/dist/cli/stash-prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stash-prune.js","sourceRoot":"","sources":["../../src/cli/stash-prune.ts"],"names":[],"mappings":"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"}

package/dist/cli/worktree-inventory.d.ts

@@ -0,0 +1,82 @@
+import type { WorktreeFacts } from "./worktree-prune-policy.js";
+/** One entry as git itself reports it. */
+export interface WorktreeEntry {
+    /** Absolute worktree path. */
+    readonly path: string;
+    /** Checked-out branch, or undefined when detached. */
+    readonly branch?: string;
+    /** Whether git reports the entry locked. */
+    readonly locked: boolean;
+    /** Whether git reports the entry's directory as gone. */
+    readonly prunable: boolean;
+    /** Whether this is the primary checkout (always the first entry). */
+    readonly isPrimary: boolean;
+}
+/**
+ * Parse `git worktree list --porcelain` output.
+ *
+ * The first record is always the primary checkout, which is how the primary is
+ * identified — not by comparing it against a path the caller supplied, which
+ * would be wrong the moment the caller ran from a worktree.
+ * @param stdout - Porcelain output
+ * @returns Parsed entries in git's order
+ */
+export declare function parseWorktreeList(stdout: string): readonly WorktreeEntry[];
+/**
+ * Run one bounded git command.
+ * @param args - Git arguments
+ * @param cwd - Directory to run git in
+ * @returns Trimmed stdout
+ */
+export declare function git(args: readonly string[], cwd: string): Promise<string>;
+/**
+ * List every worktree registered for a checkout.
+ * @param repoPath - Any path inside the repository
+ * @returns Registered entries
+ */
+export declare function listWorktrees(repoPath: string): Promise<readonly WorktreeEntry[]>;
+/** The half of the facts that only git and the filesystem can answer. */
+export interface WorktreeGitState {
+    /** Ownership verdict from the receipt check. */
+    readonly ownership: WorktreeFacts["ownership"];
+    /** Seconds since the worktree last showed activity. */
+    readonly idleSeconds: number;
+    /** Modified, staged, added, deleted, or renamed TRACKED files. */
+    readonly trackedChanges: number;
+    /** Untracked, non-ignored files. */
+    readonly untrackedFiles: number;
+    /** Commits present locally and on no remote. */
+    readonly unpushedCommits: number;
+}
+/** Inputs shared by every fact-gathering call in one run. */
+export interface GatherContext {
+    /** Live working directories, or undefined when the probe could not run. */
+    readonly liveWorkingDirectories: readonly string[] | undefined;
+    /** Owner id of the process running the cleaner. */
+    readonly callerOwnerId: string | undefined;
+    /** Absolute path the cleaner is running from. */
+    readonly currentPath: string;
+    /** Clock in epoch milliseconds. */
+    readonly nowMs: number;
+}
+/**
+ * Gather every fact the entitlement rule is allowed to consider.
+ *
+ * A worktree git cannot report on yields `readable: false` with zeroed counts.
+ * The zeros are never read as "holds nothing" because `readable: false` is
+ * itself a blocker — the same reason the doctor check returns undefined for an
+ * unreadable worktree instead of a zeroed exposure.
+ * @param entry - Registered worktree entry
+ * @param context - Shared run inputs
+ * @returns Facts for the entitlement rule
+ */
+export declare function gatherWorktreeFacts(entry: WorktreeEntry, context: GatherContext): Promise<WorktreeFacts>;
+/**
+ * Gather facts for many worktrees without spawning git for all of them at once.
+ * @param entries - Registered worktree entries
+ * @param context - Shared run inputs
+ * @param start - Batch start index
+ * @returns Facts in the original entry order
+ */
+export declare function gatherAllWorktreeFacts(entries: readonly WorktreeEntry[], context: GatherContext, start?: number): Promise<readonly WorktreeFacts[]>;
+//# sourceMappingURL=worktree-inventory.d.ts.map

package/dist/cli/worktree-inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-inventory.d.ts","sourceRoot":"","sources":["../../src/cli/worktree-inventory.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAOhE,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE,CAM1E;AA+BD;;;;;GAKG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAInC;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC/C,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,oCAAoC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gDAAgD;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC/D,mDAAmD;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,aAAa,CAAC,CAgCxB;AAuFD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,EAAE,aAAa,EACtB,KAAK,SAAI,GACR,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAanC"}