@opengsd/gsd-pi 1.1.1-dev.74e8dd1 → 1.1.1-dev.9bb7453

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -314,9 +314,18 @@ export async function handleCompleteTask(params, basePath) {
     // overwrite it; gate rows are UPSERT-keyed per task and will also be
     // overwritten. This restores the invariant that deriveState() sees a
     // consistent "task not done" view so the loop re-dispatches the task.
+    let escalationMetadata;
     if (validatedEscalationArtifact) {
         try {
-            writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+            const escalationPath = writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+            escalationMetadata = {
+                artifactPath: escalationPath,
+                question: validatedEscalationArtifact.question,
+                options: validatedEscalationArtifact.options,
+                recommendation: validatedEscalationArtifact.recommendation,
+                recommendationRationale: validatedEscalationArtifact.recommendationRationale,
+                continueWithDefault: validatedEscalationArtifact.continueWithDefault,
+            };
         }
         catch (escalationErr) {
             const msg = `complete-task escalation write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${escalationErr.message}`;
@@ -378,6 +387,7 @@ export async function handleCompleteTask(params, basePath) {
         sliceId: params.sliceId,
         milestoneId: params.milestoneId,
         summaryPath,
+        ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
         ...(projectionStale ? { stale: true } : {}),
     };
 }

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

@@ -334,6 +334,28 @@ export async function executeTaskComplete(params, basePath = process.cwd()) {
                 isError: true,
             };
         }
+        if (result.escalation) {
+            const recommended = result.escalation.options.find((option) => option.id === result.escalation?.recommendation);
+            const optionIds = result.escalation.options.map((option) => option.id).join("|");
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `Task completed with escalation decision required: ${result.escalation.question}`,
+                            `Recommendation: ${result.escalation.recommendation}${recommended ? ` (${recommended.label})` : ""} — ${result.escalation.recommendationRationale}`,
+                            `Resolve with: /gsd escalate resolve ${result.taskId} <${optionIds}|accept|reject-blocker> [rationale...]`,
+                        ].join("\n"),
+                    }],
+                details: {
+                    operation: "complete_task",
+                    taskId: result.taskId,
+                    sliceId: result.sliceId,
+                    milestoneId: result.milestoneId,
+                    summaryPath: result.summaryPath,
+                    escalation: result.escalation,
+                },
+            };
+        }
         return {
             content: [{ type: "text", text: `Completed task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
             details: {
@@ -932,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) &&
@@ -947,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",
@@ -959,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/gsd/verification-gate.js

@@ -246,6 +246,76 @@ function hasUnsafeShellSyntax(cmd) {
     }
     return false;
 }
+function splitLeadingShellWords(cmd) {
+    const words = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < cmd.length; i += 1) {
+        const ch = cmd[i];
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\" && !inSingle) {
+            escaped = true;
+            continue;
+        }
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === "\"" && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (!inSingle && !inDouble) {
+            if (/\s/.test(ch)) {
+                if (current) {
+                    words.push(current);
+                    current = "";
+                }
+                continue;
+            }
+            if ([";", "|", "&", "<", ">"].includes(ch)) {
+                break;
+            }
+        }
+        current += ch;
+    }
+    if (current) {
+        words.push(current);
+    }
+    return words;
+}
+function isCountFlag(token) {
+    return (token === "--count" ||
+        token.startsWith("--count=") ||
+        token === "--count-matches" ||
+        token.startsWith("--count-matches=") ||
+        /^-[A-Za-z]*c[A-Za-z]*$/.test(token));
+}
+function countSearchWarning(command, exitCode) {
+    if (exitCode !== 1)
+        return null;
+    const trimmed = command.trim();
+    if (trimmed.startsWith("!"))
+        return null;
+    const [tool, ...args] = splitLeadingShellWords(trimmed);
+    if (tool !== "grep" && tool !== "rg")
+        return null;
+    if (!args.some(isCountFlag))
+        return null;
+    return `verification-gate: warning: '${tool} -c' returns exit 1 when count=0; for absence checks use '! ${tool} -q ...' instead.`;
+}
+function appendStderrWarning(stderr, warning) {
+    if (!warning)
+        return stderr;
+    const trimmed = stderr.trimEnd();
+    return trimmed ? `${trimmed}\n${warning}` : warning;
+}
 /**
  * Known executable first-tokens that are safe to run.
  * Lowercase commands, common build/test tools, and npm/yarn/pnpm invocations.
@@ -411,11 +481,12 @@ export function runVerificationGate(options) {
             exitCode = result.status ?? 1;
             stderr = truncate(result.stderr, MAX_OUTPUT_BYTES);
         }
+        const warning = countSearchWarning(command, exitCode);
         checks.push({
             command,
             exitCode,
             stdout: truncate(result.stdout, MAX_OUTPUT_BYTES),
-            stderr,
+            stderr: truncate(appendStderrWarning(stderr, warning), MAX_OUTPUT_BYTES),
             durationMs,
         });
     }

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