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

package/src/resources/extensions/gsd/auto/workflow-unit-dispatch.ts

@@ -10,7 +10,7 @@ import type {
 } from "./types.js";
 import { ExecutionGraphScheduler } from "../uok/execution-graph.js";
 import type { UokGraphNode } from "../uok/contracts.js";
-import { runUnitPhase } from "./phases.js";
+import { runUnitPhase } from "./unit-phase.js";
 import { decideDispatchNodeKind } from "./workflow-kernel.js";
 
 export type DispatchContract = "legacy-direct" | "uok-scheduler";

package/src/resources/extensions/gsd/auto/worktree-safety-phase.ts

@@ -0,0 +1,149 @@
+// Project/App: gsd-pi
+// File Purpose: Worktree-safety helpers shared across auto-loop phase modules.
+
+import { classifyProject } from "../detection.js";
+import { resolveEffectiveUnitIsolationMode, getIsolationMode } from "../preferences.js";
+import { createWorktreeSafetyModule, type WorktreeSafetyResult } 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";
+import type { IterationContext } from "./types.js";
+
+export function shouldDegradeEmptyWorktreeToProjectRoot(
+  worktreeClassification: ReturnType<typeof classifyProject>,
+  projectRootClassification: ReturnType<typeof classifyProject>,
+): boolean {
+  return (
+    worktreeClassification.kind === "greenfield" &&
+    projectRootClassification.kind !== "greenfield" &&
+    projectRootClassification.kind !== "invalid-repo"
+  );
+}
+
+export function unitWritesSource(unitType: string): boolean | null {
+  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: Extract<WorktreeSafetyResult, { ok: false }>): string {
+  return `Worktree Safety failed (${result.kind}): ${result.reason} ${result.remediation}`;
+}
+
+export function formatWorktreeSafetyStopReason(result: Extract<WorktreeSafetyResult, { ok: false }>): string {
+  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: string,
+  projectRoot: string,
+): boolean {
+  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: IterationContext,
+  unitType: string,
+  unitId: string,
+  milestoneId: string | undefined,
+  phase: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  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/src/resources/extensions/gsd/auto-direct-dispatch.ts

@@ -31,10 +31,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { MinimalModelRegistry } from "./context-budget.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: ExtensionCommandContext,
@@ -256,18 +253,15 @@ export async function dispatchDirectPhase(
       return;
   }
 
-  const compatibilityError = getWorkflowTransportSupportError(
-    ctx.model?.provider,
-    getRequiredWorkflowToolsForAutoUnit(unitType),
-    {
-      projectRoot,
-      surface: "direct phase dispatch",
-      unitType,
-      authMode: ctx.model?.provider ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) : undefined,
-      baseUrl: ctx.model?.baseUrl,
-      activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
-    },
-  );
+  const compatibilityError = getUnitWorkflowDispatchReadinessError({
+    provider: ctx.model?.provider,
+    projectRoot,
+    surface: "direct phase dispatch",
+    unitType,
+    authMode: ctx.model?.provider ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) : undefined,
+    baseUrl: ctx.model?.baseUrl,
+    activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+  });
   if (compatibilityError) {
     ctx.ui.notify(compatibilityError, "error");
     return;

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -91,11 +91,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,
@@ -745,11 +742,15 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // 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" as const, reason: transportError, level: "warning" as const };
       }

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

@@ -2025,16 +2025,30 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         );
       } 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 });
+          // 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}. The tool surface may still be registering — retrying.`,
+            `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);
           const errMsg = isUserSkip
@@ -2193,6 +2207,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         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/src/resources/extensions/gsd/auto-start.ts

@@ -1271,11 +1271,29 @@ export async function bootstrapAutoSession(
       }
     }
 
-    const blockingStrandedRecoveryAction = state.activeMilestone
-      ? strandedRecoveryActions.find(
+    const requestedMilestoneLock = process.env.GSD_MILESTONE_LOCK?.trim() || null;
+    const lockedActiveMilestone =
+      requestedMilestoneLock && state.activeMilestone?.id === requestedMilestoneLock;
+    let blockingStrandedRecoveryAction: OrphanAuditAction | null;
+    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
-      : strandedRecoveryAction;
+      ) ?? strandedRecoveryAction;
+    } else {
+      blockingStrandedRecoveryAction = strandedRecoveryAction;
+    }
 
     if (blockingStrandedRecoveryAction) {
       if (!state.activeMilestone) {
@@ -1297,6 +1315,8 @@ export async function bootstrapAutoSession(
         formatStrandedWorkRecoveryMessage(strandedRecoveryAction),
         "info",
       );
+    } else if (lockedActiveMilestone) {
+      strandedRecoveryAction = null;
     }
 
     if (

package/src/resources/extensions/gsd/auto-unit-closeout.ts

@@ -33,6 +33,24 @@ export interface UnitActivitySnapshot {
   assistantMessages: number;
 }
 
+export interface AutoUnitCloseoutRequest {
+  ctx: ExtensionContext;
+  basePath: string;
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  opts?: CloseoutOptions;
+}
+
+export interface AutoUnitCloseoutResult {
+  activityFile?: string;
+  gitTransactionRecorded: boolean;
+}
+
+type GitTransactionCloseoutOptions =
+  Required<Pick<CloseoutOptions, "traceId" | "turnId" | "gitAction" | "gitStatus">>
+  & Pick<CloseoutOptions, "gitPush" | "gitError">;
+
 export const GHOST_COMPLETION_MAX_ELAPSED_MS = 500;
 
 export function snapshotUnitActivity(
@@ -76,25 +94,27 @@ export function isSuspiciousGhostCompletion(
 }
 
 /**
- * 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: ExtensionContext,
-  basePath: string,
-  unitType: string,
-  unitId: string,
-  startedAt: number,
-  opts?: CloseoutOptions,
-): Promise<string | undefined> {
-  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: AutoUnitCloseoutRequest,
+): Promise<AutoUnitCloseoutResult> {
+  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
@@ -103,11 +123,11 @@ export async function closeoutUnit(
         // 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 as Error).message}`,
+            `memory extraction failed for ${request.unitType}/${request.unitId}: ${(err as Error).message}`,
           );
         }
       }
@@ -116,23 +136,58 @@ export async function closeoutUnit(
     }
   }
 
-  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: CloseoutOptions | undefined,
+): GitTransactionCloseoutOptions | null {
+  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: ExtensionContext,
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+  opts?: CloseoutOptions,
+): Promise<string | undefined> {
+  const result = await closeoutAutoUnit({ ctx, basePath, unitType, unitId, startedAt, opts });
+  return result.activityFile;
 }

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

@@ -50,6 +50,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";
 
 export interface VerificationContext {
   s: AutoSession;
@@ -787,17 +788,32 @@ export async function runPostUnitVerification(
       s.verificationRetryFailureHashes.delete(retryKey);
       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;
+      const pauseMessage = `Verification failed: ${verdict.failureContext}`;
       ctx.ui.notify(
-        "Verification gate FAILED — no runnable host-owned verification checks were discovered. Pausing for human review.",
+        `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/src/resources/extensions/gsd/auto-worktree.ts

@@ -972,6 +972,14 @@ function _resolveIntegrationBranchForReuse(
   }
 }
 
+function safeCwd(fallback: string): string {
+  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
@@ -1155,7 +1163,7 @@ export function teardownAutoWorktree(
 
   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
@@ -1250,7 +1258,7 @@ export function teardownAutoWorktree(
  * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath: string): boolean {
-  const targetPath = isGsdWorktreePath(basePath) ? basePath : process.cwd();
+  const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
   if (!isGsdWorktreePath(targetPath)) return false;
 
   const storedBase = getAutoWorktreeOriginalBase();
@@ -2229,6 +2237,11 @@ export function mergeMilestoneToMain(
       process.chdir(originalBasePath_);
     } 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),
+      });
     }
   };
 

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

@@ -859,6 +859,20 @@ export function _warnIfWorktreeMissingForTest(
   return false;
 }
 
+export function anchorProcessCwdForAutoResume(basePath: string): boolean {
+  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(): boolean {
   return s.paused;
 }
@@ -1008,6 +1022,41 @@ export function stopAutoRemote(projectRoot: string): {
   }
 }
 
+/**
+ * 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: string): {
+  found: boolean;
+  pid?: number;
+  error?: string;
+} {
+  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 as Error).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.
@@ -1125,6 +1174,10 @@ function pauseAutoUnitIdentityMatches(expected: PauseAutoUnitIdentity | null): b
     s.currentUnit.startedAt === expected.startedAt;
 }
 
+function shouldPreserveCoordinationForPause(errorContext?: ErrorContext): boolean {
+  return errorContext?.category === "provider" && errorContext.isTransient === true;
+}
+
 function setLifecycleOutcome(
   ctx: ExtensionContext | undefined,
   input: {
@@ -2085,7 +2138,7 @@ export async function pauseAuto(
     clearLock(lockBase());
   }
 
-  if (s.workerId) {
+  if (s.workerId && !shouldPreserveCoordinationForPause(_errorContext)) {
     try {
       if (s.currentMilestoneId && s.milestoneLeaseToken) {
         releaseMilestoneLease(s.workerId, s.currentMilestoneId, s.milestoneLeaseToken);
@@ -2408,7 +2461,7 @@ export async function startAuto(
     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",
     );
@@ -2603,6 +2656,7 @@ export async function startAuto(
     }
     // 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