@opengsd/gsd-pi 1.0.2-dev.235ebf3 → 1.0.2-dev.29398d2

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

@@ -50,6 +50,7 @@ import { handleCustomEngineVerifyPause, handleCustomEngineVerifyRetryOutcome, }
 import { handleCustomEngineReconcile } from "./workflow-custom-engine-reconcile.js";
 import { handleCustomEngineReconcileOutcome } from "./workflow-custom-engine-reconcile-outcome.js";
 import { formatLeaseConflictNotice } from "./lease-conflict-notice.js";
+import { setAutoOutcomeWidget, unitVerb } from "../auto-dashboard.js";
 /**
  * Returns true if workerId is an active worker in this project whose OS
  * process no longer exists. Used to detect dead lease holders before
@@ -690,6 +691,24 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 if (reconcileFlow.action === "break")
                     break;
+                if (s.stepMode) {
+                    if (ctx.hasUI) {
+                        ctx.ui.setWidget?.("gsd-progress", undefined);
+                        setAutoOutcomeWidget(ctx, {
+                            status: "step",
+                            title: "Step complete",
+                            detail: `Completed ${unitVerb(iterData.unitType)} ${iterData.unitId}.`,
+                            unitLabel: `${unitVerb(iterData.unitType)} ${iterData.unitId}`,
+                            nextAction: "Advance one step, or resume automatic mode.",
+                            commands: ["/gsd next", "/gsd auto", "/gsd status for overview"],
+                            startedAt: s.autoStartTime,
+                        });
+                    }
+                    ctx.ui.setStatus("gsd-auto", "next");
+                    ctx.ui.notify(`Step complete: ${unitVerb(iterData.unitType)} ${iterData.unitId}. Run /gsd next for the next step, or /gsd auto to continue automatically.`, "info");
+                    s.preserveStepSurfaceAfterLoopExit = true;
+                    break;
+                }
                 continue;
             }
             if (!sidecarItem) {

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

@@ -1568,7 +1568,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     const dispatchKey = `${unitType}/${unitId}`;
     const nextDispatchCount = (s.unitDispatchCount.get(dispatchKey) ?? 0) + 1;
     // Status bar (widget + preconditions deferred until after model selection — see #2899)
-    ctx.ui.setStatus("gsd-auto", "auto");
+    ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
     if (mid)
         deps.updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
     // ── Safety harness: reset evidence + create checkpoint ──

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

@@ -132,6 +132,8 @@ export class AutoSession {
     // ── Isolation degradation ────────────────────────────────────────────
     /** Set to true when worktree creation fails; prevents merge of nonexistent branch. */
     isolationDegraded = false;
+    /** Temporary recovery mode for stranded work adopted from physical git evidence. */
+    strandedRecoveryIsolationMode = null;
     /** Project-root dirty snapshot captured before an isolated worktree unit runs. */
     rootWriteBaseline = null;
     // ── Merge guard ──────────────────────────────────────────────────────
@@ -285,6 +287,7 @@ export class AutoSession {
         this.lastGitActionFailure = null;
         this.lastGitActionStatus = null;
         this.isolationDegraded = false;
+        this.strandedRecoveryIsolationMode = null;
         this.rootWriteBaseline = null;
         this.milestoneMergedInPhases = false;
         this.milestoneStartShas = new Map();

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

@@ -21,7 +21,7 @@ import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
 import { acquireSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
-import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchList, nativeBranchExists, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchList, nativeBranchExists, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, nativeHasChanges, } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
 import { getAutoWorktreePath, checkoutBranchWithStashGuard } from "./auto-worktree.js";
@@ -126,17 +126,68 @@ export function resolveSurvivorRecoveryIsolationMode(isolationMode, phase) {
         return "branch";
     return isolationMode;
 }
-export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps = {}) {
+function isBlockingStrandedWorkAction(action) {
+    return action.kind === "in-progress-stranded-work" && action.blocksAuto;
+}
+function detectWorktreeEvidence(basePath, milestoneId, hasChanges) {
+    const wtDir = getWorktreeDir(basePath, milestoneId);
+    const wtPath = getAutoWorktreePath(basePath, milestoneId);
+    let dirty = false;
+    if (wtPath) {
+        try {
+            dirty = hasChanges(wtPath);
+        }
+        catch {
+            dirty = false;
+        }
+    }
+    return {
+        path: wtPath,
+        dirExists: existsSync(wtDir),
+        dirty,
+    };
+}
+function strandedWorkMessage(args) {
+    const evidence = [];
+    if (args.branch && args.commitsAhead > 0) {
+        evidence.push(`branch ${args.branch} has ${args.commitsAhead} commit(s) ahead of ${args.mainBranch}`);
+    }
+    if (args.dirtyWorktree) {
+        evidence.push("the worktree has uncommitted changes");
+    }
+    if (evidence.length === 0) {
+        evidence.push("physical git evidence exists");
+    }
+    const wtSuffix = args.worktreeDirExists
+        ? ` Worktree directory at .gsd/worktrees/${args.milestoneId}/ holds live work.`
+        : "";
+    const recovery = args.recoveryMode === "worktree"
+        ? "Recovering will adopt the existing worktree."
+        : "Recovering will adopt the milestone branch.";
+    return (`Stranded work for in-progress milestone ${args.milestoneId}: ${evidence.join("; ")}.` +
+        wtSuffix +
+        ` ${recovery} Park or discard explicitly if abandoning.`);
+}
+export function auditOrphanedMilestoneBranches(basePath, _isolationMode, gitDeps = {}) {
     const recovered = [];
     const warnings = [];
+    const actions = [];
     const branchList = gitDeps.branchList ?? nativeBranchList;
     const branchExists = gitDeps.branchExists ?? nativeBranchExists;
-    // Skip in none mode — no milestone branches are created
-    if (isolationMode === "none")
-        return { recovered, warnings };
+    const hasChanges = gitDeps.hasChanges ?? nativeHasChanges;
+    const pushAction = (action) => {
+        actions.push(action);
+        if (action.severity === "info") {
+            recovered.push(action.message);
+        }
+        else {
+            warnings.push(action.message);
+        }
+    };
     // Skip if DB not available — can't determine completion status
-    if (!isDbAvailable())
-        return { recovered, warnings };
+    if (!isDbAvailable()) {
+        return { recovered, warnings, actions, blockingStrandedWork: null };
+    }
     let milestoneBranches;
     let milestoneBranchListAvailable = true;
     try {
@@ -170,6 +221,7 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps
         if (!milestone)
             continue;
         const isMerged = mergedBranches.has(branch);
+        const worktreeEvidence = detectWorktreeEvidence(basePath, milestoneId, hasChanges);
         // #4762 — in-progress milestone branch with unmerged commits ahead of
         // main. This is the pre-completion orphan case: auto-mode exited without
         // completing the milestone (pause, stop, crash, merge error, blocker) and
@@ -181,32 +233,45 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps
         // Parked/other closed statuses go through the legacy complete/unmerged
         // path below where appropriate.
         if (!isClosedStatus(milestone.status)) {
-            if (isMerged)
-                continue; // nothing to recover
             let commitsAhead = 0;
             try {
                 commitsAhead = nativeCommitCountBetween(basePath, mainBranch, branch);
             }
             catch {
-                // Rev-walk failure — skip rather than noise
-                continue;
+                commitsAhead = 0;
             }
-            if (commitsAhead === 0)
+            if ((isMerged || commitsAhead === 0) && !worktreeEvidence.dirty)
                 continue;
-            const wtDir = getWorktreeDir(basePath, milestoneId);
-            const wtDirExists = existsSync(wtDir);
-            const wtSuffix = wtDirExists
-                ? ` Worktree directory at .gsd/worktrees/${milestoneId}/ holds the live work.`
-                : "";
-            warnings.push(`Branch ${branch} has ${commitsAhead} commit(s) ahead of ${mainBranch} for in-progress milestone ${milestoneId}.` +
-                wtSuffix +
-                ` Run \`/gsd auto\` to resume, or merge manually if abandoning.`);
+            const recoveryMode = worktreeEvidence.path
+                ? "worktree"
+                : "branch";
+            const message = strandedWorkMessage({
+                milestoneId,
+                branch,
+                commitsAhead,
+                mainBranch,
+                dirtyWorktree: worktreeEvidence.dirty,
+                worktreeDirExists: worktreeEvidence.dirExists,
+                recoveryMode,
+            });
+            pushAction({
+                kind: "in-progress-stranded-work",
+                milestoneId,
+                branch,
+                commitsAhead,
+                dirtyWorktree: worktreeEvidence.dirty,
+                worktreeDirExists: worktreeEvidence.dirExists,
+                recoveryMode,
+                message,
+                severity: "warning",
+                blocksAuto: true,
+            });
             // #4764 telemetry
             try {
                 emitWorktreeOrphaned(basePath, milestoneId, {
                     reason: "in-progress-unmerged",
                     commitsAhead,
-                    worktreeDirExists: wtDirExists,
+                    worktreeDirExists: worktreeEvidence.dirExists,
                 });
             }
             catch (err) {
@@ -223,7 +288,14 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps
             // Branch is merged — safe to delete branch and clean up worktree dir
             try {
                 nativeBranchDelete(basePath, branch, true);
-                recovered.push(`Deleted merged branch ${branch} for completed milestone ${milestoneId}.`);
+                pushAction({
+                    kind: "complete-merged-branch",
+                    milestoneId,
+                    branch,
+                    message: `Deleted merged branch ${branch} for completed milestone ${milestoneId}.`,
+                    severity: "info",
+                    blocksAuto: false,
+                });
             }
             catch (err) {
                 warnings.push(`Failed to delete merged branch ${branch}: ${err instanceof Error ? err.message : String(err)}`);
@@ -246,7 +318,15 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps
                     if (isInsideWorktreesDir(basePath, wtDir)) {
                         try {
                             rmSync(wtDir, { recursive: true, force: true });
-                            recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`);
+                            pushAction({
+                                kind: "complete-merged-worktree",
+                                milestoneId,
+                                branch,
+                                worktreeDirExists: true,
+                                message: `Removed orphaned worktree directory for ${milestoneId}.`,
+                                severity: "info",
+                                blocksAuto: false,
+                            });
                         }
                         catch (err2) {
                             warnings.push(`Failed to remove worktree directory for ${milestoneId}: ${err2 instanceof Error ? err2.message : String(err2)}`);
@@ -257,14 +337,30 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps
                     }
                 }
                 else {
-                    recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`);
+                    pushAction({
+                        kind: "complete-merged-worktree",
+                        milestoneId,
+                        branch,
+                        worktreeDirExists: true,
+                        message: `Removed orphaned worktree directory for ${milestoneId}.`,
+                        severity: "info",
+                        blocksAuto: false,
+                    });
                 }
             }
         }
         else {
             // Branch is NOT merged — preserve for safety, warn the user
-            warnings.push(`Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` +
-                `This may contain unmerged work. Merge manually or run \`/gsd doctor fix\` to resolve.`);
+            pushAction({
+                kind: "complete-unmerged-branch",
+                milestoneId,
+                branch,
+                worktreeDirExists: worktreeEvidence.dirExists,
+                message: `Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` +
+                    `This may contain unmerged work. Merge manually or run \`/gsd doctor fix\` to resolve.`,
+                severity: "warning",
+                blocksAuto: false,
+            });
             // #4764 telemetry
             try {
                 emitWorktreeOrphaned(basePath, milestoneId, {
@@ -300,6 +396,43 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps
         completedMilestones = [];
     }
     for (const m of completedMilestones) {
+        if (!isClosedStatus(m.status)) {
+            if (seenMilestoneIds.has(m.id))
+                continue;
+            const worktreeEvidence = detectWorktreeEvidence(basePath, m.id, hasChanges);
+            if (!worktreeEvidence.dirty)
+                continue;
+            const message = strandedWorkMessage({
+                milestoneId: m.id,
+                commitsAhead: 0,
+                mainBranch,
+                dirtyWorktree: true,
+                worktreeDirExists: worktreeEvidence.dirExists,
+                recoveryMode: "worktree",
+            });
+            pushAction({
+                kind: "in-progress-stranded-work",
+                milestoneId: m.id,
+                commitsAhead: 0,
+                dirtyWorktree: true,
+                worktreeDirExists: worktreeEvidence.dirExists,
+                recoveryMode: "worktree",
+                message,
+                severity: "warning",
+                blocksAuto: true,
+            });
+            try {
+                emitWorktreeOrphaned(basePath, m.id, {
+                    reason: "in-progress-unmerged",
+                    commitsAhead: 0,
+                    worktreeDirExists: worktreeEvidence.dirExists,
+                });
+            }
+            catch (err) {
+                logWarning("engine", `worktree-orphaned telemetry failed for ${m.id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            continue;
+        }
         if (m.status !== "complete")
             continue;
         if (seenMilestoneIds.has(m.id))
@@ -332,17 +465,36 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps
         if (existsSync(wtDir)) {
             try {
                 rmSync(wtDir, { recursive: true, force: true });
-                recovered.push(`Removed orphaned worktree directory for ${m.id} (branch already deleted).`);
+                pushAction({
+                    kind: "complete-branchless-worktree",
+                    milestoneId: m.id,
+                    worktreeDirExists: true,
+                    message: `Removed orphaned worktree directory for ${m.id} (branch already deleted).`,
+                    severity: "info",
+                    blocksAuto: false,
+                });
             }
             catch (err) {
                 warnings.push(`Failed to remove orphaned worktree directory for ${m.id}: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         else {
-            recovered.push(`Removed orphaned worktree directory for ${m.id} (branch already deleted).`);
+            pushAction({
+                kind: "complete-branchless-worktree",
+                milestoneId: m.id,
+                worktreeDirExists: true,
+                message: `Removed orphaned worktree directory for ${m.id} (branch already deleted).`,
+                severity: "info",
+                blocksAuto: false,
+            });
         }
     }
-    return { recovered, warnings };
+    return {
+        recovered,
+        warnings,
+        actions,
+        blockingStrandedWork: actions.find(isBlockingStrandedWorkAction) ?? null,
+    };
 }
 /**
  * Pure decision function for picking which orphan milestone the auto-loop
@@ -679,17 +831,27 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // was lost due to session ending between completion and teardown.
         // Must run after DB open and before worktree entry.
         let orphanAuditRecovered = false;
+        let strandedRecoveryActions = [];
+        let strandedRecoveryAction = null;
         try {
             const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode(base));
+            strandedRecoveryActions = auditResult.actions.filter(isBlockingStrandedWorkAction);
+            strandedRecoveryAction = strandedRecoveryActions[0] ?? null;
             for (const msg of auditResult.recovered) {
                 ctx.ui.notify(`Orphan audit: ${msg}`, "info");
             }
             for (const msg of auditResult.warnings) {
-                ctx.ui.notify(`Orphan audit: ${msg}`, "warning");
+                const prefix = msg.startsWith("Stranded work") ? "" : "Orphan audit: ";
+                ctx.ui.notify(`${prefix}${msg}`, "warning");
             }
             if (auditResult.recovered.length > 0) {
                 orphanAuditRecovered = true;
-                debugLog("orphan-audit", { recovered: auditResult.recovered, warnings: auditResult.warnings });
+                debugLog("orphan-audit", {
+                    recovered: auditResult.recovered,
+                    warnings: auditResult.warnings,
+                    strandedRecoveryAction,
+                    strandedRecoveryActions,
+                });
             }
         }
         catch (err) {
@@ -724,13 +886,6 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             logWarning("bootstrap", `orphaned preflight-stash audit failed: ${err instanceof Error ? err.message : String(err)}`);
         }
         let state = await deriveState(base);
-        if (process.env.GSD_HEADLESS === "1" &&
-            orphanAuditRecovered &&
-            !state.activeMilestone &&
-            state.phase === "complete") {
-            ctx.ui.notify("Auto-mode stopped (Recovered completed milestone cleanup; all milestones complete).", "info");
-            return releaseLockAndReturn();
-        }
         // Stale worktree state recovery (#654)
         if (state.activeMilestone &&
             shouldUseWorktreeIsolation(base) &&
@@ -740,6 +895,28 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 state = await deriveState(wtPath);
             }
         }
+        const blockingStrandedRecoveryAction = state.activeMilestone
+            ? strandedRecoveryActions.find((action) => action.milestoneId !== state.activeMilestone?.id) ?? strandedRecoveryAction
+            : strandedRecoveryAction;
+        if (blockingStrandedRecoveryAction) {
+            if (!state.activeMilestone) {
+                ctx.ui.notify(`Stranded work for ${blockingStrandedRecoveryAction.milestoneId} blocks auto-mode, but that milestone is not active in project state. Park or discard it explicitly before continuing.`, "error");
+                return releaseLockAndReturn();
+            }
+            if (state.activeMilestone.id !== blockingStrandedRecoveryAction.milestoneId) {
+                ctx.ui.notify(`Stranded work for ${blockingStrandedRecoveryAction.milestoneId} blocks auto-mode before ${state.activeMilestone.id}. Recover, park, or discard ${blockingStrandedRecoveryAction.milestoneId} explicitly before continuing.`, "error");
+                return releaseLockAndReturn();
+            }
+            strandedRecoveryAction = blockingStrandedRecoveryAction;
+            ctx.ui.notify(`Recovering stranded work for ${strandedRecoveryAction.milestoneId} before dispatching new units.`, "info");
+        }
+        if (process.env.GSD_HEADLESS === "1" &&
+            orphanAuditRecovered &&
+            !state.activeMilestone &&
+            state.phase === "complete") {
+            ctx.ui.notify("Auto-mode stopped (Recovered completed milestone cleanup; all milestones complete).", "info");
+            return releaseLockAndReturn();
+        }
         // Milestone branch recovery (#601, #2358)
         // Detect survivor milestone branches in both pre-planning and complete phases.
         // In phase=complete, the milestone artifacts exist but finalization (merge,
@@ -768,7 +945,8 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // The worktree/branch was created but the milestone only has CONTEXT-DRAFT.md.
         // Route to the interactive discussion handler instead of falling through to
         // auto-mode, which would immediately stop with "needs discussion".
-        if (decideSurvivorAction(hasSurvivorBranch, state.phase) === "discuss") {
+        if (!strandedRecoveryAction &&
+            decideSurvivorAction(hasSurvivorBranch, state.phase) === "discuss") {
             const { showSmartEntry } = await import("./guided-flow.js");
             await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
             invalidateAllCaches();
@@ -848,14 +1026,14 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         const effectivePrefs = loadEffectiveGSDPreferences(base)?.preferences;
         const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
         const deepProjectStagePending = shouldRunDeepProjectSetup(state, effectivePrefs, base, { hasSurvivorBranch });
-        if (deepProjectStagePending) {
+        if (deepProjectStagePending && !strandedRecoveryAction) {
             // Deep project-level setup runs before the first milestone exists. Let
             // the auto loop dispatch workflow-preferences / project / requirements
             // units instead of recursing back through showSmartEntry while this
             // bootstrap still holds the session lock.
             s.currentMilestoneId = null;
         }
-        if (!hasSurvivorBranch && !deepProjectStagePending) {
+        if (!hasSurvivorBranch && !deepProjectStagePending && !strandedRecoveryAction) {
             // No active work — start a new milestone via discuss flow
             if (!state.activeMilestone || state.phase === "complete") {
                 // Guard against recursive dialog loop (#1348):
@@ -917,7 +1095,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             }
         }
         // Unreachable safety check
-        if (!state.activeMilestone && !deepProjectStagePending) {
+        if (!state.activeMilestone && !deepProjectStagePending && !strandedRecoveryAction) {
             const { showSmartEntry } = await import("./guided-flow.js");
             await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
             return releaseLockAndReturn();
@@ -952,7 +1130,9 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         s.resourceVersionOnStart = readResourceVersion();
         s.pendingQuickTasks = [];
         s.currentUnit = null;
-        s.currentMilestoneId ??= deepProjectStagePending ? null : state.activeMilestone?.id ?? null;
+        s.currentMilestoneId ??=
+            strandedRecoveryAction?.milestoneId ??
+                (deepProjectStagePending ? null : state.activeMilestone?.id ?? null);
         s.originalModelId = startModelSnapshot?.id ?? ctx.model?.id ?? null;
         s.originalModelProvider = startModelSnapshot?.provider ?? ctx.model?.provider ?? null;
         s.originalThinkingLevel = startThinkingSnapshot ?? null;
@@ -960,7 +1140,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         registerSigtermHandler(base);
         // Capture integration branch
         if (s.currentMilestoneId) {
-            if (getIsolationMode(base) !== "none") {
+            if (getIsolationMode(base) !== "none" || strandedRecoveryAction) {
                 captureIntegrationBranch(base, s.currentMilestoneId);
             }
             setActiveMilestoneId(base, s.currentMilestoneId);
@@ -970,7 +1150,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // milestone/<MID>. Auto-checkout back to the integration branch.
         const isolationMode = getIsolationMode(base);
         const isRepo = nativeIsRepo(base);
-        if (isolationMode === "none" && isRepo) {
+        if (isolationMode === "none" && isRepo && !strandedRecoveryAction) {
             try {
                 const currentBranch = nativeGetCurrentBranch(base);
                 const integrationBranch = nativeDetectMainBranch(base);
@@ -1001,12 +1181,15 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             return symlinkRe.test(p);
         };
         if (s.currentMilestoneId &&
-            getIsolationMode(base) !== "none" &&
+            (getIsolationMode(base) !== "none" || strandedRecoveryAction?.recoveryMode) &&
             !detectWorktreeName(base) &&
             !isUnderGsdWorktrees(base)) {
-            const enterResult = buildLifecycle().enterMilestone(s.currentMilestoneId, {
-                notify: ctx.ui.notify.bind(ctx.ui),
-            });
+            const lifecycle = buildLifecycle();
+            const enterResult = strandedRecoveryAction?.recoveryMode
+                ? lifecycle.adoptStrandedMilestone(s.currentMilestoneId, base, { notify: ctx.ui.notify.bind(ctx.ui) }, { mode: strandedRecoveryAction.recoveryMode })
+                : lifecycle.enterMilestone(s.currentMilestoneId, {
+                    notify: ctx.ui.notify.bind(ctx.ui),
+                });
             if (!enterResult.ok) {
                 s.active = false;
                 if (enterResult.reason === "lease-conflict") {

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

@@ -23,6 +23,7 @@ import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, nativeWorktreeList, nativeLsFiles, } from "./native-git-bridge.js";
 import { gsdHome } from "./gsd-home.js";
 import { createWorkspace } from "./workspace.js";
@@ -796,60 +797,7 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
 export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
     return _finalizeProjectionForMergeImpl(mainBasePath, worktreePath, milestoneId);
 }
-// ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
-/**
- * Run the user-configured post-create hook script after worktree creation.
- * The script receives SOURCE_DIR and WORKTREE_DIR as environment variables.
- * Failure is non-fatal — returns the error message or null on success.
- *
- * Reads the hook path from git.worktree_post_create in preferences.
- * Pass hookPath directly to bypass preference loading (useful for testing).
- */
-export function runWorktreePostCreateHook(sourceDir, worktreeDir, hookPath) {
-    if (hookPath === undefined) {
-        const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-        hookPath = prefs?.worktree_post_create;
-    }
-    if (!hookPath)
-        return null;
-    // Resolve relative paths against the source project root.
-    // On Windows, convert 8.3 short paths (e.g. RUNNER~1) to long paths
-    // so execFileSync can locate the file correctly.
-    let resolved = isAbsolute(hookPath) ? hookPath : join(sourceDir, hookPath);
-    if (!existsSync(resolved)) {
-        return `Worktree post-create hook not found: ${resolved}`;
-    }
-    if (process.platform === "win32") {
-        try {
-            resolved = realpathSync.native(resolved);
-        }
-        catch (err) { /* keep original */
-            logWarning("worktree", `realpath failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    try {
-        // .bat/.cmd files on Windows require shell mode — execFileSync cannot
-        // spawn them directly (EINVAL).
-        const needsShell = process.platform === "win32" && /\.(bat|cmd)$/i.test(resolved);
-        execFileSync(resolved, [], {
-            cwd: worktreeDir,
-            env: {
-                ...process.env,
-                SOURCE_DIR: sourceDir,
-                WORKTREE_DIR: worktreeDir,
-            },
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-            timeout: 30_000, // 30 second timeout
-            shell: needsShell,
-        });
-        return null;
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return `Worktree post-create hook failed: ${msg}`;
-    }
-}
+export { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 // ─── Auto-Worktree Branch Naming ───────────────────────────────────────────
 /** Returns the git branch name for a milestone worktree (`milestone/<MID>`). */
 export function autoWorktreeBranch(milestoneId) {

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -678,8 +678,9 @@ export function registerDbTools(pi) {
         promptSnippet: "Complete a GSD task (DB write + summary render + checkbox toggle)",
         promptGuidelines: [
             "Use gsd_task_complete (or gsd_complete_task) when a task is finished and needs to be recorded.",
-            "All string fields are required. verificationEvidence is an array of objects with command, exitCode, verdict, durationMs.",
-            "The tool validates required fields and returns an error message if any are missing.",
+            "Include verification whenever possible. If verification is omitted, the executor derives it from verificationEvidence when possible.",
+            "verificationEvidence is an array of objects with command, exitCode, verdict, durationMs.",
+            "The tool validates required fields and returns an error message if verification cannot be derived.",
             "On success, returns the summaryPath where the SUMMARY.md was written.",
             "Idempotent — calling with the same params twice will upsert (INSERT OR REPLACE) without error.",
         ],
@@ -690,7 +691,7 @@ export function registerDbTools(pi) {
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             oneLiner: Type.String({ description: "One-line summary of what was accomplished" }),
             narrative: Type.String({ description: "Detailed narrative of what happened during the task" }),
-            verification: Type.String({ description: "What was verified and how — commands run, tests passed, behavior confirmed" }),
+            verification: Type.Optional(Type.String({ description: "What was verified and how — commands run, tests passed, behavior confirmed. If omitted, derived from verificationEvidence when possible." })),
             // ── Enrichment metadata (optional — defaults to empty) ────────────
             deviations: Type.Optional(Type.String({ description: "Deviations from the task plan, or 'None.'" })),
             knownIssues: Type.Optional(Type.String({ description: "Known issues discovered but not fixed, or 'None.'" })),