@codyswann/lisa 4.10.15 → 4.11.1

package/dist/cli/worktree-prune-policy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The entitlement rule for removing an agent worktree.
+ *
+ * Deliberately pure: every fact is gathered elsewhere and handed in, so the
+ * decision that authorizes a deletion is a function that can be exhaustively
+ * tested and mutation-tested rather than a side effect of a shell pipeline.
+ *
+ * The rule is **entitlement by proof, never by location.** Nothing here looks
+ * at where a worktree lives. `$TMPDIR` and the worktree roots are shared by
+ * every agent on the machine, so a path prefix identifies a neighbourhood, not
+ * an owner; reaping on one deletes siblings' live work. A worktree is the
+ * caller's to remove only when it is claimed by the caller, or when no other
+ * party can possibly have a claim on it — no live process inside it, no recent
+ * activity, and nothing in it that exists nowhere else.
+ * @module cli/worktree-prune-policy
+ */
+/** Why one worktree was refused. Every value names a specific unmet proof. */
+export type WorktreeBlocker = "primary-checkout" | "current-worktree" | "git-locked" | "claimed-by-another-owner" | "liveness-unknown" | "in-use" | "recently-active" | "unpushed-commits" | "uncommitted-changes" | "unreadable";
+/** Everything the rule is allowed to consider about one worktree. */
+export interface WorktreeFacts {
+    /** Absolute worktree path. */
+    readonly path: string;
+    /** Checked-out branch, or undefined when detached. */
+    readonly branch?: string;
+    /** Whether this is the repository's primary checkout. */
+    readonly isPrimary: boolean;
+    /** Whether the cleaner itself is running inside this worktree. */
+    readonly isCurrent: boolean;
+    /** Whether git reports the worktree as locked. */
+    readonly locked: boolean;
+    /** Whether git could report on the worktree at all. */
+    readonly readable: boolean;
+    /** Ownership verdict from the receipt check. */
+    readonly ownership: "mine" | "theirs" | "unclaimed";
+    /** Live processes whose working directory is inside, or undefined if unknown. */
+    readonly liveHolders: number | undefined;
+    /** 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;
+}
+/** Tunable part of the rule. */
+export interface WorktreePrunePolicy {
+    /** Quiescence a worktree must show before an unclaimed one is eligible. */
+    readonly minIdleSeconds: number;
+}
+/** Result of applying the rule to one worktree. */
+export interface WorktreeVerdict {
+    /** Absolute worktree path. */
+    readonly path: string;
+    /** Whether the worktree may be removed. */
+    readonly eligible: boolean;
+    /** Every unmet proof, most severe first. */
+    readonly blockers: readonly WorktreeBlocker[];
+}
+/** Default quiescence window: one day of no activity. */
+export declare const DEFAULT_MIN_IDLE_SECONDS: number;
+/** Operator-readable explanation for each blocker. */
+export declare const BLOCKER_EXPLANATIONS: Readonly<Record<WorktreeBlocker, string>>;
+/**
+ * Decide whether one worktree may be removed, and say why not when it may not.
+ *
+ * Blockers are returned in full rather than short-circuiting at the first
+ * failure. A worktree refused for three reasons and a worktree refused for one
+ * need different remedies, and reporting only the first trains a reader to fix
+ * one thing and re-run into the next refusal.
+ * @param facts - Gathered facts about the worktree
+ * @param policy - Tunable thresholds
+ * @returns Verdict with every unmet proof
+ */
+export declare function classifyWorktree(facts: WorktreeFacts, policy: WorktreePrunePolicy): WorktreeVerdict;
+//# sourceMappingURL=worktree-prune-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-prune-policy.d.ts","sourceRoot":"","sources":["../../src/cli/worktree-prune-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,kBAAkB,GAClB,YAAY,GACZ,0BAA0B,GAC1B,kBAAkB,GAClB,QAAQ,GACR,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,YAAY,CAAC;AAEjB,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;IACpD,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,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,gCAAgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED,yDAAyD;AACzD,eAAO,MAAM,wBAAwB,QAAe,CAAC;AAErD,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAgBvE,CAAC;AAEL;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,mBAAmB,GAC1B,eAAe,CAOjB"}

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

@@ -0,0 +1,114 @@
+/**
+ * The entitlement rule for removing an agent worktree.
+ *
+ * Deliberately pure: every fact is gathered elsewhere and handed in, so the
+ * decision that authorizes a deletion is a function that can be exhaustively
+ * tested and mutation-tested rather than a side effect of a shell pipeline.
+ *
+ * The rule is **entitlement by proof, never by location.** Nothing here looks
+ * at where a worktree lives. `$TMPDIR` and the worktree roots are shared by
+ * every agent on the machine, so a path prefix identifies a neighbourhood, not
+ * an owner; reaping on one deletes siblings' live work. A worktree is the
+ * caller's to remove only when it is claimed by the caller, or when no other
+ * party can possibly have a claim on it — no live process inside it, no recent
+ * activity, and nothing in it that exists nowhere else.
+ * @module cli/worktree-prune-policy
+ */
+/** Default quiescence window: one day of no activity. */
+export const DEFAULT_MIN_IDLE_SECONDS = 24 * 60 * 60;
+/** Operator-readable explanation for each blocker. */
+export const BLOCKER_EXPLANATIONS = Object.freeze({
+    "primary-checkout": "this is the repository's primary checkout",
+    "current-worktree": "the cleaner is running inside it",
+    "git-locked": "git reports it locked, which means somebody claimed it",
+    "claimed-by-another-owner": "its ownership receipt names a different agent, so it is not yours to remove",
+    "liveness-unknown": "the live-process probe could not run, so nothing could be proven idle",
+    "in-use": "a live process is working inside it right now",
+    "recently-active": "it showed activity too recently to be called abandoned",
+    "unpushed-commits": "it holds commits that exist on no remote — push them first",
+    "uncommitted-changes": "it holds uncommitted work — commit and push, or stash it, first",
+    unreadable: "git could not report on it, so nothing about it was proven",
+});
+/**
+ * Decide whether one worktree may be removed, and say why not when it may not.
+ *
+ * Blockers are returned in full rather than short-circuiting at the first
+ * failure. A worktree refused for three reasons and a worktree refused for one
+ * need different remedies, and reporting only the first trains a reader to fix
+ * one thing and re-run into the next refusal.
+ * @param facts - Gathered facts about the worktree
+ * @param policy - Tunable thresholds
+ * @returns Verdict with every unmet proof
+ */
+export function classifyWorktree(facts, policy) {
+    const blockers = [
+        ...structuralBlockers(facts),
+        ...idlenessBlockers(facts, policy),
+        ...workAtRiskBlockers(facts),
+    ];
+    return { path: facts.path, eligible: blockers.length === 0, blockers };
+}
+/**
+ * Blockers that make a worktree ineligible regardless of its contents.
+ * @param facts - Gathered facts about the worktree
+ * @returns Structural blockers
+ */
+function structuralBlockers(facts) {
+    const candidates = [
+        facts.readable ? undefined : "unreadable",
+        facts.isPrimary ? "primary-checkout" : undefined,
+        facts.isCurrent ? "current-worktree" : undefined,
+        facts.locked ? "git-locked" : undefined,
+        facts.ownership === "theirs"
+            ? "claimed-by-another-owner"
+            : undefined,
+    ];
+    return candidates.filter((blocker) => blocker !== undefined);
+}
+/**
+ * Blockers derived from whether anybody could still be using the worktree.
+ *
+ * A matching ownership receipt waives the quiescence window and NOTHING else.
+ * An owner asking to clean its own worktree has said what the window is there
+ * to infer. It never waives `in-use`: a claim says the work is finished, not
+ * that no process is still standing in the directory.
+ * @param facts - Gathered facts about the worktree
+ * @param policy - Tunable thresholds
+ * @returns Non-use blockers
+ */
+function idlenessBlockers(facts, policy) {
+    const liveness = facts.liveHolders === undefined
+        ? "liveness-unknown"
+        : facts.liveHolders > 0
+            ? "in-use"
+            : undefined;
+    const stale = facts.ownership === "mine" || facts.idleSeconds >= policy.minIdleSeconds
+        ? undefined
+        : "recently-active";
+    const candidates = [
+        liveness,
+        stale,
+    ];
+    return candidates.filter((blocker) => blocker !== undefined);
+}
+/**
+ * Blockers derived from work that would not survive the removal.
+ *
+ * Untracked files count. The existing doctor check deliberately excludes them
+ * from its "work at risk" signal because untracked droppings make every
+ * worktree look catastrophic in a REPORT. A report is not a deletion: here the
+ * files are about to stop existing, and an untracked file is in no object
+ * database at all, so it is the least recoverable thing in the tree.
+ * @param facts - Gathered facts about the worktree
+ * @returns Work-at-risk blockers
+ */
+function workAtRiskBlockers(facts) {
+    const candidates = [
+        facts.unpushedCommits > 0 ? "unpushed-commits" : undefined,
+        facts.trackedChanges > 0 || facts.untrackedFiles > 0
+            ? "uncommitted-changes"
+            : undefined,
+    ];
+    return candidates.filter((blocker) => blocker !== undefined);
+}
+//# sourceMappingURL=worktree-prune-policy.js.map

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

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

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

@@ -0,0 +1,96 @@
+import { type LivenessProbe } from "./worktree-liveness.js";
+import { type WorktreeFacts, type WorktreeVerdict } from "./worktree-prune-policy.js";
+/** Command-line options for the prune verb. */
+export interface WorktreePruneOptions {
+    /** Perform the removals instead of reporting them. */
+    readonly apply?: boolean;
+    /** Quiescence window in hours before an unclaimed worktree is eligible. */
+    readonly idleHours?: string;
+    /** Emit machine-readable output. */
+    readonly json?: boolean;
+}
+/** What one run decided, before anything is removed. */
+export interface WorktreePrunePlan {
+    /** Repository the plan was computed for. */
+    readonly repoPath: string;
+    /** Verdict for every registered worktree. */
+    readonly verdicts: readonly WorktreeVerdict[];
+    /** Facts behind each verdict, in the same order. */
+    readonly facts: readonly WorktreeFacts[];
+    /** Whether the live-process probe produced an answer. */
+    readonly livenessAvailable: boolean;
+    /** Registrations whose directory is already gone. */
+    readonly prunableRegistrations: readonly string[];
+}
+/** Injectable collaborators, overridden by tests. */
+export interface WorktreePruneDependencies {
+    /** Machine-wide live working directory probe. */
+    readonly probeLive: LivenessProbe;
+    /** Owner id of the running process. */
+    readonly callerOwnerId: string | undefined;
+    /** Clock in epoch milliseconds. */
+    readonly now: () => number;
+    /** Path the cleaner is running from. */
+    readonly currentPath: string;
+}
+/**
+ * Arguments used to remove one worktree.
+ *
+ * Exported so a test can pin the absence of `--force` by value rather than by
+ * reading the source. The plain form is not a stylistic preference: it is the
+ * backstop that makes a bug in the entitlement rule non-destructive, because
+ * git still refuses a dirty tree on its own.
+ * @param worktreePath - Absolute worktree path
+ * @returns Git arguments
+ */
+export declare function buildWorktreeRemoveArgs(worktreePath: string): readonly string[];
+/**
+ * Resolve the quiescence window from the command line.
+ * @param idleHours - Raw `--idle-hours` value
+ * @returns Window in seconds
+ */
+export declare function resolveMinIdleSeconds(idleHours: string | undefined): number;
+/**
+ * Compute what a run would do, without doing any of it.
+ * @param repoPath - Any path inside the repository
+ * @param options - Command-line options
+ * @param dependencies - Injectable collaborators
+ * @returns The plan
+ */
+export declare function planWorktreePrune(repoPath: string, options: WorktreePruneOptions, dependencies: WorktreePruneDependencies): Promise<WorktreePrunePlan>;
+/** Outcome of removing one worktree. */
+export interface RemovalOutcome {
+    /** Absolute worktree path. */
+    readonly path: string;
+    /** Whether git removed it. */
+    readonly removed: boolean;
+    /** Git's message when it refused. */
+    readonly error?: string;
+}
+/**
+ * Remove every eligible worktree in a plan.
+ *
+ * Removals run one at a time rather than concurrently. `git worktree remove`
+ * takes the repository's worktree lock, and a batch of parallel removals on a
+ * machine where other agents are also running git turns a contended lock into
+ * a spurious failure that reads like a refusal.
+ * @param plan - Plan produced by {@link planWorktreePrune}
+ * @param index - Index of the eligible worktree to remove next
+ * @returns One outcome per eligible worktree
+ */
+export declare function applyWorktreePrune(plan: WorktreePrunePlan, index?: number): Promise<readonly RemovalOutcome[]>;
+/**
+ * Drop registrations whose directory has already disappeared.
+ *
+ * Separate from removal because it destroys nothing: git is only forgetting a
+ * pointer to a directory that no longer exists.
+ * @param plan - Plan produced by {@link planWorktreePrune}
+ * @returns Number of registrations git was asked to forget
+ */
+export declare function pruneMissingRegistrations(plan: WorktreePrunePlan): Promise<number>;
+/**
+ * Default collaborators for a real run.
+ * @returns Dependencies wired to the real probe, environment, and clock
+ */
+export declare function defaultWorktreePruneDependencies(): WorktreePruneDependencies;
+//# sourceMappingURL=worktree-prune.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-prune.d.ts","sourceRoot":"","sources":["../../src/cli/worktree-prune.ts"],"names":[],"mappings":"AAyBA,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,yDAAyD;IACzD,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;CACnD;AAED,qDAAqD;AACrD,MAAM,WAAW,yBAAyB;IACxC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,GACnB,SAAS,MAAM,EAAE,CAEnB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAO3E;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,iBAAiB,EACvB,KAAK,SAAI,GACR,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAgBpC;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,IAAI,yBAAyB,CAO5E"}

package/dist/cli/worktree-prune.js

@@ -0,0 +1,153 @@
+/**
+ * `lisa worktree prune` — the vetted verb for retiring agent worktrees.
+ *
+ * The guard in `parity-safety-net.sh` blocks `git worktree remove --force`
+ * because it discards a dirty tree, and that block is correct and stays. This
+ * command does not relax it, is not an override for it, and never passes
+ * `--force` to git: it performs the safety checks itself and then uses the
+ * plain `git worktree remove`, whose own refusal of a dirty tree remains in
+ * place underneath as a last line of defence.
+ *
+ * Dry-run is the default. The command is meant to be called by unattended
+ * loops on a machine shared with other agents' live work, so the first contact
+ * a mis-scoped invocation makes must be a report and not a deletion. `--apply`
+ * is the whole opt-in; there is no flag anywhere that widens the entitlement
+ * rule itself.
+ * @module cli/worktree-prune
+ */
+import { realpathSync } from "node:fs";
+import * as path from "node:path";
+import { gatherAllWorktreeFacts, git, listWorktrees, } from "./worktree-inventory.js";
+import { probeLiveWorkingDirectories, } from "./worktree-liveness.js";
+import { resolveCallerOwnerId } from "./worktree-ownership.js";
+import { classifyWorktree, DEFAULT_MIN_IDLE_SECONDS, } from "./worktree-prune-policy.js";
+/**
+ * Arguments used to remove one worktree.
+ *
+ * Exported so a test can pin the absence of `--force` by value rather than by
+ * reading the source. The plain form is not a stylistic preference: it is the
+ * backstop that makes a bug in the entitlement rule non-destructive, because
+ * git still refuses a dirty tree on its own.
+ * @param worktreePath - Absolute worktree path
+ * @returns Git arguments
+ */
+export function buildWorktreeRemoveArgs(worktreePath) {
+    return ["worktree", "remove", worktreePath];
+}
+/**
+ * Resolve the quiescence window from the command line.
+ * @param idleHours - Raw `--idle-hours` value
+ * @returns Window in seconds
+ */
+export function resolveMinIdleSeconds(idleHours) {
+    if (idleHours === undefined)
+        return DEFAULT_MIN_IDLE_SECONDS;
+    const parsed = Number.parseFloat(idleHours);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error("--idle-hours must be a non-negative number");
+    }
+    return Math.floor(parsed * 3600);
+}
+/**
+ * Compute what a run would do, without doing any of it.
+ * @param repoPath - Any path inside the repository
+ * @param options - Command-line options
+ * @param dependencies - Injectable collaborators
+ * @returns The plan
+ */
+export async function planWorktreePrune(repoPath, options, dependencies) {
+    const minIdleSeconds = resolveMinIdleSeconds(options.idleHours);
+    const entries = await listWorktrees(repoPath);
+    const live = await dependencies.probeLive();
+    const present = entries.filter(entry => !entry.prunable);
+    const facts = await gatherAllWorktreeFacts(present, {
+        liveWorkingDirectories: live,
+        callerOwnerId: dependencies.callerOwnerId,
+        currentPath: dependencies.currentPath,
+        nowMs: dependencies.now(),
+    });
+    return {
+        repoPath,
+        verdicts: facts.map(fact => classifyWorktree(fact, { minIdleSeconds })),
+        facts,
+        livenessAvailable: live !== undefined,
+        prunableRegistrations: entries
+            .filter((entry) => entry.prunable)
+            .map(entry => entry.path),
+    };
+}
+/**
+ * Remove every eligible worktree in a plan.
+ *
+ * Removals run one at a time rather than concurrently. `git worktree remove`
+ * takes the repository's worktree lock, and a batch of parallel removals on a
+ * machine where other agents are also running git turns a contended lock into
+ * a spurious failure that reads like a refusal.
+ * @param plan - Plan produced by {@link planWorktreePrune}
+ * @param index - Index of the eligible worktree to remove next
+ * @returns One outcome per eligible worktree
+ */
+export async function applyWorktreePrune(plan, index = 0) {
+    const eligible = plan.verdicts.filter(verdict => verdict.eligible);
+    if (index >= eligible.length)
+        return [];
+    const target = eligible[index];
+    const outcome = await git(buildWorktreeRemoveArgs(target.path), plan.repoPath).then(() => ({ path: target.path, removed: true }), (error) => ({
+        path: target.path,
+        removed: false,
+        error: describeError(error),
+    }));
+    return [outcome, ...(await applyWorktreePrune(plan, index + 1))];
+}
+/**
+ * Drop registrations whose directory has already disappeared.
+ *
+ * Separate from removal because it destroys nothing: git is only forgetting a
+ * pointer to a directory that no longer exists.
+ * @param plan - Plan produced by {@link planWorktreePrune}
+ * @returns Number of registrations git was asked to forget
+ */
+export async function pruneMissingRegistrations(plan) {
+    if (plan.prunableRegistrations.length === 0)
+        return 0;
+    await git(["worktree", "prune"], plan.repoPath).catch(() => "");
+    return plan.prunableRegistrations.length;
+}
+/**
+ * Default collaborators for a real run.
+ * @returns Dependencies wired to the real probe, environment, and clock
+ */
+export function defaultWorktreePruneDependencies() {
+    return {
+        probeLive: probeLiveWorkingDirectories,
+        callerOwnerId: resolveCallerOwnerId(),
+        now: () => Date.now(),
+        currentPath: resolvePhysicalCwd(),
+    };
+}
+/**
+ * Resolve the directory the cleaner runs from, following symlinks.
+ *
+ * The physical form is what the liveness probe reports, so the two have to be
+ * in the same spelling or the cleaner cannot recognise its own worktree.
+ * @returns Absolute physical path of the current working directory
+ */
+function resolvePhysicalCwd() {
+    const resolved = path.resolve(process.cwd());
+    try {
+        return realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * Render an error for the report.
+ * @param error - Rejection from git
+ * @returns Single-line message
+ */
+function describeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.split("\n").filter(line => line.trim() !== "")[0] ?? "unknown";
+}
+//# sourceMappingURL=worktree-prune.js.map

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

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

package/dist/core/upstream-evidence-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAw5EpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAipPjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}
+{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAw5EpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAmqPjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}

package/dist/core/upstream-evidence-manifest.js

@@ -7255,6 +7255,8 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/cli/merge-learnings-cmd.ts": true,
     "src/cli/print-update-warning.ts": true,
     "src/cli/prompts.ts": true,
+    "src/cli/prune-commands.ts": true,
+    "src/cli/prune-report.ts": true,
     "src/cli/remote-env-cmd.ts": true,
     "src/cli/remote-environment-catalog.ts": true,
     "src/cli/remote-environment-contract.ts": true,
@@ -7265,6 +7267,8 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/cli/shared-options.ts": true,
     "src/cli/standards-proof-cmd.ts": true,
     "src/cli/starters.ts": true,
+    "src/cli/stash-prune-policy.ts": true,
+    "src/cli/stash-prune.ts": true,
     "src/cli/sync-cmd.ts": true,
     "src/cli/ui-automations-adapters.ts": true,
     "src/cli/ui-automations.ts": true,
@@ -7302,6 +7306,11 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/cli/version.ts": true,
     "src/cli/workflow-moments.ts": true,
     "src/cli/workstation-cmd.ts": true,
+    "src/cli/worktree-inventory.ts": true,
+    "src/cli/worktree-liveness.ts": true,
+    "src/cli/worktree-ownership.ts": true,
+    "src/cli/worktree-prune-policy.ts": true,
+    "src/cli/worktree-prune.ts": true,
     "src/codex/agent-installer.ts": true,
     "src/codex/agent-transformer.ts": true,
     "src/codex/agents-md-installer.ts": true,
@@ -7746,6 +7755,8 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/integration/pre-tool-refusal-scripts-resolve-gates.test.ts": true,
     "tests/integration/prepare-setup-command.test.ts": true,
     "tests/integration/presence-gated-absence-fail-closed.test.ts": true,
+    "tests/integration/prune-report-reachability.test.ts": true,
+    "tests/integration/prune-verbs-negative-controls.test.ts": true,
     "tests/integration/push-collects-integration-tree-once.test.ts": true,
     "tests/integration/quality-declaration-required-jobs.test.ts": true,
     "tests/integration/quality-dual-adoption-controls.test.ts": true,
@@ -7791,6 +7802,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/integration/threshold-ratchet-gate-fail-closed.test.ts": true,
     "tests/integration/tracked-source-nul-bytes.test.ts": true,
     "tests/support/git-executable.ts": true,
+    "tests/support/prune-fixtures.ts": true,
     "tests/support/work-item-cli.ts": true,
     "tests/unit/agy/block-no-verify-agy.test.ts": true,
     "tests/unit/agy/mcp-collect.test.ts": true,
@@ -7882,11 +7894,14 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/cli/merge-learnings-cmd.test.ts": true,
     "tests/unit/cli/parse-refresh-templates.test.ts": true,
     "tests/unit/cli/prompts.test.ts": true,
+    "tests/unit/cli/prune-commands.test.ts": true,
+    "tests/unit/cli/prune-parsing.test.ts": true,
     "tests/unit/cli/serialize-legs-callee-grant.test.ts": true,
     "tests/unit/cli/setup-project.test.ts": true,
     "tests/unit/cli/setup-wiki.test.ts": true,
     "tests/unit/cli/shared-options.test.ts": true,
     "tests/unit/cli/starters.test.ts": true,
+    "tests/unit/cli/stash-prune-policy.test.ts": true,
     "tests/unit/cli/sync-cmd.test.ts": true,
     "tests/unit/cli/ui-automations-fixture.test.ts": true,
     "tests/unit/cli/ui-automations-map.test.ts": true,
@@ -7921,6 +7936,9 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/cli/update-cmd.test.ts": true,
     "tests/unit/cli/version-cmd.test.ts": true,
     "tests/unit/cli/workstation-cmd.test.ts": true,
+    "tests/unit/cli/worktree-liveness.test.ts": true,
+    "tests/unit/cli/worktree-ownership.test.ts": true,
+    "tests/unit/cli/worktree-prune-policy.test.ts": true,
     "tests/unit/codex/agent-installer.test.ts": true,
     "tests/unit/codex/agent-transformer.test.ts": true,
     "tests/unit/codex/agents-md-installer.test.ts": true,