gsd-pi 2.28.0-dev.e19bf89 → 2.29.0-dev.2ccf3fb

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

@@ -35,6 +35,7 @@ import {
 import { writeUnitRuntimeRecord, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences } from "./preferences.js";
 import { runGSDDoctor, rebuildState, summarizeDoctorIssues } from "./doctor.js";
+import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
 import { recordHealthSnapshot, checkHealEscalation } from "./doctor-proactive.js";
 import { syncStateToProjectRoot } from "./auto-worktree-sync.js";
 import { resetRewriteCircuitBreaker } from "./auto-dispatch.js";
@@ -154,13 +155,17 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
         ctx.ui.notify(`Post-hook: applied ${report.fixesApplied.length} fix(es).`, "info");
       }
 
-      // Proactive health tracking
-      const summary = summarizeDoctorIssues(report.issues);
+      // Proactive health tracking — exclude completion-transition codes at task level
+      // since they are expected after the last task and resolved by complete-slice
+      const issuesForHealth = effectiveFixLevel === "task"
+        ? report.issues.filter(i => !COMPLETION_TRANSITION_CODES.has(i.code))
+        : report.issues;
+      const summary = summarizeDoctorIssues(issuesForHealth);
       recordHealthSnapshot(summary.errors, summary.warnings, report.fixesApplied.length);
 
       // Check if we should escalate to LLM-assisted heal
       if (summary.errors > 0) {
-        const unresolvedErrors = report.issues
+        const unresolvedErrors = issuesForHealth
           .filter(i => i.severity === "error" && !i.fixable)
           .map(i => ({ code: i.code, message: i.message, unitId: i.unitId }));
         const escalation = checkHealEscalation(summary.errors, unresolvedErrors);
@@ -171,7 +176,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
           );
           try {
             const { formatDoctorIssuesForPrompt, formatDoctorReport } = await import("./doctor.js");
-            const { dispatchDoctorHeal } = await import("./commands.js");
+            const { dispatchDoctorHeal } = await import("./commands-handlers.js");
             const actionable = report.issues.filter(i => i.severity === "error");
             const reportText = formatDoctorReport(report, { scope: doctorScope, includeWarnings: true });
             const structuredIssues = formatDoctorIssuesForPrompt(actionable);
@@ -197,10 +202,13 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
       }
     }
 
-    // Prune dead bg-shell processes
+    // Prune dead bg-shell processes and kill non-persistent live ones.
+    // Without killing live processes between units, dev servers spawned during
+    // one task keep ports bound, causing conflicts in subsequent tasks (#1209).
     try {
-      const { pruneDeadProcesses } = await import("../bg-shell/process-manager.js");
+      const { pruneDeadProcesses, killSessionProcesses } = await import("../bg-shell/process-manager.js");
       pruneDeadProcesses();
+      killSessionProcesses();
     } catch {
       // Non-fatal
     }

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

@@ -36,8 +36,10 @@ import {
   clearPathCache,
   resolveGsdRootFile,
 } from "./paths.js";
+import { isValidationTerminal } from "./state.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
+import { loadJsonFileOrNull } from "./json-persistence.js";
 import { dirname, join } from "node:path";
 
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
@@ -137,6 +139,21 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   if (!absPath) return false;
   if (!existsSync(absPath)) return false;
 
+  // validate-milestone must have a VALIDATION file with a terminal verdict
+  // (pass, needs-attention, or needs-remediation). Without this check, a
+  // VALIDATION file with missing/malformed frontmatter or an unrecognized
+  // verdict is treated as "complete" by the artifact check but deriveState
+  // still returns phase:"validating-milestone" (because isValidationTerminal
+  // returns false), creating an infinite skip loop that hits the lifetime cap.
+  if (unitType === "validate-milestone") {
+    try {
+      const validationContent = readFileSync(absPath, "utf-8");
+      if (!isValidationTerminal(validationContent)) return false;
+    } catch {
+      return false;
+    }
+  }
+
   // plan-slice must produce a plan with actual task entries, not just a scaffold.
   // The plan file may exist from a prior discussion/context step with only headings
   // but no tasks. Without this check the artifact is considered "complete" and the
@@ -211,7 +228,7 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
         try {
           const roadmapContent = readFileSync(roadmapFile, "utf-8");
           const roadmap = parseRoadmap(roadmapContent);
-          const slice = roadmap.slices.find(s => s.id === sid);
+          const slice = (roadmap.slices ?? []).find(s => s.id === sid);
           if (slice && !slice.done) return false;
         } catch {
           // Corrupt/unparseable roadmap — fail verification so the unit
@@ -338,6 +355,10 @@ export function skipExecuteTask(
 
 // ─── Disk-backed completed-unit helpers ───────────────────────────────────────
 
+function isStringArray(data: unknown): data is string[] {
+  return Array.isArray(data) && data.every(item => typeof item === "string");
+}
+
 /** Path to the persisted completed-unit keys file. */
 export function completedKeysPath(base: string): string {
   return join(base, ".gsd", "completed-units.json");
@@ -346,12 +367,7 @@ export function completedKeysPath(base: string): string {
 /** Write a completed unit key to disk (read-modify-write append to set). */
 export function persistCompletedKey(base: string, key: string): void {
   const file = completedKeysPath(base);
-  let keys: string[] = [];
-  try {
-    if (existsSync(file)) {
-      keys = JSON.parse(readFileSync(file, "utf-8"));
-    }
-  } catch (e) { /* corrupt file — start fresh */ void e; }
+  const keys = loadJsonFileOrNull(file, isStringArray) ?? [];
   const keySet = new Set(keys);
   if (!keySet.has(key)) {
     keys.push(key);
@@ -362,27 +378,21 @@ export function persistCompletedKey(base: string, key: string): void {
 /** Remove a stale completed unit key from disk. */
 export function removePersistedKey(base: string, key: string): void {
   const file = completedKeysPath(base);
-  try {
-    if (existsSync(file)) {
-      const keys: string[] = JSON.parse(readFileSync(file, "utf-8"));
-      const filtered = keys.filter(k => k !== key);
-      // Only write if the key was actually present
-      if (filtered.length !== keys.length) {
-        atomicWriteSync(file, JSON.stringify(filtered));
-      }
-    }
-  } catch (e) { /* non-fatal: removePersistedKey failure */ void e; }
+  const keys = loadJsonFileOrNull(file, isStringArray);
+  if (!keys) return;
+  const filtered = keys.filter(k => k !== key);
+  if (filtered.length !== keys.length) {
+    atomicWriteSync(file, JSON.stringify(filtered));
+  }
 }
 
 /** Load all completed unit keys from disk into the in-memory set. */
 export function loadPersistedKeys(base: string, target: Set<string>): void {
   const file = completedKeysPath(base);
-  try {
-    if (existsSync(file)) {
-      const keys: string[] = JSON.parse(readFileSync(file, "utf-8"));
-      for (const k of keys) target.add(k);
-    }
-  } catch (e) { /* non-fatal: loadPersistedKeys failure */ void e; }
+  const keys = loadJsonFileOrNull(file, isStringArray);
+  if (keys) {
+    for (const k of keys) target.add(k);
+  }
 }
 
 // ─── Merge State Reconciliation ───────────────────────────────────────────────

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

@@ -26,6 +26,13 @@ import {
 import { invalidateAllCaches } from "./cache.js";
 import { synthesizeCrashRecovery } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, formatCrashInfo, isLockProcessAlive } from "./crash-recovery.js";
+import {
+  acquireSessionLock,
+  updateSessionLock,
+  releaseSessionLock,
+  readSessionLockData,
+  isSessionLockProcessAlive,
+} from "./session-lock.js";
 import { selfHealRuntimeRecords } from "./auto-recovery.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
@@ -81,6 +88,18 @@ export async function bootstrapAutoSession(
 ): Promise<boolean> {
   const { shouldUseWorktreeIsolation, registerSigtermHandler, lockBase } = deps;
 
+  // ── Session lock: acquire FIRST, before any state mutation ──────────────
+  // This is the primary guard against concurrent sessions on the same project.
+  // Uses OS-level file locking (proper-lockfile) to prevent TOCTOU races.
+  const lockResult = acquireSessionLock(base);
+  if (!lockResult.acquired) {
+    ctx.ui.notify(
+      `${lockResult.reason}\nStop it with \`kill ${lockResult.existingPid ?? "the other process"}\` before starting a new session.`,
+      "error",
+    );
+    return false;
+  }
+
   // Ensure git repo exists
   if (!nativeIsRepo(base)) {
     const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
@@ -109,16 +128,11 @@ export async function bootstrapAutoSession(
   // Initialize GitServiceImpl
   s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
 
-  // Check for crash from previous session
+  // Check for crash from previous session (use both old and new lock data)
   const crashLock = readCrashLock(base);
   if (crashLock) {
-    if (isLockProcessAlive(crashLock)) {
-      ctx.ui.notify(
-        `Another auto-mode session (PID ${crashLock.pid}) appears to be running.\nStop it with \`kill ${crashLock.pid}\` before starting a new session.`,
-        "error",
-      );
-      return false;
-    }
+    // We already hold the session lock, so no concurrent session is running.
+    // The crash lock is from a dead process — recover context from it.
     const recoveredMid = crashLock.unitId.split("/")[0];
     const milestoneAlreadyComplete = recoveredMid
       ? !!resolveMilestoneFile(base, recoveredMid, "SUMMARY")
@@ -401,13 +415,14 @@ export async function bootstrapAutoSession(
   ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
   ctx.ui.setFooter(hideFooter);
   const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
-  const pendingCount = state.registry.filter(m => m.status !== 'complete' && m.status !== 'parked').length;
+  const pendingCount = (state.registry ?? []).filter(m => m.status !== 'complete' && m.status !== 'parked').length;
   const scopeMsg = pendingCount > 1
     ? `Will loop through ${pendingCount} milestones.`
     : "Will loop until milestone complete.";
   ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
 
-  // Write initial lock file
+  // Update lock file with milestone info (OS lock already acquired at bootstrap start)
+  updateSessionLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown", 0);
   writeLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown", 0);
 
   // Secrets collection gate — pause instead of blocking (#1146)

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

@@ -105,19 +105,39 @@ export async function runPostUnitVerification(
     const completionKey = `${s.currentUnit.type}/${s.currentUnit.id}`;
 
     if (result.checks.length > 0) {
-      const passCount = result.checks.filter(c => c.exitCode === 0).length;
-      const total = result.checks.length;
+      const blockingChecks = result.checks.filter(c => c.blocking);
+      const advisoryChecks = result.checks.filter(c => !c.blocking);
+      const blockingPassCount = blockingChecks.filter(c => c.exitCode === 0).length;
+      const advisoryFailCount = advisoryChecks.filter(c => c.exitCode !== 0).length;
+
       if (result.passed) {
-        ctx.ui.notify(`Verification gate: ${passCount}/${total} checks passed`);
+        let msg = blockingChecks.length > 0
+          ? `Verification gate: ${blockingPassCount}/${blockingChecks.length} blocking checks passed`
+          : `Verification gate: passed (no blocking checks)`;
+        if (advisoryFailCount > 0) {
+          msg += ` (${advisoryFailCount} advisory warning${advisoryFailCount > 1 ? "s" : ""})`;
+        }
+        ctx.ui.notify(msg);
+        // Log advisory warnings to stderr for visibility
+        if (advisoryFailCount > 0) {
+          const advisoryFailures = advisoryChecks.filter(c => c.exitCode !== 0);
+          process.stderr.write(`verification-gate: ${advisoryFailCount} advisory (non-blocking) failure(s)\n`);
+          for (const f of advisoryFailures) {
+            process.stderr.write(`  [advisory] ${f.command} exited ${f.exitCode}\n`);
+          }
+        }
       } else {
-        const failures = result.checks.filter(c => c.exitCode !== 0);
-        const failNames = failures.map(f => f.command).join(", ");
+        const blockingFailures = blockingChecks.filter(c => c.exitCode !== 0);
+        const failNames = blockingFailures.map(f => f.command).join(", ");
         ctx.ui.notify(`Verification gate: FAILED — ${failNames}`);
-        process.stderr.write(`verification-gate: ${total - passCount}/${total} checks failed\n`);
-        for (const f of failures) {
+        process.stderr.write(`verification-gate: ${blockingFailures.length}/${blockingChecks.length} blocking checks failed\n`);
+        for (const f of blockingFailures) {
           process.stderr.write(`  ${f.command} exited ${f.exitCode}\n`);
           if (f.stderr) process.stderr.write(`  stderr: ${f.stderr.slice(0, 500)}\n`);
         }
+        if (advisoryFailCount > 0) {
+          process.stderr.write(`verification-gate: ${advisoryFailCount} additional advisory (non-blocking) failure(s)\n`);
+        }
       }
     }
 
@@ -155,6 +175,20 @@ export async function runPostUnitVerification(
       s.verificationRetryCount.delete(s.currentUnit.id);
       s.pendingVerificationRetry = null;
       return "continue";
+    } else if (result.discoverySource === "package-json") {
+      // Auto-discovered checks from package.json may fail on pre-existing errors
+      // that the current task didn't introduce. Don't trigger the retry loop —
+      // log a warning and let the task proceed (#1186).
+      process.stderr.write(
+        `verification-gate: auto-discovered checks failed (source: package-json) — treating as advisory, not blocking\n`,
+      );
+      ctx.ui.notify(
+        `Verification: auto-discovered checks failed (pre-existing errors likely). Continuing without retry.`,
+        "warning",
+      );
+      s.verificationRetryCount.delete(s.currentUnit.id);
+      s.pendingVerificationRetry = null;
+      return "continue";
     } else if (autoFixEnabled && attempt + 1 <= maxRetries) {
       const nextAttempt = attempt + 1;
       s.verificationRetryCount.set(s.currentUnit.id, nextAttempt);

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

@@ -11,6 +11,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, cpSync, unlinkSync, readdirSync } from "node:fs";
+import { loadJsonFileOrNull } from "./json-persistence.js";
 import { join, sep as pathSep } from "node:path";
 import { homedir } from "node:os";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
@@ -36,6 +37,12 @@ export function syncProjectRootToWorktree(projectRoot: string, worktreePath: str
   // has newer artifacts (e.g. slices that don't exist in the worktree yet)
   safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId))
 
+  // Copy living documents from project root to worktree so agents have the
+  // latest decisions, requirements, project state, and knowledge.
+  for (const doc of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md"]) {
+    safeCopy(join(prGsd, doc), join(wtGsd, doc), { force: true });
+  }
+
   // 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 {
@@ -89,6 +96,14 @@ export function syncStateToProjectRoot(worktreePath: string, projectRoot: string
   // 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 })
+
+  // 5. Living documents — decisions, requirements, project description, knowledge.
+  // Agents update these during slice execution. Without syncing, a new session
+  // reads stale copies from the project root, losing architectural decisions,
+  // requirement status updates, and accumulated knowledge (#1168).
+  for (const doc of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md"]) {
+    safeCopy(join(wtGsd, doc), join(prGsd, doc), { force: true });
+  }
 }
 
 // ─── Resource Staleness ───────────────────────────────────────────────────
@@ -98,15 +113,15 @@ export function syncStateToProjectRoot(worktreePath: string, projectRoot: string
  * Uses gsdVersion instead of syncedAt so that launching a second session
  * doesn't falsely trigger staleness (#804).
  */
+function isManifestWithVersion(data: unknown): data is { gsdVersion: string } {
+  return data !== null && typeof data === "object" && "gsdVersion" in data! && typeof (data as Record<string, unknown>).gsdVersion === "string";
+}
+
 export function readResourceVersion(): string | null {
   const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "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;
-  }
+  const manifest = loadJsonFileOrNull(manifestPath, isManifestWithVersion);
+  return manifest?.gsdVersion ?? null;
 }
 
 /**

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

@@ -22,7 +22,6 @@ import { loadFile, getManifestStatus, resolveAllOverrides, parsePlan, parseSumma
 import { loadPrompt } from "./prompt-loader.js";
 import { runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
-export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
@@ -33,6 +32,12 @@ import { invalidateAllCaches } from "./cache.js";
 import { saveActivityLog, clearActivityLogState } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, formatCrashInfo, isLockProcessAlive } from "./crash-recovery.js";
+import {
+  acquireSessionLock,
+  validateSessionLock,
+  releaseSessionLock,
+  updateSessionLock,
+} from "./session-lock.js";
 import {
   clearUnitRuntimeRecord,
   inspectExecuteTaskDurability,
@@ -186,12 +191,6 @@ import {
   NEW_SESSION_TIMEOUT_MS, DISPATCH_HANG_TIMEOUT_MS,
 } from "./auto/session.js";
 import type { CompletedUnit, CurrentUnit, UnitRouting, StartModel, PendingVerificationRetry } from "./auto/session.js";
-export {
-  MAX_UNIT_DISPATCHES, STUB_RECOVERY_THRESHOLD, MAX_LIFETIME_DISPATCHES,
-  MAX_CONSECUTIVE_SKIPS, DISPATCH_GAP_TIMEOUT_MS, MAX_SKIP_DEPTH,
-  NEW_SESSION_TIMEOUT_MS, DISPATCH_HANG_TIMEOUT_MS,
-} from "./auto/session.js";
-export type { CompletedUnit, CurrentUnit, UnitRouting, StartModel } from "./auto/session.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -262,8 +261,6 @@ export function shouldUseWorktreeIsolation(): boolean {
  * 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).
  */
-// Re-export budget utilities for external consumers
-export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction } from "./auto-budget.js";
 
 /** Wrapper: register SIGTERM handler and store reference. */
 function registerSigtermHandler(currentBasePath: string): void {
@@ -276,8 +273,6 @@ function deregisterSigtermHandler(): void {
   s.sigtermHandler = null;
 }
 
-export { type AutoDashboardData } from "./auto-dashboard.js";
-
 export function getAutoDashboardData(): AutoDashboardData {
   const ledger = getLedger();
   const totals = ledger ? getProjectTotals(ledger.units) : null;
@@ -451,7 +446,10 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   if (!s.active && !s.paused) return;
   const reasonSuffix = reason ? ` — ${reason}` : "";
   clearUnitTimeout();
-  if (lockBase()) clearLock(lockBase());
+  if (lockBase()) {
+    releaseSessionLock(lockBase());
+    clearLock(lockBase());
+  }
   clearSkillSnapshot();
   resetSkillTelemetry();
   s.dispatching = false;
@@ -565,7 +563,10 @@ export async function pauseAuto(ctx?: ExtensionContext, _pi?: ExtensionAPI): Pro
 
   s.pausedSessionFile = ctx?.sessionManager?.getSessionFile() ?? null;
 
-  if (lockBase()) clearLock(lockBase());
+  if (lockBase()) {
+    releaseSessionLock(lockBase());
+    clearLock(lockBase());
+  }
 
   deregisterSigtermHandler();
 
@@ -598,6 +599,16 @@ export async function startAuto(
 
   // If resuming from paused state, just re-activate and dispatch next unit.
   if (s.paused) {
+    // Re-acquire session lock before resuming
+    const resumeLock = acquireSessionLock(base);
+    if (!resumeLock.acquired) {
+      ctx.ui.notify(
+        `Cannot resume: ${resumeLock.reason}`,
+        "error",
+      );
+      return;
+    }
+
     s.paused = false;
     s.active = true;
     s.verbose = verboseMode;
@@ -699,6 +710,7 @@ export async function startAuto(
       s.pausedForSecrets = false;
     }
 
+    updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
     writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
 
     await dispatchNextUnit(ctx, pi);
@@ -854,7 +866,7 @@ async function showStepWizard(
     : "previous unit";
 
   if (!mid || state.phase === "complete") {
-    const incomplete = state.registry.filter(m => m.status !== "complete" && m.status !== "parked");
+    const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
     if (incomplete.length > 0 && state.phase !== "complete" && state.phase !== "blocked" && state.phase !== "pre-planning") {
       const ids = incomplete.map(m => m.id).join(", ");
       const diag = `basePath=${s.basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
@@ -911,8 +923,6 @@ async function showStepWizard(
   }
 }
 
-// describeNextUnit is imported from auto-dashboard.ts and re-exported
-export { describeNextUnit } from "./auto-dashboard.js";
 
 /** Thin wrapper: delegates to auto-dashboard.ts, passing state accessors. */
 function updateProgressWidget(
@@ -950,6 +960,24 @@ async function dispatchNextUnit(
     return;
   }
 
+  // ── Session lock validation: detect if another process has taken over ──
+  if (lockBase() && !validateSessionLock(lockBase())) {
+    debugLog("dispatchNextUnit session-lock-lost — another process may have taken over");
+    ctx.ui.notify(
+      "Session lock lost — another GSD process appears to have taken over. Stopping gracefully.",
+      "error",
+    );
+    // Don't call stopAuto here to avoid releasing the lock we don't own
+    s.active = false;
+    s.paused = false;
+    clearUnitTimeout();
+    deregisterSigtermHandler();
+    ctx.ui.setStatus("gsd-auto", undefined);
+    ctx.ui.setWidget("gsd-progress", undefined);
+    ctx.ui.setFooter(undefined);
+    return;
+  }
+
   // Reentrancy guard
   if (s.dispatching && s.skipDepth === 0) {
     debugLog("dispatchNextUnit reentrancy guard — another dispatch in progress, bailing");
@@ -1130,7 +1158,7 @@ async function dispatchNextUnit(
       }
     }
 
-    const pendingIds = state.registry
+    const pendingIds = (state.registry ?? [])
       .filter(m => m.status !== "complete")
       .map(m => m.id);
     pruneQueueOrder(s.basePath, pendingIds);
@@ -1145,7 +1173,7 @@ async function dispatchNextUnit(
       await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
     }
 
-    const incomplete = state.registry.filter(m => m.status !== "complete" && m.status !== "parked");
+    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) {
@@ -1171,7 +1199,7 @@ async function dispatchNextUnit(
             try { process.chdir(s.basePath); } catch { /* best-effort */ }
           }
         }
-      } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() !== "none") {
+      } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() === "branch") {
         try {
           const currentBranch = getCurrentBranch(s.basePath);
           const milestoneBranch = autoWorktreeBranch(s.currentMilestoneId);
@@ -1273,7 +1301,7 @@ async function dispatchNextUnit(
           try { process.chdir(s.basePath); } catch { /* best-effort */ }
         }
       }
-    } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() !== "none") {
+    } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() === "branch") {
       try {
         const currentBranch = getCurrentBranch(s.basePath);
         const milestoneBranch = autoWorktreeBranch(s.currentMilestoneId);
@@ -1398,6 +1426,23 @@ async function dispatchNextUnit(
 
   await runSecretsGate();
 
+  // ── Interactive discussion gate ──
+  // If the active milestone needs discussion (has CONTEXT-DRAFT.md but no roadmap),
+  // stop auto-mode and route to the interactive discussion flow. The guided-flow
+  // handles needs-discussion correctly — it just needs to be called instead of
+  // letting the dispatch table fire "needs-discussion → stop" (#1170).
+  if (state.phase === "needs-discussion") {
+    if (s.currentUnit) {
+      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+    }
+    const cmdCtx = s.cmdCtx!;
+    const basePath = s.basePath;
+    await stopAuto(ctx, pi, `${mid}: ${midTitle} needs discussion before planning.`);
+    const { showSmartEntry } = await import("./guided-flow.js");
+    await showSmartEntry(cmdCtx, pi, basePath);
+    return;
+  }
+
   // ── Dispatch table ──
   const dispatchResult = await resolveDispatch({ basePath: s.basePath, mid, midTitle: midTitle!, state, prefs,
   });
@@ -1583,6 +1628,7 @@ async function dispatchNextUnit(
   }
 
   const sessionFile = ctx.sessionManager.getSessionFile();
+  updateSessionLock(lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
   writeLock(lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
 
   // Prompt injection
@@ -1809,6 +1855,7 @@ export async function dispatchHookUnit(
   }
 
   const sessionFile = ctx.sessionManager.getSessionFile();
+  updateSessionLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
   writeLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
 
   clearUnitTimeout();
@@ -1845,5 +1892,3 @@ export async function dispatchHookUnit(
 }
 
 
-// Direct phase dispatch → auto-direct-dispatch.ts
-export { dispatchDirectPhase } from "./auto-direct-dispatch.js";

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

@@ -18,19 +18,11 @@ import {
   selectDoctorScope,
   filterDoctorIssues,
 } from "./doctor.js";
-import { loadPrompt } from "./prompt-loader.js";
 import { isAutoActive } from "./auto.js";
-import { resolveProjectRoot } from "./worktree.js";
-import { assertSafeDirectory } from "./validate-directory.js";
-
-/** Resolve the effective project root, accounting for worktree paths. */
-function projectRoot(): string {
-  const root = resolveProjectRoot(process.cwd());
-  assertSafeDirectory(root);
-  return root;
-}
+import { projectRoot } from "./commands.js";
+import { loadPrompt } from "./prompt-loader.js";
 
-function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
+export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {