@opengsd/gsd-pi 1.2.0-dev.d6c5343c → 1.2.0-dev.e8563f58

package/dist/resources/extensions/gsd/gsd-command-home.js

@@ -28,13 +28,17 @@ export function buildGsdHomeModel(state, closeout) {
     const workLabel = activeWorkLabel(state);
     const strandedQuick = closeout?.strandedQuick ?? null;
     const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+    const idleResidueHint = closeout?.idleResidueHint ?? null;
+    const hasIdleResidue = Boolean(idleResidueHint);
     const nextReason = complete
         ? "all milestones are complete"
         : blocked
             ? "the active milestone is blocked"
-            : !hasActiveWork
-                ? "there is no active milestone"
-                : "";
+            : hasIdleResidue
+                ? "milestone git residue needs recovery"
+                : !hasActiveWork
+                    ? "there is no active milestone"
+                    : "";
     const canAdvance = hasActiveWork && !blocked && !complete;
     const unmappedActive = complete ? countUnmappedActiveRequirements() : 0;
     const recommended = strandedQuick
@@ -43,11 +47,13 @@ export function buildGsdHomeModel(state, closeout) {
             ? "finish_milestone"
             : blocked
                 ? "fix_recover"
-                : canAdvance
-                    ? "continue_step"
-                    : complete && unmappedActive > 0
-                        ? "review_requirements_backlog"
-                        : "start_configure";
+                : hasIdleResidue
+                    ? "fix_recover"
+                    : canAdvance
+                        ? "continue_step"
+                        : complete && unmappedActive > 0
+                            ? "review_requirements_backlog"
+                            : "start_configure";
     const completionSummary = complete
         ? appendRequirementsBacklogToSummary(state, [
             `All milestones complete${state.lastCompletedMilestone ? ` after ${state.lastCompletedMilestone.id}: ${state.lastCompletedMilestone.title}` : ""}.`,
@@ -57,7 +63,9 @@ export function buildGsdHomeModel(state, closeout) {
         ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
         : unmergedMilestone
             ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
-            : completionSummary;
+            : idleResidueHint
+                ? [idleResidueHint.message]
+                : completionSummary;
     return {
         title: "GSD — What now?",
         summary: [
@@ -130,10 +138,12 @@ export function buildGsdHomeModel(state, closeout) {
                 label: "Fix or recover",
                 description: blocked
                     ? "Review the blocker and recovery commands for the active milestone."
-                    : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-                enabled: blocked,
+                    : hasIdleResidue
+                        ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
+                        : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
+                enabled: blocked || hasIdleResidue,
                 recommended: recommended === "fix_recover",
-                disabledReason: blocked ? undefined : "no blocker is active",
+                disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
             },
             {
                 id: "start_configure",

package/dist/resources/extensions/gsd/gsd-db.js

@@ -169,7 +169,7 @@ export function insertArtifact(a) {
 export function insertMilestone(m) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
+    const result = getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
       id, title, status, depends_on, created_at,
       vision, success_criteria, key_risks, proof_strategy,
       verification_contract, verification_integration, verification_operational, verification_uat,
@@ -199,6 +199,7 @@ export function insertMilestone(m) {
         ":requirement_coverage": m.planning?.requirementCoverage ?? "",
         ":boundary_map_markdown": m.planning?.boundaryMapMarkdown ?? "",
     });
+    return (result.changes ?? 0) > 0;
 }
 export function upsertMilestonePlanning(milestoneId, planning) {
     if (!getDbOrNull())

package/dist/resources/extensions/gsd/milestone-closeout.js

@@ -4,10 +4,13 @@
 // - preflight: dispatch git clean before complete-milestone agent (auto-dispatch)
 // - postUnit: git commit, artifact verify, DB settle, then GitHub finalize
 // - recovery: DB repair from artifacts, then GitHub finalize
+import { existsSync } from "node:fs";
 import { loadFile } from "./files.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { getMilestone, getClosedSliceIds, isDbAvailable } from "./gsd-db.js";
+import { getMilestone, getClosedSliceIds, getLatestAssessmentByScope, getMilestoneSlices, isDbAvailable, } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { handleCompleteMilestone } from "./tools/complete-milestone.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { uatSignoffBlockerGuidance } from "./guidance.js";
@@ -19,6 +22,60 @@ import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { commitPendingMilestoneCloseoutChanges, findMissingSummaries, isVerificationNotApplicable, readUatGateVerdict, } from "./auto-dispatch.js";
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
+/**
+ * True when a milestone is terminal for git cleanup (orphaned worktrees, stale branches).
+ * DB-authoritative (ADR-017): closed status, or validation-pass with all slices closed.
+ * When the DB is unavailable we cannot make this decision and conservatively
+ * return false so callers leave the worktree/branch alone instead of cleaning
+ * up based on parsed projections.
+ */
+export async function isCompletedMilestoneTerminal(_basePath, milestoneId) {
+    if (!isDbAvailable())
+        return false;
+    const milestone = getMilestone(milestoneId);
+    if (!milestone)
+        return false;
+    if (isClosedStatus(milestone.status)) {
+        return true;
+    }
+    const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    if (validation?.status !== "pass") {
+        return false;
+    }
+    const slices = getMilestoneSlices(milestoneId);
+    if (slices.length === 0)
+        return false;
+    return slices.every((slice) => isClosedStatus(slice.status));
+}
+/** Write a missing milestone SUMMARY projection when canonical DB closeout already settled. */
+export async function repairMissingMilestoneSummaryProjection(basePath, milestoneId) {
+    const milestone = getMilestone(milestoneId);
+    if (!milestone) {
+        return { ok: false, error: `milestone not found: ${milestoneId}` };
+    }
+    const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const summaryPath = resolveExpectedArtifactPath("complete-milestone", milestoneId, artifactBasePath);
+    if (summaryPath && existsSync(summaryPath)) {
+        return { ok: true };
+    }
+    const result = await handleCompleteMilestone({
+        milestoneId,
+        title: milestone.title,
+        oneLiner: "Canonical closeout completed; summary projection repaired automatically.",
+        narrative: "The workflow database recorded this milestone as complete, but the milestone SUMMARY artifact was missing on disk. " +
+            "Dispatch policy repaired the projection so closeout proof and cleanup can proceed.",
+        verificationPassed: true,
+        triggerReason: "closeout-projection-repair",
+    }, basePath);
+    if ("error" in result) {
+        return { ok: false, error: result.error };
+    }
+    const writtenSummaryPath = result.summaryPath;
+    if (result.stale || !writtenSummaryPath || !existsSync(writtenSummaryPath)) {
+        return { ok: false, error: "milestone SUMMARY projection write failed" };
+    }
+    return { ok: true };
+}
 /**
  * True when the milestone is closed in the DB and the completion summary artifact exists.
  * Polls briefly so post-unit verification can observe the tool's DB write.
@@ -65,7 +122,21 @@ export async function evaluateCompleteMilestoneDispatch(ctx) {
     if (isDbAvailable()) {
         const milestone = getMilestone(mid);
         if (milestone && isClosedStatus(milestone.status)) {
-            return { action: "skip" };
+            const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, mid);
+            const summaryPath = resolveExpectedArtifactPath("complete-milestone", mid, artifactBasePath);
+            const summaryMissing = !summaryPath || !existsSync(summaryPath);
+            if (summaryMissing) {
+                const repair = await repairMissingMilestoneSummaryProjection(basePath, mid);
+                if (!repair.ok) {
+                    logWarning("dispatch", `Milestone ${mid} is closed in DB but SUMMARY repair failed: ${repair.error}. Dispatching complete-milestone to retry.`);
+                }
+                else {
+                    return { action: "skip" };
+                }
+            }
+            else {
+                return { action: "skip" };
+            }
         }
     }
     const closeoutGitStop = commitPendingMilestoneCloseoutChanges(basePath, mid);

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -6,9 +6,10 @@ import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, should
 import { getActiveRequirements, getAllMilestones, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertMilestone, insertAssessment, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
@@ -25,9 +26,11 @@ import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
-import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import { prepareUatRun, saveUatAttemptArtifact, } from "../uat-run.js";
+import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
+import { claimMilestoneLease, releaseMilestoneLease, getMilestoneLease, refreshMilestoneLease, milestoneLeaseTtlSeconds, } from "../db/milestone-leases.js";
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -61,6 +64,19 @@ function blockIfWrongAutoUnit(requiredUnitType, operation) {
         isError: true,
     };
 }
+function milestoneLeaseConflictResult(milestoneId, byWorker, expiresAt) {
+    return {
+        content: [{ type: "text", text: `Milestone ${milestoneId} is currently leased by ${byWorker}. Retry after ${expiresAt}.` }],
+        details: {
+            operation: "plan_milestone",
+            error: "milestone_lease_conflict",
+            milestoneId,
+            byWorker,
+            expiresAt,
+        },
+        isError: true,
+    };
+}
 function registerProjectMilestoneSequence(content) {
     const parsed = parseProject(content);
     const registered = [];
@@ -1066,7 +1082,45 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             isError: true,
         };
     }
+    let workerId = null;
+    let acquiredToken = null;
+    let leaseRefreshTimer;
     try {
+        // Re-read at the gate so a peer-created milestone is not treated as fresh.
+        const milestoneExists = getMilestone(params.milestoneId) !== null;
+        if (milestoneExists) {
+            const heldLease = getMilestoneLease(params.milestoneId);
+            if (heldLease?.status === "held" && Date.parse(heldLease.expires_at) > Date.now()) {
+                const holder = getAutoWorker(heldLease.worker_id);
+                // Let the one-shot claim path recover stale same-process worker rows.
+                const projectRoot = normalizeRealPath(basePath);
+                const isOurAutoLease = isAutoActive() && heldLease.worker_id === autoSession.workerId;
+                const holderIsOneShotReentrantPeer = !isAutoActive()
+                    && !!holder
+                    && holder.host === hostname()
+                    && holder.pid === process.pid
+                    && holder.project_root_realpath === projectRoot;
+                if (holder?.status === "active" && !isOurAutoLease && !holderIsOneShotReentrantPeer) {
+                    return milestoneLeaseConflictResult(params.milestoneId, heldLease.worker_id, heldLease.expires_at);
+                }
+            }
+        }
+        // Fresh creation cannot claim a lease because the FK row does not exist.
+        // In-process auto already owns its lease; re-claiming would bump its token.
+        if (!isAutoActive() && milestoneExists) {
+            workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(basePath) });
+            const lease = claimMilestoneLease(workerId, params.milestoneId);
+            if (!lease.ok) {
+                return milestoneLeaseConflictResult(params.milestoneId, lease.byWorker, lease.expiresAt);
+            }
+            acquiredToken = lease.token;
+            const leaseRefreshMs = (milestoneLeaseTtlSeconds() / 2) * 1000;
+            leaseRefreshTimer = setInterval(() => {
+                if (acquiredToken !== null && workerId !== null) {
+                    refreshMilestoneLease(workerId, params.milestoneId, acquiredToken);
+                }
+            }, leaseRefreshMs);
+        }
         const result = await handlePlanMilestone(params, basePath);
         if ("error" in result) {
             return {
@@ -1093,6 +1147,17 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             isError: true,
         };
     }
+    finally {
+        if (leaseRefreshTimer !== undefined) {
+            clearInterval(leaseRefreshTimer);
+        }
+        if (workerId !== null && acquiredToken !== null) {
+            releaseMilestoneLease(workerId, params.milestoneId, acquiredToken);
+        }
+        if (workerId !== null) {
+            markWorkerStopping(workerId);
+        }
+    }
 }
 export async function executePlanSlice(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);

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

@@ -38,6 +38,22 @@ 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);
 }
@@ -67,7 +83,8 @@ function resolvePathGsdBrowserVersion(env) {
     if (cachedPathProbeVersion !== undefined)
         return cachedPathProbeVersion;
     try {
-        cachedPathProbeVersion = 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"],
@@ -176,7 +193,8 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     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 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
@@ -198,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",

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);