@opengsd/gsd-pi 1.2.0-dev.e8563f58 → 1.2.0-dev.fbdca60b

package/dist/resources/extensions/gsd/auto/workflow-unit-dispatch.js

@@ -1,7 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Unit dispatch contract adapter for auto-mode loop.
 import { ExecutionGraphScheduler } from "../uok/execution-graph.js";
-import { runUnitPhase } from "./phases.js";
+import { runUnitPhase } from "./unit-phase.js";
 import { decideDispatchNodeKind } from "./workflow-kernel.js";
 export async function runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem, deps) {
     if (dispatchContract === "legacy-direct") {

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

@@ -0,0 +1,125 @@
+// Project/App: gsd-pi
+// File Purpose: Worktree-safety helpers shared across auto-loop phase modules.
+import { classifyProject } from "../detection.js";
+import { resolveEffectiveUnitIsolationMode } from "../preferences.js";
+import { createWorktreeSafetyModule } from "../worktree-safety.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { resolveManifest } from "../unit-context-manifest.js";
+import { debugLog } from "../debug-logger.js";
+import { isSamePathLocal } from "./phase-helpers.js";
+import { hasHeldMilestoneLease, reclaimMissingMilestoneLease } from "./milestone-lease-reclaim.js";
+export function shouldDegradeEmptyWorktreeToProjectRoot(worktreeClassification, projectRootClassification) {
+    return (worktreeClassification.kind === "greenfield" &&
+        projectRootClassification.kind !== "greenfield" &&
+        projectRootClassification.kind !== "invalid-repo");
+}
+export function unitWritesSource(unitType) {
+    if (unitType.startsWith("hook/"))
+        return false;
+    // Backward compatibility: sidecar queues from older builds may persist
+    // prefixed unit types (e.g. "sidecar/quick-task").
+    const normalizedUnitType = unitType.startsWith("sidecar/")
+        ? unitType.slice("sidecar/".length)
+        : unitType;
+    const manifest = resolveManifest(normalizedUnitType);
+    if (!manifest)
+        return null;
+    return manifest.tools.mode === "all" || manifest.tools.mode === "docs";
+}
+export function formatWorktreeSafetyFailure(result) {
+    return `Worktree Safety failed (${result.kind}): ${result.reason} ${result.remediation}`;
+}
+export function formatWorktreeSafetyStopReason(result) {
+    if (result.kind === "empty-worktree-with-project-content") {
+        return `Worktree Safety failed (${result.kind}). Run /gsd doctor fix, then /gsd auto.`;
+    }
+    return `Worktree Safety failed (${result.kind}).`;
+}
+export function resolveEmptyWorktreeWithProjectContent(unitRoot, projectRoot) {
+    if (isSamePathLocal(unitRoot, projectRoot))
+        return false;
+    const worktreeClassification = classifyProject(unitRoot);
+    if (worktreeClassification.kind !== "greenfield")
+        return false;
+    const projectRootClassification = classifyProject(projectRoot);
+    return shouldDegradeEmptyWorktreeToProjectRoot(worktreeClassification, projectRootClassification);
+}
+export async function validateSourceWriteWorktreeSafety(ic, unitType, unitId, milestoneId, phase) {
+    const { ctx, pi, s, deps } = ic;
+    if (!s.basePath)
+        return null;
+    // Custom engine workflows (graph-driven, registered via run dirs) define
+    // their own step ids that are not in the GSD UnitContextManifest. Don't
+    // fail closed for those — the custom engine owns its own dispatch
+    // contract. The fail-closed safety check applies only to built-in GSD
+    // units whose Tool Contract is registered in the manifest. Use a truthy
+    // check so undefined (test sessions that never set the field) routes
+    // through the safety check, matching the regression test contract.
+    if (s.activeEngineId)
+        return null;
+    const writesSource = unitWritesSource(unitType);
+    if (writesSource === null) {
+        const msg = `Worktree Safety failed (missing-tool-contract): missing Tool Contract for ${unitType}. Add a UnitContextManifest entry before dispatching this Unit.`;
+        debugLog("worktreeSafety", {
+            phase,
+            unitType,
+            unitId,
+            milestoneId,
+            result: { ok: false, kind: "missing-tool-contract", reason: msg },
+            basePath: s.basePath,
+        });
+        ctx.ui.notify(msg, "error");
+        await deps.stopAuto(ctx, pi, msg);
+        return { action: "break", reason: "missing-tool-contract" };
+    }
+    if (!writesSource)
+        return null;
+    const projectRoot = s.canonicalProjectRoot ?? resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
+    // A degraded session already fell back to the milestone branch in the
+    // project root — validating against the canonical worktree root there
+    // would fail every dispatch with a false invalid-root. The same applies
+    // to a stranded-recovery session that adopted the milestone branch.
+    const isolationMode = resolveEffectiveUnitIsolationMode(deps.getIsolationMode(projectRoot), s.isolationDegraded, s.strandedRecoveryIsolationMode);
+    reclaimMissingMilestoneLease(s, milestoneId, isolationMode, phase);
+    const safety = createWorktreeSafetyModule();
+    const result = safety.validateUnitRoot({
+        unitType,
+        unitId,
+        writeScope: "source-writing",
+        projectRoot,
+        unitRoot: s.basePath,
+        milestoneId,
+        isolationMode,
+        expectedBranch: isolationMode !== "none" && milestoneId ? deps.autoWorktreeBranch(milestoneId) : null,
+        emptyWorktreeWithProjectContent: resolveEmptyWorktreeWithProjectContent(s.basePath, projectRoot),
+        // The milestone lease coordinates concurrent workers on an isolated
+        // milestone worktree/branch, which is established by enterMilestone in
+        // worktree/branch modes. `none` mode has no per-milestone isolation and
+        // does not reliably claim a lease (e.g. a fresh headless resume of an
+        // already-active milestone never re-enters it), so requiring a held lease
+        // there would falsely fail dispatch. Enforce the lease only in isolated
+        // modes; none-mode safety still validates the unit root.
+        lease: s.workerId
+            ? {
+                required: isolationMode !== "none",
+                held: hasHeldMilestoneLease(s, milestoneId),
+                owner: s.workerId,
+            }
+            : undefined,
+    });
+    if (result.ok)
+        return null;
+    const msg = formatWorktreeSafetyFailure(result);
+    debugLog("worktreeSafety", {
+        phase,
+        unitType,
+        unitId,
+        milestoneId,
+        result,
+        basePath: s.basePath,
+        projectRoot,
+    });
+    ctx.ui.notify(msg, "error");
+    await deps.stopAuto(ctx, pi, formatWorktreeSafetyStopReason(result));
+    return { action: "break", reason: result.kind };
+}

package/dist/resources/extensions/gsd/auto-direct-dispatch.js

@@ -10,7 +10,7 @@ import { buildResearchSlicePrompt, buildResearchMilestonePrompt, buildPlanSliceP
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { pauseAuto } from "./auto.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit, } from "./workflow-mcp.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 export async function dispatchDirectPhase(ctx, pi, phase, base) {
     const state = await deriveState(base);
     const mid = state.activeMilestone?.id;
@@ -201,7 +201,8 @@ export async function dispatchDirectPhase(ctx, pi, phase, base) {
             ctx.ui.notify(`Unknown phase "${phase}". Valid phases: research, plan, execute, complete, validate, reassess, uat, replan.`, "warning");
             return;
     }
-    const compatibilityError = getWorkflowTransportSupportError(ctx.model?.provider, getRequiredWorkflowToolsForAutoUnit(unitType), {
+    const compatibilityError = getUnitWorkflowDispatchReadinessError({
+        provider: ctx.model?.provider,
         projectRoot,
         surface: "direct phase dispatch",
         unitType,

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

@@ -24,7 +24,8 @@ import { isAutoActive } from "./auto.js";
 import { hostWriteGateAdapter } from "./bootstrap/write-gate.js";
 import { ensureWorkflowPreferencesCaptured } from "./planning-depth.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit, resolveWorkflowMcpProjectRoot, } from "./workflow-mcp.js";
+import { resolveWorkflowMcpProjectRoot } from "./workflow-mcp.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import { prepareBrowserDaemonForUat } from "./browser-daemon-auto-prep.js";
 import { PROJECT_RESEARCH_INFLIGHT_MARKER, } from "./project-research-policy.js";
 import { isWorkflowPrefsCaptured, resolveDeepProjectSetupState, } from "./deep-project-setup-policy.js";
@@ -512,7 +513,15 @@ export const DISPATCH_RULES = [
             // Transport preflight: verify required MCP tools are actually connected
             // before consuming a retry attempt. Fixes tool-starved sessions burning
             // all MAX_UAT_ATTEMPTS before stopping (#477).
-            const transportError = getWorkflowTransportSupportError(sessionProvider, getRequiredWorkflowToolsForAutoUnit("run-uat"), { projectRoot: basePath, surface: "auto-mode", unitType: "run-uat", authMode: sessionAuthMode, baseUrl: sessionBaseUrl, activeTools });
+            const transportError = getUnitWorkflowDispatchReadinessError({
+                provider: sessionProvider,
+                projectRoot: basePath,
+                surface: "auto-mode",
+                unitType: "run-uat",
+                authMode: sessionAuthMode,
+                baseUrl: sessionBaseUrl,
+                activeTools,
+            });
             if (transportError) {
                 return { action: "stop", reason: transportError, level: "warning" };
             }

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

@@ -1704,13 +1704,24 @@ export async function postUnitPreVerification(pctx, opts) {
             }
             else if (!triggerArtifactVerified) {
                 if (s.lastToolInvocationError && isToolUnavailableError(s.lastToolInvocationError)) {
-                    // Tool-unavailable is the one transient invocation error: the
-                    // workflow MCP server registers its surface asynchronously, so a
-                    // Unit's first call can race the registration. Fall through to the
-                    // bounded verification retry instead of pausing.
-                    debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError });
-                    ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. The tool surface may still be registering — retrying.`, "warning");
+                    // Tool-unavailable is transient: the workflow MCP server registers
+                    // its surface asynchronously, so a Unit's first call can race the
+                    // registration. Retry with escalating delay, bounded at 3 attempts.
+                    // ponytail: MAX constant so the guard, log, and display all agree
+                    const MAX_TOOL_UNAVAIL_RETRIES = 3;
+                    if (s.toolUnavailableRetries >= MAX_TOOL_UNAVAIL_RETRIES) {
+                        debugLog("postUnit", { phase: "tool-unavailable-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, retries: s.toolUnavailableRetries });
+                        ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type} after ${MAX_TOOL_UNAVAIL_RETRIES} retries: ${s.lastToolInvocationError}. MCP server may not be starting — pausing auto-mode.`, "error");
+                        s.lastToolInvocationError = null;
+                        await pauseAuto(ctx, pi);
+                        return "dispatched";
+                    }
+                    s.toolUnavailableRetries++;
+                    const delayMs = s.toolUnavailableRetries * 1000;
+                    debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError, attempt: s.toolUnavailableRetries, delayMs });
+                    ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Waiting ${delayMs}ms for MCP server — retry ${s.toolUnavailableRetries}/${MAX_TOOL_UNAVAIL_RETRIES}.`, "warning");
                     s.lastToolInvocationError = null;
+                    await new Promise(r => setTimeout(r, delayMs));
                 }
                 else if (s.lastToolInvocationError) {
                     const isUserSkip = /queued user message/i.test(s.lastToolInvocationError);
@@ -1825,6 +1836,7 @@ export async function postUnitPreVerification(pctx, opts) {
                 if (s.pendingVerificationRetry?.unitId === s.currentUnit.id) {
                     s.pendingVerificationRetry = null;
                 }
+                s.toolUnavailableRetries = 0;
                 s.verificationRetryCount.delete(retryKey);
                 s.verificationRetryFailureHashes.delete(retryKey);
                 s.exhaustedVerificationUnits.delete(retryKey);

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

@@ -976,9 +976,26 @@ 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;
+        const requestedMilestoneLock = process.env.GSD_MILESTONE_LOCK?.trim() || null;
+        const lockedActiveMilestone = requestedMilestoneLock && state.activeMilestone?.id === requestedMilestoneLock;
+        let blockingStrandedRecoveryAction;
+        if (lockedActiveMilestone) {
+            // Parallel worker or explicit `/gsd auto Mxxx`: sibling milestones'
+            // stranded work must not block this milestone's resumption, and the
+            // downstream `strandedRecoveryAction` (used for currentMilestoneId,
+            // setActiveMilestoneId, and adoptStrandedMilestone) must be scoped to
+            // the locked milestone only. Falling back to the first sibling action
+            // would mis-target adoption (#742).
+            const lockMatch = strandedRecoveryActions.find((action) => action.milestoneId === requestedMilestoneLock) ?? null;
+            blockingStrandedRecoveryAction = lockMatch;
+            strandedRecoveryAction = lockMatch;
+        }
+        else if (state.activeMilestone) {
+            blockingStrandedRecoveryAction = strandedRecoveryActions.find((action) => action.milestoneId !== state.activeMilestone?.id) ?? strandedRecoveryAction;
+        }
+        else {
+            blockingStrandedRecoveryAction = strandedRecoveryAction;
+        }
         if (blockingStrandedRecoveryAction) {
             if (!state.activeMilestone) {
                 ctx.ui.notify(formatStrandedWorkBlockerMessage(blockingStrandedRecoveryAction, null), "error");
@@ -991,6 +1008,9 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             strandedRecoveryAction = blockingStrandedRecoveryAction;
             ctx.ui.notify(formatStrandedWorkRecoveryMessage(strandedRecoveryAction), "info");
         }
+        else if (lockedActiveMilestone) {
+            strandedRecoveryAction = null;
+        }
         if (process.env.GSD_HEADLESS === "1" &&
             orphanAuditRecovered &&
             !state.activeMilestone &&

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

@@ -36,17 +36,17 @@ export function isSuspiciousGhostCompletion(ctx, startedAt, maxElapsedMs = GHOST
         activity.assistantMessages === 0);
 }
 /**
- * Snapshot metrics, save activity log, and fire-and-forget memory extraction
- * for a completed unit. Returns the activity log file path (if any).
+ * Snapshot metrics, save activity log, extract memories, and record the git
+ * transaction for a completed auto-mode unit.
  */
-export async function closeoutUnit(ctx, basePath, unitType, unitId, startedAt, opts) {
-    const modelId = ctx.model?.id ?? "unknown";
-    snapshotUnitMetrics(ctx, unitType, unitId, startedAt, modelId, opts);
-    const activityFile = saveActivityLog(ctx, basePath, unitType, unitId);
+export async function closeoutAutoUnit(request) {
+    const modelId = request.ctx.model?.id ?? "unknown";
+    snapshotUnitMetrics(request.ctx, request.unitType, request.unitId, request.startedAt, modelId, request.opts);
+    const activityFile = saveActivityLog(request.ctx, request.basePath, request.unitType, request.unitId);
     if (activityFile) {
         try {
-            const { buildMemoryLLMCall, extractMemoriesFromUnit } = await import('./memory-extractor.js');
-            const llmCallFn = buildMemoryLLMCall(ctx);
+            const { buildMemoryLLMCall, extractMemoriesFromUnit } = await import("./memory-extractor.js");
+            const llmCallFn = buildMemoryLLMCall(request.ctx);
             if (llmCallFn) {
                 // Awaited: a fire-and-forget here lets memory-extractor writes land in
                 // .gsd/ after closeoutUnit returns but before the milestone merge
@@ -55,10 +55,10 @@ export async function closeoutUnit(ctx, basePath, unitType, unitId, startedAt, o
                 // bounded by the extractor's LLM call, which is the acceptable price
                 // for not racing the merge boundary.
                 try {
-                    await extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn);
+                    await extractMemoriesFromUnit(activityFile, request.unitType, request.unitId, llmCallFn);
                 }
                 catch (err) {
-                    logWarning("engine", `memory extraction failed for ${unitType}/${unitId}: ${err.message}`);
+                    logWarning("engine", `memory extraction failed for ${request.unitType}/${request.unitId}: ${err.message}`);
                 }
             }
         }
@@ -66,22 +66,46 @@ export async function closeoutUnit(ctx, basePath, unitType, unitId, startedAt, o
             logWarning("engine", `operation failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    if (opts?.traceId && opts.turnId && opts.gitAction && opts.gitStatus) {
+    const gitTransaction = resolveGitTransactionOptions(request.opts);
+    if (gitTransaction) {
         writeTurnGitTransaction({
-            basePath,
-            traceId: opts.traceId,
-            turnId: opts.turnId,
-            unitType,
-            unitId,
+            basePath: request.basePath,
+            traceId: gitTransaction.traceId,
+            turnId: gitTransaction.turnId,
+            unitType: request.unitType,
+            unitId: request.unitId,
             stage: "record",
-            action: opts.gitAction,
-            push: opts.gitPush === true,
-            status: opts.gitStatus,
-            error: opts.gitError,
+            action: gitTransaction.gitAction,
+            push: gitTransaction.gitPush === true,
+            status: gitTransaction.gitStatus,
+            error: gitTransaction.gitError,
             metadata: {
                 activityFile,
             },
         });
     }
-    return activityFile ?? undefined;
+    return {
+        ...(activityFile ? { activityFile } : {}),
+        gitTransactionRecorded: Boolean(gitTransaction),
+    };
+}
+function resolveGitTransactionOptions(opts) {
+    if (!opts?.traceId || !opts.turnId || !opts.gitAction || !opts.gitStatus)
+        return null;
+    return {
+        traceId: opts.traceId,
+        turnId: opts.turnId,
+        gitAction: opts.gitAction,
+        gitStatus: opts.gitStatus,
+        gitPush: opts.gitPush,
+        gitError: opts.gitError,
+    };
+}
+/**
+ * Compatibility wrapper for existing auto-loop callers. New code should prefer
+ * closeoutAutoUnit so the closeout request and result stay explicit.
+ */
+export async function closeoutUnit(ctx, basePath, unitType, unitId, startedAt, opts) {
+    const result = await closeoutAutoUnit({ ctx, basePath, unitType, unitId, startedAt, opts });
+    return result.activityFile;
 }

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

@@ -23,6 +23,7 @@ import { getSlice } from "./gsd-db.js";
 import { getLedger } from "./metrics.js";
 import { getUnitCostSpikeAction, resolveUnitCostSpikeMultiplier } from "./auto-budget.js";
 import { formatPostUnitStatusCard } from "./auto-status-message.js";
+import { detectWebApp } from "./web-app-uat.js";
 function getCurrentUnitCostStats(unitId) {
     const ledger = getLedger();
     if (!ledger || !Array.isArray(ledger.units) || ledger.units.length === 0) {
@@ -617,14 +618,25 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
             s.pendingVerificationRetry = null;
             return "continue";
         }
+        else if (verdict.reason === "no-host-checks" &&
+            taskAlreadyComplete &&
+            detectWebApp(s.basePath) &&
+            !result.runtimeErrors?.some((e) => e.blocking)) {
+            s.verificationRetryCount.delete(retryKey);
+            s.verificationRetryFailureHashes.delete(retryKey);
+            s.pendingVerificationRetry = null;
+            ctx.ui.notify("No task-level host verification command was found for a completed browser-facing task; continuing so slice UAT can verify the UI with browser tools.", "warning");
+            return "continue";
+        }
         else if (verdict.reason === "no-host-checks") {
             s.verificationRetryCount.delete(retryKey);
             s.verificationRetryFailureHashes.delete(retryKey);
             s.pendingVerificationRetry = null;
-            ctx.ui.notify("Verification gate FAILED — no runnable host-owned verification checks were discovered. Pausing for human review.", "error");
+            const pauseMessage = `Verification failed: ${verdict.failureContext}`;
+            ctx.ui.notify(`Verification gate FAILED — ${verdict.failureContext}`, "error");
             process.stderr.write(`verification-gate: ${verdict.failureContext}\n`);
             await pauseAuto(ctx, pi, {
-                message: "Verification failed: no runnable host-owned verification checks were discovered.",
+                message: pauseMessage,
                 category: "unknown",
             });
             return "pause";

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

@@ -800,6 +800,14 @@ function _resolveIntegrationBranchForReuse(basePath, milestoneId) {
         return null;
     }
 }
+function safeCwd(fallback) {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return fallback;
+    }
+}
 /**
  * When reusing an existing milestone branch, fast-forward it onto the
  * integration branch when that's safe (branch is a strict ancestor of
@@ -949,7 +957,7 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
     originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
     const branch = autoWorktreeBranch(milestoneId);
     const { preserveBranch = false, preserveWorktree = false } = opts;
-    const previousCwd = process.cwd();
+    const previousCwd = safeCwd(originalBasePath);
     // Wrap the entire teardown body in a single try/finally so activeWorkspace
     // is ALWAYS cleared — even if process.chdir throws (e.g. originalBasePath
     // was deleted before teardown ran). Previously the finally only covered
@@ -1033,7 +1041,7 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
  * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath) {
-    const targetPath = isGsdWorktreePath(basePath) ? basePath : process.cwd();
+    const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
     if (!isGsdWorktreePath(targetPath))
         return false;
     const storedBase = getAutoWorktreeOriginalBase();
@@ -1901,6 +1909,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         }
         catch (err) {
             logWarning("worktree", `chdir to project root after merge failed: ${err instanceof Error ? err.message : String(err)}`);
+            debugLog("mergeMilestoneToMain", {
+                phase: "post-merge-chdir-failed",
+                target: originalBasePath_,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     };
     let shouldCleanup = false;

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

@@ -512,6 +512,16 @@ export function _warnIfWorktreeMissingForTest(worktreePath, milestoneId) {
     }
     return false;
 }
+export function anchorProcessCwdForAutoResume(basePath) {
+    try {
+        process.chdir(basePath);
+        return true;
+    }
+    catch (err) {
+        logWarning("session", `resume cwd anchor failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts", basePath });
+        return false;
+    }
+}
 export function isAutoPaused() {
     return s.paused;
 }
@@ -630,6 +640,35 @@ export function stopAutoRemote(projectRoot) {
         return { found: false, error: err.message };
     }
 }
+/**
+ * Force-stop a remote auto-mode session before stealing its lock.
+ * The normal stop path stays SIGTERM-only so cooperative sessions can clean up;
+ * this path is only for the explicit "Force start" action.
+ */
+export function forceStopAutoRemote(projectRoot) {
+    const lock = readCrashLock(projectRoot);
+    if (!lock)
+        return { found: false };
+    if (lock.pid === process.pid) {
+        clearLock(projectRoot);
+        return { found: false };
+    }
+    if (!isLockProcessAlive(lock)) {
+        clearLock(projectRoot);
+        return { found: false };
+    }
+    try {
+        process.kill(lock.pid, "SIGTERM");
+        if (isLockProcessAlive(lock)) {
+            process.kill(lock.pid, "SIGKILL");
+        }
+        clearLock(projectRoot);
+        return { found: true, pid: lock.pid };
+    }
+    catch (err) {
+        return { found: false, error: err.message };
+    }
+}
 /**
  * Check if a remote auto-mode session is running (from a different process).
  * Reads the crash lock, checks PID liveness, and returns session details.
@@ -722,6 +761,9 @@ function pauseAutoUnitIdentityMatches(expected) {
         s.currentUnit.id === expected.id &&
         s.currentUnit.startedAt === expected.startedAt;
 }
+function shouldPreserveCoordinationForPause(errorContext) {
+    return errorContext?.category === "provider" && errorContext.isTransient === true;
+}
 function setLifecycleOutcome(ctx, input) {
     if (!ctx?.hasUI)
         return;
@@ -1556,7 +1598,7 @@ export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
         releaseSessionLock(lockBase());
         clearLock(lockBase());
     }
-    if (s.workerId) {
+    if (s.workerId && !shouldPreserveCoordinationForPause(_errorContext)) {
         try {
             if (s.currentMilestoneId && s.milestoneLeaseToken) {
                 releaseMilestoneLease(s.workerId, s.currentMilestoneId, s.milestoneLeaseToken);
@@ -1831,7 +1873,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     if (freshStartAssessment.classification === "running") {
         const pid = freshStartAssessment.lock?.pid;
         ctx.ui.notify(pid
-            ? `Another auto-mode session (PID ${pid}) appears to be running.\nStop it with \`kill ${pid}\` before starting a new session.`
+            ? `Another auto-mode session (PID ${pid}) appears to be running.\nRun \`/gsd stop\` for graceful shutdown, or choose "Force start" from \`/gsd auto\` to terminate it.`
             : "Another auto-mode session appears to be running.", "error");
         return;
     }
@@ -2001,6 +2043,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         }
         // ADR-016 phase 2 / B3 (#5621): paused-resume worktree-path adoption.
         buildLifecycle().resumeFromPausedSession(base, resumeWorktreePath);
+        anchorProcessCwdForAutoResume(s.basePath || base);
         // Rebuild scope now that s.basePath reflects the actual worktree (or project root).
         rebuildScope(s.basePath, s.currentMilestoneId);
         // Ensure the workflow-logger audit log is pinned to the project root

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

@@ -5,7 +5,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 import { logWarning } from "../workflow-logger.js";
-import { openWorkflowDatabase } from "../db-workspace.js";
+import { getWorkflowDatabaseStatus, openWorkflowDatabase, } from "../db-workspace.js";
 import { getAutoWorktreePath } from "../auto-worktree.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
@@ -61,16 +61,46 @@ export function resolveWorkflowToolBasePath(ctx, scope) {
     return cwd;
 }
 export { resolveProjectRootDbPath } from "../db-workspace.js";
+function sqliteProviderHint(status, nodeVersion) {
+    if (status.provider)
+        return `Provider: ${status.provider}.`;
+    const major = Number.parseInt(nodeVersion.split(".")[0] ?? "", 10);
+    if (Number.isFinite(major) && major < 22) {
+        return (`No SQLite provider available. Upgrade Node to >= 22.0.0 (current: v${nodeVersion}), ` +
+            "use the packaged GSD runtime, or install/restore better-sqlite3 in this runtime.");
+    }
+    return ("No SQLite provider available. Use a Node build with node:sqlite enabled, " +
+        "run the packaged GSD runtime, or install/restore better-sqlite3 in this runtime.");
+}
+function dbOpenPhaseHint(status) {
+    if (status.lastPhase === "open")
+        return "The database file could not be opened";
+    if (status.lastPhase === "initSchema")
+        return "The database schema could not be initialized";
+    if (status.lastPhase === "vacuum-recovery")
+        return "Corruption recovery (VACUUM) failed";
+    if (status.attempted)
+        return "The database could not be opened";
+    return "The database provider could not be loaded";
+}
+export function formatWorkflowDatabaseOpenFailure(result, status, nodeVersion = process.versions.node) {
+    if (result.reason === "missing-gsd-dir") {
+        return `ensureDbOpen failed — no .gsd directory found at ${result.location.projectGsd}`;
+    }
+    if (result.reason === "missing-database") {
+        return `ensureDbOpen failed — no GSD database found at ${result.location.projectDb}`;
+    }
+    const resolvedStatus = status ?? getWorkflowDatabaseStatus();
+    const detail = result.error?.message ?? resolvedStatus.lastError?.message ?? "";
+    const detailSuffix = detail ? ` (${detail})` : "";
+    return (`ensureDbOpen failed for ${result.location.projectDb}: ` +
+        `${dbOpenPhaseHint(resolvedStatus)}${detailSuffix}. ${sqliteProviderHint(resolvedStatus, nodeVersion)}`);
+}
 export async function ensureDbOpen(basePath = safeWorkspaceCwd()) {
     const result = openWorkflowDatabase(basePath);
     if (result.ok)
         return true;
-    if (result.reason === "missing-gsd-dir") {
-        logWarning("bootstrap", "ensureDbOpen failed — no .gsd directory found");
-    }
-    else {
-        logWarning("bootstrap", `ensureDbOpen failed: ${result.error?.message ?? "open failed"}`);
-    }
+    logWarning("bootstrap", formatWorkflowDatabaseOpenFailure(result));
     return false;
 }
 export function registerDynamicTools(pi) {

package/dist/resources/extensions/gsd/commands/context.js

@@ -1,4 +1,4 @@
-import { checkRemoteAutoSession, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
+import { checkRemoteAutoSession, forceStopAutoRemote, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
 import { validateDirectory } from "../validate-directory.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { showNextAction } from "../../shared/tui.js";
@@ -135,5 +135,19 @@ export async function guardRemoteSession(ctx, pi) {
         }
         return false;
     }
-    return choice === "force";
+    if (choice === "force") {
+        const result = forceStopAutoRemote(projectRoot());
+        if (result.error) {
+            ctx.ui.notify(`Failed to force-stop remote auto-mode: ${result.error}`, "error");
+            return false;
+        }
+        if (result.found) {
+            ctx.ui.notify(`Force-stopped auto-mode session (PID ${result.pid}). Starting a new session.`, "warning");
+        }
+        else {
+            ctx.ui.notify("Remote session is no longer running. Starting a new session.", "info");
+        }
+        return true;
+    }
+    return false;
 }

package/dist/resources/extensions/gsd/commands-mcp-status.js

@@ -59,7 +59,7 @@ export function formatMcpStatusReport(servers) {
                 : s.connected
                     ? `connected — ${s.toolCount} tools`
                     : s.available
-                        ? `available — ${s.toolCount} tools`
+                        ? `probe available — ${s.toolCount} tools`
                         : "disconnected";
         const warningText = s.envWarnings?.length ? ` — ${s.envWarnings.length} warning(s)` : "";
         lines.push(`  ${icon} ${s.name} (${s.transport}) — ${status}${warningText}`);
@@ -83,7 +83,7 @@ export function formatMcpServerDetail(server) {
         lines.push(`  Error:     ${server.error}`);
     }
     else if (server.connected || server.available) {
-        lines.push(`  Status:    ${server.connected ? "connected" : "available"}`);
+        lines.push(`  Status:    ${server.connected ? "connected" : "probe available"}`);
         lines.push(`  Tools:     ${server.toolCount}`);
         if (server.tools.length > 0) {
             lines.push("");