gsd-pi 2.49.0-dev.de3d9f6 → 2.50.0-dev.9476db8

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -6,8 +6,10 @@ import {
   insertTask,
   upsertSlicePlanning,
   upsertTaskPlanning,
+  insertGateRow,
   _getAdapter,
 } from "../gsd-db.js";
+import type { GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import { renderAllProjections } from "../workflow-projections.js";
@@ -190,6 +192,20 @@ export async function handlePlanSlice(
           fullPlanMd: task.fullPlanMd,
         });
       }
+
+      // Seed quality gate rows inside the transaction — all-or-nothing with
+      // the plan data so a crash can't leave orphaned gates without tasks.
+      const sliceGates: GateId[] = ["Q3", "Q4"];
+      for (const gid of sliceGates) {
+        insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "slice" });
+      }
+      const taskGates: GateId[] = ["Q5", "Q6", "Q7"];
+      for (const task of params.tasks) {
+        for (const gid of taskGates) {
+          insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: task.taskId });
+        }
+      }
+      insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: "Q8", scope: "slice" });
     });
   } catch (err) {
     return { error: `db write failed: ${(err as Error).message}` };

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -14,6 +14,7 @@ import {
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
+import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
 
 export interface ValidateMilestoneParams {
   milestoneId: string;
@@ -71,9 +72,8 @@ export async function handleValidateMilestone(
   if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
     return { error: "milestoneId is required and must be a non-empty string" };
   }
-  const validVerdicts = ["pass", "needs-attention", "needs-remediation"];
-  if (!validVerdicts.includes(params.verdict)) {
-    return { error: `verdict must be one of: ${validVerdicts.join(", ")}` };
+  if (!isValidMilestoneVerdict(params.verdict)) {
+    return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
   }
 
   // ── Filesystem render ──────────────────────────────────────────────────

package/src/resources/extensions/gsd/types.ts

@@ -11,6 +11,7 @@ export type Phase =
   | "discussing"
   | "researching"
   | "planning"
+  | "evaluating-gates"
   | "executing"
   | "verifying"
   | "summarizing"
@@ -557,3 +558,32 @@ export interface CompleteSliceParams {
   /** Optional caller-provided reason this action was triggered */
   triggerReason?: string;
 }
+
+// ─── Quality Gates ───────────────────────────────────────────────────────
+
+export type GateId = "Q3" | "Q4" | "Q5" | "Q6" | "Q7" | "Q8";
+export type GateScope = "slice" | "task";
+export type GateStatus = "pending" | "complete" | "omitted";
+export type GateVerdict = "pass" | "flag" | "omitted" | "";
+
+export interface GateRow {
+  milestone_id: string;
+  slice_id: string;
+  gate_id: GateId;
+  scope: GateScope;
+  task_id: string;
+  status: GateStatus;
+  verdict: GateVerdict;
+  rationale: string;
+  findings: string;
+  evaluated_at: string | null;
+}
+
+/** Configuration for parallel quality gate evaluation during slice planning. */
+export interface GateEvaluationConfig {
+  enabled: boolean;
+  /** Which slice-scoped gates to evaluate in parallel. Default: ['Q3', 'Q4']. */
+  slice_gates?: string[];
+  /** Whether to evaluate task-level gates (Q5/Q6/Q7) via reactive-execute. Default: true when enabled. */
+  task_gates?: boolean;
+}

package/src/resources/extensions/gsd/verdict-parser.ts

@@ -0,0 +1,95 @@
+/**
+ * Centralized verdict extraction, normalization, and schema validation.
+ *
+ * All verdict-related logic lives here so that normalization rules
+ * (e.g. `passed` → `pass`) are applied consistently across the codebase.
+ */
+
+import { extractUatType } from "./files.js";
+import type { UatType } from "./files.js";
+
+// ── Verdict extraction ──────────────────────────────────────────────────
+
+/**
+ * Extract and normalize the `verdict` value from YAML frontmatter.
+ *
+ * Normalization:
+ * - lowercased
+ * - `passed` → `pass`
+ *
+ * Returns `undefined` when frontmatter is absent or has no `verdict` field.
+ */
+export function extractVerdict(content: string): string | undefined {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return undefined;
+  const verdictMatch = fmMatch[1].match(/verdict:\s*([\w-]+)/i);
+  if (!verdictMatch) return undefined;
+  let v = verdictMatch[1].toLowerCase();
+  if (v === "passed") v = "pass";
+  return v;
+}
+
+/**
+ * Returns `true` when the content's frontmatter contains a `verdict` field.
+ */
+export function hasVerdict(content: string): boolean {
+  return /verdict:\s*[\w-]+/i.test(content);
+}
+
+// ── UAT verdict schema ──────────────────────────────────────────────────
+
+/**
+ * Base verdicts that are always acceptable for UAT results.
+ */
+export const UAT_ACCEPTABLE_VERDICTS: readonly string[] = ["pass", "passed"];
+
+/**
+ * UAT types whose results may legitimately produce a `partial` verdict
+ * when all automatable checks pass but human-only checks remain.
+ */
+const PARTIAL_ELIGIBLE_UAT_TYPES: readonly UatType[] = [
+  "mixed",
+  "human-experience",
+  "live-runtime",
+];
+
+/**
+ * Check whether a verdict is acceptable for a given UAT type.
+ *
+ * `pass` / `passed` are always acceptable. `partial` is acceptable only for
+ * UAT types that include non-automatable human checks.
+ */
+export function isAcceptableUatVerdict(verdict: string, uatType: UatType | undefined): boolean {
+  if (UAT_ACCEPTABLE_VERDICTS.includes(verdict)) return true;
+  if (verdict === "partial" && uatType && (PARTIAL_ELIGIBLE_UAT_TYPES as readonly string[]).includes(uatType)) {
+    return true;
+  }
+  return false;
+}
+
+// ── Milestone validation verdict schema ─────────────────────────────────
+
+/**
+ * Valid verdicts for the `validate-milestone` tool.
+ */
+export const VALIDATION_VERDICTS = ["pass", "needs-attention", "needs-remediation"] as const;
+export type ValidationVerdict = (typeof VALIDATION_VERDICTS)[number];
+
+/**
+ * Check whether a string is a valid milestone validation verdict.
+ */
+export function isValidMilestoneVerdict(verdict: string): verdict is ValidationVerdict {
+  return (VALIDATION_VERDICTS as readonly string[]).includes(verdict);
+}
+
+// ── UAT type helper ─────────────────────────────────────────────────────
+
+/**
+ * Extract the UAT type from content, defaulting to `"artifact-driven"`.
+ *
+ * The `"artifact-driven"` fallback is the original default used throughout
+ * the codebase when a UAT file lacks an explicit `## UAT Type` section.
+ */
+export function getUatType(content: string): UatType {
+  return extractUatType(content) ?? "artifact-driven";
+}

package/src/resources/extensions/gsd/verification-gate.ts

@@ -220,8 +220,6 @@ function sanitizeCommand(cmd: string): string | null {
 }
 
 export interface RunVerificationGateOptions {
-  basePath: string;
-  unitId: string;
   cwd: string;
   preferenceCommands?: string[];
   taskPlanVerify?: string;

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -150,6 +150,18 @@ export class WorktreeResolver {
    */
   enterMilestone(milestoneId: string, ctx: NotifyCtx): void {
     this.validateMilestoneId(milestoneId);
+
+    // If worktree creation failed earlier this session, skip all future attempts
+    if (this.s.isolationDegraded) {
+      debugLog("WorktreeResolver", {
+        action: "enterMilestone",
+        milestoneId,
+        skipped: true,
+        reason: "isolation-degraded",
+      });
+      return;
+    }
+
     if (!this.deps.shouldUseWorktreeIsolation()) {
       debugLog("WorktreeResolver", {
         action: "enterMilestone",
@@ -220,6 +232,9 @@ export class WorktreeResolver {
         `Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`,
         "warning",
       );
+      // Degrade isolation for the rest of this session so mergeAndExit
+      // doesn't try to merge a nonexistent worktree branch (#2483)
+      this.s.isolationDegraded = true;
       // Do NOT update s.basePath — stay in project root
     }
   }
@@ -304,6 +319,22 @@ export class WorktreeResolver {
    */
   mergeAndExit(milestoneId: string, ctx: NotifyCtx): void {
     this.validateMilestoneId(milestoneId);
+
+    // If worktree creation failed earlier, skip merge — work is on current branch (#2483)
+    if (this.s.isolationDegraded) {
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        skipped: true,
+        reason: "isolation-degraded",
+      });
+      ctx.notify(
+        `Skipping worktree merge for ${milestoneId} — isolation was degraded (worktree creation failed earlier). Work is on the current branch.`,
+        "info",
+      );
+      return;
+    }
+
     const mode = this.deps.getIsolationMode();
     debugLog("WorktreeResolver", {
       action: "mergeAndExit",

package/src/resources/extensions/gsd/worktree.ts

@@ -235,8 +235,9 @@ export function getSliceBranchName(milestoneId: string, sliceId: string, worktre
   return `gsd/${milestoneId}/${sliceId}`;
 }
 
-/** Regex that matches both plain and worktree-namespaced slice branches. */
-export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{6})?)\/(S\d+)$/;
+/** Re-export for backward compatibility — canonical definition in branch-patterns.ts */
+export { SLICE_BRANCH_RE } from "./branch-patterns.js";
+import { SLICE_BRANCH_RE } from "./branch-patterns.js";
 
 /**
  * Parse a slice branch name into its components.

package/src/resources/extensions/remote-questions/config.ts

@@ -2,7 +2,7 @@
  * Remote Questions — configuration resolution and validation
  */
 
-import { join } from "node:path";
+import { AuthStorage } from "@gsd/pi-coding-agent";
 import { loadEffectiveGSDPreferences, type RemoteQuestionsConfig } from "../gsd/preferences.js";
 import type { RemoteChannel } from "./types.js";
 
@@ -54,9 +54,7 @@ function hydrateRemoteTokensFromAuth(): void {
   if (needed.length === 0) return;
 
   try {
-    const { AuthStorage } = require("@gsd/pi-coding-agent") as typeof import("@gsd/pi-coding-agent");
-    const authPath = join(process.env.HOME ?? "~", ".gsd", "agent", "auth.json");
-    const auth = AuthStorage.create(authPath);
+    const auth = AuthStorage.create();
 
     for (const [providerId, envVar] of needed) {
       try {
@@ -72,7 +70,7 @@ function hydrateRemoteTokensFromAuth(): void {
       }
     }
   } catch {
-    // AuthStorage unavailable (unit tests, stripped build) — skip silently.
+    // AuthStorage unavailable or auth.json missing/unreadable — skip silently.
   }
 }
 

package/src/resources/extensions/search-the-web/native-search.ts

@@ -176,11 +176,15 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
     );
     payload.tools = tools;
 
-    // ── Session-level search budget (#1309) ──────────────────────────────
+    // ── Session-level search budget (#1309, #compaction-safe) ─────────────
     // Count web_search_tool_result blocks in the conversation history to
     // determine how many native searches have already been used this session.
     // The Anthropic API's max_uses resets per request, so without this guard,
     // pause_turn → resubmit cycles allow unlimited total searches.
+    //
+    // Use the monotonic high-water mark: take the max of the history count
+    // and the running counter. This prevents budget resets when context
+    // compaction removes web_search_tool_result blocks from history.
     if (Array.isArray(messages)) {
       let historySearchCount = 0;
       for (const msg of messages) {
@@ -192,8 +196,9 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
           }
         }
       }
-      // Sync counter from history (handles session restore / context replay)
-      sessionSearchCount = historySearchCount;
+      // High-water mark: never decrease the counter, even if compaction
+      // removes web_search_tool_result blocks from the visible history.
+      sessionSearchCount = Math.max(sessionSearchCount, historySearchCount);
     }
 
     const remaining = Math.max(0, MAX_NATIVE_SEARCHES_PER_SESSION - sessionSearchCount);

package/src/resources/extensions/search-the-web/tool-search.ts

@@ -106,14 +106,20 @@ searchCache.startPurgeInterval(60_000);
 
 // Consecutive duplicate search guard (#949)
 // Tracks recent query keys to detect and break search loops.
-const MAX_CONSECUTIVE_DUPES = 3;
+const MAX_CONSECUTIVE_DUPES = 1;
 let lastSearchKey = "";
 let consecutiveDupeCount = 0;
 
-/** Reset session-scoped duplicate-search guard state. */
+// Session-level total search budget (all queries, not just duplicates).
+// Prevents unbounded search accumulation across varied queries.
+const MAX_SEARCHES_PER_SESSION = 15;
+let sessionTotalSearches = 0;
+
+/** Reset session-scoped search guard state (both duplicate and budget). */
 export function resetSearchLoopGuardState(): void {
   lastSearchKey = "";
   consecutiveDupeCount = 0;
+  sessionTotalSearches = 0;
 }
 
 // Summarizer responses: max 50 entries, 15-minute TTL
@@ -357,6 +363,17 @@ export function registerSearchTool(pi: ExtensionAPI) {
         };
       }
 
+      // ------------------------------------------------------------------
+      // Session-level search budget
+      // ------------------------------------------------------------------
+      if (sessionTotalSearches >= MAX_SEARCHES_PER_SESSION) {
+        return {
+          content: [{ type: "text" as const, text: `⚠️ Search budget exhausted: ${sessionTotalSearches}/${MAX_SEARCHES_PER_SESSION} searches used this session. The information you need should already be in previous search results. Stop searching and use those results to proceed with your task.` }],
+          isError: true,
+          details: { errorKind: "budget_exhausted", error: `Session search budget exhausted (${MAX_SEARCHES_PER_SESSION})` } satisfies Partial<SearchDetails>,
+        };
+      }
+
       const count = params.count ?? 5;
       const wantSummary = params.summary ?? false;
 
@@ -410,6 +427,9 @@ export function registerSearchTool(pi: ExtensionAPI) {
         consecutiveDupeCount = 1;
       }
 
+      // Count every search that passes the guards toward the session budget.
+      sessionTotalSearches++;
+
       const cached = searchCache.get(cacheKey);
 
       if (cached) {

package/src/resources/skills/github-workflows/references/gh/SKILL.md

@@ -103,9 +103,12 @@ gh issue list -R gsd-build/gsd-2
 gh issue list -R gsd-build/gsd-2 --label "priority:p1" --state open
 
 # Create issue with labels and milestone
+# NOTE: Do NOT use labels for issue classification (bug, feature, etc.)
+# Use labels for metadata (priority, status, auto-generated) only.
+# Issue classification uses GitHub Issue Types, set via GraphQL after creation.
 gh issue create -R gsd-build/gsd-2 \
   --title "feat: add feature X" \
-  --label "priority:p1" --label "type:feature" \
+  --label "priority:p1" \
   --milestone "v1.0"
 
 # View issue
@@ -120,6 +123,24 @@ gh issue edit <number> -R gsd-build/gsd-2 \
   --remove-label "status:needs-grooming"
 ```
 
+### Issue Types (Classification)
+
+`gh issue create` has no `--type` flag. Issue types (Bug, Feature Request, etc.) are set via GraphQL after creation:
+
+```bash
+# Step 1: Create the issue (returns URL)
+ISSUE_URL=$(gh issue create -R gsd-build/gsd-2 \
+  --title "..." --body "...")
+
+# Step 2: Set the issue type via GraphQL
+ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
+ISSUE_ID=$(gh api graphql -f query='{ repository(owner:"gsd-build",name:"gsd-2") { issue(number:'"$ISSUE_NUM"') { id } } }' --jq '.data.repository.issue.id')
+TYPE_ID=$(gh api graphql -f query='{ repository(owner:"gsd-build",name:"gsd-2") { issueTypes(first:20) { nodes { id name } } } }' --jq '.data.repository.issueTypes.nodes[] | select(.name=="Bug") | .id')
+gh api graphql -f query='mutation { updateIssue(input:{id:"'"$ISSUE_ID"'",issueTypeId:"'"$TYPE_ID"'"}) { issue { number } } }'
+```
+
+Replace `"Bug"` with the appropriate type name (`"Feature Request"`, `"Task"`, etc.).
+
 ### Labels
 
 ```bash

package/dist/resources/extensions/gsd/auto-worktree-sync.js

@@ -1,191 +0,0 @@
-/**
- * Worktree ↔ project root state synchronization for auto-mode.
- *
- * When auto-mode runs inside a worktree, dispatch-critical state files
- * (.gsd/ metadata) diverge between the worktree (where work happens)
- * and the project root (where startAutoMode reads initial state on restart).
- * Without syncing, restarting auto-mode reads stale state from the project
- * root and re-dispatches already-completed units.
- *
- * Also contains resource staleness detection and stale worktree escape.
- */
-import { existsSync, readFileSync, unlinkSync, readdirSync, } from "node:fs";
-import { join, sep as pathSep } from "node:path";
-import { homedir } from "node:os";
-import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-// ─── Project Root → Worktree Sync ─────────────────────────────────────────
-/**
- * Sync milestone artifacts from project root INTO worktree before deriveState.
- * Covers the case where the LLM wrote artifacts to the main repo filesystem
- * (e.g. via absolute paths) but the worktree has stale data. Also deletes
- * gsd.db in the worktree so it rebuilds from fresh disk state (#853).
- * Non-fatal — sync failure should never block dispatch.
- */
-export function syncProjectRootToWorktree(projectRoot, worktreePath, milestoneId) {
-    if (!worktreePath || !projectRoot || worktreePath === projectRoot)
-        return;
-    if (!milestoneId)
-        return;
-    const prGsd = join(projectRoot, ".gsd");
-    const wtGsd = join(worktreePath, ".gsd");
-    // Copy milestone directory from project root to worktree if the project root
-    // has newer artifacts (e.g. slices that don't exist in the worktree yet)
-    safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId));
-    // Delete worktree gsd.db so it rebuilds from the freshly synced files.
-    // Stale DB rows are the root cause of the infinite skip loop (#853).
-    try {
-        const wtDb = join(wtGsd, "gsd.db");
-        if (existsSync(wtDb)) {
-            unlinkSync(wtDb);
-        }
-    }
-    catch {
-        /* non-fatal */
-    }
-}
-// ─── Worktree → Project Root Sync ─────────────────────────────────────────
-/**
- * Sync dispatch-critical .gsd/ state files from worktree to project root.
- * Only runs when inside an auto-worktree (worktreePath differs from projectRoot).
- * Copies: STATE.md + active milestone directory (roadmap, slice plans, task summaries).
- * Non-fatal — sync failure should never block dispatch.
- */
-export function syncStateToProjectRoot(worktreePath, projectRoot, milestoneId) {
-    if (!worktreePath || !projectRoot || worktreePath === projectRoot)
-        return;
-    if (!milestoneId)
-        return;
-    const wtGsd = join(worktreePath, ".gsd");
-    const prGsd = join(projectRoot, ".gsd");
-    // 1. STATE.md — the quick-glance status used by initial deriveState()
-    safeCopy(join(wtGsd, "STATE.md"), join(prGsd, "STATE.md"), { force: true });
-    // 2. Milestone directory — ROADMAP, slice PLANs, task summaries
-    // Copy the entire milestone .gsd subtree so deriveState reads current checkboxes
-    safeCopyRecursive(join(wtGsd, "milestones", milestoneId), join(prGsd, "milestones", milestoneId), { force: true });
-    // 3. metrics.json — session cost/token tracking (#2313).
-    // Without this, metrics accumulated in the worktree are invisible from the
-    // project root and never appear in the dashboard or skill-health reports.
-    safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
-    // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
-    // Without this, a crash during a unit leaves the runtime record only in the
-    // worktree. If the next session resolves basePath before worktree re-entry,
-    // selfHeal can't find or clear the stale record (#769).
-    safeCopyRecursive(join(wtGsd, "runtime", "units"), join(prGsd, "runtime", "units"), { force: true });
-}
-// ─── Resource Staleness ───────────────────────────────────────────────────
-/**
- * Read the resource version (semver) from the managed-resources manifest.
- * Uses gsdVersion instead of syncedAt so that launching a second session
- * doesn't falsely trigger staleness (#804).
- */
-export function readResourceVersion() {
-    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
-    const manifestPath = join(agentDir, "managed-resources.json");
-    try {
-        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-        return typeof manifest?.gsdVersion === "string"
-            ? manifest.gsdVersion
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Check if managed resources have been updated since session start.
- * Returns a warning message if stale, null otherwise.
- */
-export function checkResourcesStale(versionOnStart) {
-    if (versionOnStart === null)
-        return null;
-    const current = readResourceVersion();
-    if (current === null)
-        return null;
-    if (current !== versionOnStart) {
-        return "GSD resources were updated since this session started. Restart gsd to load the new code.";
-    }
-    return null;
-}
-// ─── Stale Worktree Escape ────────────────────────────────────────────────
-/**
- * Detect and escape a stale worktree cwd (#608).
- *
- * After milestone completion + merge, the worktree directory is removed but
- * the process cwd may still point inside `.gsd/worktrees/<MID>/`.
- * When a new session starts, `process.cwd()` is passed as `base` to startAuto
- * and all subsequent writes land in the wrong directory. This function detects
- * that scenario and chdir back to the project root.
- *
- * Returns the corrected base path.
- */
-export function escapeStaleWorktree(base) {
-    // Direct layout: /.gsd/worktrees/
-    const directMarker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
-    let idx = base.indexOf(directMarker);
-    if (idx === -1) {
-        // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-        const symlinkRe = new RegExp(`\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees\\${pathSep}`);
-        const match = base.match(symlinkRe);
-        if (!match || match.index === undefined)
-            return base;
-        idx = match.index;
-    }
-    // base is inside .gsd/worktrees/<something> — extract the project root
-    const projectRoot = base.slice(0, idx);
-    // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
-    // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
-    // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
-    // resolved through the symlink. Returning ~ would be catastrophic (#1676).
-    const candidateGsd = join(projectRoot, ".gsd").replaceAll("\\", "/");
-    const gsdHomePath = gsdHome.replaceAll("\\", "/");
-    if (candidateGsd === gsdHomePath || candidateGsd.startsWith(gsdHomePath + "/")) {
-        // Don't chdir to home — return base unchanged.
-        // resolveProjectRoot() in worktree.ts has the full git-file-based recovery
-        // and will be called by the caller (startAuto → projectRoot()).
-        return base;
-    }
-    try {
-        process.chdir(projectRoot);
-    }
-    catch {
-        // If chdir fails, return the original — caller will handle errors downstream
-        return base;
-    }
-    return projectRoot;
-}
-/**
- * Clean stale runtime unit files for completed milestones.
- *
- * After restart, stale runtime/units/*.json from prior milestones can
- * cause deriveState to resume the wrong milestone (#887). Removes files
- * for milestones that have a SUMMARY (fully complete).
- */
-export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
-    const runtimeUnitsDir = join(gsdRootPath, "runtime", "units");
-    if (!existsSync(runtimeUnitsDir))
-        return 0;
-    let cleaned = 0;
-    try {
-        for (const file of readdirSync(runtimeUnitsDir)) {
-            if (!file.endsWith(".json"))
-                continue;
-            const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
-            if (!midMatch)
-                continue;
-            if (hasMilestoneSummary(midMatch[1])) {
-                try {
-                    unlinkSync(join(runtimeUnitsDir, file));
-                    cleaned++;
-                }
-                catch {
-                    /* non-fatal */
-                }
-            }
-        }
-    }
-    catch {
-        /* non-fatal */
-    }
-    return cleaned;
-}