@mstar-harness/engine 3.8.2 → 3.9.0

package/dist/audit.js

@@ -186,6 +186,10 @@ function isAtOrBelow(dir, root) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
 }
 
+// src/status.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync } from "node:fs";
+import { dirname as dirname4, join as join5, resolve as resolve5, sep } from "node:path";
+
 // src/store.ts
 import { existsSync as existsSync2, readdirSync, unlinkSync as unlinkSync3 } from "node:fs";
 import { isAbsolute as isAbsolute3, join as join4, resolve as resolve4 } from "node:path";
@@ -318,10 +322,6 @@ function assertFsStorePath(store, ref, expectedPath) {
   }
 }
 
-// src/status.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync } from "node:fs";
-import { dirname as dirname4, join as join5, resolve as resolve5, sep } from "node:path";
-
 // src/workflow.ts
 var WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
 var WORKFLOW_TERMINAL_STATUSES = ["completed", "failed", "stopped"];

package/dist/cleanup.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Engine cleanup module — pure worktree/branch cleanup planner.
+ *
+ * `planWorktreeCleanup` is the ONE planner ( — no `planBranchCleanup`, no
+ * injected callback/git probe, no IO/time/env access): immutable facts in,
+ * one stable decision per candidate out, in input order, facts never
+ * mutated. The CLI alone probes Git/state and applies current decisions;
+ * the planner only classifies.
+ *
+ * Behavior contract (locked):
+ * - Locked interface block, candidate ownership/attribution, decision
+ *   precedence, two timing lanes and every `cleanup.*` machine code are a
+ *   stable contract: consumers match on the exact codes, so both codes and
+ *   precedence may only change as a deliberate contract update.
+ * - Reuses the P1 canonical snapshot shape (`WorkflowSnapshot`) and the P2
+ *   terminal predicate (`isTerminalSnapshot`); snapshot/terminal semantics
+ *   are never re-derived here.
+ *
+ * Locked decision precedence (first match wins):
+ *   1. main-worktree keep            → cleanup.keep.main-worktree
+ *   2. default/base-ref keep         → cleanup.keep.protected-ref
+ *   3. active execution/merge lease  → cleanup.refuse.active-lease
+ *   4. missing/foreign ownership     → cleanup.refuse.foreign-worktree /
+ *                                      cleanup.refuse.foreign-branch
+ *   5. non-terminal integration or non-Done plan
+ *                                    → cleanup.refuse.non-terminal
+ *   6. branch checked out anywhere   → cleanup.refuse.checked-out
+ *   7. unmerged/missing evidence     → cleanup.refuse.unmerged
+ *   8. dirty/locked worktree         → cleanup.refuse.dirty-worktree /
+ *                                      cleanup.refuse.locked-worktree
+ *   9. eligible                      → cleanup.remove.merged
+ *
+ * Guard scoping locked by the spec: the checked-out guard applies to branch
+ * deletion (local and remote candidates), never to removal of the eligible
+ * owned worktree (otherwise physical cleanup could never remove a normal
+ * attached worktree — dry-run correctly prints worktree `remove` plus its
+ * branch `refuse` until the post-removal re-plan). Merged evidence is a
+ * branch-deletion precondition; removing a clean owned worktree loses no
+ * commits, so worktree decisions are gated by ownership/eligibility and
+ * cleanliness/lock only. Non-terminal integration branches/worktrees and
+ * non-Done plan/track branches stay protected across ALL supplied
+ * lifecycles, not only the selected one; a main worktree is never removed
+ * and its branch candidate is independently protected by the ordinary
+ * rules.
+ */
+import { type WorkflowSnapshot } from "./workflow.js";
+export type CleanupTargetKind = "worktree" | "local-branch" | "remote-branch";
+export type CleanupTarget = {
+    kind: CleanupTargetKind;
+    ref: string;
+    branch: string;
+    tip: string;
+    owner: {
+        workflowId: string;
+        planId?: string;
+    } | null;
+};
+export type CleanupDecision = {
+    kind: CleanupTargetKind;
+    ref: string;
+    verdict: "remove" | "keep" | "refuse";
+    reason: string;
+};
+export type CleanupFacts = {
+    targets: readonly CleanupTarget[];
+    worktrees: readonly {
+        path: string;
+        branch: string | null;
+        isMain: boolean;
+        clean: boolean;
+        locked: boolean;
+    }[];
+    snapshots: readonly WorkflowSnapshot[];
+    defaultBranch: string;
+    mergedLocalBranches: Readonly<Record<string, readonly string[]>>;
+    remoteEvidence: readonly {
+        branch: string;
+        tip: string;
+        base: string;
+        ancestor: boolean;
+        prMerged: boolean | null;
+    }[];
+};
+/**
+ * Pure cleanup planner ( — locked interface). Consumes immutable facts,
+ * returns exactly one decision per candidate in input order, never mutates
+ * its inputs and never touches Git, the filesystem, the clock or the
+ * environment.
+ */
+export declare function planWorktreeCleanup(snapshot: WorkflowSnapshot, facts: CleanupFacts): CleanupDecision[];