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

package/dist/resources/extensions/gsd/worktree-git-recovery.js

@@ -7,8 +7,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
@@ -240,20 +241,25 @@ export function checkoutBranchWithStashGuard(basePath, branch, reason) {
                     : "";
             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/dist/resources/extensions/gsd/worktree-lifecycle.js

@@ -32,6 +32,7 @@ import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain, } fr
 // 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";
@@ -343,7 +344,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
                 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) {
@@ -517,7 +518,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
             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/dist/resources/extensions/gsd/worktree-manager.js

@@ -528,7 +528,13 @@ export function removeWorktree(basePath, name, opts = {}) {
     // inside .gsd/worktrees/ — a symlink inside the directory could point out.
     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;
+    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/dist/resources/extensions/gsd/worktree-root.js

@@ -57,6 +57,17 @@ export function findWorktreeSegment(normalizedPath) {
 export function isGsdWorktreePath(path) {
     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) {
+    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/dist/resources/extensions/gsd/worktree-session-state.js

@@ -1,5 +1,5 @@
 // GSD worktree session state
-import { findWorktreeSegment } from "./worktree-root.js";
+import { findWorktreeSegment, projectRootFromWorktreePath } from "./worktree-root.js";
 let originalCwd = null;
 export function getWorktreeOriginalCwd() {
     return originalCwd;
@@ -13,10 +13,9 @@ export function clearWorktreeOriginalCwd() {
 export function ensureWorktreeOriginalCwdFromPath(cwd = process.cwd()) {
     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;
 }
 export function getActiveWorktreeName() {

package/dist/resources/extensions/gsd/worktree.js

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

package/dist/resources/extensions/search-the-web/native-search.js

@@ -214,9 +214,11 @@ export function registerNativeSearchHooks(pi) {
             isAnthropic = isAnthropicProvider && payloadLooksAnthropic !== false;
         }
         else {
-            // Last resort: session-restore paths where the SDK doesn't pass model.
-            // The model-name prefix is best-effort and assumes direct Anthropic.
-            isAnthropic = payloadLooksAnthropic === true;
+            // No authoritative provider info available (no event.model, no model_select).
+            // Do NOT inject native web_search — guessing on model name alone causes 400
+            // "unsupported_value" errors when the actual provider (copilot, openrouter,
+            // proxy, etc.) doesn't expose the server-side search tool (#648).
+            isAnthropic = false;
         }
         if (!isAnthropic)
             return;

package/dist/resources/extensions/shared/browser-contract.js

@@ -0,0 +1,59 @@
+// Project/App: gsd-pi
+// File Purpose: Browser Automation Contract — the single source for the canonical
+// Pi-facing browser tool vocabulary. Engine adapters (legacy Playwright, managed
+// gsd-browser), UAT policy, dispatch preflight, and evidence detection all derive
+// their browser tool knowledge from this module instead of re-listing names.
+/**
+ * Canonical `browser_*` tool names of the Browser Automation Contract.
+ *
+ * These are the product-level names Units see regardless of which Browser
+ * Automation Engine serves them (ADR-024). Adding a capability here is the
+ * one-line vocabulary change; the engine adapters and presentation surfaces
+ * are typed against this list, so missing coverage fails typecheck.
+ */
+export const BROWSER_CONTRACT_TOOL_NAMES = [
+    "browser_navigate",
+    "browser_click",
+    "browser_type",
+    "browser_fill_form",
+    "browser_click_ref",
+    "browser_fill_ref",
+    "browser_wait_for",
+    "browser_assert",
+    "browser_verify",
+    "browser_screenshot",
+    "browser_snapshot_refs",
+    "browser_find",
+    "browser_get_console_logs",
+    "browser_get_network_logs",
+    "browser_evaluate",
+    "browser_reload",
+    "browser_batch",
+    "browser_act",
+];
+const BROWSER_CONTRACT_TOOL_NAME_SET = new Set(BROWSER_CONTRACT_TOOL_NAMES);
+export function isBrowserContractToolName(name) {
+    return BROWSER_CONTRACT_TOOL_NAME_SET.has(name);
+}
+/**
+ * Whether a canonical (non-MCP-prefixed) tool name belongs to the browser tool
+ * family. Broader than the contract list on purpose: an External MCP Client or
+ * host integration may supply additional `browser_*` tools that still satisfy
+ * browser-backed UAT.
+ */
+export function hasBrowserContractPrefix(canonicalToolName) {
+    return canonicalToolName.startsWith("browser_");
+}
+/**
+ * Contract tool names whose appearance in prose marks browser-backed UAT
+ * activity (requirement or evidence language). Consumed by the
+ * browser-evidence regexes so textual detection stays derived from the
+ * contract vocabulary.
+ */
+export const BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES = [
+    "browser_assert",
+    "browser_batch",
+    "browser_find",
+    "browser_verify",
+    "browser_snapshot_refs",
+];

package/dist/resources/extensions/shared/gsd-browser-cli.js

@@ -38,6 +38,28 @@ function compareSemverLocal(a, b) {
 function parseGsdBrowserVersion(output) {
     return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
 }
+function splitCommandLine(commandLine) {
+    const parts = commandLine.match(/(?:"[^"]*"|'[^']*'|[^\s"']+)/g) ?? [];
+    return parts.map((part) => {
+        const quote = part[0];
+        if ((quote === '"' || quote === "'") && part.endsWith(quote)) {
+            return part.slice(1, -1);
+        }
+        return part;
+    });
+}
+function buildPathGsdBrowserVersionInvocation(platform) {
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/d", "/s", "/c", "gsd-browser", "--version"] };
+    }
+    return { command: "gsd-browser", args: ["--version"] };
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function resolveExplicitGsdBrowserCliPath(env) {
+    return env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim() || undefined;
+}
 function resolveBundledGsdBrowserPackageVersion() {
     try {
         const requireFromHere = createRequire(import.meta.url);
@@ -49,12 +71,20 @@ function resolveBundledGsdBrowserPackageVersion() {
         return null;
     }
 }
+// The `gsd-browser --version` subprocess result cannot change mid-session (the
+// engine-switch guard forbids restarting with a different engine), and both the
+// availability probe and the launch-config resolution ask for it at session
+// start — memoize so the up-to-2s spawn happens once per process.
+let cachedPathProbeVersion;
 function resolvePathGsdBrowserVersion(env) {
     const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
     if (explicit)
         return parseGsdBrowserVersion(explicit);
+    if (cachedPathProbeVersion !== undefined)
+        return cachedPathProbeVersion;
     try {
-        return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+        const invocation = buildPathGsdBrowserVersionInvocation(process.platform);
+        cachedPathProbeVersion = parseGsdBrowserVersion(execFileSync(invocation.command, invocation.args, {
             encoding: "utf-8",
             env,
             stdio: ["ignore", "pipe", "ignore"],
@@ -62,8 +92,9 @@ function resolvePathGsdBrowserVersion(env) {
         }));
     }
     catch {
-        return null;
+        cachedPathProbeVersion = null;
     }
+    return cachedPathProbeVersion;
 }
 function shouldPreferPathGsdBrowser(env) {
     const pathVersion = resolvePathGsdBrowserVersion(env);
@@ -73,7 +104,7 @@ function shouldPreferPathGsdBrowser(env) {
     return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
 }
 export function resolveBundledGsdBrowserCliPath(env = process.env) {
-    const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+    const explicit = resolveExplicitGsdBrowserCliPath(env);
     if (explicit)
         return explicit;
     try {
@@ -96,6 +127,36 @@ export function resolveBundledGsdBrowserCliPath(env = process.env) {
     }
     return null;
 }
+/**
+ * Cheap availability probe for the gsd-browser CLI: explicit env overrides,
+ * then the bundled @opengsd/gsd-browser binary (filesystem checks only), then
+ * a PATH lookup (one short subprocess, memoized). Used by Browser Automation
+ * Engine resolution to decide whether the managed engine is provable before
+ * preferring it over legacy Playwright. `via` names the provable source, not
+ * necessarily the launch source — resolveGsdBrowserMcpLaunchConfig may still
+ * prefer a newer PATH CLI over the bundled one.
+ */
+export function resolveGsdBrowserCliAvailability(env = process.env) {
+    const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+    if (explicitCommand) {
+        return { available: true, via: "explicit-env", detail: `GSD_BROWSER_MCP_COMMAND=${explicitCommand}` };
+    }
+    const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
+    if (explicitCliPath) {
+        return existsSync(explicitCliPath)
+            ? { available: true, via: "explicit-env", detail: `CLI at ${explicitCliPath}` }
+            : { available: false, detail: `configured gsd-browser CLI path does not exist: ${explicitCliPath}` };
+    }
+    const bundledCliPath = resolveBundledGsdBrowserCliPath(env);
+    if (bundledCliPath) {
+        return { available: true, via: "bundled", detail: `bundled CLI at ${bundledCliPath}` };
+    }
+    const pathVersion = resolvePathGsdBrowserVersion(env);
+    if (pathVersion) {
+        return { available: true, via: "path", detail: `gsd-browser ${pathVersion} on PATH` };
+    }
+    return { available: false, detail: "no bundled or PATH gsd-browser CLI found" };
+}
 export function buildGsdBrowserSessionName(projectRoot, suffix) {
     const resolvedProjectRoot = resolve(projectRoot);
     const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
@@ -103,13 +164,38 @@ export function buildGsdBrowserSessionName(projectRoot, suffix) {
     const cleanSuffix = suffix ? sanitizeSessionSegment(suffix) : "";
     return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
 }
+/**
+ * Recognize an MCP server config (from .mcp.json / Claude settings) as a
+ * gsd-browser server. Paired with resolveGsdBrowserMcpLaunchConfig: this module
+ * writes the config shape, so it also owns recognizing it. New launch shapes
+ * are taught here, in one place.
+ */
+export function isGsdBrowserMcpServerConfig(config) {
+    if (!isRecord(config))
+        return false;
+    const command = typeof config.command === "string" ? config.command : "";
+    if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
+        return true;
+    }
+    if (isRecord(config.env)) {
+        const env = config.env;
+        if (typeof env.GSD_BROWSER_CLI_PATH === "string"
+            || typeof env.GSD_BROWSER_BIN_PATH === "string"
+            || typeof env.GSD_BROWSER_MCP_COMMAND === "string") {
+            return true;
+        }
+    }
+    const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
+    return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
+}
 export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env, options = {}) {
     const resolvedProjectRoot = resolve(projectRoot);
     const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
     const explicitArgs = parseJsonEnv(env, "GSD_BROWSER_MCP_ARGS");
     const explicitEnv = parseJsonEnv(env, "GSD_BROWSER_MCP_ENV");
-    const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
-    const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+    const explicitCommandLine = env.GSD_BROWSER_MCP_COMMAND?.trim();
+    const [explicitCommand, ...explicitCommandArgs] = explicitCommandLine ? splitCommandLine(explicitCommandLine) : [];
+    const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
     const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
     const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
         ? resolveBundledGsdBrowserCliPath(env)
@@ -119,6 +205,9 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     // profile/cookies persist across pi sessions for the same project. gsd-browser
     // rejects --identity-scope unless --identity-key is also supplied.
     const identityKey = env.GSD_BROWSER_IDENTITY_KEY?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
+    // identity-project must be a safe identifier (no path separators); full paths
+    // cause daemon startup to fail with "invalid name".
+    const identityProject = env.GSD_BROWSER_IDENTITY_PROJECT?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
     const command = explicitCommand
         || explicitCliPath
         || (preferPathCli ? "gsd-browser" : undefined)
@@ -127,6 +216,7 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
         ? explicitArgs.map(String)
         : [
+            ...explicitCommandArgs,
             ...(bundledCliPath ? [bundledCliPath] : []),
             "mcp",
             "--session",
@@ -136,7 +226,7 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
             "--identity-key",
             identityKey,
             "--identity-project",
-            resolvedProjectRoot,
+            identityProject,
         ];
     const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
     return {
@@ -149,3 +239,23 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
         sessionName,
     };
 }
+/**
+ * CLI invocation that starts the gsd-browser session daemon with the same
+ * session and identity flags as {@link resolveGsdBrowserMcpLaunchConfig}, so
+ * browser UAT can warm Chrome/CDP before the first MCP navigation.
+ */
+export function resolveGsdBrowserDaemonStartInvocation(projectRoot, env = process.env, options = {}) {
+    const launch = resolveGsdBrowserMcpLaunchConfig(projectRoot, env, options);
+    const mcpIndex = launch.args.indexOf("mcp");
+    if (mcpIndex < 0) {
+        throw new Error("gsd-browser launch config is missing mcp subcommand");
+    }
+    const prefix = launch.args.slice(0, mcpIndex);
+    const sessionFlags = launch.args.slice(mcpIndex + 1);
+    return {
+        command: launch.command,
+        args: [...prefix, "daemon", "start", ...sessionFlags],
+        cwd: launch.cwd,
+        ...(launch.env ? { env: launch.env } : {}),
+    };
+}

package/dist/resources/shared/gsd-browser-path-sync.js

@@ -0,0 +1,214 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, copyFileSync, existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, delimiter as pathDelimiter, resolve as resolvePath } from 'node:path';
+import { isPnpmInstall, pathStartsWith } from './package-manager-detection.js';
+function isBunGlobalInstall(argv1, env) {
+    if ('bun' in process.versions)
+        return true;
+    if (!argv1)
+        return false;
+    const bunBinDirs = [];
+    if (env.BUN_INSTALL)
+        bunBinDirs.push(join(env.BUN_INSTALL, 'bin'));
+    bunBinDirs.push(join(homedir(), '.bun', 'bin'));
+    return bunBinDirs.some((dir) => pathStartsWith(argv1, dir));
+}
+function gsdBrowserBinaryName(platform) {
+    return platform === 'win32' ? 'gsd-browser.cmd' : 'gsd-browser';
+}
+function tryResolveFromBinDir(binDir, platform) {
+    const primary = join(binDir, gsdBrowserBinaryName(platform));
+    if (existsSync(primary))
+        return primary;
+    if (platform === 'win32') {
+        const fallback = join(binDir, 'gsd-browser');
+        if (existsSync(fallback))
+            return fallback;
+    }
+    return null;
+}
+function tryResolveFromPackageRoot(rootDir, platform) {
+    const candidate = join(rootDir, '@opengsd', 'gsd-browser', 'bin', gsdBrowserBinaryName(platform));
+    if (existsSync(candidate))
+        return candidate;
+    if (platform === 'win32') {
+        const fallback = join(rootDir, '@opengsd', 'gsd-browser', 'bin', 'gsd-browser');
+        if (existsSync(fallback))
+            return fallback;
+    }
+    return null;
+}
+function tryExecLookup(command, args, env, platform, resolve) {
+    try {
+        const dir = execFileSync(command, args, {
+            encoding: 'utf-8',
+            env,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).trim();
+        return resolve(dir, platform);
+    }
+    catch {
+        return null;
+    }
+}
+function resolvePathBinary(env, platform) {
+    if (platform === 'win32') {
+        try {
+            const out = execFileSync('where', ['gsd-browser'], {
+                encoding: 'utf-8',
+                env,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: 5000,
+            }).trim();
+            const first = out.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+            return first && existsSync(first) ? first : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    for (const entry of (env.PATH ?? '').split(pathDelimiter)) {
+        if (!entry)
+            continue;
+        const candidate = join(entry, 'gsd-browser');
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function resolveRealPath(pathValue) {
+    try {
+        return realpathSync(pathValue);
+    }
+    catch {
+        return resolvePath(pathValue);
+    }
+}
+function resolveSymlinkTarget(pathCli) {
+    try {
+        const stat = lstatSync(pathCli);
+        if (!stat.isSymbolicLink())
+            return pathCli;
+        const target = readlinkSync(pathCli);
+        return isAbsolute(target) ? target : resolvePath(dirname(pathCli), target);
+    }
+    catch {
+        // PATH entry vanished or is inaccessible between resolution and sync.
+        // Fall back to the original path; subsequent sync will surface a useful
+        // error rather than escaping as an unhandled throw.
+        return pathCli;
+    }
+}
+function resolveHomeDir(env) {
+    const fromEnv = env.HOME?.trim() || env.USERPROFILE?.trim();
+    return resolvePath(fromEnv || homedir());
+}
+function canAutoSyncTarget(targetPath, env) {
+    const home = resolveHomeDir(env);
+    const resolved = resolvePath(targetPath);
+    return pathStartsWith(resolved, home);
+}
+function syncBinary(installedCli, targetPath, platform) {
+    const source = resolveRealPath(installedCli);
+    copyFileSync(source, targetPath);
+    if (platform !== 'win32') {
+        chmodSync(targetPath, 0o755);
+    }
+}
+/**
+ * Resolve the gsd-browser binary installed by the active global package manager.
+ */
+export function resolveGlobalGsdBrowserCliPath(options = {}) {
+    const env = options.env ?? process.env;
+    const argv1 = options.argv1 ?? process.argv[1];
+    const platform = options.platform ?? process.platform;
+    if (isBunGlobalInstall(argv1, env)) {
+        return (tryExecLookup('bun', ['pm', 'bin', '-g'], env, platform, tryResolveFromBinDir)
+            ?? (env.BUN_INSTALL ? tryResolveFromBinDir(join(env.BUN_INSTALL, 'bin'), platform) : null)
+            ?? tryResolveFromBinDir(join(homedir(), '.bun', 'bin'), platform));
+    }
+    if (isPnpmInstall(argv1, env)) {
+        return (tryExecLookup('pnpm', ['bin', '-g'], env, platform, tryResolveFromBinDir)
+            ?? tryExecLookup('pnpm', ['root', '-g'], env, platform, tryResolveFromPackageRoot));
+    }
+    return (tryExecLookup('npm', ['bin', '-g'], env, platform, tryResolveFromBinDir)
+        ?? tryExecLookup('npm', ['root', '-g'], env, platform, tryResolveFromPackageRoot));
+}
+/**
+ * Resolve the gsd-browser binary that wins on PATH (`command -v` / `where`).
+ */
+export function resolveGsdBrowserOnPath(env = process.env, platform = process.platform) {
+    return resolvePathBinary(env, platform);
+}
+/**
+ * After a global gsd-browser install, ensure the PATH-resolved binary matches
+ * the freshly installed global binary when an older copy is shadowing it.
+ */
+export function reconcileGsdBrowserPathAfterInstall(options) {
+    const env = options.env ?? process.env;
+    const argv1 = options.argv1 ?? process.argv[1];
+    const platform = options.platform ?? process.platform;
+    const installedCli = resolveGlobalGsdBrowserCliPath({ env, argv1, platform });
+    if (!installedCli) {
+        return { action: 'none' };
+    }
+    const pathCli = resolveGsdBrowserOnPath(env, platform);
+    const installedReal = resolveRealPath(installedCli);
+    if (pathCli && resolveRealPath(pathCli) === installedReal) {
+        return { action: 'none', pathCli, installedCli };
+    }
+    const pathVersion = options.resolvePathVersion(env);
+    if (pathVersion && options.compareSemver(pathVersion, options.latestVersion) >= 0) {
+        return { action: 'none', pathCli: pathCli ?? undefined, installedCli };
+    }
+    if (!pathCli) {
+        return {
+            action: 'shadowed',
+            installedCli,
+            message: 'Installed gsd-browser globally, but no gsd-browser was found on PATH. Add your package manager global bin directory to PATH.',
+        };
+    }
+    const syncTarget = resolveSymlinkTarget(pathCli);
+    if (!canAutoSyncTarget(syncTarget, env)) {
+        return {
+            action: 'shadowed',
+            pathCli,
+            installedCli,
+            syncTarget,
+            message: `PATH resolves gsd-browser to ${pathCli}, but the updated global install is at ${installedCli}. ` +
+                'Move your package manager global bin directory ahead of the stale location on PATH, or update the stale binary manually.',
+        };
+    }
+    let syncSucceeded = false;
+    try {
+        syncBinary(installedCli, syncTarget, platform);
+        syncSucceeded = true;
+    }
+    catch {
+        // Fall through to shadowed guidance.
+    }
+    if (syncSucceeded) {
+        const refreshedVersion = options.resolvePathVersion(env);
+        const verified = refreshedVersion !== null
+            && options.compareSemver(refreshedVersion, options.latestVersion) >= 0;
+        return {
+            action: 'synced',
+            pathCli,
+            installedCli,
+            syncTarget,
+            message: verified
+                ? `Synced PATH-resolved gsd-browser at ${syncTarget} to the updated global install.`
+                : `Synced PATH-resolved gsd-browser at ${syncTarget} to the updated global install. Could not verify the new version on PATH; restart your shell or rerun if it still reports the old version.`,
+        };
+    }
+    return {
+        action: 'shadowed',
+        pathCli,
+        installedCli,
+        syncTarget,
+        message: `PATH resolves gsd-browser to ${pathCli}, but the updated global install is at ${installedCli}. ` +
+            'Move your package manager global bin directory ahead of the stale location on PATH, or update the stale binary manually.',
+    };
+}

package/dist/resources/shared/package-manager-detection.js

@@ -9,7 +9,7 @@ function hasPnpmPath(value) {
         normalized.endsWith('/pnpm.cjs') ||
         normalized.endsWith('/pnpm.js'));
 }
-function pathStartsWith(pathValue, dir) {
+export function pathStartsWith(pathValue, dir) {
     if (!pathValue)
         return false;
     const resolvedPath = resolvePath(pathValue);

package/dist/resources/shared/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/resources/skills/create-skill/SKILL.md

@@ -174,6 +174,9 @@ description: ...          # What it does AND when to use it (third person)
 ---
 ```
 
+Frontmatter must parse as YAML. Quote description values containing `:` or use
+a folded block (`description: >`) for longer trigger descriptions.
+
 Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*`
 </yaml_requirements>