gsd-pi 2.80.0 → 2.81.0

package/src/resources/extensions/gsd/tests/worktree-health-dispatch.test.ts

@@ -9,12 +9,13 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readdirSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
-import { PROJECT_FILES } from "../detection.js";
+import { PROJECT_FILES, classifyProject } from "../detection.js";
+import { _shouldProceedWithInvalidRepoClassificationForTest } from "../auto/phases.ts";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -30,6 +31,14 @@ function createGitRepo(): string {
   return dir;
 }
 
+function createEmptyGitRepo(): string {
+  const dir = mkdtempSync(join(tmpdir(), "wt-dispatch-test-empty-"));
+  execSync("git init", { cwd: dir, stdio: "ignore" });
+  execSync("git config user.email test@test.com", { cwd: dir, stdio: "ignore" });
+  execSync("git config user.name Test", { cwd: dir, stdio: "ignore" });
+  return dir;
+}
+
 /**
  * Simulate the health check logic from auto/phases.ts.
  *
@@ -64,8 +73,6 @@ function hasXcodeBundle(basePath: string): boolean {
   } catch { return false; }
 }
 
-import { existsSync } from "node:fs";
-
 // ─── Tests ───────────────────────────────────────────────────────────────────
 
 test("PROJECT_FILES is exported and contains expected multi-ecosystem entries", () => {
@@ -80,6 +87,21 @@ test("PROJECT_FILES is exported and contains expected multi-ecosystem entries",
   assert.ok(PROJECT_FILES.includes("Package.swift"), "includes Swift marker");
 });
 
+test("invalid-repo classification only proceeds when the git marker was already confirmed", () => {
+  assert.equal(
+    _shouldProceedWithInvalidRepoClassificationForTest("missing .git", true),
+    true,
+  );
+  assert.equal(
+    _shouldProceedWithInvalidRepoClassificationForTest("missing .git", false),
+    false,
+  );
+  assert.equal(
+    _shouldProceedWithInvalidRepoClassificationForTest("permission denied", true),
+    false,
+  );
+});
+
 describe("health check with git repo", () => {
   let dir: string;
   beforeEach(() => { dir = createGitRepo(); });
@@ -132,8 +154,18 @@ describe("health check with git repo", () => {
   });
 
   test("health check passes for empty git repo (greenfield project)", () => {
-    assert.ok(wouldPassHealthCheck(dir, existsSync), "empty git repo should pass health check (greenfield)");
-    assert.ok(!hasRecognizedProjectFiles(dir, existsSync), "empty git repo has no recognized project files");
+    const empty = createEmptyGitRepo();
+    try {
+      assert.ok(wouldPassHealthCheck(empty, existsSync), "empty git repo should pass health check (greenfield)");
+      assert.equal(classifyProject(empty).kind, "greenfield");
+    } finally {
+      rmSync(empty, { recursive: true, force: true });
+    }
+  });
+
+  test("health check classifies README-only repo as untyped existing, not greenfield", () => {
+    assert.ok(wouldPassHealthCheck(dir, existsSync), "README-only repo should pass health check");
+    assert.equal(classifyProject(dir).kind, "untyped-existing");
   });
 });
 

package/src/resources/extensions/gsd/tests/worktree-journal-events.test.ts

@@ -4,10 +4,25 @@ import { mkdtempSync, rmSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
-  WorktreeResolver,
-  type WorktreeResolverDeps,
+  WorktreeLifecycle,
+  type WorktreeLifecycleDeps,
   type NotifyCtx,
-} from "../worktree-resolver.js";
+} from "../worktree-lifecycle.js";
+import { WorktreeStateProjection } from "../worktree-state-projection.js";
+
+// Test-local: LegacyTestDeps had three fields Lifecycle does not need
+// (shouldUseWorktreeIsolation, syncWorktreeStateBack, captureIntegrationBranch).
+// Permit them in test fixtures so existing override patterns keep working —
+// Lifecycle ignores the extras via structural typing.
+type LegacyTestDeps = WorktreeLifecycleDeps & {
+  shouldUseWorktreeIsolation?: () => boolean;
+  syncWorktreeStateBack?: (
+    mainBasePath: string,
+    worktreePath: string,
+    milestoneId: string,
+  ) => { synced: string[] };
+  captureIntegrationBranch?: (basePath: string, mid: string | undefined) => void;
+};
 import { AutoSession } from "../auto/session.js";
 import type { JournalEntry } from "../journal.js";
 
@@ -23,9 +38,9 @@ function makeSession(
 }
 
 function makeDeps(
-  overrides?: Partial<WorktreeResolverDeps>,
-): WorktreeResolverDeps {
-  const deps: WorktreeResolverDeps = {
+  overrides?: Partial<LegacyTestDeps>,
+): LegacyTestDeps {
+  const deps: LegacyTestDeps = {
     isInAutoWorktree: () => false,
     shouldUseWorktreeIsolation: () => true,
     getIsolationMode: () => "worktree",
@@ -39,17 +54,19 @@ function makeDeps(
     getAutoWorktreePath: () => null,
     autoCommitCurrentBranch: () => {},
     getCurrentBranch: () => "main",
+    checkoutBranch: () => {},
     autoWorktreeBranch: (milestoneId: string) => `milestone/${milestoneId}`,
     resolveMilestoneFile: (_basePath: string, milestoneId: string) =>
       `/project/.gsd/milestones/${milestoneId}/${milestoneId}-ROADMAP.md`,
     readFileSync: () => "# Roadmap\n- [x] S01: Slice one\n",
     GitServiceImpl: class {
       constructor() {}
-    } as unknown as WorktreeResolverDeps["GitServiceImpl"],
+    } as unknown as LegacyTestDeps["GitServiceImpl"],
     loadEffectiveGSDPreferences: () => ({ preferences: { git: {} } }),
     invalidateAllCaches: () => {},
     captureIntegrationBranch: () => {},
     enterBranchModeForMilestone: () => {},
+    worktreeProjection: new WorktreeStateProjection(),
     ...overrides,
   };
   return deps;
@@ -99,9 +116,7 @@ describe("worktree journal events", () => {
   test("enterMilestone emits worktree-enter on success (new worktree)", () => {
     const s = makeSession({ basePath: tmp, originalBasePath: tmp });
     const deps = makeDeps({ getAutoWorktreePath: () => null });
-    const resolver = new WorktreeResolver(s, deps);
-
-    resolver.enterMilestone("M001", makeNotifyCtx());
+    new WorktreeLifecycle(s, deps).enterMilestone("M001", makeNotifyCtx());
 
     const entries = readJournalEntries(tmp);
     const enter = entries.find(e => e.eventType === "worktree-enter");
@@ -116,9 +131,7 @@ describe("worktree journal events", () => {
     const deps = makeDeps({
       getAutoWorktreePath: () => "/project/.gsd/worktrees/M001",
     });
-    const resolver = new WorktreeResolver(s, deps);
-
-    resolver.enterMilestone("M001", makeNotifyCtx());
+    new WorktreeLifecycle(s, deps).enterMilestone("M001", makeNotifyCtx());
 
     const entries = readJournalEntries(tmp);
     const enter = entries.find(e => e.eventType === "worktree-enter");
@@ -129,9 +142,7 @@ describe("worktree journal events", () => {
   test("enterMilestone emits worktree-skip when isolation disabled", () => {
     const s = makeSession({ basePath: tmp, originalBasePath: tmp });
     const deps = makeDeps({ shouldUseWorktreeIsolation: () => false, getIsolationMode: () => "none" });
-    const resolver = new WorktreeResolver(s, deps);
-
-    resolver.enterMilestone("M001", makeNotifyCtx());
+    new WorktreeLifecycle(s, deps).enterMilestone("M001", makeNotifyCtx());
 
     const entries = readJournalEntries(tmp);
     const skip = entries.find(e => e.eventType === "worktree-skip");
@@ -146,9 +157,7 @@ describe("worktree journal events", () => {
       getAutoWorktreePath: () => null,
       createAutoWorktree: () => { throw new Error("disk full"); },
     });
-    const resolver = new WorktreeResolver(s, deps);
-
-    resolver.enterMilestone("M001", makeNotifyCtx());
+    new WorktreeLifecycle(s, deps).enterMilestone("M001", makeNotifyCtx());
 
     const entries = readJournalEntries(tmp);
     const failed = entries.find(e => e.eventType === "worktree-create-failed");
@@ -167,9 +176,11 @@ describe("worktree journal events", () => {
       isInAutoWorktree: () => true,
       getIsolationMode: () => "worktree",
     });
-    const resolver = new WorktreeResolver(s, deps);
-
-    resolver.mergeAndExit("M001", makeNotifyCtx());
+    new WorktreeLifecycle(s, deps).exitMilestone(
+      "M001",
+      { merge: true },
+      makeNotifyCtx(),
+    );
 
     const entries = readJournalEntries(tmp);
     const start = entries.find(e => e.eventType === "worktree-merge-start");
@@ -188,14 +199,24 @@ describe("worktree journal events", () => {
       getIsolationMode: () => "worktree",
       mergeMilestoneToMain: () => { throw new Error("conflict in main"); },
     });
-    const resolver = new WorktreeResolver(s, deps);
-
     // Since #4380, mergeAndExit re-throws all errors after emitting the journal
-    // event and restoring state — callers must handle the throw.
-    assert.throws(
-      () => resolver.mergeAndExit("M001", makeNotifyCtx()),
-      /conflict in main/,
+    // event and restoring state. Lifecycle now wraps that throw in a typed
+    // ExitResult — failure surfaces as ok:false / cause.
+    const result = new WorktreeLifecycle(s, deps).exitMilestone(
+      "M001",
+      { merge: true },
+      makeNotifyCtx(),
     );
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.equal(result.reason, "teardown-failed");
+      assert.match(
+        result.cause instanceof Error
+          ? result.cause.message
+          : String(result.cause),
+        /conflict in main/,
+      );
+    }
 
     const entries = readJournalEntries(tmp);
     const failed = entries.find(e => e.eventType === "worktree-merge-failed");
@@ -207,9 +228,7 @@ describe("worktree journal events", () => {
   test("journal entries have valid flowId, seq, and ts fields", () => {
     const s = makeSession({ basePath: tmp, originalBasePath: tmp });
     const deps = makeDeps({ shouldUseWorktreeIsolation: () => false });
-    const resolver = new WorktreeResolver(s, deps);
-
-    resolver.enterMilestone("M001", makeNotifyCtx());
+    new WorktreeLifecycle(s, deps).enterMilestone("M001", makeNotifyCtx());
 
     const entries = readJournalEntries(tmp);
     assert.ok(entries.length > 0, "at least one entry should exist");

package/src/resources/extensions/gsd/tests/worktree-lifecycle.test.ts

@@ -0,0 +1,434 @@
+// Project/App: GSD-2
+// File Purpose: Worktree Lifecycle Module — typed-result contract tests for enterMilestone (ADR-016).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  WorktreeLifecycle,
+  type WorktreeLifecycleDeps,
+  type NotifyCtx,
+} from "../worktree-lifecycle.js";
+import { WorktreeStateProjection } from "../worktree-state-projection.js";
+import { AutoSession } from "../auto/session.js";
+import { openDatabase, closeDatabase, insertMilestone } from "../gsd-db.js";
+import { registerAutoWorker } from "../db/auto-workers.js";
+import { claimMilestoneLease } from "../db/milestone-leases.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+interface CallLog {
+  fn: string;
+  args: unknown[];
+}
+
+function makeSession(overrides?: Partial<AutoSession>): AutoSession {
+  const s = new AutoSession();
+  s.basePath = overrides?.basePath ?? "/project";
+  s.originalBasePath = overrides?.originalBasePath ?? "/project";
+  Object.assign(s, overrides);
+  return s;
+}
+
+function makeDeps(
+  overrides?: Partial<WorktreeLifecycleDeps>,
+): WorktreeLifecycleDeps & { calls: CallLog[] } {
+  const calls: CallLog[] = [];
+  const deps: WorktreeLifecycleDeps & { calls: CallLog[] } = {
+    calls,
+    enterAutoWorktree: (basePath, milestoneId) => {
+      calls.push({ fn: "enterAutoWorktree", args: [basePath, milestoneId] });
+      return `/project/.gsd/worktrees/${milestoneId}`;
+    },
+    createAutoWorktree: (basePath, milestoneId) => {
+      calls.push({ fn: "createAutoWorktree", args: [basePath, milestoneId] });
+      return `/project/.gsd/worktrees/${milestoneId}`;
+    },
+    enterBranchModeForMilestone: (basePath, milestoneId) => {
+      calls.push({
+        fn: "enterBranchModeForMilestone",
+        args: [basePath, milestoneId],
+      });
+    },
+    getAutoWorktreePath: (basePath, milestoneId) => {
+      calls.push({ fn: "getAutoWorktreePath", args: [basePath, milestoneId] });
+      return null;
+    },
+    getIsolationMode: () => {
+      calls.push({ fn: "getIsolationMode", args: [] });
+      return "worktree";
+    },
+    invalidateAllCaches: () => {
+      calls.push({ fn: "invalidateAllCaches", args: [] });
+    },
+    GitServiceImpl: class MockGitService {
+      basePath: string;
+      gitConfig: unknown;
+      constructor(basePath: string, gitConfig: unknown) {
+        calls.push({ fn: "GitServiceImpl", args: [basePath, gitConfig] });
+        this.basePath = basePath;
+        this.gitConfig = gitConfig;
+      }
+    } as unknown as WorktreeLifecycleDeps["GitServiceImpl"],
+    loadEffectiveGSDPreferences: () => {
+      calls.push({ fn: "loadEffectiveGSDPreferences", args: [] });
+      return { preferences: { git: {} } };
+    },
+    // Slice 7 widened WorktreeLifecycleDeps with merge/exit-side fields.
+    // These tests focus on enter; merge-side helpers are no-op stubs.
+    worktreeProjection: new WorktreeStateProjection(),
+    isInAutoWorktree: () => false,
+    autoCommitCurrentBranch: () => {},
+    autoWorktreeBranch: (mid: string) => `milestone/${mid}`,
+    teardownAutoWorktree: () => {},
+    mergeMilestoneToMain: () => ({ pushed: false, codeFilesChanged: true }),
+    getCurrentBranch: () => "main",
+    checkoutBranch: () => {},
+    resolveMilestoneFile: () => null,
+    readFileSync: () => "",
+    ...overrides,
+  };
+  return deps;
+}
+
+function makeCtx(): NotifyCtx & {
+  messages: Array<{ msg: string; level?: string }>;
+} {
+  const messages: Array<{ msg: string; level?: string }> = [];
+  return {
+    messages,
+    notify: (msg, level) => {
+      messages.push({ msg, level });
+    },
+  };
+}
+
+function makeDbBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-lifecycle-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanupDbBase(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+// ─── enterMilestone — typed-result contract ──────────────────────────────────
+
+test("enterMilestone returns ok:true mode:worktree on successful create", () => {
+  const s = makeSession();
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.mode, "worktree");
+    assert.equal(result.path, "/project/.gsd/worktrees/M001");
+  }
+  assert.equal(s.basePath, "/project/.gsd/worktrees/M001");
+  assert.equal(
+    deps.calls.filter((c) => c.fn === "invalidateAllCaches").length,
+    1,
+  );
+});
+
+test("enterMilestone returns ok:true mode:branch on successful branch fallback", () => {
+  const s = makeSession();
+  const deps = makeDeps({ getIsolationMode: () => "branch" });
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.mode, "branch");
+    assert.equal(result.path, "/project");
+  }
+  // Branch mode does not mutate s.basePath
+  assert.equal(s.basePath, "/project");
+});
+
+test("enterMilestone returns ok:true mode:none when isolation disabled", () => {
+  const s = makeSession();
+  const deps = makeDeps({ getIsolationMode: () => "none" });
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.mode, "none");
+    assert.equal(result.path, "/project");
+  }
+  assert.equal(s.basePath, "/project");
+});
+
+test("enterMilestone returns ok:false reason:isolation-degraded when session degraded", () => {
+  const s = makeSession({ isolationDegraded: true });
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.reason, "isolation-degraded");
+  }
+  // No worktree primitives invoked
+  assert.equal(deps.calls.filter((c) => c.fn === "createAutoWorktree").length, 0);
+  assert.equal(deps.calls.filter((c) => c.fn === "enterAutoWorktree").length, 0);
+});
+
+test("enterMilestone returns ok:false reason:creation-failed and degrades session on worktree throw", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    createAutoWorktree: () => {
+      throw new Error("boom");
+    },
+  });
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.reason, "creation-failed");
+    assert.ok(result.cause instanceof Error);
+  }
+  assert.equal(s.isolationDegraded, true);
+  // s.basePath unchanged on failure
+  assert.equal(s.basePath, "/project");
+});
+
+test("enterMilestone returns ok:false reason:creation-failed when branch mode throws", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+    enterBranchModeForMilestone: () => {
+      throw new Error("branch checkout failed");
+    },
+  });
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.reason, "creation-failed");
+  }
+  assert.equal(s.isolationDegraded, true);
+});
+
+test("enterMilestone enters existing worktree when path resolves", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    getAutoWorktreePath: () => "/project/.gsd/worktrees/M001",
+  });
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, true);
+  assert.equal(deps.calls.filter((c) => c.fn === "enterAutoWorktree").length, 1);
+  assert.equal(deps.calls.filter((c) => c.fn === "createAutoWorktree").length, 0);
+});
+
+test("enterMilestone returns ok:false reason:lease-conflict when another worker holds the lease", (t) => {
+  const base = makeDbBase();
+  t.after(() => cleanupDbBase(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  const holder = registerAutoWorker({ projectRootRealpath: base });
+  const contender = registerAutoWorker({ projectRootRealpath: base });
+  const claim = claimMilestoneLease(holder, "M001");
+  assert.equal(claim.ok, true);
+
+  const s = makeSession({ basePath: base, originalBasePath: base, workerId: contender });
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.reason, "lease-conflict");
+  }
+  assert.equal(s.isolationDegraded, false);
+  assert.equal(deps.calls.filter((c) => c.fn === "createAutoWorktree").length, 0);
+  assert.equal(deps.calls.filter((c) => c.fn === "enterAutoWorktree").length, 0);
+});
+
+test("enterMilestone is idempotent when already in the milestone worktree", () => {
+  const s = makeSession({
+    basePath: "/project/.gsd/worktrees/M001",
+    originalBasePath: "/project",
+    currentMilestoneId: "M001",
+  });
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.mode, "worktree");
+    assert.equal(result.path, "/project/.gsd/worktrees/M001");
+  }
+  assert.equal(s.basePath, "/project/.gsd/worktrees/M001");
+  assert.equal(deps.calls.filter((c) => c.fn === "createAutoWorktree").length, 0);
+  assert.equal(deps.calls.filter((c) => c.fn === "enterAutoWorktree").length, 0);
+});
+
+test("enterMilestone returns ok:false reason:invalid-milestone-id on path traversal", () => {
+  const s = makeSession();
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const traversal = lifecycle.enterMilestone("../escape", ctx);
+  const separator = lifecycle.enterMilestone("a/b", ctx);
+
+  assert.equal(traversal.ok, false);
+  if (!traversal.ok) {
+    assert.equal(traversal.reason, "invalid-milestone-id");
+  }
+  assert.equal(separator.ok, false);
+  if (!separator.ok) {
+    assert.equal(separator.reason, "invalid-milestone-id");
+  }
+});
+
+// ─── exitMilestone — typed-result contract ────────────────────────────────────
+//
+// The delegation-shape tests that lived here were retired in slice 7 / step
+// D of ADR-016: Lifecycle no longer takes a `resolverFactory`. The merge
+// behaviour they covered now runs inside Lifecycle directly and is exercised
+// end-to-end by the merge-mode tests in worktree-resolver.test.ts (which
+// drive Lifecycle through Resolver delegation until step E retires the
+// Resolver class entirely). When that retirement lands, those tests move
+// here verbatim.
+
+// ─── Queries (issue #5587) ────────────────────────────────────────────────────
+
+test("isInMilestone returns true when session matches milestone id", () => {
+  const s = makeSession();
+  s.currentMilestoneId = "M001";
+  const lifecycle = new WorktreeLifecycle(s, makeDeps());
+
+  assert.equal(lifecycle.isInMilestone("M001"), true);
+  assert.equal(lifecycle.isInMilestone("M002"), false);
+});
+
+test("isInMilestone returns false when session has no active milestone", () => {
+  const s = makeSession();
+  s.currentMilestoneId = null;
+  const lifecycle = new WorktreeLifecycle(s, makeDeps());
+
+  assert.equal(lifecycle.isInMilestone("M001"), false);
+});
+
+test("getCurrentMilestoneIfAny returns the active milestone id or null", () => {
+  const s = makeSession();
+  s.currentMilestoneId = "M042";
+  const lifecycle = new WorktreeLifecycle(s, makeDeps());
+
+  assert.equal(lifecycle.getCurrentMilestoneIfAny(), "M042");
+
+  s.currentMilestoneId = null;
+  assert.equal(lifecycle.getCurrentMilestoneIfAny(), null);
+});
+
+// ─── degradeToBranchMode (issue #5587) ────────────────────────────────────────
+
+test("degradeToBranchMode sets isolationDegraded and invokes branch-mode helper", () => {
+  const s = makeSession();
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  lifecycle.degradeToBranchMode("M001", ctx);
+
+  assert.equal(s.isolationDegraded, true);
+  assert.equal(
+    deps.calls.filter((c) => c.fn === "enterBranchModeForMilestone").length,
+    1,
+  );
+  assert.equal(deps.calls.filter((c) => c.fn === "invalidateAllCaches").length, 1);
+});
+
+test("degradeToBranchMode is no-op when isolationDegraded is already true", () => {
+  const s = makeSession();
+  s.isolationDegraded = true;
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  lifecycle.degradeToBranchMode("M001", ctx);
+
+  assert.equal(
+    deps.calls.filter((c) => c.fn === "enterBranchModeForMilestone").length,
+    0,
+  );
+});
+
+test("degradeToBranchMode marks degraded and notifies on branch-mode failure", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    enterBranchModeForMilestone: () => {
+      throw new Error("checkout failed");
+    },
+  });
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  lifecycle.degradeToBranchMode("M001", ctx);
+
+  assert.equal(s.isolationDegraded, true);
+  assert.ok(
+    ctx.messages.some(
+      (m) => m.level === "warning" && m.msg.includes("Branch isolation setup"),
+    ),
+  );
+});
+
+// ─── restoreToProjectRoot (issue #5587) ───────────────────────────────────────
+
+test("restoreToProjectRoot restores basePath to originalBasePath and rebuilds git service", () => {
+  const s = makeSession();
+  s.originalBasePath = "/project";
+  s.basePath = "/project/.gsd/worktrees/M001";
+  const deps = makeDeps();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  lifecycle.restoreToProjectRoot();
+
+  assert.equal(s.basePath, "/project");
+  assert.equal(deps.calls.filter((c) => c.fn === "GitServiceImpl").length, 1);
+  assert.equal(deps.calls.filter((c) => c.fn === "invalidateAllCaches").length, 1);
+});
+
+test("restoreToProjectRoot is no-op when originalBasePath is empty", () => {
+  const s = makeSession();
+  s.originalBasePath = "";
+  s.basePath = "/some/path";
+  const deps = makeDeps();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  lifecycle.restoreToProjectRoot();
+
+  assert.equal(s.basePath, "/some/path"); // unchanged
+  assert.equal(deps.calls.filter((c) => c.fn === "GitServiceImpl").length, 0);
+});