gsd-pi 2.33.0 → 2.33.1-dev.29a8268

package/README.md

@@ -24,24 +24,19 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.32
-
-- **Simplified pipeline** — research merged into planning, mechanical completion (ADR-003)
-- **Always-on health widget** — 🟢🟡🔴 traffic-light indicator in the progress widget and visualizer health tab
-- **Environment health checks** — progress scoring and status integration for auto-mode
-- **Extension registry** — user-managed enable/disable for bundled and custom extensions
-- **Built-in skill authoring** — create and distribute custom skills from within GSD
-- **Workflow templates** — right-sized workflows for every task type (research, plan, execute, complete)
-- **AWS Bedrock auth** — automatic credential refresh via the new `aws-auth` extension
-- **`-w` / `--worktree` CLI flag** — launch isolated worktree sessions from the command line
-- **Native MCP client** — replaced MCPorter with a built-in MCP client for better reliability
-- **External state directory** — `.gsd/` now lives in `~/.gsd/projects/` with a symlink (ADR-002)
-- **Model health indicator** — live health status based on error trends and consecutive failures
-- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back after completion
-- **Windows EPERM fallback** — migration rename uses copy+delete when NTFS blocks rename
-- **Worktree identity fix** — stable project hash across worktrees and main repo
-- **Crash recovery guidance** — actionable next-step messages based on what was interrupted
-- **UAT verdict gating** — non-PASS verdicts now block slice progression instead of being ignored
+## What's New in v2.33
+
+- **Dispatch loop hardening** — defensive guards, reentrancy protection, and 125 new regression tests covering the full `deriveState → resolveDispatch` chain without an LLM
+- **Live regression test harness** — post-build pipeline validation that catches dispatch, parser, and lock lifecycle regressions before promotion
+- **Unified error handling** — `getErrorMessage()` helper replaces 65 inline duplicates across the codebase
+- **Centralized unit ID parsing** — `parseUnitId()` eliminates fragile regex patterns scattered across dispatch, recovery, and metrics code
+- **Milestone merge consolidation** — `tryMergeMilestone()` replaces 4 duplicate merge paths in the auto-mode loop
+- **Lock alignment fix** — retry lock path now matches primary lock settings, preventing `ECOMPROMISED` errors on resume
+- **NixOS/nix-darwin support** — symlinks in `.gsd/` are skipped during `makeTreeWritable` to prevent `EPERM` failures
+- **Windows EPERM fallback** — `.gsd/` migration uses copy+delete when NTFS blocks direct rename
+- **Worktree identity fix** — stable project hash resolved from main repo root, not worktree path
+- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back to the original branch after completion
+- **Crash recovery guidance** — actionable next-step messages based on what was interrupted and what state survived
 
 See the full [Changelog](./CHANGELOG.md) for details.
 

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

@@ -1,5 +1,5 @@
 /**
- * Auto-mode Supervisor — SIGTERM handling and working-tree activity detection.
+ * Auto-mode Supervisor — signal handling and working-tree activity detection.
  *
  * Pure functions — no module-level globals or AutoContext dependency.
  */
@@ -8,10 +8,10 @@ import { clearLock } from "./crash-recovery.js";
 import { releaseSessionLock } from "./session-lock.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
 
-// ─── SIGTERM Handling ─────────────────────────────────────────────────────────
+// ─── Signal Handling ──────────────────────────────────────────────────────────
 
 /**
- * Register a SIGTERM handler that clears the lock file and exits cleanly.
+ * Register SIGTERM and SIGINT handlers that clear lock files and exit cleanly.
  * Captures the active base path at registration time so the handler
  * always references the correct path even if the module variable changes.
  * Removes any previously registered handler before installing the new one.
@@ -22,20 +22,25 @@ export function registerSigtermHandler(
   currentBasePath: string,
   previousHandler: (() => void) | null,
 ): () => void {
-  if (previousHandler) process.off("SIGTERM", previousHandler);
+  if (previousHandler) {
+    process.off("SIGTERM", previousHandler);
+    process.off("SIGINT", previousHandler);
+  }
   const handler = () => {
     releaseSessionLock(currentBasePath);
     clearLock(currentBasePath);
     process.exit(0);
   };
   process.on("SIGTERM", handler);
+  process.on("SIGINT", handler);
   return handler;
 }
 
-/** Deregister the SIGTERM handler (called on stop/pause). */
+/** Deregister signal handlers (called on stop/pause). */
 export function deregisterSigtermHandler(handler: (() => void) | null): void {
   if (handler) {
     process.off("SIGTERM", handler);
+    process.off("SIGINT", handler);
   }
 }
 

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

@@ -6,7 +6,7 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync, readdirSync, cpSync, lstatSync as lstatSyncFn } from "node:fs";
 import { isAbsolute, join, sep } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { execSync, execFileSync } from "node:child_process";
@@ -45,6 +45,122 @@ import { getErrorMessage } from "./error-utils.js";
 /** Original project root before chdir into auto-worktree. */
 let originalBase: string | null = null;
 
+// ─── Worktree ↔ Main Repo Sync (#1311) ──────────────────────────────────────
+
+/**
+ * Sync .gsd/ state from the main repo into the worktree.
+ *
+ * When .gsd/ is a symlink to the external state directory, both the main
+ * repo and worktree share the same directory — no sync needed.
+ *
+ * When .gsd/ is a real directory (e.g., git-tracked or manage_gitignore:false),
+ * the worktree has its own copy that may be stale. This function copies
+ * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
+ * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
+ *
+ * Only adds missing content — never overwrites existing files in the worktree
+ * (the worktree's execution state is authoritative for in-progress work).
+ */
+export function syncGsdStateToWorktree(mainBasePath: string, worktreePath_: string): { synced: string[] } {
+  const mainGsd = gsdRoot(mainBasePath);
+  const wtGsd = gsdRoot(worktreePath_);
+  const synced: string[] = [];
+
+  // If both resolve to the same directory (symlink), no sync needed
+  try {
+    const mainResolved = realpathSync(mainGsd);
+    const wtResolved = realpathSync(wtGsd);
+    if (mainResolved === wtResolved) return { synced };
+  } catch {
+    // Can't resolve — proceed with sync as a safety measure
+  }
+
+  if (!existsSync(mainGsd) || !existsSync(wtGsd)) return { synced };
+
+  // Sync root-level .gsd/ files (DECISIONS, REQUIREMENTS, PROJECT, KNOWLEDGE)
+  const rootFiles = ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md", "OVERRIDES.md"];
+  for (const f of rootFiles) {
+    const src = join(mainGsd, f);
+    const dst = join(wtGsd, f);
+    if (existsSync(src) && !existsSync(dst)) {
+      try {
+        cpSync(src, dst);
+        synced.push(f);
+      } catch { /* non-fatal */ }
+    }
+  }
+
+  // Sync milestones: copy entire milestone directories that are missing
+  const mainMilestonesDir = join(mainGsd, "milestones");
+  const wtMilestonesDir = join(wtGsd, "milestones");
+  if (existsSync(mainMilestonesDir) && existsSync(wtMilestonesDir)) {
+    try {
+      const mainMilestones = readdirSync(mainMilestonesDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && /^M\d{3}/.test(d.name))
+        .map(d => d.name);
+
+      for (const mid of mainMilestones) {
+        const srcDir = join(mainMilestonesDir, mid);
+        const dstDir = join(wtMilestonesDir, mid);
+
+        if (!existsSync(dstDir)) {
+          // Entire milestone missing from worktree — copy it
+          try {
+            cpSync(srcDir, dstDir, { recursive: true });
+            synced.push(`milestones/${mid}/`);
+          } catch { /* non-fatal */ }
+        } else {
+          // Milestone directory exists but may be missing files (stale snapshot).
+          // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
+          try {
+            const srcFiles = readdirSync(srcDir).filter(f => f.endsWith(".md") || f.endsWith(".json"));
+            for (const f of srcFiles) {
+              const srcFile = join(srcDir, f);
+              const dstFile = join(dstDir, f);
+              if (!existsSync(dstFile)) {
+                try {
+                  const srcStat = lstatSyncFn(srcFile);
+                  if (srcStat.isFile()) {
+                    cpSync(srcFile, dstFile);
+                    synced.push(`milestones/${mid}/${f}`);
+                  }
+                } catch { /* non-fatal */ }
+              }
+            }
+
+            // Sync slices directory if it exists in main but not in worktree
+            const srcSlicesDir = join(srcDir, "slices");
+            const dstSlicesDir = join(dstDir, "slices");
+            if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
+              try {
+                cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+                synced.push(`milestones/${mid}/slices/`);
+              } catch { /* non-fatal */ }
+            } else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
+              // Both exist — sync missing slice directories
+              const srcSlices = readdirSync(srcSlicesDir, { withFileTypes: true })
+                .filter(d => d.isDirectory())
+                .map(d => d.name);
+              for (const sid of srcSlices) {
+                const srcSlice = join(srcSlicesDir, sid);
+                const dstSlice = join(dstSlicesDir, sid);
+                if (!existsSync(dstSlice)) {
+                  try {
+                    cpSync(srcSlice, dstSlice, { recursive: true });
+                    synced.push(`milestones/${mid}/slices/${sid}/`);
+                  } catch { /* non-fatal */ }
+                }
+              }
+            }
+          } catch { /* non-fatal */ }
+        }
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  return { synced };
+}
+
 // ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
 
 /**
@@ -125,6 +241,12 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
   // Ensure worktree shares external state via symlink
   ensureGsdSymlink(info.path);
 
+  // Sync .gsd/ state from main repo into the worktree (#1311).
+  // Even with the symlink, the worktree may have stale git-tracked files
+  // if .gsd/ is not gitignored. And on fresh create, the milestone files
+  // created on main since the branch point won't be in the worktree.
+  syncGsdStateToWorktree(basePath, info.path);
+
   // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets
   const hookError = runWorktreePostCreateHook(basePath, info.path);
   if (hookError) {
@@ -267,6 +389,18 @@ export function enterAutoWorktree(basePath: string, milestoneId: string): string
     throw new GSDError(GSD_IO_ERROR, `Auto-worktree path ${p} exists but .git is unreadable`);
   }
 
+  // Ensure worktree shares external state via symlink (#1311).
+  // On resume (enterAutoWorktree), the symlink may be missing if it was
+  // created before ensureGsdSymlink existed, or the .gsd/ directory may be
+  // a stale git-tracked copy instead of a symlink. Refreshing here ensures
+  // the worktree sees the same milestone state as the main repo.
+  ensureGsdSymlink(p);
+
+  // Sync .gsd/ state from main repo into worktree (#1311).
+  // Covers the case where .gsd/ is a real directory (not symlinked) and
+  // milestones were created on main after the worktree was last used.
+  syncGsdStateToWorktree(basePath, p);
+
   const previousCwd = process.cwd();
 
   try {

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/git-service.ts

@@ -336,13 +336,17 @@ export class GitServiceImpl {
    * @param extraExclusions Additional pathspec exclusions beyond RUNTIME_EXCLUSION_PATHS.
    */
   private smartStage(extraExclusions: readonly string[] = []): void {
-    // Always exclude .gsd/ — state is managed externally (symlinked to ~/.gsd/projects/<hash>/)
-    const allExclusions = [".gsd/", ...extraExclusions];
-
     // One-time cleanup: if runtime files are already tracked in the index
     // (from older versions where the fallback bug staged them), untrack them
     // in a dedicated commit. This must happen as a separate commit because
     // the git reset HEAD step below would otherwise undo the rm --cached.
+    //
+    // SAFETY: Only untrack the specific RUNTIME paths (activity/, runtime/,
+    // auto.lock, etc.) — NOT all of .gsd/. If .gsd/milestones/ files were
+    // previously tracked, they stay tracked until the milestone completes
+    // and the worktree is torn down. This prevents a mid-execution behavioral
+    // discontinuity where the first half of a milestone has .gsd/ artifacts
+    // committed but the second half doesn't (#1326).
     if (!this._runtimeFilesCleanedUp) {
       let cleaned = false;
       for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
@@ -357,17 +361,19 @@ export class GitServiceImpl {
 
     // Stage everything, then unstage excluded paths.
     //
-    // Previous approach used pathspec excludes (:(exclude)...) with git add -A,
-    // but that fails when .gsd/ is in .gitignore — git exits non-zero before
-    // evaluating the excludes. The catch fallback ran plain `git add -A`,
-    // staging all tracked runtime files unconditionally and defeating the
-    // exclusion list entirely.
+    // Exclude only RUNTIME paths from staging — not the entire .gsd/ directory.
+    // When .gsd/milestones/ files are already tracked in the index (projects
+    // where .gsd/ is not gitignored, or Windows junctions that git sees as
+    // real directories), they should continue to be committed. Excluding the
+    // entire .gsd/ directory mid-milestone causes silent commit failure where
+    // the second half of a milestone's artifacts are never committed (#1326).
     //
-    // git reset HEAD silently succeeds when the path isn't staged, so no
-    // error handling is needed per-path.
+    // If .gsd/ IS in .gitignore (the default for external state projects),
+    // git add -A already skips it and the reset is a harmless no-op.
     nativeAddAll(this.basePath);
 
-    for (const exclusion of allExclusions) {
+    const runtimeExclusions = [...RUNTIME_EXCLUSION_PATHS, ...extraExclusions];
+    for (const exclusion of runtimeExclusions) {
       try { nativeResetPaths(this.basePath, [exclusion]); } catch { /* path not staged — ignore */ }
     }
   }

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

@@ -223,11 +223,22 @@ export default function (pi: ExtensionAPI) {
   // chance to persist state and pause instead of crashing (see issue #739).
   if (!process.listeners("uncaughtException").some(l => l.name === "_gsdEpipeGuard")) {
     const _gsdEpipeGuard = (err: Error): void => {
-      if ((err as NodeJS.ErrnoException).code === "EPIPE") {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "EPIPE") {
         // Pipe closed — nothing we can write; just exit cleanly
         process.exit(0);
       }
-      // Re-throw anything that isn't EPIPE so real crashes still surface
+      // ECOMPROMISED: proper-lockfile's update timer detected mtime drift (system
+      // sleep, heavy event loop stall, or filesystem precision mismatch on Node.js
+      // v25+). The onCompromised callback already set _lockCompromised = true, but
+      // due to a subtle interaction between the synchronous fs adapter and the
+      // setTimeout boundary, the error can still propagate here as an uncaught
+      // exception. Exit cleanly so the process.once("exit") handler removes the
+      // lock directory — allowing the next session to acquire cleanly (#1322).
+      if (code === "ECOMPROMISED") {
+        process.exit(1);
+      }
+      // Re-throw anything that isn't EPIPE or ECOMPROMISED so real crashes still surface
       throw err;
     };
     process.on("uncaughtException", _gsdEpipeGuard);

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;