gsd-pi 2.80.0-dev.2848d9009 → 2.80.0-dev.3065f7bfa

package/README.md

@@ -259,6 +259,7 @@ Full documentation is in the [`docs/`](./docs/) directory:
 
 - **[Architecture](./docs/dev/architecture.md)** — system design and dispatch pipeline
 - **[CI/CD Pipeline](./docs/dev/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)
+- **[E2E Testing](./tests/e2e/README.md)** — real-process CLI/runtime coverage and CI runner expectations
 - **[Pipeline Simplification (ADR-003)](./docs/dev/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion
 - **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
 
@@ -361,7 +362,7 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
 
-3. **Context Mode** — Context Mode is enabled by default and gives every auto-mode unit guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; full stdout/stderr is saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads `.gsd/last-snapshot.md` after compaction or resume. Opt out with `context_mode.enabled: false`; tune sandbox timeout/output caps with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, and `context_mode.exec_digest_chars`.
+3. **Context Mode** — Context Mode is enabled by default and gives eligible auto-mode units guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; capped stdout/stderr and metadata are saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads a prior compaction snapshot from `.gsd/last-snapshot.md` when one exists. Opt out with `context_mode.enabled: false` to disable Context Mode guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume`; tune sandbox timeout/output caps and environment forwarding with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, `context_mode.exec_digest_chars`, and `context_mode.exec_env_allowlist`.
 
 4. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.
 
@@ -659,10 +660,11 @@ auto_report: true
 | `unique_milestone_ids`            | Uses unique milestone names to avoid clashes when working in teams of people                          |
 | `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |
 | `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |
-| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable `gsd_exec`, exec history guidance, and resume snapshots |
+| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable prompt guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume` |
 | `context_mode.exec_timeout_ms`    | Timeout for sandboxed `gsd_exec` runs (default: 30000)                                                |
 | `context_mode.exec_stdout_cap_bytes` | Persisted stdout cap for `gsd_exec` output (default: 1048576)                                      |
 | `context_mode.exec_digest_chars`  | Trailing stdout characters returned to the agent context (default: 300)                              |
+| `context_mode.exec_env_allowlist` | Environment variables forwarded to sandboxed `gsd_exec` runs in addition to `PATH` and `HOME`        |
 | `verification_commands`           | Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
 | `verification_auto_fix`           | Auto-retry on verification failures (default: true)                                                   |
 | `verification_max_retries`        | Max retries for verification failures (default: 2)                                                    |

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-4b5e4f1bfb55a0a1
+89938c18ffd18359

package/dist/resources/extensions/gsd/auto/loop.js

@@ -25,6 +25,8 @@ import { normalizeRealPath } from "../paths.js";
 import { decideCooldownRecovery, decideDispatchClaim, decideEngineDispatch, decideFinalizeResult, decideInfrastructureError, decideIterationErrorRecovery, decideMemoryPressure, decideModelPolicyBlocked, decideMinRequestInterval, decideWorkflowLoop, formatDispatchExceptionSummary, formatUnhandledDispatchErrorSummary, resolveUnitRequestTimestamp, shouldUseCustomEnginePath, } from "./workflow-kernel.js";
 import { hydrateCustomVerifyRetryCounts, saveCustomVerifyRetryCounts, } from "./custom-verify-retry-store.js";
 import { settleDispatchCompleted, settleDispatchFailed, } from "./workflow-dispatch-ledger.js";
+import { emitOpenUnitEndForUnit } from "../crash-recovery.js";
+import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { openDispatchClaim } from "./workflow-dispatch-claim.js";
 import { completeWorkflowIteration } from "./workflow-iteration-completion.js";
 import { createWorkflowJournalReporter } from "./workflow-journal-reporter.js";
@@ -133,6 +135,24 @@ async function enforceMinRequestInterval(s, prefs) {
         await new Promise(r => setTimeout(r, decision.waitMs));
     }
 }
+function closeOutCrashedUnit(s, iterData, err) {
+    const summary = formatDispatchExceptionSummary({ error: err });
+    try {
+        emitOpenUnitEndForUnit(s.basePath, iterData.unitType, iterData.unitId, "cancelled", {
+            message: summary,
+            category: "unit-exception",
+            isTransient: false,
+        });
+        writeUnitRuntimeRecord(s.basePath, iterData.unitType, iterData.unitId, s.currentUnit?.startedAt ?? Date.now(), {
+            phase: "crashed",
+            lastProgressAt: Date.now(),
+            lastProgressKind: "unit-exception",
+        });
+    }
+    catch (closeoutErr) {
+        logWarning("dispatch", `unit crash closeout failed: ${closeoutErr instanceof Error ? closeoutErr.message : String(closeoutErr)}`);
+    }
+}
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
  * runUnit → finalize → repeat. Exits when s.active becomes false or a
@@ -392,7 +412,17 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 }
                 // ── Unit execution (shared with dev path) ──
                 await enforceMinRequestInterval(s, prefs);
-                const unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, undefined, unitDispatchDeps);
+                let unitPhaseResult;
+                try {
+                    unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, undefined, unitDispatchDeps);
+                }
+                catch (err) {
+                    if (err instanceof ModelPolicyDispatchBlockedError) {
+                        throw err;
+                    }
+                    closeOutCrashedUnit(s, iterData, err);
+                    throw err;
+                }
                 if (unitPhaseResult.action === "next") {
                     const requestTimestamp = resolveUnitRequestTimestamp(unitPhaseResult.data);
                     if (requestTimestamp !== undefined)
@@ -580,6 +610,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 if (err instanceof ModelPolicyDispatchBlockedError) {
                     throw err;
                 }
+                closeOutCrashedUnit(s, iterData, err);
                 dispatchSettled = settleDispatchFailed(dispatchId, formatDispatchExceptionSummary({ error: err }), {
                     markFailed: markDispatchFailed,
                     logWriteFailure: logDispatchLedgerWriteFailure,

package/dist/resources/extensions/gsd/auto/phases.js

@@ -23,12 +23,12 @@ import { existsSync, cpSync } from "node:fs";
 import { logWarning, logError, _resetLogs, drainLogs, drainAndSummarize, formatForNotification, hasAnyIssues, } from "../workflow-logger.js";
 import { gsdRoot } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
-import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.js";
+import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps, refreshRecoveryDbForArtifact } from "../auto-recovery.js";
 import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
-import { isDbAvailable, getMilestoneSlices, refreshOpenDatabaseFromDisk } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
 import { ensurePlanV2Graph, isEmptyPlanV2GraphResult, isMissingFinalizedContextResult } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
@@ -42,12 +42,10 @@ import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit,
 function isSamePathLocal(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
-function refreshPlanSliceRecoveryDbIfNeeded(unitType) {
-    if (unitType !== "plan-slice")
-        return true;
-    if (!isDbAvailable())
-        return true;
-    return refreshOpenDatabaseFromDisk();
+export function shouldDegradeEmptyWorktreeToProjectRoot(worktreeClassification, projectRootClassification) {
+    return (worktreeClassification.kind === "greenfield" &&
+        projectRootClassification.kind !== "greenfield" &&
+        projectRootClassification.kind !== "invalid-repo");
 }
 // ─── Session timeout auto-resume state ────────────────────────────────────────
 let consecutiveSessionTimeouts = 0;
@@ -136,6 +134,74 @@ async function closeoutAndStop(ctx, pi, s, deps, reason) {
     }
     await deps.stopAuto(ctx, pi, reason);
 }
+async function stopOnPostflightRecoveryNeeded(ic, result, milestoneId) {
+    if (!result.needsManualRecovery)
+        return null;
+    const { ctx, pi, deps } = ic;
+    const reason = `Post-merge stash restore failed for milestone ${milestoneId}`;
+    ctx.ui.notify(`${reason}. Resolve the working tree before resuming auto-mode. ${result.message}`, "error");
+    await deps.stopAuto(ctx, pi, reason);
+    return { action: "break", reason: "postflight-stash-restore-failed" };
+}
+async function restorePreflightStashOrStop(ic, preflight, milestoneId) {
+    if (!preflight.stashPushed)
+        return null;
+    const { ctx, s, deps } = ic;
+    const result = deps.postflightPopStash(s.originalBasePath || s.basePath, milestoneId, preflight.stashMarker, ctx.ui.notify.bind(ctx.ui));
+    return stopOnPostflightRecoveryNeeded(ic, result, milestoneId);
+}
+/**
+ * Run a milestone merge surrounded by preflight stash + always-on postflight
+ * pop. The previous code popped the stash only after a successful merge, which
+ * leaked `gsd-preflight-stash:M00x:*` entries whenever `mergeAndExit` threw —
+ * leaving the user's pre-merge working tree silently stashed away after a
+ * merge-conflict or other merge error. This helper restores the stash on
+ * every exit path, then surfaces the merge or stash failure (in priority
+ * order) as the loop's stop reason.
+ *
+ * Returns a `break` action when auto-mode must stop, or `null` when the merge
+ * succeeded and the stash (if any) was restored cleanly.
+ */
+export async function _runMilestoneMergeWithStashRestore(ic, milestoneId) {
+    const { ctx, pi, s, deps } = ic;
+    const preflight = deps.preflightCleanRoot(s.originalBasePath || s.basePath, milestoneId, ctx.ui.notify.bind(ctx.ui));
+    let mergeError = null;
+    try {
+        deps.resolver.mergeAndExit(milestoneId, ctx.ui);
+        s.milestoneMergedInPhases = true;
+    }
+    catch (mergeErr) {
+        mergeError = mergeErr;
+    }
+    // Always attempt to restore the stashed working tree, even on merge error.
+    // postflightPopStash itself does not throw; failures surface via the
+    // PostflightResult.needsManualRecovery flag.
+    let stashResult = null;
+    if (preflight.stashPushed) {
+        stashResult = deps.postflightPopStash(s.originalBasePath || s.basePath, milestoneId, preflight.stashMarker, ctx.ui.notify.bind(ctx.ui));
+    }
+    // Merge failure takes priority over stash recovery — the merge is the
+    // authoritative gate. If the stash also needed manual recovery, the user
+    // already saw the postflightPopStash notify above.
+    if (mergeError) {
+        if (mergeError instanceof MergeConflictError) {
+            ctx.ui.notify(`Merge conflict: ${mergeError.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
+            await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${milestoneId}`);
+            return { action: "break", reason: "merge-conflict" };
+        }
+        logError("engine", "Milestone merge failed with non-conflict error", {
+            milestone: milestoneId,
+            error: String(mergeError),
+        });
+        ctx.ui.notify(`Merge failed: ${mergeError instanceof Error ? mergeError.message : String(mergeError)}. Resolve and run /gsd auto to resume.`, "error");
+        await deps.stopAuto(ctx, pi, `Merge error on milestone ${milestoneId}: ${String(mergeError)}`);
+        return { action: "break", reason: "merge-failed" };
+    }
+    if (stashResult) {
+        return stopOnPostflightRecoveryNeeded(ic, stashResult, milestoneId);
+    }
+    return null;
+}
 async function emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, errorContext) {
     ic.deps.emitJournalEvent({
         ts: new Date().toISOString(),
@@ -477,28 +543,12 @@ export async function runPreDispatch(ic, loopState) {
         s.unitLifetimeDispatches.clear();
         loopState.recentUnits.length = 0;
         loopState.stuckRecoveryAttempts = 0;
-        // Worktree lifecycle on milestone transition — merge current, enter next
-        // #2909: preflight — warn + stash dirty working tree before merge
-        const preflightTransition = deps.preflightCleanRoot(s.originalBasePath || s.basePath, s.currentMilestoneId, ctx.ui.notify.bind(ctx.ui));
-        try {
-            deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-        }
-        catch (mergeErr) {
-            if (mergeErr instanceof MergeConflictError) {
-                // Real code conflicts — stop the loop instead of retrying forever (#2330)
-                ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
-                await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
-                return { action: "break", reason: "merge-conflict" };
-            }
-            // Non-conflict merge errors — stop auto to avoid advancing with unmerged work
-            logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId, error: String(mergeErr) });
-            ctx.ui.notify(`Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`, "error");
-            await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
-            return { action: "break", reason: "merge-failed" };
-        }
-        // #2909: postflight — restore stashed changes after successful merge
-        if (preflightTransition.stashPushed) {
-            deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, preflightTransition.stashMarker, ctx.ui.notify.bind(ctx.ui));
+        // Worktree lifecycle on milestone transition — merge current, enter next.
+        // #2909 / #5538-followup: preflight stash + always-on postflight pop.
+        {
+            const stop = await _runMilestoneMergeWithStashRestore(ic, s.currentMilestoneId);
+            if (stop)
+                return stop;
         }
         // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         deps.invalidateAllCaches();
@@ -552,30 +602,12 @@ export async function runPreDispatch(ic, loopState) {
         }
         const incomplete = state.registry.filter((m) => m.status !== "complete" && m.status !== "parked");
         if (incomplete.length === 0 && state.registry.length > 0) {
-            // All milestones complete — merge milestone branch before stopping
+            // All milestones complete — merge milestone branch before stopping.
             if (s.currentMilestoneId) {
-                // #2909: preflight — warn + stash dirty working tree before merge
-                const preflightAllComplete = deps.preflightCleanRoot(s.originalBasePath || s.basePath, s.currentMilestoneId, ctx.ui.notify.bind(ctx.ui));
-                try {
-                    deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-                    // Prevent stopAuto from attempting the same merge (#2645)
-                    s.milestoneMergedInPhases = true;
-                }
-                catch (mergeErr) {
-                    if (mergeErr instanceof MergeConflictError) {
-                        ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
-                        await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
-                        return { action: "break", reason: "merge-conflict" };
-                    }
-                    logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId, error: String(mergeErr) });
-                    ctx.ui.notify(`Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`, "error");
-                    await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
-                    return { action: "break", reason: "merge-failed" };
-                }
-                // #2909: postflight — restore stashed changes after successful merge
-                if (preflightAllComplete.stashPushed) {
-                    deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, preflightAllComplete.stashMarker, ctx.ui.notify.bind(ctx.ui));
-                }
+                // #2909 / #5538-followup: preflight stash + always-on postflight pop.
+                const stop = await _runMilestoneMergeWithStashRestore(ic, s.currentMilestoneId);
+                if (stop)
+                    return stop;
                 // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
             }
             deps.sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone", basename(s.originalBasePath || s.basePath));
@@ -638,30 +670,12 @@ export async function runPreDispatch(ic, loopState) {
     }
     // Terminal: complete
     if (state.phase === "complete") {
-        // Milestone merge on complete (before closeout so branch state is clean)
+        // Milestone merge on complete (before closeout so branch state is clean).
         if (s.currentMilestoneId) {
-            // #2909: preflight — warn + stash dirty working tree before merge
-            const preflightComplete = deps.preflightCleanRoot(s.originalBasePath || s.basePath, s.currentMilestoneId, ctx.ui.notify.bind(ctx.ui));
-            try {
-                deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-                // Prevent stopAuto from attempting the same merge (#2645)
-                s.milestoneMergedInPhases = true;
-            }
-            catch (mergeErr) {
-                if (mergeErr instanceof MergeConflictError) {
-                    ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
-                    await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
-                    return { action: "break", reason: "merge-conflict" };
-                }
-                logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId, error: String(mergeErr) });
-                ctx.ui.notify(`Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`, "error");
-                await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
-                return { action: "break", reason: "merge-failed" };
-            }
-            // #2909: postflight — restore stashed changes after successful merge
-            if (preflightComplete.stashPushed) {
-                deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, preflightComplete.stashMarker, ctx.ui.notify.bind(ctx.ui));
-            }
+            // #2909 / #5538-followup: preflight stash + always-on postflight pop.
+            const stop = await _runMilestoneMergeWithStashRestore(ic, s.currentMilestoneId);
+            if (stop)
+                return stop;
             // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         }
         deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone", basename(s.originalBasePath || s.basePath));
@@ -754,6 +768,48 @@ export async function runDispatch(ic, preData, loopState) {
     let unitId = dispatchResult.unitId;
     let prompt = dispatchResult.prompt;
     const pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
+    // Resolve hooks and prior-slice gating before health/stuck accounting so
+    // those checks run against the final dispatch unit.
+    const preDispatchResult = deps.runPreDispatchHooks(unitType, unitId, prompt, s.basePath);
+    if (preDispatchResult.firedHooks.length > 0) {
+        ctx.ui.notify(`Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`, "info");
+        deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "pre-dispatch-hook", data: { firedHooks: preDispatchResult.firedHooks, action: preDispatchResult.action } });
+    }
+    if (preDispatchResult.action === "skip") {
+        ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
+        await new Promise((r) => setImmediate(r));
+        return { action: "continue" };
+    }
+    if (preDispatchResult.action === "replace") {
+        prompt = preDispatchResult.prompt ?? prompt;
+        if (preDispatchResult.unitType)
+            unitType = preDispatchResult.unitType;
+    }
+    else if (preDispatchResult.prompt) {
+        prompt = preDispatchResult.prompt;
+    }
+    const guardBasePath = _resolveDispatchGuardBasePath(s);
+    const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(guardBasePath, deps.getMainBranch(guardBasePath), unitType, unitId);
+    if (priorSliceBlocker) {
+        await deps.stopAuto(ctx, pi, priorSliceBlocker);
+        debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
+        return { action: "break", reason: "prior-slice-blocker" };
+    }
+    // Execute-task needs a real writable checkout. The same health check also
+    // exists in runUnitPhase, but the stuck-window detector runs before that
+    // phase. Check here too so repeated derivations of a broken worktree stop
+    // with the actionable worktree error instead of the generic stuck-loop error.
+    if (s.basePath && unitType === "execute-task") {
+        const gitMarker = join(s.basePath, ".git");
+        const hasGit = deps.existsSync(gitMarker);
+        if (!hasGit) {
+            const msg = `Worktree health check failed: ${s.basePath} has no .git — refusing to dispatch ${unitType} ${unitId}`;
+            debugLog("autoLoop", { phase: "dispatch-worktree-health-fail", basePath: s.basePath, hasGit });
+            ctx.ui.notify(msg, "error");
+            await deps.stopAuto(ctx, pi, msg);
+            return { action: "break", reason: "worktree-invalid" };
+        }
+    }
     // ── Sliding-window stuck detection with graduated recovery ──
     const derivedKey = `${unitType}/${unitId}`;
     // Always record this dispatch in the sliding window so detectStuck() has
@@ -795,11 +851,18 @@ export async function runDispatch(ic, preData, loopState) {
                         level: 1,
                         action: "artifact-found",
                     });
-                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
-                    if (!refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
-                        ctx.ui.notify(`Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Keeping stuck state for retry.`, "warning");
+                    const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId);
+                    if (!recoveryDb.ok) {
+                        ctx.ui.notify(recoveryDb.fatal
+                            ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+                            : `${recoveryDb.message} Keeping stuck state for retry.`, "warning");
+                        if (recoveryDb.fatal) {
+                            await deps.pauseAuto(ctx, pi);
+                            return { action: "break", reason: recoveryDb.reason };
+                        }
                         return { action: "continue" };
                     }
+                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
                     deps.invalidateAllCaches();
                     loopState.recentUnits.length = 0;
                     loopState.stuckRecoveryAttempts = 0;
@@ -818,13 +881,20 @@ export async function runDispatch(ic, preData, loopState) {
                         level: 2,
                         action: "artifact-found",
                     });
-                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`, "info");
-                    if (refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+                    const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId);
+                    if (recoveryDb.ok) {
+                        ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`, "info");
                         loopState.recentUnits.length = 0;
                         loopState.stuckRecoveryAttempts = 0;
                         return { action: "continue" };
                     }
-                    ctx.ui.notify(`Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Stopping for manual recovery.`, "warning");
+                    ctx.ui.notify(recoveryDb.fatal
+                        ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+                        : `${recoveryDb.message} Stopping for manual recovery.`, "warning");
+                    if (recoveryDb.fatal) {
+                        await deps.pauseAuto(ctx, pi);
+                        return { action: "break", reason: recoveryDb.reason };
+                    }
                 }
                 debugLog("autoLoop", {
                     phase: "stuck-detected",
@@ -856,32 +926,6 @@ export async function runDispatch(ic, preData, loopState) {
             }
         }
     }
-    // Pre-dispatch hooks
-    const preDispatchResult = deps.runPreDispatchHooks(unitType, unitId, prompt, s.basePath);
-    if (preDispatchResult.firedHooks.length > 0) {
-        ctx.ui.notify(`Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`, "info");
-        deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "pre-dispatch-hook", data: { firedHooks: preDispatchResult.firedHooks, action: preDispatchResult.action } });
-    }
-    if (preDispatchResult.action === "skip") {
-        ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
-        await new Promise((r) => setImmediate(r));
-        return { action: "continue" };
-    }
-    if (preDispatchResult.action === "replace") {
-        prompt = preDispatchResult.prompt ?? prompt;
-        if (preDispatchResult.unitType)
-            unitType = preDispatchResult.unitType;
-    }
-    else if (preDispatchResult.prompt) {
-        prompt = preDispatchResult.prompt;
-    }
-    const guardBasePath = _resolveDispatchGuardBasePath(s);
-    const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(guardBasePath, deps.getMainBranch(guardBasePath), unitType, unitId);
-    if (priorSliceBlocker) {
-        await deps.stopAuto(ctx, pi, priorSliceBlocker);
-        debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
-        return { action: "break", reason: "prior-slice-blocker" };
-    }
     return {
         action: "next",
         data: {
@@ -1111,6 +1155,25 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
             }
         }
         else if (projectClassification.kind === "greenfield") {
+            const projectRoot = s.canonicalProjectRoot;
+            if (!isSamePathLocal(s.basePath, projectRoot)) {
+                const projectRootClassification = classifyProject(projectRoot);
+                if (shouldDegradeEmptyWorktreeToProjectRoot(projectClassification, projectRootClassification)) {
+                    debugLog("runUnitPhase", {
+                        phase: "worktree-health-degrade-to-project-root",
+                        worktreePath: s.basePath,
+                        projectRoot,
+                        worktreeClassification: projectClassification,
+                        projectRootClassification,
+                    });
+                    ctx.ui.notify(`Warning: ${s.basePath} has no project content, but ${projectRoot} does. Continuing in project root because the milestone worktree cannot represent untracked project files.`, "warning");
+                    s.basePath = projectRoot;
+                    s.isolationDegraded = true;
+                    projectClassification = projectRootClassification;
+                }
+            }
+        }
+        if (projectClassification.kind === "greenfield") {
             debugLog("runUnitPhase", { phase: "worktree-health-greenfield", basePath: s.basePath, classification: projectClassification });
             ctx.ui.notify(`Warning: ${s.basePath} has no project content yet — proceeding as greenfield project`, "warning");
         }
@@ -1672,6 +1735,13 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
     }
     // Both pre and post verification completed without timeout — reset counter
     loopState.consecutiveFinalizeTimeouts = 0;
+    if (preUnitSnapshot) {
+        writeUnitRuntimeRecord(s.basePath, preUnitSnapshot.type, preUnitSnapshot.id, preUnitSnapshot.startedAt, {
+            phase: "finalized",
+            lastProgressAt: Date.now(),
+            lastProgressKind: "finalize-success",
+        });
+    }
     s.currentUnit = null;
     clearCurrentPhase();
     // Surface accumulated workflow-logger issues for this unit to the user.

package/dist/resources/extensions/gsd/auto/resolve.js

@@ -17,6 +17,7 @@ import { bumpTurnGeneration } from "./turn-epoch.js";
 // scoped pendingResolve + pendingAgentEndQueue pattern.
 let _currentResolve = null;
 let _sessionSwitchInFlight = false;
+let _pendingSwitchCancellation = null;
 // ─── Setters (needed for cross-module mutation) ─────────────────────────────
 export function _setCurrentResolve(fn) {
     _currentResolve = fn;
@@ -27,6 +28,11 @@ export function _setSessionSwitchInFlight(v) {
 export function _clearCurrentResolve() {
     _currentResolve = null;
 }
+export function _consumePendingSwitchCancellation() {
+    const pending = _pendingSwitchCancellation;
+    _pendingSwitchCancellation = null;
+    return pending;
+}
 // ─── resolveAgentEnd ─────────────────────────────────────────────────────────
 /**
  * Called from the agent_end event handler in index.ts to resolve the
@@ -90,8 +96,18 @@ export function resolveAgentEndCancelled(errorContext) {
         debugLog("resolveAgentEndCancelled", { status: "resolving-cancelled" });
         const r = _currentResolve;
         _currentResolve = null;
+        _pendingSwitchCancellation = null;
         r({ status: "cancelled", ...(errorContext ? { errorContext } : {}) });
+        return true;
+    }
+    if (_sessionSwitchInFlight) {
+        bumpTurnGeneration(`cancelled-during-switch:${errorContext?.category ?? "unknown"}`);
+        _pendingSwitchCancellation = errorContext ? { errorContext } : {};
+        debugLog("resolveAgentEndCancelled", { status: "queued-during-switch" });
+        return false;
     }
+    debugLog("resolveAgentEndCancelled", { status: "no-pending-resolve" });
+    return false;
 }
 // ─── resetPendingResolve (test helper) ───────────────────────────────────────
 /**
@@ -101,6 +117,7 @@ export function resolveAgentEndCancelled(errorContext) {
 export function _resetPendingResolve() {
     _currentResolve = null;
     _sessionSwitchInFlight = false;
+    _pendingSwitchCancellation = null;
 }
 export function _hasPendingResolveForTest() {
     return _currentResolve !== null;

package/dist/resources/extensions/gsd/auto/run-unit.js

@@ -1,6 +1,6 @@
 // GSD-2 + src/resources/extensions/gsd/auto/run-unit.ts - Runs one GSD auto-mode unit from session creation through agent completion.
 import { NEW_SESSION_TIMEOUT_MS } from "./session.js";
-import { _clearCurrentResolve, _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js";
+import { _clearCurrentResolve, _consumePendingSwitchCancellation, _setCurrentResolve, _setSessionSwitchInFlight, } from "./resolve.js";
 import { getCurrentTurnGeneration, runWithTurnGeneration, } from "./turn-epoch.js";
 import { debugLog } from "../debug-logger.js";
 import { logWarning } from "../workflow-logger.js";
@@ -19,43 +19,21 @@ let sessionSwitchGeneration = 0;
  */
 export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     debugLog("runUnit", { phase: "start", unitType, unitId });
-    // Ensure cwd matches basePath BEFORE newSession() captures it. The new
-    // session reads process.cwd() during construction to anchor its tool
-    // runtime and system prompt; if cwd has drifted (async_bash, background
-    // jobs, prior unit cleanup), the session would otherwise be rooted to
-    // the wrong directory. Must be synchronous — no awaits between chdir
-    // and newSession (#1389, #4762 follow-up).
-    try {
-        if (process.cwd() !== s.basePath) {
-            process.chdir(s.basePath);
-        }
-    }
-    catch (e) {
-        const msg = `Failed to chdir to basePath before newSession (basePath: ${s.basePath}): ${String(e)}`;
-        logWarning("engine", msg, { basePath: s.basePath, error: String(e) });
-        return {
-            status: "cancelled",
-            errorContext: {
-                message: msg,
-                category: "session-failed",
-                isTransient: true,
-            },
-        };
-    }
     // ── Session creation with timeout ──
     debugLog("runUnit", { phase: "session-create", unitType, unitId });
     let sessionResult;
     let sessionTimeoutHandle;
     const mySessionSwitchGeneration = ++sessionSwitchGeneration;
-    // #3731: Cancellation controller for newSession(). When the session-creation
-    // timeout fires, we abort this controller so that the still-in-flight
-    // newSession() discards itself after await this.abort() completes, preventing
-    // it from capturing the (now-root) process.cwd() and rebuilding the tool
-    // runtime with the wrong cwd.
+    // #3731: Cancellation controller for newSession(). When session creation
+    // times out, abort before a late session switch can rebuild the tool runtime
+    // against a stale workspace root.
     const sessionAbortController = new AbortController();
     _setSessionSwitchInFlight(true);
     try {
-        const sessionPromise = s.cmdCtx.newSession({ abortSignal: sessionAbortController.signal }).finally(() => {
+        const sessionPromise = s.cmdCtx.newSession({
+            abortSignal: sessionAbortController.signal,
+            workspaceRoot: s.basePath,
+        }).finally(() => {
             if (sessionSwitchGeneration === mySessionSwitchGeneration) {
                 _setSessionSwitchInFlight(false);
             }
@@ -71,6 +49,7 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     catch (sessionErr) {
         if (sessionTimeoutHandle)
             clearTimeout(sessionTimeoutHandle);
+        _consumePendingSwitchCancellation();
         const msg = sessionErr instanceof Error ? sessionErr.message : String(sessionErr);
         debugLog("runUnit", {
             phase: "session-error",
@@ -83,15 +62,18 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     if (sessionTimeoutHandle)
         clearTimeout(sessionTimeoutHandle);
     if (sessionResult.cancelled) {
+        _consumePendingSwitchCancellation();
         debugLog("runUnit-session-timeout", { unitType, unitId });
         return { status: "cancelled", errorContext: { message: "Session creation timed out", category: "timeout", isTransient: true } };
     }
     if (!s.active) {
+        _consumePendingSwitchCancellation();
         return { status: "cancelled" };
     }
     if (s.currentUnitModel && typeof pi.setModel === "function") {
         const restored = await pi.setModel(s.currentUnitModel, { persist: false });
         if (!restored) {
+            _consumePendingSwitchCancellation();
             const message = `Failed to restore configured model ${s.currentUnitModel.provider}/${s.currentUnitModel.id} after session creation`;
             ctx.ui.notify(`${message}. Cancelling unit before dispatch.`, "warning");
             return {
@@ -111,6 +93,14 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     const unitPromise = new Promise((resolve) => {
         _setCurrentResolve(resolve);
     });
+    const pendingSwitchCancellation = _consumePendingSwitchCancellation();
+    if (pendingSwitchCancellation) {
+        _clearCurrentResolve();
+        return {
+            status: "cancelled",
+            ...(pendingSwitchCancellation.errorContext ? { errorContext: pendingSwitchCancellation.errorContext } : {}),
+        };
+    }
     // ── Provider request-readiness pre-check (#4555) ──
     // Verify the provider can accept requests before dispatching. If the token
     // has expired since bootstrap, return cancelled immediately so the unit is