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

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

@@ -58,7 +58,11 @@ import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
-import { resolveEffectiveUatType, shouldDispatchUatForContent, type UatType } from "./uat-policy.js";
+import {
+  classifyUatContentForRun,
+  shouldDispatchUatForContent,
+  type UatType,
+} from "./uat-policy.js";
 import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
@@ -972,7 +976,7 @@ export async function inlineDecisionsFromDb(
 
 /**
  * Inline requirements with optional milestone and slice scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable.
  */
 export async function inlineRequirementsFromDb(
   base: string, milestoneId?: string, sliceId?: string, level?: InlineLevel,
@@ -982,14 +986,28 @@ export async function inlineRequirementsFromDb(
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
       const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-      const requirements = queryRequirements({ milestoneId, sliceId });
+      let requirements = queryRequirements({ milestoneId, sliceId });
+      let broadenedScope = false;
+      if (requirements.length === 0 && sliceId) {
+        requirements = queryRequirements({ milestoneId });
+        broadenedScope = true;
+      }
+      if (requirements.length === 0 && milestoneId) {
+        requirements = queryRequirements({ status: "active" });
+        broadenedScope = true;
+      }
       if (requirements.length > 0) {
-        // Use compact format for non-full levels to save ~40% tokens
-        const formatted = inlineLevel !== "full"
+        // Use compact format for non-full levels, milestone-scoped calls, and
+        // any cascade stage that broadened past the originally requested scope —
+        // a slice-scoped "full" call that fell through to the project-wide
+        // active fallback must not format those rows as full requirements.
+        const useCompact = inlineLevel !== "full" || !sliceId || broadenedScope;
+        const formatted = useCompact
           ? formatRequirementsCompact(requirements)
           : formatRequirementsForPrompt(requirements);
         return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
       }
+      return null;
     }
   } catch (err) {
     logWarning("prompt", `inlineRequirementsFromDb failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1445,6 +1463,40 @@ export async function checkNeedsReassessment(
  * - No UAT file exists for the slice
  * - UAT result file already exists (idempotent — already ran)
  */
+/**
+ * Resolve the effective UAT mode for the dispatch gate the same way
+ * `buildRunUatPrompt` does: classify the UAT body with the slice's SUMMARY as
+ * supplemental context, so a `browser-executable` UAT whose slice references a
+ * self-contained harness (`npm run test:uat`, `search-uat.mjs`, `npx
+ * playwright test`) is promoted to `runtime-executable` for the gate too.
+ *
+ * Without this, `checkNeedsRunUat` returns `browser-executable` while the
+ * prompt instructs runtime-only execution, causing the dispatch gate to
+ * require browser tools / warm up the browser daemon (or stop dispatch when
+ * browser MCP is unavailable) for UAT runs that never touch the browser. See
+ * cursor[bot] review on PR #696 for the M007/S01 regression.
+ */
+async function resolveRunUatEffectiveType(
+  base: string,
+  mid: string,
+  sliceId: string,
+  uatContent: string,
+): Promise<UatType> {
+  let summaryContent = "";
+  try {
+    const summaryPath = resolveSliceFile(base, mid, sliceId, "SUMMARY");
+    if (summaryPath) {
+      summaryContent = (await loadFile(summaryPath)) ?? "";
+    }
+  } catch (err) {
+    logWarning(
+      "prompt",
+      `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
+
 export async function checkNeedsRunUat(
   base: string, mid: string, state: GSDState, prefs: GSDPreferences | undefined,
 ): Promise<{ sliceId: string; uatType: UatType } | null> {
@@ -1473,7 +1525,8 @@ export async function checkNeedsRunUat(
             if (assessmentContent && hasVerdict(assessmentContent)) continue;
           }
           if (!shouldDispatchUatForContent(uatContent, prefs)) continue;
-          return { sliceId: sid, uatType: resolveEffectiveUatType(uatContent) };
+          const uatType = await resolveRunUatEffectiveType(base, mid, sid, uatContent);
+          return { sliceId: sid, uatType };
         }
         return null;
       }
@@ -1506,7 +1559,8 @@ export async function checkNeedsRunUat(
       if (assessmentContentFb && hasVerdict(assessmentContentFb)) continue;
     }
     if (!shouldDispatchUatForContent(uatContentFb, prefs)) continue;
-    return { sliceId: uatSid, uatType: resolveEffectiveUatType(uatContentFb) };
+    const uatType = await resolveRunUatEffectiveType(base, mid, uatSid, uatContentFb);
+    return { sliceId: uatSid, uatType };
   }
   return null;
 }
@@ -3560,15 +3614,30 @@ export async function buildRunUatPrompt(
     null,
     cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget",
   );
+  const uatPolicy = classifyUatContentForRun(uatContent, cappedInlinedContext);
+  const uatType = uatPolicy.effectiveType;
+  const runtimeHarnessOverride = uatPolicy.declaredType === "browser-executable" && uatType === "runtime-executable"
+    ? [
+      "## Runtime harness override",
+      "",
+      "This UAT declares `browser-executable` but the slice references a self-contained verification command (`npm run test:uat`, `search-uat.mjs`, or similar).",
+      "Run **only** that command via `gsd_uat_exec` with `uat-runtime-check` intent.",
+      "Do **not** call `uat-service-start`, do **not** run `npm run start`, `npm run test:server`, or any separate server command.",
+      "Do **not** use `browser_navigate` or other `browser_*` tools — the harness already exercises the browser.",
+      "When the harness exits 0, save **PASS** with `uatType: \"runtime-executable\"` (the effective mode above, not the UAT file header) and **runtime** check modes only.",
+      "",
+    ].join("\n")
+    : "";
   const inlinedContext = prependContextModeToBlock(
     "run-uat",
     base,
-    cappedInlinedContext,
+    runtimeHarnessOverride
+      ? `${runtimeHarnessOverride}\n${cappedInlinedContext}`
+      : cappedInlinedContext,
   );
   emitPromptContextTelemetry("run-uat", contextTelemetry, inlinedContext);
 
   const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
-  const uatType = resolveEffectiveUatType(uatContent);
   const canonicalPresentation = JSON.stringify(buildRunUatPresentationForType(uatType), null, 2);
 
   return loadPrompt("run-uat", {

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

@@ -28,6 +28,7 @@ import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-ide
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile } from "./paths.js";
+import { milestoneEntryBlockedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
 import {
@@ -1270,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) {
@@ -1296,6 +1315,8 @@ export async function bootstrapAutoSession(
         formatStrandedWorkRecoveryMessage(strandedRecoveryAction),
         "info",
       );
+    } else if (lockedActiveMilestone) {
+      strandedRecoveryAction = null;
     }
 
     if (
@@ -1645,14 +1666,9 @@ export async function bootstrapAutoSession(
             `Cannot enter milestone ${s.currentMilestoneId}: lease is held by another worker.`,
             "error",
           );
-        } else if (enterResult.reason === "creation-failed") {
-          ctx.ui.notify(
-            `Cannot enter milestone ${s.currentMilestoneId}: worktree/branch creation failed. Isolation is degraded.`,
-            "error",
-          );
-        } else if (enterResult.reason === "isolation-degraded") {
+        } else if (enterResult.reason === "creation-failed" || enterResult.reason === "isolation-degraded") {
           ctx.ui.notify(
-            `Cannot enter milestone ${s.currentMilestoneId}: isolation is degraded from a prior worktree failure. Close processes locking the worktree and retry, or run /gsd doctor fix.`,
+            milestoneEntryBlockedGuidance(s.currentMilestoneId, enterResult.reason),
             "error",
           );
         } else if (enterResult.reason === "invalid-milestone-id") {

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-unit-tool-scope.ts

@@ -5,10 +5,10 @@ import {
 } from "./unit-tool-contracts.js";
 import {
   WORKFLOW_TOOL_ALIAS_PAIRS,
-  canonicalWorkflowSurfaceToolName,
   isWorkflowSurfaceAliasTool,
   stripMcpToolPrefix,
 } from "./workflow-tool-surface.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 
 export {
   AUTO_UNIT_SCOPED_TOOLS,
@@ -51,9 +51,9 @@ type AutoUnitToolScopeResult = {
   displayReason?: string;
 };
 
-export function canonicalWorkflowToolName(toolName: string): string {
-  return canonicalWorkflowSurfaceToolName(toolName);
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing scope importers.
+export { canonicalWorkflowToolName };
 
 export function isWorkflowAliasTool(toolName: string): boolean {
   return isWorkflowSurfaceAliasTool(toolName);

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

@@ -15,7 +15,7 @@
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { gsdProjectionRoot, resolveSliceFile, resolveSlicePath, resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, resolveSliceFile, resolveSlicePath } from "./paths.js";
 import { resolveMilestoneValidationVerdict } from "./milestone-validation-verdict.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { parseUnitId } from "./unit-id.js";
@@ -25,8 +25,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { GSDPreferences } from "./preferences-types.js";
 import { isClosedStatus } from "./status-guards.js";
 import { loadFile } from "./files.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { isMilestoneComplete } from "./state.js";
 import {
   runVerificationGate,
   runVerificationGateForTargets,
@@ -52,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;
@@ -373,29 +372,13 @@ async function runValidateMilestonePostCheck(
  * DB-backed projects are authoritative (#4094 peer review); falls back to
  * roadmap parsing only when the DB is unavailable.
  */
-async function countIncompleteSlices(basePath: string, milestoneId: string): Promise<number> {
-  if (isDbAvailable()) {
-    const slices = getMilestoneSlices(milestoneId);
-    if (slices.length === 0) {
-      // No DB rows — treat as "unknown", do not pause.
-      return 1;
-    }
-    return slices.filter((slice) => !isClosedStatus(slice.status)).length;
-  }
-
-  // Filesystem fallback: parse the roadmap markdown.
-  try {
-    const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    if (!roadmapFile) return 1;
-    const roadmapContent = await loadFile(roadmapFile);
-    if (!roadmapContent) return 1;
-    const roadmap = parseRoadmap(roadmapContent);
-    if (roadmap.slices.length === 0) return 1;
-    return isMilestoneComplete(roadmap) ? 0 : 1;
-  } catch {
-    // Parsing failures should not cause false-positive pauses.
-    return 1;
-  }
+async function countIncompleteSlices(_basePath: string, milestoneId: string): Promise<number> {
+  // DB-authoritative (ADR-017): no markdown fallback. DB unavailable or no
+  // rows means "unknown" — do not pause.
+  if (!isDbAvailable()) return 1;
+  const slices = getMilestoneSlices(milestoneId);
+  if (slices.length === 0) return 1;
+  return slices.filter((slice) => !isClosedStatus(slice.status)).length;
 }
 
 /**
@@ -805,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;
 }
@@ -924,6 +938,14 @@ export function setCurrentDispatchedModelId(model: { provider: string; id: strin
   s.currentDispatchedModelId = model ? `${model.provider}/${model.id}` : null;
 }
 
+/**
+ * Update the active unit model after runtime recovery switches models mid-unit.
+ * The next session restore path reads this field before dispatching again.
+ */
+export function setCurrentUnitModelForRecovery(model: any | null): void {
+  s.currentUnitModel = model;
+}
+
 // Tool tracking — delegates to auto-tool-tracking.ts
 export function markToolStart(toolCallId: string, toolName?: string): void {
   _markToolStart(toolCallId, s.active, toolName);
@@ -1000,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.
@@ -1117,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: {
@@ -2077,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);
@@ -2400,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",
     );
@@ -2595,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