@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.822c9439

package/src/resources/extensions/gsd/browser-daemon-auto-prep.ts

@@ -0,0 +1,108 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+
+import {
+  resolveAmbientBrowserEngineResolution,
+  resolveBrowserEngineResolution,
+  type BrowserEngineMode,
+} from "../browser-tools/engine/selection.js";
+import {
+  resolveGsdBrowserCliAvailability,
+  resolveGsdBrowserDaemonStartInvocation,
+} from "../shared/gsd-browser-cli.js";
+import { uatTypeIncludesBrowser, type UatType } from "./uat-policy.js";
+
+const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+
+function isEnvDisabled(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "0" || normalized === "false" || normalized === "off";
+}
+
+function isWarmUpDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
+  return value === "0" || value === "false" || value === "off";
+}
+
+export interface BrowserDaemonWarmContext {
+  uatType: UatType;
+  sessionProvider?: string;
+  sessionAuthMode?: "apiKey" | "oauth" | "externalCli" | "none";
+  sessionBaseUrl?: string;
+  projectRoot: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Active engine for warm-up: explicit env override, else session-committed ambient resolution. */
+function resolveActiveBrowserEngine(projectRoot: string, env: NodeJS.ProcessEnv): BrowserEngineMode {
+  if (env.GSD_BROWSER_ENGINE?.trim()) {
+    return resolveBrowserEngineResolution(env, projectRoot).engine;
+  }
+  return resolveAmbientBrowserEngineResolution(projectRoot).engine;
+}
+
+export function shouldWarmBrowserDaemonForUat(ctx: BrowserDaemonWarmContext): boolean {
+  if (!uatTypeIncludesBrowser(ctx.uatType)) return false;
+
+  const env = ctx.env ?? process.env;
+  if (isWarmUpDisabled(env)) return false;
+  if (isEnvDisabled(env.GSD_BROWSER_MCP_ENABLED)) return false;
+
+  const availability = resolveGsdBrowserCliAvailability(env);
+  if (!availability.available) return false;
+
+  const projectRoot = resolve(ctx.projectRoot);
+  return resolveActiveBrowserEngine(projectRoot, env) === "gsd-browser";
+}
+
+export function ensureBrowserDaemonStarted(
+  projectRoot: string,
+  options: { env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): { ok: true } | { ok: false; error: string } {
+  const env = options.env ?? process.env;
+  const availability = resolveGsdBrowserCliAvailability(env);
+  if (!availability.available) {
+    return { ok: false, error: availability.detail };
+  }
+
+  let invocation: ReturnType<typeof resolveGsdBrowserDaemonStartInvocation>;
+  try {
+    invocation = resolveGsdBrowserDaemonStartInvocation(projectRoot, env);
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  try {
+    execFileSync(invocation.command, invocation.args, {
+      cwd: invocation.cwd,
+      env: { ...process.env, ...env, ...(invocation.env ?? {}) },
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: options.timeoutMs ?? DEFAULT_DAEMON_START_TIMEOUT_MS,
+      encoding: "utf-8",
+    });
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Best-effort pre-warm of the gsd-browser session daemon before browser-backed
+ * run-uat dispatch. Returns an actionable stop reason when warm-up is required
+ * but fails; returns null when warm-up is skipped or succeeds.
+ */
+export function prepareBrowserDaemonForUat(ctx: BrowserDaemonWarmContext): string | null {
+  if (!shouldWarmBrowserDaemonForUat(ctx)) return null;
+
+  const result = ensureBrowserDaemonStarted(ctx.projectRoot, { env: ctx.env });
+  if (result.ok) return null;
+
+  return `Cannot dispatch browser-backed run-uat: gsd-browser daemon failed to start (${result.error}). Ensure Chrome/Chromium is installed, run \`gsd-browser daemon health\` with the project session flags from .mcp.json, or set GSD_BROWSER_PATH to a Chromium binary.`;
+}

package/src/resources/extensions/gsd/browser-evidence.ts

@@ -1,9 +1,25 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
 
-export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
+import { BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES } from "../shared/browser-contract.js";
+
+// Alternation fragment over the contract's evidence-signal names, e.g.
+// `browser_(?:assert|batch|...)`. The names are `browser_`-prefixed
+// identifiers (pinned by tests/browser-contract.test.ts), so no escaping is
+// needed.
+const BROWSER_TOOL_SIGNAL = `browser_(?:${
+  BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES.map((name) => name.slice("browser_".length)).join("|")
+})`;
+
+export const BROWSER_REQUIREMENT_RE = new RegExp(
+  String.raw`\b(?:file://|localhost|playwright|chrome|screenshot|snapshot|${BROWSER_TOOL_SIGNAL})\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file://)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b`,
+  "i",
+);
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
-export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
+export const BROWSER_RUNTIME_RE = new RegExp(
+  String.raw`\b(?:browser|playwright|chrome|camoufox|${BROWSER_TOOL_SIGNAL}|screenshot|snapshot|file://|localhost)\b`,
+  "i",
+);
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
 const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;

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

@@ -9,9 +9,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -59,21 +60,9 @@ const VALID_CLASSIFICATIONS: readonly string[] = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath: string): string {
-  const resolved = resolve(basePath);
-  // Direct layout: /.gsd/worktrees/
-  const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-  let idx = resolved.indexOf(worktreeMarker);
-  if (idx === -1) {
-    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-    const symlinkRe = new RegExp(
-      `\\${sep}\\.gsd\\${sep}projects\\${sep}[a-f0-9]+\\${sep}worktrees\\${sep}`,
-    );
-    const match = resolved.match(symlinkRe);
-    if (match && match.index !== undefined) idx = match.index;
-  }
-  if (idx !== -1) {
-    // basePath is inside a worktree — resolve to project root
-    const projectRoot = resolved.slice(0, idx);
+  // If basePath is inside a worktree, resolve to the project root.
+  const projectRoot = projectRootFromWorktreePath(resolve(basePath));
+  if (projectRoot) {
     return join(projectRoot, ".gsd", CAPTURES_FILENAME);
   }
   return join(gsdRoot(basePath), CAPTURES_FILENAME);

package/src/resources/extensions/gsd/closeout-recovery.ts

@@ -10,6 +10,7 @@ import { runTurnGitAction, type TurnGitActionMode, type TurnGitActionResult } fr
 import { _getAdapter, upsertTurnGitTransaction } from "./gsd-db.js";
 import { probeGitConflictState } from "./git-conflict-state.js";
 import { parseUnitId } from "./unit-id.js";
+import { worktreePathFor } from "./worktree-placement.js";
 
 export interface CloseoutFailureRecord {
   traceId: string;
@@ -156,7 +157,7 @@ export function resolveCloseoutRecoveryBasePath(projectRoot: string, record: Clo
   const parsed = parseUnitId(record.unitId);
   const milestoneId = parsed.milestone ?? (/^M\d+(?:-[a-z0-9]{6})?/.exec(record.unitId)?.[0] ?? "");
   if (milestoneId) {
-    const worktreePath = existingRealPath(join(projectRoot, ".gsd", "worktrees", milestoneId));
+    const worktreePath = existingRealPath(worktreePathFor(projectRoot, milestoneId));
     if (worktreePath) return worktreePath;
   }
 

package/src/resources/extensions/gsd/closeout-wizard.ts

@@ -1,25 +1,40 @@
 // Project/App: gsd-pi
 // File Purpose: Shared closeout detection and merge actions for /gsd home and smart entry.
 
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import type { NextAction } from "../shared/next-action-ui.js";
 import type { GSDState } from "./types.js";
 import { setAutoOutcomeWidget } from "./auto-dashboard.js";
 import { invalidateAllCaches } from "./cache.js";
+import { isDbAvailable } from "./db/engine.js";
+import { getMilestone } from "./db/queries.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { mergeCompletedMilestone } from "./parallel-merge.js";
 import { cleanupQuickBranch, detectStrandedQuickBranch, type StrandedQuickBranch } from "./quick.js";
+import { isClosedStatus } from "./status-guards.js";
 import {
   findUnmergedCompletedMilestones,
   type UnmergedMilestoneBlocker,
 } from "./unmerged-milestone-guard.js";
 import { appendRequirementsBacklogToSummary } from "./requirements-backlog.js";
+import { nativeBranchList, nativeIsRepo } from "./native-git-bridge.js";
+import { allWorktreesDirs } from "./worktree-manager.js";
 
 export type CloseoutActionId = "finish_quick" | "finish_milestone";
 
+export interface IdleMilestoneResidueHint {
+  message: string;
+  milestoneIds: string[];
+}
+
 export interface CloseoutContext {
   strandedQuick: StrandedQuickBranch | null;
   unmergedMilestones: UnmergedMilestoneBlocker[];
+  idleResidueHint?: IdleMilestoneResidueHint | null;
 }
 
 const MILESTONE_MERGE_CLOSEOUT_COMMANDS = [
@@ -29,11 +44,90 @@ const MILESTONE_MERGE_CLOSEOUT_COMMANDS = [
   "/gsd start for new work",
 ];
 
+function listMilestoneWorktreeIds(basePath: string): string[] {
+  const ids = new Set<string>();
+  for (const wtDir of allWorktreesDirs(basePath)) {
+    if (!existsSync(wtDir)) continue;
+    for (const entry of readdirSync(wtDir)) {
+      if (!MILESTONE_ID_RE.test(entry)) continue;
+      try {
+        if (statSync(join(wtDir, entry)).isDirectory()) ids.add(entry);
+      } catch {
+        // skip unreadable entries
+      }
+    }
+  }
+  return [...ids].sort();
+}
+
+function listMilestoneBranchIds(basePath: string): string[] {
+  try {
+    return nativeBranchList(basePath, "milestone/*")
+      .map((branch) => branch.replace(/^milestone\//, ""))
+      .filter((id) => MILESTONE_ID_RE.test(id))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * A milestone ID is "stranded residue" only when its worktree/branch artifacts
+ * exist for a milestone the DB does not consider currently in flight — i.e. the
+ * row is closed (complete/done/skipped/closed) or absent. Active, pending,
+ * blocked, parked, queued, and deferred rows describe normal in-flight or
+ * intentionally-preserved state, never residue. Returning `false` skips the ID;
+ * returning `true` keeps it in the hint.
+ */
+function isStrandedMilestoneId(milestoneId: string): boolean {
+  if (!isDbAvailable()) return true;
+  const row = getMilestone(milestoneId);
+  if (!row) return true;
+  return isClosedStatus(row.status);
+}
+
+/** Surface stranded milestone git residue when closeout guards did not classify it. */
+export function detectIdleMilestoneResidueHint(basePath: string): IdleMilestoneResidueHint | null {
+  if (!nativeIsRepo(basePath)) return null;
+
+  const gsdDir = join(basePath, ".gsd");
+  const dbPath = join(gsdDir, "gsd.db");
+  if (!existsSync(gsdDir) || !existsSync(dbPath)) {
+    return {
+      milestoneIds: [],
+      message:
+        "This git repo has no local GSD workflow database (.gsd/gsd.db). " +
+        "Workflow state may live in an external worktree, or run /gsd new-project to initialize here.",
+    };
+  }
+
+  const worktreeIds = listMilestoneWorktreeIds(basePath);
+  const branchIds = listMilestoneBranchIds(basePath);
+  const candidateIds = [...new Set([...worktreeIds, ...branchIds])].sort();
+  const milestoneIds = candidateIds.filter(isStrandedMilestoneId);
+  if (milestoneIds.length === 0) return null;
+
+  const listed = milestoneIds.join(", ");
+  const recovery =
+    milestoneIds.length === 1
+      ? `/gsd dispatch complete-milestone ${milestoneIds[0]}`
+      : "/gsd doctor --fix";
+  return {
+    milestoneIds,
+    message:
+      `Stranded milestone git residue detected (${listed}: worktree dir and/or milestone/* branch). ` +
+      `Run ${recovery} or /gsd status to recover closeout before starting new work.`,
+  };
+}
+
 export async function loadCloseoutContext(basePath: string): Promise<CloseoutContext> {
   const unmergedMilestones = await findUnmergedCompletedMilestones(basePath);
+  const idleResidueHint =
+    unmergedMilestones.length === 0 ? detectIdleMilestoneResidueHint(basePath) : null;
   return {
     strandedQuick: detectStrandedQuickBranch(basePath),
     unmergedMilestones,
+    idleResidueHint,
   };
 }
 
@@ -87,6 +181,14 @@ export function buildIdleMenuSummary(state: GSDState, closeout: CloseoutContext)
     ];
   }
 
+  // Surface idle residue before the completion summary so smart entry shows
+  // the same recovery text /gsd home would: a closed/unknown milestone with
+  // lingering worktree/branch artifacts must not be hidden behind the
+  // "all milestones complete" message.
+  if (closeout.idleResidueHint) {
+    return [closeout.idleResidueHint.message];
+  }
+
   if (state.phase === "complete") {
     const last = state.lastCompletedMilestone;
     return appendRequirementsBacklogToSummary(state, [

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
 
 
@@ -396,75 +397,12 @@ function getExtensionCompletions(prefix: string, action: string) {
   }
 }
 
-function normalizePathForCompare(path: string): string {
-  return path.replaceAll("\\", "/").replace(/\/+$/, "");
-}
-
-function findWorktreeSegment(normalizedPath: string): { gsdIdx: number; afterWorktrees: number } | null {
-  const directMarker = "/.gsd/worktrees/";
-  const directIdx = normalizedPath.indexOf(directMarker);
-  if (directIdx !== -1) {
-    return { gsdIdx: directIdx, afterWorktrees: directIdx + directMarker.length };
-  }
-
-  const symlinkMatch = normalizedPath.match(/\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//);
-  if (symlinkMatch?.index !== undefined) {
-    return { gsdIdx: symlinkMatch.index, afterWorktrees: symlinkMatch.index + symlinkMatch[0].length };
-  }
-
-  return null;
-}
-
-function resolveProjectRootFromGitFile(worktreePath: string): string | null {
-  try {
-    let dir = worktreePath;
-    for (let i = 0; i < 30; i++) {
-      const gitPath = join(dir, ".git");
-      if (existsSync(gitPath)) {
-        const content = readFileSync(gitPath, "utf8").trim();
-        if (content.startsWith("gitdir: ")) {
-          const gitDir = resolve(dir, content.slice(8));
-          const dotGitDir = resolve(gitDir, "..", "..");
-          if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
-            return resolve(dotGitDir, "..");
-          }
-          const commonDirPath = join(gitDir, "commondir");
-          if (existsSync(commonDirPath)) {
-            const commonDir = readFileSync(commonDirPath, "utf8").trim();
-            return resolve(resolve(gitDir, commonDir), "..");
-          }
-        }
-        break;
-      }
-      const parent = resolve(dir, "..");
-      if (parent === dir) break;
-      dir = parent;
-    }
-  } catch {
-    // Completion must stay best-effort.
-  }
-  return null;
-}
-
 function resolveProjectRootForCompletion(basePath: string): string {
+  // Completion honors GSD_PROJECT_ROOT unconditionally (worker processes may
+  // complete from any cwd); resolveWorktreeProjectRoot only honors it for
+  // worktree paths.
   if (process.env.GSD_PROJECT_ROOT) return process.env.GSD_PROJECT_ROOT;
-
-  const normalizedPath = normalizePathForCompare(basePath);
-  const segment = findWorktreeSegment(normalizedPath);
-  if (!segment) return basePath;
-
-  const separator = basePath.includes("\\") ? "\\" : "/";
-  const gsdMarker = `${separator}.gsd${separator}`;
-  const gsdIdx = basePath.indexOf(gsdMarker);
-  const candidate = gsdIdx !== -1 ? basePath.slice(0, gsdIdx) : basePath.slice(0, segment.gsdIdx);
-
-  const normalizedGsdHome = normalizePathForCompare(gsdHome());
-  const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
-  if (candidateGsdPath === normalizedGsdHome || candidateGsdPath.startsWith(`${normalizedGsdHome}/`)) {
-    return resolveProjectRootFromGitFile(basePath) ?? basePath;
-  }
-
-  return candidate;
+  return resolveWorktreeProjectRoot(basePath);
 }
 
 export function getGsdArgumentCompletions(prefix: string) {

package/src/resources/extensions/gsd/commands/context.ts

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

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -9,7 +9,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { join, resolve as resolvePath, sep } from "node:path";
+import { join, resolve as resolvePath, sep, win32 as pathWin32 } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
@@ -29,6 +29,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { buildClaudeRuntimeFloorAdvisory } from "../../shared/claude-runtime-floor.js";
+import { reconcileGsdBrowserPathAfterInstall } from "../../shared/gsd-browser-path-sync.js";
 import { isPnpmInstall } from "../../shared/package-manager-detection.js";
 import {
   buildDoctorHealIssuePayload,
@@ -65,9 +66,33 @@ function isBunInstall(argv1: string | undefined = process.argv[1]): boolean {
 function resolveInstallCommand(pkg: string): string {
   if (isBunInstall()) return `bun add -g ${pkg}`;
   if (isPnpmInstall()) return `pnpm add -g ${pkg}`;
+  const npmPrefix = resolveWindowsNpmGlobalPrefix();
+  if (npmPrefix) return `npm --prefix ${quoteWindowsArg(npmPrefix)} install -g ${pkg}`;
   return `npm install -g ${pkg}`;
 }
 
+function resolveWindowsNpmGlobalPrefix(
+  argv1: string | undefined = process.argv[1],
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  if (platform !== "win32" || !argv1) return null;
+  const normalized = pathWin32.normalize(argv1);
+  const marker = `${pathWin32.sep}node_modules${pathWin32.sep}`;
+  const index = normalized.toLowerCase().lastIndexOf(marker);
+  if (index <= 0) return null;
+  const prefix = normalized.slice(0, index);
+  // Verify this is a real npm global prefix: such a directory always contains
+  // npm's own bin shim (`npm.cmd`) as a sibling of `node_modules/`. Local
+  // project `node_modules/`, npx caches, and other non-global layouts do not,
+  // so without this check `--prefix` would target the wrong directory.
+  if (!existsSync(pathWin32.join(prefix, "npm.cmd"))) return null;
+  return prefix;
+}
+
+function quoteWindowsArg(value: string): string {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+
 function notifyClaudeRuntimeFloorAdvisory(ctx: ExtensionCommandContext): void {
   let advisory: string | null = null;
   try {
@@ -576,12 +601,30 @@ export async function handleUpdate(ctx: ExtensionCommandContext, args = ""): Pro
     execSync(installCmd, {
       stdio: ["ignore", "pipe", "ignore"],
     });
+    let reconcile: ReturnType<typeof reconcileGsdBrowserPathAfterInstall> | null = null;
+    if (browserUpdate) {
+      try {
+        reconcile = reconcileGsdBrowserPathAfterInstall({
+          latestVersion: latest,
+          compareSemver: compareSemverLocal,
+          resolvePathVersion: resolveGsdBrowserPathVersionForCommand,
+        });
+      } catch {
+        // Reconciliation is best-effort: the install above already succeeded,
+        // so a reconcile failure must not flip the result to "Update failed".
+        reconcile = null;
+      }
+    }
     const newPathVersion = browserUpdate ? resolveGsdBrowserPathVersionForCommand() : null;
-    const pathReady = !browserUpdate || (!!newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0);
+    const pathNote = browserUpdate && !(newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0)
+      ? (reconcile?.message
+        ?? "Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+      : "";
     ctx.ui.notify(
       browserUpdate
         ? `Updated gsd-browser to v${latest}. Restart your GSD session to use the new browser automation version.` +
-          (pathReady ? "" : "\nNote: Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+          (reconcile?.action === "synced" && reconcile.message ? `\n${reconcile.message}` : "") +
+          (pathNote ? `\nNote: ${pathNote}` : "")
         : `Updated to v${latest}. Restart your GSD session to use the new version.`,
       "info",
     );