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

package/src/resources/extensions/gsd/web-app-uat.ts

@@ -1,10 +1,12 @@
 // Project/App: gsd-pi
-// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { resolveAmbientBrowserEngineResolution, type BrowserEngineResolution } from "../browser-tools/engine/selection.js";
 import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES, type UatType } from "./uat-policy.js";
 
 export { detectWebApp };
 
@@ -47,24 +49,61 @@ export function findPlaywrightTestScript(projectRoot: string): string | null {
   return null;
 }
 
+function describeBrowserToolBacking(engineResolution: BrowserEngineResolution): string {
+  switch (engineResolution.engine) {
+    case "gsd-browser":
+      return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+    case "legacy":
+      return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+    case "off":
+      return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+  }
+}
+
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE: ReadonlyArray<{ mode: UatType; bullet: string }> = [
+  {
+    mode: "browser-executable",
+    bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+  },
+  {
+    mode: "runtime-executable",
+    bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+  },
+  {
+    mode: "mixed",
+    bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+  },
+];
+
 /**
  * Markdown block injected into plan/complete-slice prompts when the project
- * looks browser-facing. Returns null for CLI/library-only repos.
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
  */
-export function buildWebAppUatGuidanceBlock(projectRoot: string): string | null {
+export function buildWebAppUatGuidanceBlock(
+  projectRoot: string,
+  engineResolution?: BrowserEngineResolution,
+): string | null {
   if (!detectWebApp(projectRoot)) return null;
 
+  const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+  const browserToolsAvailable = resolvedEngine.engine !== "off";
   const playwrightScript = findPlaywrightTestScript(projectRoot);
   const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
   const lines = [
     "### Web App UAT (detected)",
     "",
-    "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools by default for run-uat.",
+    describeBrowserToolBacking(resolvedEngine),
     "",
     "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
-    "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
-    "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
-    "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    ...UAT_MODE_GUIDANCE
+      .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+      .map(({ bullet }) => bullet),
     "",
     "**Planning / closeout rules:**",
     "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
@@ -93,8 +132,12 @@ export function buildWebAppUatGuidanceBlock(projectRoot: string): string | null
       "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.",
       "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)",
       "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command",
-      "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout",
     );
+    if (browserToolsAvailable) {
+      lines.push(
+        "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout",
+      );
+    }
   }
 
   return lines.join("\n");

package/src/resources/extensions/gsd/workflow-event-ledger.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { normalizeWorkflowEventCommand } from "./workflow-event-vocabulary.js";
+import type { WorkflowEvent } from "./workflow-events.js";
+
+export const WORKFLOW_EVENT_LOG_FILENAME = "event-log.jsonl";
+
+export interface WorkflowEventLedgerLocation {
+  projectRoot: string;
+  workRoot: string;
+  projectGsd: string;
+  worktreeGsd: string | null;
+  projectLogPath: string;
+  worktreeLogPath: string | null;
+  isWorktree: boolean;
+}
+
+export type WorkflowEventInput = Omit<WorkflowEvent, "hash" | "session_id"> & {
+  actor_name?: string;
+  trigger_reason?: string;
+};
+
+export function resolveWorkflowEventLedgerLocation(
+  basePath: string,
+  originalProjectRoot?: string | null,
+): WorkflowEventLedgerLocation {
+  const contract = resolveGsdPathContract(basePath, originalProjectRoot);
+  return {
+    projectRoot: contract.projectRoot,
+    workRoot: contract.workRoot,
+    projectGsd: contract.projectGsd,
+    worktreeGsd: contract.worktreeGsd,
+    projectLogPath: join(contract.projectGsd, WORKFLOW_EVENT_LOG_FILENAME),
+    worktreeLogPath: contract.worktreeGsd
+      ? join(contract.worktreeGsd, WORKFLOW_EVENT_LOG_FILENAME)
+      : null,
+    isWorktree: contract.isWorktree,
+  };
+}
+
+export function workflowEventLogPath(basePath: string): string {
+  return resolveWorkflowEventLedgerLocation(basePath).projectLogPath;
+}
+
+export function workflowEventArchivePath(basePath: string, milestoneId: string): string {
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+  return join(location.projectGsd, `event-log-${milestoneId}.jsonl.archived`);
+}
+
+export function readWorktreeEventLogPath(worktreeBasePath: string): string {
+  const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+  return location.worktreeLogPath ?? location.projectLogPath;
+}
+
+export function buildWorkflowEvent(event: WorkflowEventInput, sessionId: string): WorkflowEvent {
+  const hash = createHash("sha256")
+    .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
+    .digest("hex")
+    .slice(0, 16);
+
+  return {
+    v: 2,
+    ...event,
+    hash,
+    session_id: sessionId,
+  };
+}
+
+export function appendWorkflowEvent(
+  basePath: string,
+  event: WorkflowEventInput,
+  sessionId: string,
+): WorkflowEvent {
+  const fullEvent = buildWorkflowEvent(event, sessionId);
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+
+  mkdirSync(location.projectGsd, { recursive: true });
+  appendFileSync(location.projectLogPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
+  emitWorkflowEventAudit(location.projectRoot, fullEvent);
+  return fullEvent;
+}
+
+export function writeWorkflowEventLog(basePath: string, events: readonly WorkflowEvent[]): void {
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+  mkdirSync(location.projectGsd, { recursive: true });
+  const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+  atomicWriteSync(location.projectLogPath, content);
+}
+
+export function writeWorktreeEventLog(
+  worktreeBasePath: string,
+  events: readonly WorkflowEvent[],
+): void {
+  const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+  const logPath = location.worktreeLogPath ?? location.projectLogPath;
+  mkdirSync(dirname(logPath), { recursive: true });
+  const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+  atomicWriteSync(logPath, content);
+}
+
+function emitWorkflowEventAudit(basePath: string, event: WorkflowEvent): void {
+  if (!isUnifiedAuditEnabled()) return;
+  try {
+    const normalized = normalizeWorkflowEventCommand(event.cmd) ?? "unknown";
+    emitUokAuditEvent(
+      basePath,
+      buildAuditEnvelope({
+        traceId: event.session_id,
+        category: "orchestration",
+        type: `workflow-event-${normalized}`,
+        payload: {
+          cmd: event.cmd,
+          params: event.params,
+          actor: event.actor,
+          actorName: event.actor_name,
+          triggerReason: event.trigger_reason,
+          eventTs: event.ts,
+          hash: event.hash,
+        },
+      }),
+    );
+  } catch {
+    // Best-effort: audit projection must never block the workflow event ledger.
+  }
+}

package/src/resources/extensions/gsd/workflow-event-vocabulary.ts

@@ -0,0 +1,59 @@
+import type { WorkflowEvent } from "./workflow-events.js";
+
+export interface WorkflowEventEntityKey {
+  type: string;
+  id: string;
+}
+
+export function normalizeWorkflowEventCommand(cmd: unknown): string | null {
+  return typeof cmd === "string" ? cmd.replace(/-/g, "_") : null;
+}
+
+/**
+ * Workflow progress events are keyed by the domain entity they mutate.
+ * Keep command aliases and conflict identity in this module so replay,
+ * conflict detection, and tests do not each grow their own vocabulary.
+ */
+export function workflowEventEntityKey(event: WorkflowEvent): WorkflowEventEntityKey | null {
+  const p = event.params;
+  const cmd = normalizeWorkflowEventCommand(event.cmd);
+  if (!cmd) return null;
+
+  switch (cmd) {
+    case "complete_task":
+    case "start_task":
+    case "skip_task":
+    case "report_blocker":
+    case "record_verification":
+    case "plan_task":
+      return typeof p["taskId"] === "string"
+        ? { type: "task", id: p["taskId"] }
+        : null;
+
+    case "complete_slice":
+    case "replan_slice":
+      return typeof p["sliceId"] === "string"
+        ? { type: "slice", id: p["sliceId"] }
+        : null;
+
+    case "plan_slice":
+      return typeof p["sliceId"] === "string"
+        ? { type: "slice_plan", id: p["sliceId"] }
+        : null;
+
+    case "complete_milestone":
+    case "plan_milestone":
+      return typeof p["milestoneId"] === "string"
+        ? { type: "milestone", id: p["milestoneId"] }
+        : null;
+
+    case "save_decision":
+      if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
+        return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
+      }
+      return null;
+
+    default:
+      return null;
+  }
+}

package/src/resources/extensions/gsd/workflow-events.ts

@@ -1,8 +1,13 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { withFileLockSync } from "./file-lock.js";
+import {
+  appendWorkflowEvent,
+  workflowEventArchivePath,
+  workflowEventLogPath,
+  type WorkflowEventInput,
+} from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 
 // ─── Session ID ───────────────────────────────────────────────────────────
@@ -40,22 +45,9 @@ export interface WorkflowEvent {
  */
 export function appendEvent(
   basePath: string,
-  event: Omit<WorkflowEvent, "hash" | "session_id"> & { actor_name?: string; trigger_reason?: string },
+  event: WorkflowEventInput,
 ): void {
-  const hash = createHash("sha256")
-    .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-    .digest("hex")
-    .slice(0, 16);
-
-  const fullEvent: WorkflowEvent = {
-    v: 2,
-    ...event,
-    hash,
-    session_id: ENGINE_SESSION_ID,
-  };
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+  appendWorkflowEvent(basePath, event, ENGINE_SESSION_ID);
 }
 
 // ─── readEvents ──────────────────────────────────────────────────────────
@@ -125,8 +117,8 @@ export function compactMilestoneEvents(
   basePath: string,
   milestoneId: string,
 ): { archived: number } {
-  const logPath = join(basePath, ".gsd", "event-log.jsonl");
-  const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+  const logPath = workflowEventLogPath(basePath);
+  const archivePath = workflowEventArchivePath(basePath, milestoneId);
 
   return withFileLockSync(logPath, () => {
     const allEvents = readEvents(logPath);

package/src/resources/extensions/gsd/workflow-reconcile.ts

@@ -3,6 +3,16 @@ import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
 import type { WorkflowEvent } from "./workflow-events.js";
+import {
+  normalizeWorkflowEventCommand,
+  workflowEventEntityKey,
+} from "./workflow-event-vocabulary.js";
+import {
+  readWorktreeEventLogPath,
+  workflowEventLogPath,
+  writeWorkflowEventLog,
+  writeWorktreeEventLog,
+} from "./workflow-event-ledger.js";
 import {
   transaction,
   updateTaskStatus,
@@ -82,14 +92,11 @@ function replayEvents(events: WorkflowEvent[]): void {
   transaction(() => {
   for (const event of events) {
     const p = event.params;
-    // Normalize cmd format: completion tools write hyphens ("complete-task"),
-    // legacy logs use underscores ("complete_task"). Accept both formats.
-    // Type guard: malformed event lines with non-string cmd are skipped.
-    if (typeof event.cmd !== "string") {
+    const cmd = normalizeWorkflowEventCommand(event.cmd);
+    if (!cmd) {
       logWarning("reconcile", `Event with non-string cmd skipped: ${JSON.stringify(event.cmd)}`);
       continue;
     }
-    const cmd = event.cmd.replace(/-/g, "_");
     switch (cmd) {
       case "complete_task": {
         const milestoneId = p["milestoneId"] as string;
@@ -235,48 +242,7 @@ function replayEvents(events: WorkflowEvent[]): void {
 export function extractEntityKey(
   event: WorkflowEvent,
 ): { type: string; id: string } | null {
-  const p = event.params;
-  // Normalize cmd format: accept both hyphens and underscores
-  if (typeof event.cmd !== "string") return null;
-  const cmd = event.cmd.replace(/-/g, "_");
-
-  switch (cmd) {
-    case "complete_task":
-    case "start_task":
-    case "skip_task":
-    case "report_blocker":
-    case "record_verification":
-    case "plan_task":
-      return typeof p["taskId"] === "string"
-        ? { type: "task", id: p["taskId"] }
-        : null;
-
-    case "complete_slice":
-    case "replan_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice", id: p["sliceId"] }
-        : null;
-
-    case "plan_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice_plan", id: p["sliceId"] }
-        : null;
-
-    case "complete_milestone":
-    case "plan_milestone":
-      return typeof p["milestoneId"] === "string"
-        ? { type: "milestone", id: p["milestoneId"] }
-        : null;
-
-    case "save_decision":
-      if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
-        return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
-      }
-      return null;
-
-    default:
-      return null;
-  }
+  return workflowEventEntityKey(event);
 }
 
 // ─── detectConflicts ──────────────────────────────────────────────────────────
@@ -360,13 +326,6 @@ function rewriteDivergedEventsForEntity(
   return rewritten;
 }
 
-function writeEventLog(basePath: string, events: WorkflowEvent[]): void {
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  const content = events.map((e) => JSON.stringify(e)).join("\n") + (events.length > 0 ? "\n" : "");
-  atomicWriteSync(join(dir, "event-log.jsonl"), content);
-}
-
 // ─── writeConflictsFile ───────────────────────────────────────────────────────
 
 /**
@@ -450,12 +409,18 @@ function _reconcileWorktreeLogsInner(
   worktreeBasePath: string,
 ): ReconcileResult {
   // Step 1: Read both logs
-  const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
-  const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+  const mainLogPath = workflowEventLogPath(mainBasePath);
+  const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
 
   const mainEvents = readEvents(mainLogPath);
   const wtEvents = readEvents(wtLogPath);
 
+  // Canonical worktree appends are already durable in the project ledger.
+  // Empty/missing worktree shards are legacy-only absence, not divergence.
+  if (wtEvents.length === 0) {
+    return { autoMerged: 0, conflicts: [] };
+  }
+
   // Step 2: Find fork point
   const forkPoint = findForkPoint(mainEvents, wtEvents);
 
@@ -495,9 +460,7 @@ function _reconcileWorktreeLogsInner(
 
   const baseEvents = mainEvents.slice(0, forkPoint + 1);
   const mergedLog = baseEvents.concat(merged);
-  const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
-  mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
-  atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
+  writeWorkflowEventLog(mainBasePath, mergedLog);
 
   // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
   openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
@@ -636,8 +599,8 @@ export function resolveConflict(
   const conflict = conflicts[idx]!;
   const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
 
-  const mainLogPath = join(basePath, ".gsd", "event-log.jsonl");
-  const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+  const mainLogPath = workflowEventLogPath(basePath);
+  const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
   const mainEvents = readEvents(mainLogPath);
   const wtEvents = readEvents(wtLogPath);
   const forkPoint = findForkPoint(mainEvents, wtEvents);
@@ -652,7 +615,11 @@ export function resolveConflict(
 
   const targetBasePath = pick === "main" ? worktreeBasePath : basePath;
   const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
-  writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  if (pick === "main") {
+    writeWorktreeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  } else {
+    writeWorkflowEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  }
 
   // Replay resolved events through the DB (updates DB state)
   openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);

package/src/resources/extensions/gsd/workflow-tool-surface.ts

@@ -28,7 +28,7 @@ export const WORKFLOW_TOOL_ALIAS_PAIRS: readonly WorkflowToolAliasPair[] =
 export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL: Readonly<Record<string, string>> =
   Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
 
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
   "gsd_cancel",
   "gsd_captures",
   "ask_user_questions",
@@ -45,6 +45,9 @@ const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
   "gsd_status",
 ] as const;
 
+/** Session-orchestration tools exposed by the workflow MCP adapter alongside the contract tools. */
+export type WorkflowMcpAdapterToolName = (typeof WORKFLOW_MCP_ADAPTER_TOOL_NAMES)[number];
+
 export const WORKFLOW_TOOL_SURFACE_NAMES = [
   ...WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
   ...DB_WORKFLOW_TOOL_NAMES,

package/src/resources/extensions/gsd/worktree-git-recovery.ts

@@ -8,8 +8,9 @@
  * git operations during worktree transitions:
  *
  *   - `checkoutBranchWithStashGuard` — branch switch with stash protection,
- *     including the stash-pop EEXIST collision recovery for `.gsd/` runtime
- *     files (force-checkout + targeted stash drop).
+ *     including the stash-pop EEXIST collision recovery for untracked files
+ *     (force-checkout + targeted stash drop; #645 broadened it beyond `.gsd/`,
+ *     guarded by "no non-.gsd unmerged entries remain").
  *   - `removeMergeStateFiles` — clears SQUASH_MSG / MERGE_HEAD / etc. left by
  *     a failed merge so subsequent merges don't fail on stale state.
  *   - `cleanupConflictState` — merge-abort + index reset + state-file cleanup
@@ -257,23 +258,28 @@ export function checkoutBranchWithStashGuard(
           : "";
       const stashPopMessage = `${stderrText}\n${msg}`.trim();
       const alreadyExists = stashAlreadyExistsFilesFromError(popErr);
-      const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
-      const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
       const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
       const stashRefForDrop = stashRefFromError(popErr);
-      const nonGsdUnmerged = nativeConflictFiles(basePath).filter((f) => !f.startsWith(".gsd/"));
+      const allConflictFiles = nativeConflictFiles(basePath);
+      const nonGsdUnmerged = allConflictFiles.filter((f) => !f.startsWith(".gsd/"));
+      const gsdUnmerged = allConflictFiles.filter((f) => f.startsWith(".gsd/"));
       const gsdContentConflicts = isUntrackedRestoreFailure
         ? gsdJsonlFilesWithConflictMarkers(basePath)
         : [];
-      const gsdConflictFiles = [...new Set([...gsdAlreadyExists, ...gsdContentConflicts])];
+      // Resolve ALL untracked-collision files by accepting HEAD — files in
+      // alreadyExists were untracked on the source branch by definition of the
+      // "already exists, no checkout" failure, so target HEAD is authoritative.
+      // gsdUnmerged: .gsd/ index conflicts left by the partial stash pop are
+      // also resolved via HEAD — .gsd/ runtime state is always authoritative
+      // on the target branch, so accepting HEAD is safe here too.
+      const resolvable = [...new Set([...alreadyExists, ...gsdContentConflicts, ...gsdUnmerged])];
 
       if (
         isUntrackedRestoreFailure &&
-        gsdConflictFiles.length > 0 &&
-        nonGsdAlreadyExists.length === 0 &&
+        resolvable.length > 0 &&
         nonGsdUnmerged.length === 0
       ) {
-        for (const f of gsdConflictFiles) {
+        for (const f of resolvable) {
           execFileSync("git", ["checkout", "HEAD", "--", f], {
             cwd: basePath,
             stdio: ["ignore", "pipe", "pipe"],

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -47,6 +47,7 @@ import {
 // callers — production wiring previously injected them via deps; the seam
 // added type churn without enabling test variation.
 import { loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
+import { isolationDegradedFallbackGuidance, worktreeCreationFailedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getMilestone, insertMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
@@ -693,10 +694,7 @@ export function _enterMilestoneCore(
         s.basePath = basePath;
         rebuildGitService(s, deps);
         invalidateAllCaches();
-        ctx.notify(
-          `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
-          "warning",
-        );
+        ctx.notify(isolationDegradedFallbackGuidance(milestoneId), "warning");
         return { ok: true, mode: "branch", path: basePath };
       } catch (err) {
         debugLog("WorktreeLifecycle", {
@@ -883,10 +881,7 @@ export function _enterMilestoneCore(
       eventType: "worktree-create-failed",
       data: { milestoneId, error: msg, fallback: "project-root" },
     });
-    ctx.notify(
-      `Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`,
-      "warning",
-    );
+    ctx.notify(worktreeCreationFailedGuidance(milestoneId, msg), "warning");
     // Degrade isolation for the rest of this session so mergeAndExit
     // doesn't try to merge a nonexistent worktree branch (#2483)
     s.isolationDegraded = true;

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -656,7 +656,12 @@ export function removeWorktree(
   const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath);
 
   // If we're inside the worktree, move out first — git can't remove an in-use directory
-  const cwd = process.cwd();
+  let cwd: string;
+  try {
+    cwd = process.cwd();
+  } catch {
+    cwd = basePath;
+  }
   const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
   if (resolvedCwd === resolvedWtPath || resolvedCwd.startsWith(resolvedWtPath + sep)) {
     process.chdir(basePath);

package/src/resources/extensions/gsd/worktree-root.ts

@@ -69,6 +69,18 @@ export function isGsdWorktreePath(path: string): boolean {
   return findWorktreeSegment(path.replaceAll("\\", "/")) !== null;
 }
 
+/**
+ * Project-root prefix of a GSD worktree path, or null when the path is not
+ * inside a recognized worktree layout. Pure string split — no env handling,
+ * HOME guard, or filesystem fallbacks (resolveWorktreeProjectRoot adds
+ * those). Separator normalization is 1:1 on characters, so the prefix is
+ * sliced from the ORIGINAL string and keeps its separators.
+ */
+export function projectRootFromWorktreePath(path: string): string | null {
+  const segment = findWorktreeSegment(path.replaceAll("\\", "/"));
+  return segment ? path.slice(0, segment.gsdIdx) : null;
+}
+
 /**
  * When a milestone worktree lives under the external-state layout
  * (`<gsdHome>/projects/<hash>/worktrees/<MID>/`, or the `GSD_STATE_DIR`

package/src/resources/extensions/gsd/worktree-session-state.ts

@@ -1,5 +1,5 @@
 // GSD worktree session state
-import { findWorktreeSegment } from "./worktree-root.js";
+import { findWorktreeSegment, projectRootFromWorktreePath } from "./worktree-root.js";
 
 let originalCwd: string | null = null;
 
@@ -17,10 +17,8 @@ export function clearWorktreeOriginalCwd(): void {
 
 export function ensureWorktreeOriginalCwdFromPath(cwd: string = process.cwd()): string | null {
   if (originalCwd) return originalCwd;
-  const segment = findWorktreeSegment(cwd.replaceAll("\\", "/"));
-  if (segment) {
-    originalCwd = cwd.slice(0, segment.gsdIdx);
-  }
+  const root = projectRootFromWorktreePath(cwd);
+  if (root) originalCwd = root;
   return originalCwd;
 }
 

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

@@ -224,7 +224,13 @@ export function resolveGitHeadPath(dir: string): string | null {
  */
 export function nudgeGitBranchCache(previousCwd: string): void {
   const now = new Date();
-  for (const dir of [previousCwd, process.cwd()]) {
+  let currentCwd: string | null = null;
+  try {
+    currentCwd = process.cwd();
+  } catch {
+    currentCwd = null;
+  }
+  for (const dir of [previousCwd, currentCwd].filter((dir): dir is string => Boolean(dir))) {
     try {
       const headPath = resolveGitHeadPath(dir);
       if (headPath) utimesSync(headPath, now, now);