@cleocode/contracts 2026.5.78 → 2026.5.79

package/src/operations/worktree.ts

@@ -349,3 +349,277 @@ export interface PruneWorktreesResult {
   /** Whether `git worktree prune` was run. */
   gitPruneRan: boolean;
 }
+
+// ---------------------------------------------------------------------------
+// Structured listing (T9546 — worktree-lifecycle 2/5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mutually-exclusive worktree status category assigned by orphan-detection
+ * heuristics in {@link WorktreeInfo}.
+ *
+ * Resolution precedence (first match wins):
+ *  1. `locked` — git porcelain reports the worktree is locked.
+ *  2. `orphan` — owning task is cancelled OR the branch has been deleted.
+ *  3. `merged` — the branch is reachable from `main` (already integrated).
+ *  4. `stale`  — no commits in N days AND (task=done OR no live owner).
+ *  5. `active` — everything else (default).
+ *
+ * @task T9546
+ */
+export type WorktreeStatusCategory = 'active' | 'stale' | 'merged' | 'orphan' | 'locked';
+
+/**
+ * A single structured worktree entry with full status classification.
+ *
+ * Returned by `cleo worktree list` and the `worktree.list` dispatch operation.
+ * Each entry combines filesystem state, git state, and owning-task state into
+ * a single JSON envelope payload that downstream consumers (prune, dashboard,
+ * sentient daemon) can act on without re-querying git.
+ *
+ * @task T9546
+ */
+export interface WorktreeInfo {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Branch checked out in this worktree. */
+  branch: string;
+  /** Task ID derived from the branch name (`task/T####`), or null. */
+  taskId: string | null;
+  /** Agent identifier that owns this worktree (from audit log / metadata), or null. */
+  owningAgent: string | null;
+  /** ISO-8601 timestamp of last activity (newest commit OR mtime of working tree). */
+  lastActivity: string;
+  /** Whether `git worktree list --porcelain` reports the worktree as locked. */
+  isLocked: boolean;
+  /** Whether the worktree is stale: no activity > N days AND (task done/cancelled OR branch merged). */
+  isStale: boolean;
+  /** Whether the branch is reachable from `main` (already integrated). */
+  isMerged: boolean;
+  /** Status of the owning task (if {@link taskId} is present and resolvable), or null. */
+  owningTaskStatus: string | null;
+  /** Mutually-exclusive status category — see {@link WorktreeStatusCategory}. */
+  statusCategory: WorktreeStatusCategory;
+}
+
+/**
+ * Options for the structured worktree listing operation.
+ *
+ * @task T9546
+ */
+export interface ListWorktreesOpts {
+  /**
+   * Absolute path to the project root (used to compute the project hash
+   * and resolve the canonical worktrees directory).
+   */
+  projectRoot?: string;
+  /**
+   * Filter results to entries with one of these status categories.
+   * When omitted, all entries are returned.
+   */
+  statusFilter?: WorktreeStatusCategory[];
+  /**
+   * Staleness threshold in days. An entry is marked stale when its last
+   * activity is older than this AND either the owning task is done/cancelled
+   * or no owning task can be resolved while the branch is merged.
+   *
+   * @default 7
+   */
+  staleDays?: number;
+}
+
+/**
+ * Result of the structured worktree listing operation.
+ *
+ * @task T9546
+ */
+export interface ListWorktreesResult {
+  /** All matched worktree entries (post-filter). */
+  worktrees: WorktreeInfo[];
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle prune + force-unlock (T9547 — worktree-lifecycle 3/5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical action recorded in `.cleo/audit/worktree-lifecycle.jsonl`.
+ *
+ * - `prune` — orphaned/merged worktree was removed.
+ * - `prune-skip` — orphan was detected but skipped (user said N, or had uncommitted changes).
+ * - `force-unlock` — git index.lock removed + `git worktree unlock` ran.
+ * - `complete` — worktree was merged (`--no-ff`) into the default branch and pruned (T9548).
+ * - `complete-skip` — idempotent no-op (worktree already integrated or branch absent) (T9548).
+ * - `complete-manual` — operator marked the worktree as manually-handled via
+ *                       `--resolve manual`; no automatic merge attempted (T9548).
+ * - `complete-conflict` — auto-merge attempted but failed (e.g. rebase/merge conflict);
+ *                          worktree was preserved for manual resolution (T9548).
+ *
+ * @task T9547
+ * @task T9548
+ */
+export type WorktreeLifecycleAction =
+  | 'prune'
+  | 'prune-skip'
+  | 'force-unlock'
+  | 'complete'
+  | 'complete-skip'
+  | 'complete-manual'
+  | 'complete-conflict';
+
+/**
+ * One append-only entry written to `.cleo/audit/worktree-lifecycle.jsonl` by
+ * the prune + force-unlock commands.
+ *
+ * The shape intentionally mirrors the existing audit-jsonl pattern used by
+ * `worktree-prune.jsonl` (single-task path) so downstream log shippers can
+ * unify both streams. Optional fields are omitted (not null) when absent,
+ * keeping the JSONL surface compact and grep-friendly.
+ *
+ * @task T9547
+ */
+export interface WorktreeLifecycleAuditEntry {
+  /** ISO-8601 timestamp when the action was attempted. */
+  timestamp: string;
+  /** Agent / actor that initiated the action (env `CLEO_AGENT_ID` ?? `'cleo'`). */
+  actor: string;
+  /** The action performed — see {@link WorktreeLifecycleAction}. */
+  action: WorktreeLifecycleAction;
+  /** Absolute path to the worktree directory the action targeted. */
+  target: string;
+  /** Branch name (e.g. `task/T9547`) when known. */
+  branch?: string;
+  /** Task ID parsed from the branch name when known. */
+  taskId?: string;
+  /** Free-form reason — e.g. `orphaned-merged`, `dirty-skip`, `index-lock`. */
+  reason?: string;
+  /** Whether the action completed without error. */
+  success: boolean;
+  /** Error message when {@link success} is false. */
+  error?: string;
+}
+
+/**
+ * Options for {@link pruneOrphanedWorktreesByStatus} — the SDK primitive behind
+ * `cleo worktree prune --orphaned`.
+ *
+ * Per-orphan Y/N confirmation is the responsibility of the CLI layer; the SDK
+ * primitive itself is non-interactive and acts on the input set wholesale.
+ *
+ * @task T9547
+ */
+export interface PruneOrphanedWorktreesOpts {
+  /** Absolute path to the project root used for git invocations + audit log. */
+  projectRoot: string;
+  /**
+   * When true, do not actually remove worktrees — return the set that WOULD
+   * be pruned with `success: true` and the appropriate `reason`. The audit
+   * log is NOT written under `--dry-run`.
+   *
+   * @default false
+   */
+  dryRun?: boolean;
+  /**
+   * Staleness threshold in days passed through to {@link listWorktrees} when
+   * the caller wants a non-default `isStale` window.
+   *
+   * @default 7
+   */
+  staleDays?: number;
+  /**
+   * Optional subset of paths to prune. When supplied, only worktrees whose
+   * absolute `path` matches one of these strings are removed. The CLI passes
+   * this set after the user has confirmed per-orphan; in pure SDK use, omit
+   * the field to prune every orphan/merged entry the listing surfaces.
+   */
+  paths?: readonly string[];
+  /**
+   * Override actor name written to the audit log. Defaults to
+   * `process.env.CLEO_AGENT_ID ?? 'cleo'`.
+   */
+  actor?: string;
+  /**
+   * Optional override for the audit-log file path (testing). When omitted,
+   * writes to `<projectRoot>/.cleo/audit/worktree-lifecycle.jsonl`.
+   */
+  auditLogPath?: string;
+}
+
+/**
+ * Per-worktree outcome from a prune attempt.
+ *
+ * @task T9547
+ */
+export interface PrunedWorktreeOutcome {
+  /** Absolute path of the worktree. */
+  path: string;
+  /** Branch name (when known) — used by callers to render audit summaries. */
+  branch: string;
+  /** Task ID derived from the branch (when known). */
+  taskId: string | null;
+  /** Why this worktree was selected — e.g. `orphaned-merged`, `orphan-cancelled`. */
+  reason: string;
+  /** Whether the worktree was actually removed (false under --dry-run or on error). */
+  pruned: boolean;
+  /** Whether the task branch was deleted (only true when it was safe to do so). */
+  branchDeleted: boolean;
+  /** Error message when prune failed (set only on `pruned=false` + error path). */
+  error?: string;
+}
+
+/**
+ * Result of {@link pruneOrphanedWorktreesByStatus}.
+ *
+ * @task T9547
+ */
+export interface PruneOrphanedWorktreesResult {
+  /** Number of worktrees successfully pruned. */
+  prunedCount: number;
+  /** Number of orphans detected but NOT pruned (filtered by `paths`, dry-run, or errored). */
+  skippedCount: number;
+  /** Per-worktree outcomes, one entry per orphan that was considered. */
+  outcomes: PrunedWorktreeOutcome[];
+  /** Per-worktree errors raised during prune (subset of {@link outcomes} where `error` is set). */
+  errors: Array<{ path: string; error: string }>;
+  /** Whether {@link PruneOrphanedWorktreesOpts.dryRun} was set. */
+  dryRun: boolean;
+}
+
+/**
+ * Options for {@link forceUnlockWorktree} — the SDK primitive behind
+ * `cleo worktree force-unlock <taskId>`.
+ *
+ * @task T9547
+ */
+export interface ForceUnlockWorktreeOpts {
+  /** Absolute path to the project root used for git invocations. */
+  projectRoot: string;
+  /** Task ID whose worktree should be force-unlocked. */
+  taskId: string;
+  /** Override actor name written to the audit log. */
+  actor?: string;
+  /** Optional override for the audit-log file path (testing). */
+  auditLogPath?: string;
+}
+
+/**
+ * Result of {@link forceUnlockWorktree}.
+ *
+ * @task T9547
+ */
+export interface ForceUnlockWorktreeResult {
+  /** Task ID whose worktree was located. */
+  taskId: string;
+  /** Absolute path to the worktree (when located). */
+  path: string | null;
+  /** Whether `.git/index.lock` was present and removed. */
+  indexLockRemoved: boolean;
+  /** Whether `git worktree unlock` was executed (because porcelain reported `locked`). */
+  worktreeUnlocked: boolean;
+  /** Whether the worktree had uncommitted changes at the time of unlock (warn-only). */
+  hadUncommittedChanges: boolean;
+  /** Aggregate success — true when at least one unlock action ran without error. */
+  success: boolean;
+  /** Error message when no worktree could be located or all actions failed. */
+  error?: string;
+}