@opengsd/gsd-pi 1.1.1-dev.2034b16 → 1.1.1-dev.2de7ea0

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -44,19 +44,12 @@ function getRequiredVerificationClasses(milestoneId) {
         required.push("UAT");
     return required;
 }
-async function collectPersistedBrowserEvidence(basePath, milestoneId) {
-    const chunks = [];
-    for (const slice of getMilestoneSlices(milestoneId)) {
-        const artifactPath = `milestones/${milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-        const artifact = getArtifact(artifactPath);
-        if (artifact?.full_content)
-            chunks.push(artifact.full_content);
-        const assessmentPath = resolveSliceFile(basePath, milestoneId, slice.id, "ASSESSMENT");
-        const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-        if (assessmentContent)
-            chunks.push(assessmentContent);
-    }
-    return chunks.join("\n\n");
+function hasRuntimeExecutableUatEvidenceText(text) {
+    if (!/\buatType:\s*runtime-executable\b/i.test(text))
+        return false;
+    if (!/\bverdict:\s*PASS\b/i.test(text))
+        return false;
+    return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
 }
 async function browserEvidenceGateRequiresAttention(params, basePath) {
     if (params.verdict !== "pass")
@@ -77,7 +70,36 @@ async function browserEvidenceGateRequiresAttention(params, basePath) {
     ]);
     if (!hasBrowserRequiredText(requirementText))
         return false;
-    const persistedEvidence = await collectPersistedBrowserEvidence(basePath, params.milestoneId);
+    // Collect per-slice evidence so the runtime bypass is checked independently
+    // for each slice. Concatenating all slices before checking would allow runtime
+    // evidence from one slice to cover another slice's browser requirements.
+    const sliceEvidencePairs = [];
+    for (const slice of slices) {
+        const chunks = [];
+        const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+        const artifact = getArtifact(artifactPath);
+        if (artifact?.full_content)
+            chunks.push(artifact.full_content);
+        const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+        const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+        if (assessmentContent)
+            chunks.push(assessmentContent);
+        sliceEvidencePairs.push({
+            sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+            evidenceText: chunks.join("\n\n"),
+        });
+    }
+    const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
+    // Runtime bypass: each slice whose own requirement text has browser-observable
+    // criteria must have its own runtime-executable UAT evidence. When no individual
+    // slice has slice-level browser requirements (e.g., they come from milestone-level
+    // fields only), fall back to checking whether any slice has runtime evidence.
+    const browserRequiringSlices = sliceEvidencePairs.filter((s) => hasBrowserRequiredText(s.sliceRequirementText));
+    const runtimeBypasses = browserRequiringSlices.length > 0
+        ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
+        : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
+    if (runtimeBypasses)
+        return false;
     const validationEvidence = compactTextParts([
         params.successCriteriaChecklist,
         params.verificationClasses,
@@ -138,12 +160,20 @@ export async function handleValidateMilestone(params, basePath, opts) {
     const requiredClasses = getRequiredVerificationClasses(params.milestoneId);
     if (requiredClasses.length > 0) {
         const verificationClasses = params.verificationClasses ?? "";
-        const missingClass = requiredClasses.find((className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses));
-        if (missingClass) {
+        const missingClasses = requiredClasses.filter((className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses));
+        if (missingClasses.length === 1) {
+            const missingClass = missingClasses[0];
             return {
                 error: `verificationClasses must include canonical row "${missingClass}" because this milestone planned ${missingClass.toLowerCase()} verification`,
             };
         }
+        if (missingClasses.length > 1) {
+            const quotedClasses = missingClasses.map((className) => `"${className}"`).join(", ");
+            const plannedClasses = missingClasses.map((className) => className.toLowerCase()).join(", ");
+            return {
+                error: `verificationClasses must include canonical rows ${quotedClasses} because this milestone planned ${plannedClasses} verification`,
+            };
+        }
     }
     const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
     const shouldApplyBrowserEvidenceGate = !opts?.skipBrowserEvidenceGate &&

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

@@ -954,6 +954,9 @@ function validateUatChecks(basePath, params) {
 function validateUatMode(params) {
     const modes = new Set(params.checks.map((check) => check.mode));
     const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+    if (params.uatType === "artifact-driven" && hasHuman && params.verdict === "PASS") {
+        return "artifact-driven UAT cannot PASS with human-only checks";
+    }
     if (hasHuman &&
         params.verdict === "PASS" &&
         !["human-experience", "mixed", "live-runtime"].includes(params.uatType) &&
@@ -969,11 +972,11 @@ function validateUatMode(params) {
     if (params.uatType === "live-runtime" && !modes.has("runtime") && !modes.has("browser")) {
         return "live-runtime UAT requires runtime or browser evidence";
     }
-    if (params.uatType === "artifact-driven" && hasHuman && params.verdict === "PASS") {
-        return "artifact-driven UAT cannot PASS with human-only checks";
-    }
     return null;
 }
+function quoteToolNames(toolNames) {
+    return toolNames.map((toolName) => `"${toolName}"`).join(", ");
+}
 function validateCanonicalPresentation(params) {
     const aliasHints = {
         gsd_save_summary: "gsd_summary_save",
@@ -981,34 +984,46 @@ function validateCanonicalPresentation(params) {
         gsd_complete_slice: "gsd_slice_complete",
         gsd_milestone_complete: "gsd_complete_milestone",
     };
+    const errors = [];
     for (const toolName of params.presentation.presentedTools) {
         const baseName = parseMcpToolName(toolName)?.tool ?? toolName;
         const canonical = aliasHints[baseName];
         if (canonical)
-            return `presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`;
+            errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
     }
     const presentedCanonical = new Set(params.presentation.presentedTools.map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
-    for (const requiredTool of RUN_UAT_WORKFLOW_TOOL_NAMES) {
-        if (!presentedCanonical.has(requiredTool)) {
-            return `presentation is missing required UAT tool "${requiredTool}"`;
-        }
+    const missingRequiredTools = RUN_UAT_WORKFLOW_TOOL_NAMES.filter((requiredTool) => !presentedCanonical.has(requiredTool));
+    if (missingRequiredTools.length === 1) {
+        errors.push(`presentation is missing required UAT tool "${missingRequiredTools[0]}"`);
+    }
+    else if (missingRequiredTools.length > 1) {
+        errors.push(`presentation is missing required UAT tools ${quoteToolNames(missingRequiredTools)}`);
     }
     const forbiddenCanonical = new Set(RUN_UAT_FORBIDDEN_TOOL_NAMES
         .filter((toolName) => !toolName.includes("*"))
         .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
+    const forbiddenPresentedTools = [];
     for (const toolName of params.presentation.presentedTools) {
         const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName);
         if (toolName === "mcp__gsd-workflow__*" || forbiddenCanonical.has(canonical)) {
-            return `presentation includes forbidden run-uat tool "${toolName}"`;
+            forbiddenPresentedTools.push(toolName);
         }
     }
+    if (forbiddenPresentedTools.length === 1) {
+        errors.push(`presentation includes forbidden run-uat tool "${forbiddenPresentedTools[0]}"`);
+    }
+    else if (forbiddenPresentedTools.length > 1) {
+        errors.push(`presentation includes forbidden run-uat tools ${quoteToolNames(forbiddenPresentedTools)}`);
+    }
     const blockedCanonical = new Set(params.presentation.blockedTools.map((entry) => canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)));
-    for (const blockedTool of ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"]) {
-        if (!blockedCanonical.has(blockedTool)) {
-            return `presentation must record "${blockedTool}" as blocked during run-uat`;
-        }
+    const missingBlockedTools = ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"].filter((blockedTool) => !blockedCanonical.has(blockedTool));
+    if (missingBlockedTools.length === 1) {
+        errors.push(`presentation must record "${missingBlockedTools[0]}" as blocked during run-uat`);
     }
-    return null;
+    else if (missingBlockedTools.length > 1) {
+        errors.push(`presentation must record ${quoteToolNames(missingBlockedTools)} as blocked during run-uat`);
+    }
+    return errors.length > 0 ? errors.join("; ") : null;
 }
 function nextUatAttempt(basePath, milestoneId, sliceId) {
     const contract = resolveGsdPathContract(basePath);

package/dist/resources/extensions/gsd/verdict-parser.js

@@ -5,7 +5,62 @@
  * (e.g. `passed` → `pass`) are applied consistently across the codebase.
  */
 import { extractUatType } from "./files.js";
+import { splitFrontmatter, parseFrontmatterMap } from "../shared/frontmatter.js";
+import { parse as parseYaml } from "yaml";
+function normalizeVerdict(value) {
+    if (typeof value !== "string")
+        return undefined;
+    let verdict = value.trim().toLowerCase();
+    if (!verdict)
+        return undefined;
+    if (verdict === "passed")
+        verdict = "pass";
+    return verdict;
+}
+function getCaseInsensitive(obj, key) {
+    const lowerKey = key.toLowerCase();
+    for (const [candidate, value] of Object.entries(obj)) {
+        if (candidate.toLowerCase() === lowerKey)
+            return value;
+    }
+    return undefined;
+}
 // ── Verdict extraction ──────────────────────────────────────────────────
+/**
+ * Extract and normalize the frontmatter `verdict` value.
+ *
+ * Supports both top-level `verdict` and the hook outcome shape
+ * `outcome.verdict`. Returns `undefined` when frontmatter is absent or has no
+ * verdict field.
+ */
+export function extractFrontmatterVerdict(content) {
+    const [frontmatterLines] = splitFrontmatter(content);
+    if (!frontmatterLines)
+        return undefined;
+    try {
+        const parsed = parseYaml(frontmatterLines.join("\n"));
+        if (parsed && typeof parsed === "object") {
+            const root = parsed;
+            const topLevel = normalizeVerdict(getCaseInsensitive(root, "verdict"));
+            if (topLevel)
+                return topLevel;
+            const outcome = getCaseInsensitive(root, "outcome");
+            if (outcome && typeof outcome === "object") {
+                const nested = normalizeVerdict(getCaseInsensitive(outcome, "verdict"));
+                if (nested)
+                    return nested;
+            }
+        }
+    }
+    catch {
+        // Fall through to the permissive parser used by legacy frontmatter paths.
+    }
+    const frontmatter = parseFrontmatterMap(frontmatterLines);
+    const topLevel = normalizeVerdict(getCaseInsensitive(frontmatter, "verdict"));
+    if (topLevel)
+        return topLevel;
+    return undefined;
+}
 /**
  * Extract and normalize the `verdict` value from YAML frontmatter.
  *
@@ -17,25 +72,14 @@ import { extractUatType } from "./files.js";
  */
 export function extractVerdict(content) {
     // Primary: YAML frontmatter verdict (canonical format)
-    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (fmMatch) {
-        const verdictMatch = fmMatch[1].match(/verdict:\s*([\w-]+)/i);
-        if (verdictMatch) {
-            let v = verdictMatch[1].toLowerCase();
-            if (v === "passed")
-                v = "pass";
-            return v;
-        }
-        return undefined;
-    }
+    const [frontmatterLines] = splitFrontmatter(content);
+    if (frontmatterLines)
+        return extractFrontmatterVerdict(content);
     // Fallback: detect verdict in markdown body (LLM manual writes, #2960).
     // Matches patterns like: **Verdict:** PASS, **Verdict:** ✅ PASS, **Verdict** needs-remediation
     const bodyMatch = content.match(/\*\*Verdict:?\*\*\s*(?:✅\s*)?(\w[\w-]*)/i);
     if (bodyMatch) {
-        let v = bodyMatch[1].toLowerCase();
-        if (v === "passed")
-            v = "pass";
-        return v;
+        return normalizeVerdict(bodyMatch[1]);
     }
     return undefined;
 }

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

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const GSD_BROWSER_MCP_SERVER_NAME = "gsd-browser";
+function parseJsonEnv(env, name) {
+    const raw = env[name];
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in ${name}`);
+    }
+}
+function sanitizeSessionSegment(value) {
+    return value
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+}
+function compareSemverLocal(a, b) {
+    const left = a.split(".").map(Number);
+    const right = b.split(".").map(Number);
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const leftValue = left[index] || 0;
+        const rightValue = right[index] || 0;
+        if (leftValue > rightValue)
+            return 1;
+        if (leftValue < rightValue)
+            return -1;
+    }
+    return 0;
+}
+function parseGsdBrowserVersion(output) {
+    return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+}
+function resolveBundledGsdBrowserPackageVersion() {
+    try {
+        const requireFromHere = createRequire(import.meta.url);
+        const packageJsonPath = requireFromHere.resolve("@opengsd/gsd-browser/package.json");
+        const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+        return typeof pkg.version === "string" ? parseGsdBrowserVersion(pkg.version) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolvePathGsdBrowserVersion(env) {
+    const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
+    if (explicit)
+        return parseGsdBrowserVersion(explicit);
+    try {
+        return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+            encoding: "utf-8",
+            env,
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+function shouldPreferPathGsdBrowser(env) {
+    const pathVersion = resolvePathGsdBrowserVersion(env);
+    if (!pathVersion)
+        return false;
+    const bundledVersion = resolveBundledGsdBrowserPackageVersion();
+    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();
+    if (explicit)
+        return explicit;
+    try {
+        const requireFromHere = createRequire(import.meta.url);
+        const packageJsonPath = requireFromHere.resolve("@opengsd/gsd-browser/package.json");
+        const candidate = resolve(packageJsonPath, "..", "bin", "gsd-browser");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    catch {
+        // Fall through to path candidates for source/dist layouts.
+    }
+    const candidates = [
+        resolve(fileURLToPath(new URL("../../../../node_modules/@opengsd/gsd-browser/bin/gsd-browser", import.meta.url))),
+        resolve(fileURLToPath(new URL("../../../../node_modules/.bin/gsd-browser", import.meta.url))),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function buildGsdBrowserSessionName(projectRoot, suffix) {
+    const resolvedProjectRoot = resolve(projectRoot);
+    const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
+    const hash = createHash("sha1").update(resolvedProjectRoot).digest("hex").slice(0, 8);
+    const cleanSuffix = suffix ? sanitizeSessionSegment(suffix) : "";
+    return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
+}
+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 preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
+    const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
+        ? resolveBundledGsdBrowserCliPath(env)
+        : null;
+    const sessionName = options.sessionName?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot, options.sessionSuffix);
+    const command = explicitCommand
+        || explicitCliPath
+        || (preferPathCli ? "gsd-browser" : undefined)
+        || (bundledCliPath ? process.execPath : undefined)
+        || "gsd-browser";
+    const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
+        ? explicitArgs.map(String)
+        : [
+            ...(bundledCliPath ? [bundledCliPath] : []),
+            "mcp",
+            "--session",
+            sessionName,
+            "--identity-scope",
+            "project",
+            "--identity-project",
+            resolvedProjectRoot,
+        ];
+    const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
+    return {
+        serverName,
+        command,
+        args,
+        cwd,
+        ...(explicitEnv ? { env: explicitEnv } : {}),
+        projectRoot: resolvedProjectRoot,
+        sessionName,
+    };
+}

package/dist/rtk.d.ts

@@ -40,6 +40,12 @@ export interface ValidateRtkBinaryOptions {
     spawnSyncImpl?: typeof spawnSync;
     env?: NodeJS.ProcessEnv;
 }
-export declare function validateRtkBinary(binaryPath: string, options?: ValidateRtkBinaryOptions): boolean;
+export type ValidateRtkBinaryResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+export declare function validateRtkBinary(binaryPath: string, options?: ValidateRtkBinaryOptions): ValidateRtkBinaryResult;
 export declare function ensureRtkAvailable(options?: EnsureRtkOptions): Promise<EnsureRtkResult>;
 export declare function bootstrapRtk(options?: EnsureRtkOptions): Promise<EnsureRtkResult>;

package/dist/rtk.js

@@ -162,19 +162,28 @@ export function rewriteCommandWithRtk(command, options = {}) {
     const rewritten = (result.stdout ?? "").trimEnd();
     return rewritten || command;
 }
+function trimSpawnOutput(output) {
+    return output?.toString().trim() ?? "";
+}
 export function validateRtkBinary(binaryPath, options = {}) {
     const run = options.spawnSyncImpl ?? spawnSync;
     const result = run(binaryPath, ["rewrite", "git status"], {
         encoding: "utf-8",
         env: buildRtkEnv(options.env ?? process.env),
-        stdio: ["ignore", "pipe", "ignore"],
+        stdio: ["ignore", "pipe", "pipe"],
         timeout: RTK_REWRITE_TIMEOUT_MS,
     });
     if (result.error)
-        return false;
-    if (result.status !== 0)
-        return false;
-    return (result.stdout ?? "").trim() === "rtk git status";
+        return { valid: false, error: result.error.message };
+    if (result.status !== 0) {
+        const stderr = trimSpawnOutput(result.stderr);
+        return { valid: false, error: stderr || `exit code ${result.status ?? "unknown"}` };
+    }
+    const stdout = trimSpawnOutput(result.stdout);
+    if (stdout !== "rtk git status") {
+        return { valid: false, error: stdout ? `unexpected output: ${stdout}` : "unexpected empty output" };
+    }
+    return { valid: true };
 }
 export async function ensureRtkAvailable(options = {}) {
     const env = options.env ?? process.env;
@@ -190,12 +199,18 @@ export async function ensureRtkAvailable(options = {}) {
     }
     const targetDir = options.targetDir ?? getManagedRtkDir(env);
     const managedPath = getManagedRtkPath(process.platform, targetDir);
-    if (existsSync(managedPath) && validateRtkBinary(managedPath, { env })) {
-        return { enabled: true, supported: true, available: true, source: "managed", binaryPath: managedPath };
+    if (existsSync(managedPath)) {
+        const managedValidation = validateRtkBinary(managedPath, { env });
+        if (managedValidation.valid) {
+            return { enabled: true, supported: true, available: true, source: "managed", binaryPath: managedPath };
+        }
     }
     const systemPath = resolveSystemRtkPath(options.pathValue ?? getPathValue(env));
-    if (systemPath && validateRtkBinary(systemPath, { env })) {
-        return { enabled: true, supported: true, available: true, source: "system", binaryPath: systemPath };
+    if (systemPath) {
+        const systemValidation = validateRtkBinary(systemPath, { env });
+        if (systemValidation.valid) {
+            return { enabled: true, supported: true, available: true, source: "system", binaryPath: systemPath };
+        }
     }
     const version = options.releaseVersion ?? RTK_VERSION;
     const assetName = resolveRtkAssetName(process.platform, osArch(), version);
@@ -241,9 +256,10 @@ export async function ensureRtkAvailable(options = {}) {
         if (process.platform !== "win32") {
             chmodSync(managedPath, 0o755);
         }
-        if (!validateRtkBinary(managedPath, { env })) {
+        const downloadedValidation = validateRtkBinary(managedPath, { env });
+        if (!downloadedValidation.valid) {
             rmSync(managedPath, { force: true });
-            throw new Error("downloaded RTK binary failed validation");
+            throw new Error(`downloaded RTK binary failed validation: ${downloadedValidation.error}`);
         }
         options.log?.(`installed RTK ${version} to ${managedPath}`);
         return { enabled: true, supported: true, available: true, source: "downloaded", binaryPath: managedPath };

package/dist/update-check.d.ts

@@ -1,5 +1,9 @@
 import { isPnpmInstall } from './resources/shared/package-manager-detection.js';
 export { isPnpmInstall };
+export declare const GSD_PI_PACKAGE_NAME = "@opengsd/gsd-pi";
+export declare const GSD_BROWSER_PACKAGE_NAME = "@opengsd/gsd-browser";
+export declare const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org/@opengsd%2fgsd-pi/latest";
+export declare const GSD_BROWSER_REGISTRY_URL = "https://registry.npmjs.org/@opengsd%2fgsd-browser/latest";
 interface UpdateCheckCache {
     lastCheck: number;
     latestVersion: string;
@@ -13,6 +17,14 @@ export declare function readUpdateCache(cachePath?: string, packageName?: string
 export declare function writeUpdateCache(cache: Omit<UpdateCheckCache, 'packageName'> & {
     packageName?: string;
 }, cachePath?: string, packageName?: string): void;
+export declare function resolveInstalledPackageVersion(packageName: string): string | null;
+/**
+ * Resolves the gsd-browser version from PATH (via `gsd-browser --version`).
+ * Respects GSD_BROWSER_PATH_VERSION env override for testing.
+ * Returns null if gsd-browser is not on PATH or times out.
+ */
+export declare function resolveGsdBrowserPathVersion(env?: NodeJS.ProcessEnv): string | null;
+export declare function pickHigherVersion(a: string | null, b: string | null): string | null;
 export declare function fetchLatestVersionFromRegistry(registryUrl?: string, fetchTimeoutMs?: number): Promise<string | null>;
 /**
  * Detects whether the currently-running gsd binary was installed via `bun add -g`.
@@ -29,18 +41,20 @@ export declare function resolveInstallCommand(pkg: string, options?: {
     env?: NodeJS.ProcessEnv;
 }): string;
 export interface UpdateCheckOptions {
+    packageName?: string;
     currentVersion?: string;
     cachePath?: string;
     registryUrl?: string;
     checkIntervalMs?: number;
     fetchTimeoutMs?: number;
-    onUpdate?: (current: string, latest: string) => void;
+    onUpdate?: (current: string, latest: string, packageName: string) => void;
 }
 /**
  * Non-blocking update check. Queries npm registry at most once per 24h,
  * caches the result, and prints a banner if a newer version is available.
  */
 export declare function checkForUpdates(options?: UpdateCheckOptions): Promise<void>;
+export declare function checkForGsdBrowserUpdates(options?: UpdateCheckOptions): Promise<void>;
 /**
  * Interactive update prompt shown at startup when a newer version is available.
  * Fetches the latest version (with cache), then asks the user whether to