gsd-pi 2.32.0-dev.f3d5d53 → 2.33.0-dev.69bff0f

package/dist/resources/extensions/gsd/auto.ts

@@ -105,6 +105,7 @@ import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.j
 import { GSDError, GSD_ARTIFACT_MISSING } from "./errors.js";
 import { join } from "node:path";
 import { sep as pathSep } from "node:path";
+import { parseUnitId } from "./unit-id.js";
 import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync, statSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
@@ -214,52 +215,7 @@ export function shouldUseWorktreeIsolation(): boolean {
   return true; // default: worktree
 }
 
-/** Crash recovery prompt — set by startAuto, consumed by first dispatchNextUnit */
-
-/** Pending verification retry — set when gate fails with retries remaining, consumed by dispatchNextUnit */
-
-/** Verification retry count per unitId — separate from s.unitDispatchCount which tracks artifact-missing retries */
-
-/** Session file path captured at pause — used to synthesize recovery briefing on resume */
-
-/** Dashboard tracking */
-
-/** Track dynamic routing decision for the current unit (for metrics) */
-
-/** Queue of quick-task captures awaiting dispatch after triage resolution */
-
-/**
- * Model captured at auto-mode start. Used to prevent model bleed between
- * concurrent GSD instances sharing the same global settings.json (#650).
- * When preferences don't specify a model for a unit type, this ensures
- * the session's original model is re-applied instead of reading from
- * the shared global settings (which another instance may have overwritten).
- */
-
-/** Track current milestone to detect transitions */
-
-/** Model the user had selected before auto-mode started */
-
-/** Progress-aware timeout supervision */
-
-/** Context-pressure continue-here monitor — fires once when context usage >= 70% */
-
-/** Dispatch gap watchdog — detects when the state machine stalls between units.
- *  After handleAgentEnd completes, if auto-mode is still active but no new unit
- *  has been dispatched (sendMessage not called), this timer fires to force a
- *  re-evaluation. Covers the case where dispatchNextUnit silently fails or
- *  an unhandled error kills the dispatch chain. */
-
-/** Prompt character measurement for token savings analysis (R051). */
-
-/** SIGTERM handler registered while auto-mode is active — cleared on stop/pause. */
-
-/**
- * Tool calls currently being executed — prevents false idle detection during long-running tools.
- * Maps toolCallId → start timestamp (ms) so the idle watchdog can detect tools that have been
- * running suspiciously long (e.g., a Bash command hung because `&` kept stdout open).
- */
-
+// All mutable state lives in AutoSession (auto/session.ts) — see encapsulation invariant above.
 /** Wrapper: register SIGTERM handler and store reference. */
 function registerSigtermHandler(currentBasePath: string): void {
   s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
@@ -405,6 +361,79 @@ function buildSnapshotOpts(unitType: string, unitId: string): { continueHereFire
   };
 }
 
+// ─── Extracted Merge Helper ───────────────────────────────────────────────
+
+/**
+ * Attempt to merge the current milestone branch to main.
+ * Handles both worktree and branch isolation modes with a single code path.
+ * Returns true if merge succeeded, false on error (non-fatal, logged).
+ *
+ * Extracted from 4 duplicate merge blocks in dispatchNextUnit to eliminate
+ * the bug factory where fixing one copy didn't fix the others (#1308).
+ */
+function tryMergeMilestone(ctx: ExtensionContext, milestoneId: string, mode: "transition" | "complete"): boolean {
+  const isolationMode = getIsolationMode();
+
+  // Worktree merge path
+  if (isInAutoWorktree(s.basePath) && s.originalBasePath) {
+    try {
+      const roadmapPath = resolveMilestoneFile(s.originalBasePath, milestoneId, "ROADMAP");
+      if (!roadmapPath) {
+        teardownAutoWorktree(s.originalBasePath, milestoneId);
+        ctx.ui.notify(`Exited worktree for ${milestoneId} (no roadmap for merge).`, "info");
+        return false;
+      }
+      const roadmapContent = readFileSync(roadmapPath, "utf-8");
+      const mergeResult = mergeMilestoneToMain(s.originalBasePath, milestoneId, roadmapContent);
+      s.basePath = s.originalBasePath;
+      s.gitService = createGitService(s.basePath);
+      ctx.ui.notify(
+        `Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
+        "info",
+      );
+      return true;
+    } catch (err) {
+      ctx.ui.notify(
+        `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+      if (s.originalBasePath) {
+        s.basePath = s.originalBasePath;
+        try { process.chdir(s.basePath); } catch { /* best-effort */ }
+      }
+      return false;
+    }
+  }
+
+  // Branch-mode merge path
+  if (isolationMode === "branch") {
+    try {
+      const currentBranch = getCurrentBranch(s.basePath);
+      const milestoneBranch = autoWorktreeBranch(milestoneId);
+      if (currentBranch === milestoneBranch) {
+        const roadmapPath = resolveMilestoneFile(s.basePath, milestoneId, "ROADMAP");
+        if (roadmapPath) {
+          const roadmapContent = readFileSync(roadmapPath, "utf-8");
+          const mergeResult = mergeMilestoneToMain(s.basePath, milestoneId, roadmapContent);
+          s.gitService = createGitService(s.basePath);
+          ctx.ui.notify(
+            `Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
+            "info",
+          );
+          return true;
+        }
+      }
+    } catch (err) {
+      ctx.ui.notify(
+        `Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+    }
+  }
+
+  return false;
+}
+
 /**
  * Start a watchdog that fires if no new unit is dispatched within DISPATCH_GAP_TIMEOUT_MS
  * after handleAgentEnd completes. This catches the case where the dispatch chain silently
@@ -1106,32 +1135,14 @@ async function dispatchNextUnit(
     } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
 
     // ── Worktree lifecycle on milestone transition (#616) ──
-    if (isInAutoWorktree(s.basePath) && s.originalBasePath && shouldUseWorktreeIsolation()) {
-      try {
-        const roadmapPath = resolveMilestoneFile(s.originalBasePath, s.currentMilestoneId, "ROADMAP");
-        if (roadmapPath) {
-          const roadmapContent = readFileSync(roadmapPath, "utf-8");
-          const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
-          ctx.ui.notify(
-            `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-            "info",
-          );
-        } else {
-          teardownAutoWorktree(s.originalBasePath, s.currentMilestoneId);
-          ctx.ui.notify(`Exited worktree for ${ s.currentMilestoneId } (no roadmap for merge).`, "info");
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Milestone merge failed during transition: ${getErrorMessage(err)}`,
-          "warning",
-        );
-        if (s.originalBasePath) {
-          try { process.chdir(s.originalBasePath); } catch { /* best-effort */ }
-        }
-      }
+    if ((isInAutoWorktree(s.basePath) || getIsolationMode() === "branch") && shouldUseWorktreeIsolation()) {
+      tryMergeMilestone(ctx, s.currentMilestoneId, "transition");
 
-      s.basePath = s.originalBasePath;
-      s.gitService = createGitService(s.basePath);
+      // Reset to project root and re-derive state for the new milestone
+      if (s.originalBasePath) {
+        s.basePath = s.originalBasePath;
+        s.gitService = createGitService(s.basePath);
+      }
       invalidateAllCaches();
 
       state = await deriveState(s.basePath);
@@ -1176,51 +1187,8 @@ async function dispatchNextUnit(
     const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
     if (incomplete.length === 0) {
       // Genuinely all complete (parked milestones excluded) — merge milestone branch to main before stopping (#962)
-      if (s.currentMilestoneId && isInAutoWorktree(s.basePath) && s.originalBasePath) {
-        try {
-          const roadmapPath = resolveMilestoneFile(s.originalBasePath, s.currentMilestoneId, "ROADMAP");
-          if (roadmapPath) {
-            const roadmapContent = readFileSync(roadmapPath, "utf-8");
-            const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
-            s.basePath = s.originalBasePath;
-            s.gitService = createGitService(s.basePath);
-            ctx.ui.notify(
-              `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-              "info",
-            );
-          }
-        } catch (err) {
-          ctx.ui.notify(
-            `Milestone merge failed: ${getErrorMessage(err)}`,
-            "warning",
-          );
-          if (s.originalBasePath) {
-            s.basePath = s.originalBasePath;
-            try { process.chdir(s.basePath); } catch { /* best-effort */ }
-          }
-        }
-      } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() === "branch") {
-        try {
-          const currentBranch = getCurrentBranch(s.basePath);
-          const milestoneBranch = autoWorktreeBranch(s.currentMilestoneId);
-          if (currentBranch === milestoneBranch) {
-            const roadmapPath = resolveMilestoneFile(s.basePath, s.currentMilestoneId, "ROADMAP");
-            if (roadmapPath) {
-              const roadmapContent = readFileSync(roadmapPath, "utf-8");
-              const mergeResult = mergeMilestoneToMain(s.basePath, s.currentMilestoneId, roadmapContent);
-              s.gitService = createGitService(s.basePath);
-              ctx.ui.notify(
-                `Milestone ${ s.currentMilestoneId } merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
-                "info",
-              );
-            }
-          }
-        } catch (err) {
-          ctx.ui.notify(
-            `Milestone merge failed (branch mode): ${getErrorMessage(err)}`,
-            "warning",
-          );
-        }
+      if (s.currentMilestoneId) {
+        tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
       }
       sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
       await stopAuto(ctx, pi, "All milestones complete");
@@ -1279,50 +1247,8 @@ async function dispatchNextUnit(
       s.completedKeySet.clear();
     } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
     // ── Milestone merge ──
-    if (s.currentMilestoneId && isInAutoWorktree(s.basePath) && s.originalBasePath) {
-      try {
-        const roadmapPath = resolveMilestoneFile(s.originalBasePath, s.currentMilestoneId, "ROADMAP");
-        if (!roadmapPath) throw new GSDError(GSD_ARTIFACT_MISSING, `Cannot resolve ROADMAP file for milestone ${ s.currentMilestoneId }`);
-        const roadmapContent = readFileSync(roadmapPath, "utf-8");
-        const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
-        s.basePath = s.originalBasePath;
-        s.gitService = createGitService(s.basePath);
-        ctx.ui.notify(
-          `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-          "info",
-        );
-      } catch (err) {
-        ctx.ui.notify(
-          `Milestone merge failed: ${getErrorMessage(err)}`,
-          "warning",
-        );
-        if (s.originalBasePath) {
-          s.basePath = s.originalBasePath;
-          try { process.chdir(s.basePath); } catch { /* best-effort */ }
-        }
-      }
-    } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() === "branch") {
-      try {
-        const currentBranch = getCurrentBranch(s.basePath);
-        const milestoneBranch = autoWorktreeBranch(s.currentMilestoneId);
-        if (currentBranch === milestoneBranch) {
-          const roadmapPath = resolveMilestoneFile(s.basePath, s.currentMilestoneId, "ROADMAP");
-          if (roadmapPath) {
-            const roadmapContent = readFileSync(roadmapPath, "utf-8");
-            const mergeResult = mergeMilestoneToMain(s.basePath, s.currentMilestoneId, roadmapContent);
-            s.gitService = createGitService(s.basePath);
-            ctx.ui.notify(
-              `Milestone ${ s.currentMilestoneId } merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
-              "info",
-            );
-          }
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Milestone merge failed (branch mode): ${getErrorMessage(err)}`,
-          "warning",
-        );
-      }
+    if (s.currentMilestoneId) {
+      tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
     }
     sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
     await stopAuto(ctx, pi, `Milestone ${mid} complete`);
@@ -1748,8 +1674,7 @@ async function dispatchNextUnit(
 function ensurePreconditions(
   unitType: string, unitId: string, base: string, state: GSDState,
 ): void {
-  const parts = unitId.split("/");
-  const mid = parts[0]!;
+  const { milestone: mid } = parseUnitId(unitId);
 
   const mDir = resolveMilestonePath(base, mid);
   if (!mDir) {
@@ -1757,8 +1682,8 @@ function ensurePreconditions(
     mkdirSync(join(newDir, "slices"), { recursive: true });
   }
 
-  if (parts.length >= 2) {
-    const sid = parts[1]!;
+  const sid = parseUnitId(unitId).slice;
+  if (sid) {
 
     const mDirResolved = resolveMilestonePath(base, mid);
     if (mDirResolved) {

package/dist/resources/extensions/gsd/commands.ts

@@ -52,8 +52,20 @@ import { handleStart, handleTemplates, getTemplateCompletions } from "./commands
 
 /** Resolve the effective project root, accounting for worktree paths. */
 export function projectRoot(): string {
-  const root = resolveProjectRoot(process.cwd());
-  assertSafeDirectory(root);
+  const cwd = process.cwd();
+  const root = resolveProjectRoot(cwd);
+
+  // When running inside a GSD worktree, the resolved root may be a "dangerous"
+  // directory (e.g., $HOME used as a git repo root — #1317). The safety check
+  // should validate the actual working directory, not the upstream root,
+  // because the worktree itself is a safe project subdirectory.
+  // Only skip the root check when we can confirm we're in a valid worktree.
+  if (root !== cwd) {
+    // We're in a worktree — validate the worktree path instead of the root
+    assertSafeDirectory(cwd);
+  } else {
+    assertSafeDirectory(root);
+  }
   return root;
 }
 

package/dist/resources/extensions/gsd/complexity-classifier.ts

@@ -6,6 +6,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { getAdaptiveTierAdjustment } from "./routing-history.js";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -180,15 +181,14 @@ function analyzePlanComplexity(
   basePath: string,
 ): TaskAnalysis | null {
   // Check if this is a milestone-level plan (more complex) vs single slice
-  const parts = unitId.split("/");
-  if (parts.length === 1) {
+  const { milestone: mid, slice: sid } = parseUnitId(unitId);
+  if (!sid) {
     // Milestone-level planning is always at least standard
     return { tier: "standard", reason: "milestone-level planning" };
   }
 
   // For slice planning, try to read the context/research to gauge complexity
   // If research exists and is large, bump to heavy
-  const [mid, sid] = parts;
   const researchPath = join(gsdRoot(basePath), mid, "slices", sid, "RESEARCH.md");
   try {
     if (existsSync(researchPath)) {
@@ -210,10 +210,8 @@ function analyzePlanComplexity(
  */
 function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata {
   const meta: TaskMetadata = {};
-  const parts = unitId.split("/");
-  if (parts.length !== 3) return meta;
-
-  const [mid, sid, tid] = parts;
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+  if (!mid || !sid || !tid) return meta;
   const taskPlanPath = join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-PLAN.md`);
 
   try {

package/dist/resources/extensions/gsd/dispatch-guard.ts

@@ -5,6 +5,7 @@ import { readdirSync } from "node:fs";
 import { resolveMilestoneFile, milestonesDir } from "./paths.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { findMilestoneIds } from "./guided-flow.js";
+import { parseUnitId } from "./unit-id.js";
 
 const SLICE_DISPATCH_TYPES = new Set([
   "research-slice",
@@ -39,7 +40,7 @@ function readRoadmapFromDisk(base: string, milestoneId: string): string | null {
 export function getPriorSliceCompletionBlocker(base: string, _mainBranch: string, unitType: string, unitId: string): string | null {
   if (!SLICE_DISPATCH_TYPES.has(unitType)) return null;
 
-  const [targetMid, targetSid] = unitId.split("/");
+  const { milestone: targetMid, slice: targetSid } = parseUnitId(unitId);
   if (!targetMid || !targetSid) return null;
 
   // Use findMilestoneIds to respect custom queue order.

package/dist/resources/extensions/gsd/metrics.ts

@@ -18,6 +18,7 @@ import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { parseUnitId } from "./unit-id.js";
 
 // Re-export from shared — canonical implementation lives in format-utils.
 export { formatTokenCount } from "../shared/mod.js";
@@ -290,9 +291,8 @@ export function aggregateByPhase(units: UnitMetrics[]): PhaseAggregate[] {
 export function aggregateBySlice(units: UnitMetrics[]): SliceAggregate[] {
   const map = new Map<string, SliceAggregate>();
   for (const u of units) {
-    const parts = u.id.split("/");
-    // Slice ID is parts[0]/parts[1] if it exists, else parts[0]
-    const sliceId = parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+    const { milestone, slice } = parseUnitId(u.id);
+    const sliceId = slice ? `${milestone}/${slice}` : milestone;
     let agg = map.get(sliceId);
     if (!agg) {
       agg = { sliceId, units: 0, tokens: emptyTokens(), cost: 0, duration: 0 };

package/dist/resources/extensions/gsd/post-unit-hooks.ts

@@ -15,6 +15,7 @@ import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js"
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Hook Queue State ──────────────────────────────────────────────────────
 
@@ -149,7 +150,7 @@ function dequeueNextHook(basePath: string): HookDispatchResult | null {
     };
 
     // Build the prompt with variable substitution
-    const [mid, sid, tid] = triggerUnitId.split("/");
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
     const prompt = config.prompt
       .replace(/\{milestoneId\}/g, mid ?? "")
       .replace(/\{sliceId\}/g, sid ?? "")
@@ -208,16 +209,14 @@ function handleHookCompletion(basePath: string): HookDispatchResult | null {
  *   - Milestone-level (M001):    .gsd/M001/{artifact}
  */
 export function resolveHookArtifactPath(basePath: string, unitId: string, artifactName: string): string {
-  const parts = unitId.split("/");
-  if (parts.length === 3) {
-    const [mid, sid, tid] = parts;
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+  if (mid && sid && tid) {
     return join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
   }
-  if (parts.length === 2) {
-    const [mid, sid] = parts;
+  if (mid && sid) {
     return join(gsdRoot(basePath), mid, "slices", sid, artifactName);
   }
-  return join(gsdRoot(basePath), parts[0], artifactName);
+  return join(gsdRoot(basePath), mid, artifactName);
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -253,7 +252,7 @@ export function runPreDispatchHooks(
     return { action: "proceed", prompt, firedHooks: [] };
   }
 
-  const [mid, sid, tid] = unitId.split("/");
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   const substitute = (text: string): string =>
     text
       .replace(/\{milestoneId\}/g, mid ?? "")
@@ -466,7 +465,7 @@ export function triggerHookManually(
   activeHook.cycle = currentCycle;
 
   // Build the prompt with variable substitution
-  const [mid, sid, tid] = unitId.split("/");
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   const prompt = hook.prompt
     .replace(/\{milestoneId\}/g, mid ?? "")
     .replace(/\{sliceId\}/g, sid ?? "")

package/dist/resources/extensions/gsd/session-lock.ts

@@ -17,7 +17,7 @@
  */
 
 import { createRequire } from "node:module";
-import { existsSync, readFileSync, mkdirSync, unlinkSync, rmSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, mkdirSync, unlinkSync, rmSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -54,12 +54,81 @@ let _lockPid: number = 0;
 /** Set to true when proper-lockfile fires onCompromised (mtime drift, sleep, etc.). */
 let _lockCompromised: boolean = false;
 
+/** Whether we've already registered a process.on('exit') handler. */
+let _exitHandlerRegistered: boolean = false;
+
 const LOCK_FILE = "auto.lock";
 
 function lockPath(basePath: string): string {
   return join(gsdRoot(basePath), LOCK_FILE);
 }
 
+// ─── Stray Lock Cleanup ─────────────────────────────────────────────────────
+
+/**
+ * Remove numbered lock file variants (e.g. "auto 2.lock", "auto 3.lock")
+ * that accumulate from macOS file conflict resolution (iCloud/Dropbox/OneDrive)
+ * or other filesystem-level copy-on-conflict behavior (#1315).
+ *
+ * Also removes stray proper-lockfile directories beyond the canonical `.gsd.lock/`.
+ */
+export function cleanupStrayLockFiles(basePath: string): void {
+  const gsdDir = gsdRoot(basePath);
+
+  // Clean numbered auto lock files inside .gsd/
+  try {
+    if (existsSync(gsdDir)) {
+      for (const entry of readdirSync(gsdDir)) {
+        // Match "auto <N>.lock" or "auto (<N>).lock" variants but NOT the canonical "auto.lock"
+        if (entry !== LOCK_FILE && /^auto\s.+\.lock$/i.test(entry)) {
+          try { unlinkSync(join(gsdDir, entry)); } catch { /* best-effort */ }
+        }
+      }
+    }
+  } catch { /* non-fatal: directory read failure */ }
+
+  // Clean stray proper-lockfile directories (e.g. ".gsd 2.lock/")
+  // The canonical one is ".gsd.lock/" — anything else is stray.
+  try {
+    const parentDir = dirname(gsdDir);
+    const gsdDirName = gsdDir.split("/").pop() || ".gsd";
+    if (existsSync(parentDir)) {
+      for (const entry of readdirSync(parentDir)) {
+        // Match ".gsd <N>.lock" or ".gsd (<N>).lock" directories but NOT ".gsd.lock"
+        if (entry !== `${gsdDirName}.lock` && entry.startsWith(gsdDirName) && entry.endsWith(".lock")) {
+          const fullPath = join(parentDir, entry);
+          try {
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+              rmSync(fullPath, { recursive: true, force: true });
+            }
+          } catch { /* best-effort */ }
+        }
+      }
+    }
+  } catch { /* non-fatal */ }
+}
+
+/**
+ * Register a single process exit handler that cleans up lock state.
+ * Uses module-level references so it always operates on current state.
+ * Only registers once — subsequent calls are no-ops.
+ */
+function ensureExitHandler(gsdDir: string): void {
+  if (_exitHandlerRegistered) return;
+  _exitHandlerRegistered = true;
+
+  process.once("exit", () => {
+    try {
+      if (_releaseFunction) { _releaseFunction(); _releaseFunction = null; }
+    } catch { /* best-effort */ }
+    try {
+      const lockDir = join(gsdDir + ".lock");
+      if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+    } catch { /* best-effort */ }
+  });
+}
+
 // ─── Public API ─────────────────────────────────────────────────────────────
 
 /**
@@ -77,6 +146,9 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
   // Ensure the directory exists
   mkdirSync(dirname(lp), { recursive: true });
 
+  // Clean up numbered lock file variants from cloud sync conflicts (#1315)
+  cleanupStrayLockFiles(basePath);
+
   // Write our lock data first (the content is informational; the OS lock is the real guard)
   const lockData: SessionLockData = {
     pid: process.pid,
@@ -124,15 +196,7 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
 
     // Safety net: clean up lock dir on process exit if _releaseFunction
     // wasn't called (e.g., normal exit after clean completion) (#1245).
-    const lockDirForCleanup = join(gsdDir + ".lock");
-    process.once("exit", () => {
-      try {
-        if (_releaseFunction) { _releaseFunction(); _releaseFunction = null; }
-      } catch { /* best-effort */ }
-      try {
-        if (existsSync(lockDirForCleanup)) rmSync(lockDirForCleanup, { recursive: true, force: true });
-      } catch { /* best-effort */ }
-    });
+    ensureExitHandler(gsdDir);
 
     // Write the informational lock data
     atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
@@ -158,18 +222,15 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
           update: 10_000,
           onCompromised: () => {
             _lockCompromised = true;
+            _releaseFunction = null;
           },
         });
         _releaseFunction = release;
         _lockedPath = basePath;
         _lockPid = process.pid;
 
-        // Safety net for retry path too
-        const retryLockDir = join(gsdDir + ".lock");
-        process.once("exit", () => {
-          try { if (_releaseFunction) { _releaseFunction(); _releaseFunction = null; } } catch {}
-          try { if (existsSync(retryLockDir)) rmSync(retryLockDir, { recursive: true, force: true }); } catch {}
-        });
+        // Safety net — uses centralized handler to avoid double-registration
+        ensureExitHandler(gsdDir);
 
         atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
         return { acquired: true };
@@ -310,6 +371,9 @@ export function releaseSessionLock(basePath: string): void {
     // Non-fatal
   }
 
+  // Clean up numbered lock file variants from cloud sync conflicts (#1315)
+  cleanupStrayLockFiles(basePath);
+
   _lockedPath = null;
   _lockPid = 0;
   _lockCompromised = false;

package/dist/resources/extensions/gsd/tests/all-milestones-complete-merge.test.ts

@@ -70,31 +70,34 @@ test("auto.ts 'all milestones complete' path merges before stopping (#962)", ()
   const incompleteIdx = autoSrc.indexOf("incomplete.length === 0");
   assert.ok(incompleteIdx > -1, "auto.ts should have 'incomplete.length === 0' check");
 
-  // The merge call must appear BETWEEN the incomplete check and the stopAuto call
-  // in that same block
+  // The merge call must appear BETWEEN the incomplete check and the stopAuto call.
+  // After the #1308 refactor, the merge is delegated to tryMergeMilestone.
   const blockAfterIncomplete = autoSrc.slice(incompleteIdx, incompleteIdx + 3000);
 
   assert.ok(
-    blockAfterIncomplete.includes("mergeMilestoneToMain"),
-    "auto.ts should call mergeMilestoneToMain in the 'all milestones complete' path",
+    blockAfterIncomplete.includes("tryMergeMilestone"),
+    "auto.ts should call tryMergeMilestone in the 'all milestones complete' path",
   );
 
   // The merge should come before stopAuto in this block
-  const mergePos = blockAfterIncomplete.indexOf("mergeMilestoneToMain");
+  const mergePos = blockAfterIncomplete.indexOf("tryMergeMilestone");
   const stopPos = blockAfterIncomplete.indexOf("stopAuto");
   assert.ok(
     mergePos < stopPos,
-    "mergeMilestoneToMain should be called before stopAuto in the 'all complete' path",
+    "tryMergeMilestone should be called before stopAuto in the 'all complete' path",
   );
 
-  // Should handle both worktree and branch isolation modes
+  // Verify tryMergeMilestone handles both worktree and branch isolation
+  const helperIdx = autoSrc.indexOf("function tryMergeMilestone");
+  assert.ok(helperIdx > -1, "tryMergeMilestone helper should exist");
+  const helperBlock = autoSrc.slice(helperIdx, helperIdx + 2000);
   assert.ok(
-    blockAfterIncomplete.includes("isInAutoWorktree"),
-    "should check isInAutoWorktree for worktree mode",
+    helperBlock.includes("isInAutoWorktree"),
+    "tryMergeMilestone should check isInAutoWorktree for worktree mode",
   );
   assert.ok(
-    blockAfterIncomplete.includes("getIsolationMode"),
-    "should check getIsolationMode for branch isolation mode",
+    helperBlock.includes("getIsolationMode") || helperBlock.includes("isolationMode"),
+    "tryMergeMilestone should check isolation mode for branch mode",
   );
 });