@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.9ad8ae33

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,32 +5,25 @@ 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,
   RUN_UAT_BROWSER_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
 
-const EXECUTE_TASK_UNIT_TYPES = new Set([
-  "execute-task",
-  "execute-task-simple",
-  "reactive-execute",
-]);
-
-// These units own quality gates, but their completion handlers persist verdicts
-// from artifact sections. gsd_save_gate_result belongs to gate-evaluate, so keep
-// blocking it here with a calm redirect to the section-write path.
-const SECTION_CLOSE_GATE_UNIT_TYPES = new Set([
-  "execute-task",
-  "execute-task-simple",
-  "reactive-execute",
-  "complete-slice",
-  "validate-milestone",
-]);
+// Scope-class membership is declared per unit in the Unit Registry (ADR-033).
+// EXECUTE_TASK_UNIT_TYPES = scopeClass "execute-task"; the section-close gate
+// Set additionally includes scopeClass "section-close" — units whose completion
+// handlers persist gate verdicts from artifact sections (gsd_save_gate_result
+// belongs to gate-evaluate, so it is soft-blocked with a redirect below).
+import {
+  EXECUTE_TASK_UNIT_TYPES,
+  SECTION_CLOSE_GATE_UNIT_TYPES,
+} from "./unit-registry.js";
 
 const EXTRA_SCOPED_GSD_LIFECYCLE_TOOLS = [
   "gsd_skip_slice",
@@ -58,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);
@@ -110,7 +103,7 @@ function isNativeWorkflowTool(toolName: string): boolean {
   return stripMcpToolPrefix(toolName) === "Workflow";
 }
 
-function readStringField(input: unknown, camel: string, snake: string): string | undefined {
+export function readStringField(input: unknown, camel: string, snake: string): string | undefined {
   if (!input || typeof input !== "object") return undefined;
   const record = input as Record<string, unknown>;
   const value = record[camel] ?? record[snake];

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

@@ -44,23 +44,21 @@ import {
   worktreePath,
   isInsideWorktreesDir,
 } from "./worktree-manager.js";
+import { worktreePathFor } from "./worktree-placement.js";
 import {
   detectWorktreeName,
   resolveGitHeadPath,
   nudgeGitBranchCache,
 } from "./worktree.js";
 import {
-  findWorktreeSegment,
   isGsdWorktreePath,
+  projectRootFromWorktreePath,
   normalizeWorktreePathForCompare,
   resolveWorktreeProjectRoot,
 } from "./worktree-root.js";
 import { autoResolveSafeConflictPaths } from "./git-conflict-resolve.js";
 import { MergeConflictError, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
-import {
-  buildPullRequestEvidence,
-  createDraftPullRequestFromEvidence,
-} from "./pull-request-process.js";
+import { publishMilestone } from "./publication.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import {
@@ -73,9 +71,6 @@ import {
   stashAlreadyExistsFilesFromError,
   stashRefFromError,
 } from "./worktree-git-recovery.js";
-
-// Re-export for existing callers/tests (auto-start.ts, checkout-branch-stash-guard.test.ts).
-export { checkoutBranchWithStashGuard } from "./worktree-git-recovery.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
@@ -290,19 +285,6 @@ export function _gitPathspecForWorktreePath(basePath: string, targetPath: string
   return gitPathspecForWorktreePath(basePath, targetPath);
 }
 
-function gitRemoteExists(basePath: string, remote: string): boolean {
-  try {
-    execFileSync("git", ["remote", "get-url", remote], {
-      cwd: basePath,
-      stdio: ["ignore", "pipe", "pipe"],
-      encoding: "utf-8",
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function findRegularMergeChangedPaths(basePath: string, milestoneBranch: string, mainBranch: string): Set<string> {
   const changedPaths = new Set<string>();
   let mergeLog = "";
@@ -520,12 +502,8 @@ export function checkResourcesStale(
  * Returns the corrected base path.
  */
 export function escapeStaleWorktree(base: string): string {
-  const segment = findWorktreeSegment(base.replaceAll("\\", "/"));
-  if (!segment) return base;
-
-  // base is inside .gsd/worktrees/<something> — extract the project root.
-  // Normalization is 1:1 on characters, so the segment index is valid in `base`.
-  const projectRoot = base.slice(0, segment.gsdIdx);
+  const projectRoot = projectRootFromWorktreePath(base);
+  if (projectRoot === null) return base;
 
   // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
   // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
@@ -994,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
@@ -1177,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
@@ -1307,7 +1293,9 @@ export function getAutoWorktreePath(
 ): string | null {
   basePath = resolveWorktreeProjectRoot(basePath);
 
-  const p = worktreePath(basePath, milestoneId);
+  // basePath is already the resolved project root — go straight to placement
+  // instead of worktreePath(), which would re-resolve the root.
+  const p = worktreePathFor(basePath, milestoneId);
   if (!existsSync(p)) return null;
 
   // Validate this is a real git worktree, not a stray directory.
@@ -2049,8 +2037,6 @@ export function mergeMilestoneToMain(
       const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
       const gsdContentConflicts: string[] = [];
       const alreadyExists = stashAlreadyExistsFilesFromError(e);
-      const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
-      const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
 
       // Untracked-file restore failures can leave marker conflicts in tracked
       // .gsd JSONL files without producing `U` status entries.
@@ -2114,11 +2100,12 @@ export function mergeMilestoneToMain(
       } else if (
         gsdUU.length === 0 &&
         nonGsdUU.length === 0 &&
-        gsdAlreadyExists.length > 0 &&
-        nonGsdAlreadyExists.length === 0
+        alreadyExists.length > 0
       ) {
-        // Untracked-file restore failure from stash pop where all collided
-        // paths are .gsd/ artifacts that already exist after merge.
+        // Untracked-file restore failure from stash pop where all collided paths
+        // already exist after merge (committed on target). Safe to drop the stash
+        // for the full alreadyExists set — they were untracked on source by
+        // definition of the "already exists, no checkout" failure.
         if (stashRefForDrop) {
           try {
             execFileSync("git", ["stash", "drop", stashRefForDrop], {
@@ -2137,10 +2124,6 @@ export function mergeMilestoneToMain(
         logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", {
           files: nonGsdUU.join(", "),
         });
-      } else if (nonGsdAlreadyExists.length > 0) {
-        logWarning("reconcile", "Stash pop restore collision on non-.gsd files after merge", {
-          files: nonGsdAlreadyExists.join(", "),
-        });
       } else {
         logWarning(
           "worktree",
@@ -2254,66 +2237,33 @@ 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),
+      });
     }
   };
 
   let shouldCleanup = false;
-  let pushed = false;
-  let prCreated = false;
   try {
-    // 10. Auto-push if enabled
-    if (prefs.auto_push === true && prefs.auto_pr !== true && !nothingToCommit) {
-      const remote = prefs.remote ?? "origin";
-      if (gitRemoteExists(originalBasePath_, remote)) {
-        try {
-          execFileSync("git", ["push", remote, mainBranch], {
-            cwd: originalBasePath_,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-          });
-          pushed = true;
-        } catch (err) {
-          // Push failure is non-fatal
-          logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-      }
-    }
-
-    // 9b. Auto-create PR if enabled (#2302: no longer gated on pushed/auto_push)
-    if (prefs.auto_pr === true && !nothingToCommit) {
-      const remote = prefs.remote ?? "origin";
-      const prTarget = prefs.pr_target_branch ?? mainBranch;
-      if (gitRemoteExists(originalBasePath_, remote)) {
-        try {
-          // Push the milestone branch to remote first
-          execFileSync("git", ["push", remote, milestoneBranch], {
-            cwd: originalBasePath_,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-          });
-          const prEvidence = buildPullRequestEvidence({
-            milestoneId,
-            milestoneTitle,
-            changeType: "feat",
-            summaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
-            testsRun: ["Auto-created after milestone merge. Run `npm run verify:merge` before marking this draft ready."],
-            rollbackNotes: ["Close the draft PR or revert the merge commit if review finds a behavior regression."],
-            how: "Generated by git.auto_pr after the milestone branch was pushed and merged locally.",
-          });
-          const prUrl = createDraftPullRequestFromEvidence(originalBasePath_, milestoneId, prEvidence, {
-            head: milestoneBranch,
-            base: prTarget,
-          });
-          if (!prUrl) {
-            throw new Error("gh pr create returned no URL");
-          }
-          prCreated = true;
-        } catch (err) {
-          // PR creation failure is non-fatal — gh may not be installed or authenticated
-          logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-      }
-    }
+    // 10/9b. Publication (auto-push / draft PR) — Publication module seam (ADR-034).
+    const publication = publishMilestone({
+      basePath: originalBasePath_,
+      milestoneId,
+      milestoneTitle,
+      integrationBranch: mainBranch,
+      milestoneBranch,
+      sliceSummaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
+      nothingToCommit,
+      prefs: {
+        autoPush: prefs.auto_push === true,
+        autoPr: prefs.auto_pr === true,
+        remote: prefs.remote,
+        prTargetBranch: prefs.pr_target_branch,
+      },
+    });
+    const { pushed, prCreated } = publication;
 
     // 11. Guard removed — step 9b (#1792) now handles this with a smarter check:
     //     throws only when the milestone has unanchored code changes, passes

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

@@ -331,6 +331,11 @@ import {
 } from "./db/auto-workers.js";
 import { releaseMilestoneLease } from "./db/milestone-leases.js";
 import { normalizeRealPath } from "./paths.js";
+import {
+  formatStopNoticePrefix,
+  isBlockedStopReason,
+  stopNoticeDisplayReason,
+} from "./stop-notice.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -355,19 +360,7 @@ export function formatAutoStopNotification(prefix: string, totals: { cost: numbe
   ].join("\n");
 }
 
-function isBlockedStopReason(reason?: string | null): boolean {
-  return /^Blocked:\s*/i.test(reason ?? "");
-}
-
-function formatAutoStopDisplayReason(reason?: string | null): string {
-  return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
-}
-
-export function formatAutoStopNotificationPrefix(reason?: string | null): string {
-  const displayReason = formatAutoStopDisplayReason(reason);
-  const prefix = isBlockedStopReason(reason) ? "Auto-mode blocked" : "Auto-mode stopped";
-  return displayReason ? `${prefix} — ${displayReason}` : prefix;
-}
+export { formatStopNoticePrefix as formatAutoStopNotificationPrefix } from "./stop-notice.js";
 
 function clearSessionModelOverrideForCommandSession(ctx?: ExtensionContext | null): void {
   const sessionId =
@@ -931,6 +924,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);
@@ -1007,6 +1008,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.
@@ -1465,8 +1501,8 @@ export async function stopAuto(
 ): Promise<void> {
   if (!s.active && !s.paused) return;
   const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
-  const stopNotificationPrefix = formatAutoStopNotificationPrefix(reason);
-  const displayReason = formatAutoStopDisplayReason(reason);
+  const stopNotificationPrefix = formatStopNoticePrefix(reason);
+  const displayReason = stopNoticeDisplayReason(reason);
   const isHeadlessStop = process.env.GSD_HEADLESS === "1";
   const completionStopRequested = Boolean(options.completionWidget);
   const preserveCloseoutTranscript = !isHeadlessStop && (
@@ -2407,7 +2443,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",
     );