feat: worktree-lifecycle service (deterministic conflict prediction + safe GC) (#2164)

* feat: add worktree-lifecycle service (ecc.worktree-lifecycle.v1)

The "unowned moat" from the orchestrator landscape research: no existing
tool ships deterministic merge-conflict prediction or a safe worktree GC.

- scripts/lib/worktree-lifecycle/git.js: injectable, hermetic git layer.
  Predicts merge conflicts WITHOUT touching the working tree via
  `git merge-tree`. Strips inherited GIT_* env so it is safe inside hooks.
- scripts/lib/worktree-lifecycle/lifecycle.js: deterministic state machine
  (main/dirty/conflict/merge-ready/merged/stale/idle) + planCleanup that
  buckets worktrees into remove / salvage / keep. Only fully-merged trees
  are auto-removable; stale (unmerged+inactive) => salvage, never deleted.
- scripts/worktree-lifecycle.js: CLI (--json/--conflicts/--stale/
  --cleanup-plan/--base/--stale-days/--repo).
- tests/lib/worktree-lifecycle.test.js: 11 tests (fake-git + real-git).

Safety model mirrors the reference-arch salvage rule, validated by the
2026-06-05 MacBook->Mac Mini consolidation. Tests: 11/0.

* fix: hermetic git env in session adapters + mcp-inventory lint

- session adapters (codex-worktree, opencode): resolveGitBranch stripped
  no git env, so the "outside a repo" path returned the host branch when
  run inside a git hook (GIT_DIR set). Strip GIT_* before rev-parse.
- mcp-inventory: fix eslint no-unused-vars (signatures) and a stale
  eslint-disable directive in the merged code.

* test: run each test with inherited git env stripped (hermetic runner)

When the suite runs inside a git hook (pre-push), git sets GIT_DIR/
GIT_WORK_TREE, which hijack 'git -C <dir>' calls in tests that exercise
real git, making them operate on the host repo. Strip GIT_* before
spawning each test so the suite is isolated from ambient git state.

---------

Co-authored-by: ECC Test <ecc@example.test>

scripts/lib/worktree-lifecycle/lifecycle.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const { createGitRunner } = require('./git');
+
+const DEFAULT_STALE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// Lifecycle states for a worktree, derived deterministically from git facts.
+//   main          - the primary worktree (== baseBranch / repo root)
+//   detached      - no branch checked out
+//   dirty         - has uncommitted changes (work in progress, never auto-GC)
+//   conflict      - would conflict if merged into base (queued for resolution)
+//   merge-ready   - ahead of base, clean, no predicted conflicts
+//   merged        - fully merged into base (ahead == 0), safe to clean
+//   stale         - clean + no recent activity past the stale threshold
+//   idle          - clean, behind/even with base, nothing to merge
+const STATES = Object.freeze({
+  MAIN: 'main',
+  DETACHED: 'detached',
+  DIRTY: 'dirty',
+  CONFLICT: 'conflict',
+  MERGE_READY: 'merge-ready',
+  MERGED: 'merged',
+  STALE: 'stale',
+  IDLE: 'idle'
+});
+
+function classifyWorktree(facts, { staleThresholdMs, nowMs }) {
+  if (facts.isMain) {
+    return STATES.MAIN;
+  }
+
+  if (facts.detached || !facts.branch) {
+    return STATES.DETACHED;
+  }
+
+  if (facts.dirty) {
+    return STATES.DIRTY;
+  }
+
+  // Clean from here on.
+  const ahead = facts.aheadBehind ? facts.aheadBehind.ahead : 0;
+
+  // No unique commits => branch work is already in base => safe to garbage-collect.
+  if (facts.aheadBehind && ahead === 0) {
+    return STATES.MERGED;
+  }
+
+  if (facts.conflict) {
+    return STATES.CONFLICT;
+  }
+
+  // Has unmerged commits (ahead > 0, or unknown merge-base). Stale = unmerged
+  // work that has gone quiet past the threshold: a salvage candidate, never a
+  // blind delete. Recent unmerged work is merge-ready.
+  const isOld = facts.lastCommitMs !== null && (nowMs - facts.lastCommitMs) > staleThresholdMs;
+  if (ahead > 0 || facts.aheadBehind === null) {
+    return isOld ? STATES.STALE : STATES.MERGE_READY;
+  }
+
+  return STATES.IDLE;
+}
+
+function analyzeWorktree(worktree, options, git) {
+  const { baseBranch, staleThresholdMs, nowMs } = options;
+  const isMain = worktree.canonicalRepoRoot === git.repoRoot
+    || worktree.path === git.repoRoot
+    || worktree.branch === baseBranch;
+
+  const branch = worktree.branch;
+  const dirty = git.isDirty(worktree.path);
+  const aheadBehind = (!isMain && branch) ? git.aheadBehind(branch, baseBranch) : null;
+  const lastCommitMs = branch ? git.lastCommitMs(branch) : null;
+
+  // Only run conflict prediction when it matters: a clean, ahead branch.
+  const ahead = aheadBehind ? aheadBehind.ahead : 0;
+  let conflictResult = { conflicted: false, files: [], method: null };
+  if (!isMain && !dirty && branch && ahead > 0) {
+    conflictResult = git.predictMergeConflicts(branch, baseBranch);
+  }
+
+  const facts = {
+    isMain,
+    branch,
+    detached: Boolean(worktree.detached),
+    dirty,
+    aheadBehind,
+    lastCommitMs,
+    conflict: conflictResult.conflicted
+  };
+
+  const state = classifyWorktree(facts, { staleThresholdMs, nowMs });
+  const ageMs = lastCommitMs !== null ? Math.max(0, nowMs - lastCommitMs) : null;
+
+  return {
+    path: worktree.path,
+    branch: branch || null,
+    state,
+    head: worktree.head || null,
+    dirty,
+    ahead: aheadBehind ? aheadBehind.ahead : null,
+    behind: aheadBehind ? aheadBehind.behind : null,
+    lastCommitMs,
+    ageMs,
+    conflictFiles: conflictResult.files,
+    conflictMethod: conflictResult.method
+  };
+}
+
+function buildLifecycleReport(repoRoot, options = {}, deps = {}) {
+  const git = deps.git || createGitRunner(repoRoot, deps.runImpl);
+  const baseBranch = options.baseBranch || 'main';
+  const staleThresholdMs = Number.isFinite(options.staleThresholdMs)
+    ? options.staleThresholdMs
+    : DEFAULT_STALE_MS;
+  const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+
+  const worktrees = git.listWorktrees().map(worktree =>
+    analyzeWorktree(worktree, { baseBranch, staleThresholdMs, nowMs }, git)
+  );
+
+  const conflictQueue = worktrees.filter(w => w.state === STATES.CONFLICT);
+  const staleQueue = worktrees.filter(w => w.state === STATES.STALE);
+  const mergeReady = worktrees.filter(w => w.state === STATES.MERGE_READY);
+
+  const states = worktrees.reduce((acc, w) => {
+    acc[w.state] = (acc[w.state] || 0) + 1;
+    return acc;
+  }, {});
+
+  return {
+    schemaVersion: 'ecc.worktree-lifecycle.v1',
+    repoRoot,
+    baseBranch,
+    staleThresholdMs,
+    worktrees,
+    conflictQueue,
+    staleQueue,
+    mergeReady,
+    aggregates: {
+      worktreeCount: worktrees.length,
+      states,
+      conflictCount: conflictQueue.length,
+      staleCount: staleQueue.length,
+      mergeReadyCount: mergeReady.length
+    }
+  };
+}
+
+// Plan which worktrees are SAFE to garbage-collect. Safety rule: only fully
+// merged trees, or stale trees that are clean AND have nothing unmerged
+// (ahead == 0 or no tracked branch). Dirty or merge-ready/conflict trees are
+// never proposed for removal so in-progress or unmerged work is preserved
+// (mirrors the reference-arch salvage safeguard).
+function planCleanup(report) {
+  const remove = [];
+  const salvage = [];
+  const keep = [];
+
+  for (const w of report.worktrees) {
+    if (w.state === 'main') {
+      continue;
+    }
+
+    const unmergedWork = (w.ahead || 0) > 0;
+
+    if (w.state === 'merged') {
+      // Safe to remove: nothing unique to lose.
+      remove.push({ path: w.path, branch: w.branch, reason: 'fully merged into base' });
+    } else if (w.dirty) {
+      keep.push({ path: w.path, branch: w.branch, reason: 'has uncommitted changes' });
+    } else if (w.state === 'stale') {
+      // Unmerged + inactive: preserve first (push/bundle), then remove. Never
+      // a blind delete of unmerged work.
+      salvage.push({ path: w.path, branch: w.branch, reason: `unmerged + stale (age ${Math.round((w.ageMs || 0) / 86400000)}d, ${w.ahead} ahead) - push/bundle before removing` });
+    } else if (unmergedWork) {
+      keep.push({ path: w.path, branch: w.branch, reason: `unmerged work (${w.ahead} commits ahead)` });
+    } else {
+      keep.push({ path: w.path, branch: w.branch, reason: `state ${w.state}` });
+    }
+  }
+
+  return { remove, salvage, keep };
+}
+
+module.exports = {
+  STATES,
+  DEFAULT_STALE_MS,
+  classifyWorktree,
+  analyzeWorktree,
+  buildLifecycleReport,
+  planCleanup
+};