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

package/src/resources/extensions/browser-tools/extension-manifest.json

@@ -2,7 +2,7 @@
   "id": "browser-tools",
   "name": "Browser Tools",
   "version": "1.0.0",
-  "description": "Playwright-based web automation, screenshots, and analysis",
+  "description": "GSD browser automation contract adapter backed by the managed gsd-browser engine",
   "tier": "bundled",
   "requires": { "platform": ">=2.29.0" },
   "provides": {
@@ -32,6 +32,6 @@
     "hooks": ["session_start", "session_shutdown"]
   },
   "dependencies": {
-    "runtime": ["playwright"]
+    "runtime": ["@opengsd/gsd-browser"]
   }
 }

package/src/resources/extensions/browser-tools/index.ts

@@ -1,11 +1,16 @@
-/** browser-tools — pi extension: full browser interaction via Playwright. */
+/** browser-tools — Pi Browser Automation Contract adapter. */
 import { importExtensionModule, type ExtensionAPI } from "@gsd/pi-coding-agent";
 
-let registrationPromise: Promise<void> | null = null;
+import { closeManagedGsdBrowser, registerManagedGsdBrowserTools } from "./engine/managed-gsd-browser.js";
+import { resolveBrowserEngineMode, type BrowserEngineMode } from "./engine/selection.js";
 
-async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
-  if (!registrationPromise) {
-    registrationPromise = (async () => {
+let legacyRegistrationPromise: Promise<void> | null = null;
+let managedRegistrationPromise: Promise<void> | null = null;
+let registeredEngine: Exclude<BrowserEngineMode, "off"> | null = null;
+
+async function registerLegacyBrowserTools(pi: ExtensionAPI): Promise<void> {
+  if (!legacyRegistrationPromise) {
+    legacyRegistrationPromise = (async () => {
       const [
         lifecycle,
         capture,
@@ -136,12 +141,55 @@ async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
       injectionDetection.registerInjectionDetectionTools(pi, deps);
       verify.registerVerifyTools(pi, deps);
     })().catch((error) => {
-      registrationPromise = null;
+      legacyRegistrationPromise = null;
       throw error;
     });
   }
 
-  return registrationPromise;
+  return legacyRegistrationPromise;
+}
+
+async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
+  const engine = resolveBrowserEngineMode();
+  if (engine === "off") return;
+  if (registeredEngine && registeredEngine !== engine) {
+    throw new Error(
+      `Browser tools already registered with GSD_BROWSER_ENGINE=${registeredEngine}. Restart GSD before switching to ${engine}.`,
+    );
+  }
+
+  let registration: Promise<void>;
+  if (engine === "legacy") {
+    registration = registerLegacyBrowserTools(pi);
+  } else if (!managedRegistrationPromise) {
+    managedRegistrationPromise = Promise.resolve()
+      .then(() => {
+        registerManagedGsdBrowserTools(pi);
+      })
+      .catch((error) => {
+        managedRegistrationPromise = null;
+        throw error;
+      });
+    registration = managedRegistrationPromise;
+  } else {
+    registration = managedRegistrationPromise;
+  }
+
+  registeredEngine = engine;
+  try {
+    await registration;
+  } catch (error) {
+    if (registeredEngine === engine) registeredEngine = null;
+    throw error;
+  }
+}
+
+async function closeActiveBrowserEngines(): Promise<void> {
+  await closeManagedGsdBrowser();
+  if (legacyRegistrationPromise) {
+    const { closeBrowser } = await importExtensionModule<typeof import("./lifecycle.js")>(import.meta.url, "./lifecycle.js");
+    await closeBrowser();
+  }
 }
 
 export default function (pi: ExtensionAPI) {
@@ -157,7 +205,10 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_shutdown", async () => {
-    const { closeBrowser } = await importExtensionModule<typeof import("./lifecycle.js")>(import.meta.url, "./lifecycle.js");
-    await closeBrowser();
+    await closeActiveBrowserEngines();
+  });
+
+  pi.on("session_switch", async () => {
+    await closeActiveBrowserEngines();
   });
 }

package/src/resources/extensions/browser-tools/package.json

@@ -4,16 +4,20 @@
   "version": "1.0.0",
   "type": "module",
   "scripts": {
-    "test": "node --test tests/*.test.mjs"
+    "test": "node --import ../gsd/tests/resolve-ts.mjs --experimental-strip-types --test tests/*.test.mjs"
   },
   "pi": {
     "extensions": ["./index.ts"]
   },
   "peerDependencies": {
+    "@opengsd/gsd-browser": ">=0.1.27",
     "playwright": ">=1.40.0",
     "sharp": ">=0.33.0"
   },
   "peerDependenciesMeta": {
+    "@opengsd/gsd-browser": {
+      "optional": true
+    },
     "playwright": {
       "optional": true
     },

package/src/resources/extensions/browser-tools/tests/browser-engine-selection.test.mjs

@@ -0,0 +1,35 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const jiti = require("jiti")(__dirname, { interopDefault: true, debug: false });
+
+const { resolveBrowserEngineMode } = jiti("../engine/selection.ts");
+
+describe("resolveBrowserEngineMode", () => {
+  it("defaults to gsd-browser", () => {
+    assert.equal(resolveBrowserEngineMode({}), "gsd-browser");
+  });
+
+  it("accepts the explicit engine modes", () => {
+    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "gsd-browser" }), "gsd-browser");
+    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "legacy" }), "legacy");
+    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "off" }), "off");
+  });
+
+  it("accepts compatibility aliases", () => {
+    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "playwright" }), "legacy");
+    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "false" }), "off");
+  });
+
+  it("rejects unknown engine modes", () => {
+    assert.throws(
+      () => resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "surprise" }),
+      /Expected "gsd-browser", "legacy", or "off"/,
+    );
+  });
+});

package/src/resources/extensions/browser-tools/tests/managed-gsd-browser-tools.test.mjs

@@ -0,0 +1,33 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+const {
+  MANAGED_GSD_BROWSER_TOOL_NAMES,
+  registerManagedGsdBrowserTools,
+} = await import("../engine/managed-gsd-browser.ts");
+
+describe("registerManagedGsdBrowserTools", () => {
+  it("registers the curated Pi browser contract", () => {
+    const tools = [];
+    registerManagedGsdBrowserTools({
+      registerTool(tool) {
+        tools.push(tool);
+      },
+    });
+
+    assert.deepEqual(tools.map((tool) => tool.name), [...MANAGED_GSD_BROWSER_TOOL_NAMES]);
+    assert.equal(new Set(tools.map((tool) => tool.name)).size, tools.length);
+  });
+
+  it("keeps screenshots marked as image-producing evidence", () => {
+    const tools = [];
+    registerManagedGsdBrowserTools({
+      registerTool(tool) {
+        tools.push(tool);
+      },
+    });
+
+    const screenshot = tools.find((tool) => tool.name === "browser_screenshot");
+    assert.equal(screenshot?.compatibility?.producesImages, true);
+  });
+});

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -55,8 +55,10 @@ import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
 import { consumeSignal } from "./session-status-io.js";
 import {
   checkPostUnitHooks,
+  consumeHookFailure,
   isRetryPending,
   consumeRetryTrigger,
+  consumeGateBlock,
   persistHookState,
   resolveHookArtifactPath,
 } from "./post-unit-hooks.js";
@@ -2227,11 +2229,11 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   // ── Post-unit hooks ──
   if (s.currentUnit && !s.stepMode) {
     const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath);
+    persistHookState(s.basePath);
     if (hookUnit) {
       if (s.currentUnit) {
         await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
       }
-      persistHookState(s.basePath);
 
       return enqueueSidecar(
         s, ctx,
@@ -2240,12 +2242,23 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
       );
     }
 
+    const hookFailure = consumeHookFailure();
+    if (hookFailure) {
+      ctx.ui.notify(
+        `Post-unit hook ${hookFailure.hookName} failed for ${hookFailure.unitId}: ${hookFailure.reason}. Pausing auto-mode.`,
+        "warning",
+      );
+      await pauseAuto(ctx, pi);
+      return "stopped";
+    }
+
     // Check if a hook requested a retry of the trigger unit
     if (isRetryPending()) {
       const trigger = consumeRetryTrigger();
       if (trigger) {
+        persistHookState(s.basePath);
         ctx.ui.notify(
-          `Hook requested retry of ${trigger.unitType} ${trigger.unitId} — resetting task state.`,
+          `Hook requested retry of ${trigger.unitType} ${trigger.unitId} — resetting trigger unit state.`,
           "info",
         );
 
@@ -2299,6 +2312,19 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
         // Fall through to normal dispatch — deriveState will re-derive the unit
       }
     }
+
+    const gateBlock = consumeGateBlock();
+    if (gateBlock) {
+      persistHookState(s.basePath);
+      const verdict = gateBlock.verdict ? ` verdict=${gateBlock.verdict};` : "";
+      const artifact = gateBlock.artifact ? ` artifact=${gateBlock.artifact};` : "";
+      const message =
+        `Post-unit gate "${gateBlock.hookName}" blocked ${gateBlock.triggerUnitType} ${gateBlock.triggerUnitId}:` +
+        `${verdict}${artifact} ${gateBlock.reason}. Run /gsd status to inspect, then /gsd auto after recovery.`;
+      ctx.ui.notify(message, "warning");
+      await pauseAuto(ctx, pi);
+      return "stopped";
+    }
   }
 
   // ── Fast-path stop detection (#3487) ──

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -1429,7 +1429,7 @@ export async function checkNeedsRunUat(
           // If the UAT file already contains a verdict, UAT has been run — skip
           if (hasVerdict(uatContent)) continue;
           // Also check the ASSESSMENT file — the run-uat prompt writes the verdict
-          // there (via gsd_summary_save artifact_type:"ASSESSMENT"), not into the
+          // there (via gsd_uat_result_save), not into the
           // UAT spec file. Without this check the unit re-dispatches indefinitely.
           const assessmentFile = resolveSliceFile(base, mid, sid, "ASSESSMENT");
           if (assessmentFile) {
@@ -2986,13 +2986,23 @@ export async function buildValidateMilestonePrompt(
     if (isDbAvailable()) {
       const milestone = getMilestone(mid);
       if (milestone) {
+        const escapeCell = (value: string) =>
+          value.replace(/[\\|]/g, (char) => `\\${char}`).replace(/\r?\n/g, " ");
         const classes: string[] = [];
-        if (milestone.verification_contract) classes.push(`- **Contract:** ${milestone.verification_contract}`);
-        if (milestone.verification_integration) classes.push(`- **Integration:** ${milestone.verification_integration}`);
-        if (milestone.verification_operational) classes.push(`- **Operational:** ${milestone.verification_operational}`);
-        if (milestone.verification_uat) classes.push(`- **UAT:** ${milestone.verification_uat}`);
+        if (milestone.verification_contract) classes.push(`| Contract | ${escapeCell(milestone.verification_contract)} |`);
+        if (milestone.verification_integration) classes.push(`| Integration | ${escapeCell(milestone.verification_integration)} |`);
+        if (milestone.verification_operational) classes.push(`| Operational | ${escapeCell(milestone.verification_operational)} |`);
+        if (milestone.verification_uat) classes.push(`| UAT | ${escapeCell(milestone.verification_uat)} |`);
         if (classes.length > 0) {
-          const verificationClasses = `### Verification Classes (from planning)\n\nThese verification tiers were defined during milestone planning. Each non-empty class must be checked for evidence during validation.\n\n${classes.join("\n")}`;
+          const verificationClasses = [
+            "### Verification Classes (from planning)",
+            "",
+            "These verification tiers were defined during milestone planning. Every row in this table must appear in `verificationClasses` with the same canonical class name.",
+            "",
+            "| Class | Planned Check |",
+            "| --- | --- |",
+            ...classes,
+          ].join("\n");
           inlined.push(verificationClasses);
           trackPromptContext(contextTelemetry, "verification-classes", "inline", verificationClasses);
         }

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -1095,7 +1095,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use gsd_validate_milestone when all slices are done and the milestone needs validation before completion.",
       "Parameters: milestoneId, verdict, remediationRound, successCriteriaChecklist, sliceDeliveryAudit, crossSliceIntegration, requirementCoverage, verificationClasses (optional), verdictRationale, remediationPlan (optional).",
-      "If verification classes were planned, verificationClasses must include canonical class rows using the exact class names Contract, Integration, Operational, and UAT when present in planning.",
+      "If verification classes were planned, verificationClasses must be a complete canonical table with one row for every applicable planned class using the exact class names Contract, Integration, Operational, and UAT. Do not submit a partial table.",
       "Planned verification text marked as none/not required/not applicable/N/A (including suffixed variants such as 'not required - backend-only') is treated as not applicable and does not require a class row.",
       "If verdict is 'needs-remediation', also provide remediationPlan and use gsd_reassess_roadmap to add remediation slices to the roadmap.",
       "On success, returns validationPath where VALIDATION.md was written.",
@@ -1108,7 +1108,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       sliceDeliveryAudit: Type.String({ description: "Markdown table auditing each slice's claimed vs delivered output" }),
       crossSliceIntegration: Type.String({ description: "Markdown describing any cross-slice boundary mismatches" }),
       requirementCoverage: Type.String({ description: "Markdown describing any unaddressed requirements" }),
-      verificationClasses: Type.Optional(Type.String({ description: "Markdown describing verification class compliance and gaps using canonical class names (Contract, Integration, Operational, UAT) for each applicable planned class" })),
+      verificationClasses: Type.Optional(Type.String({ description: "Complete markdown table describing verification class compliance and gaps; include one canonical row for every applicable planned class (Contract, Integration, Operational, UAT)" })),
       verdictRationale: Type.String({ description: "Why this verdict was chosen" }),
       remediationPlan: Type.Optional(Type.String({ description: "Remediation plan (required if verdict is needs-remediation)" })),
     }),

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

@@ -1,11 +1,13 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
 
-export const BROWSER_REQUIREMENT_RE = /\b(?:browser|file:\/\/|localhost|dom|localstorage|click(?:ing|ed)?|button|screenshot|snapshot|reload(?:ed)?|page refresh|user-visible|strikethrough|search box)\b/i;
+export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
 export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
+const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;
+const NON_REQUIREMENT_BROWSER_LINE_RE = /\b(?:deferred|not\s+proven|not\s+covered|out\s+of\s+scope|future\s+slice|follow-?up|no\s+(?:live\s+)?browser|without\s+(?:a\s+)?browser|not\s+(?:a\s+)?browser)\b/i;
 
 export function compactTextParts(parts: Array<string | string[] | null | undefined>): string {
   return parts.flatMap((part) => Array.isArray(part) ? part : [part])
@@ -14,7 +16,29 @@ export function compactTextParts(parts: Array<string | string[] | null | undefin
 }
 
 export function hasBrowserRequiredText(text: string): boolean {
-  return BROWSER_REQUIREMENT_RE.test(text);
+  let inNonRequirementSection = false;
+  let nonRequirementDepth = 0;
+  for (const line of text.split(/\r?\n/)) {
+    const headingMatch = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (headingMatch) {
+      const depth = headingMatch[1]!.length;
+      const title = headingMatch[2] ?? "";
+      // Only update section context when at the same or higher level than the
+      // heading that opened the non-requirement zone. A sub-heading deeper than
+      // the opening heading must not escape or re-enter the zone on its own.
+      if (!inNonRequirementSection || depth <= nonRequirementDepth) {
+        inNonRequirementSection = NON_REQUIREMENT_BROWSER_HEADING_RE.test(title);
+        nonRequirementDepth = inNonRequirementSection ? depth : 0;
+      }
+      // Check the heading title itself — section state is already updated, so
+      // we correctly skip headings that opened a non-requirement zone.
+      if (!inNonRequirementSection && BROWSER_REQUIREMENT_RE.test(title)) return true;
+      continue;
+    }
+    if (inNonRequirementSection || NON_REQUIREMENT_BROWSER_LINE_RE.test(line)) continue;
+    if (BROWSER_REQUIREMENT_RE.test(line)) return true;
+  }
+  return false;
 }
 
 export function hasBrowserEvidenceText(text: string): boolean {

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

@@ -282,8 +282,8 @@ Examples:
     await handleInspect(ctx);
     return true;
   }
-  if (trimmed === "update" || trimmed === "upgrade") {
-    await handleUpdate(ctx);
+  if (trimmed === "update" || trimmed.startsWith("update ") || trimmed === "upgrade" || trimmed.startsWith("upgrade ")) {
+    await handleUpdate(ctx, trimmed.replace(/^(?:update|upgrade)\s*/, "").trim());
     return true;
   }
   if (trimmed === "fast" || trimmed.startsWith("fast ")) {

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

@@ -7,6 +7,8 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { join, resolve as resolvePath, sep } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
@@ -37,7 +39,10 @@ import {
   scopeGsdWorkflowToolsForDispatch,
 } from "./bootstrap/register-hooks.js";
 
+const GSD_PI_PACKAGE = "@opengsd/gsd-pi";
+const GSD_BROWSER_PACKAGE = "@opengsd/gsd-browser";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/@opengsd%2fgsd-pi/latest";
+const BROWSER_UPDATE_REGISTRY_URL = "https://registry.npmjs.org/@opengsd%2fgsd-browser/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
 
 // Detects a bun-installed gsd via `process.argv[1]`. Mirrors isBunInstall in
@@ -62,12 +67,12 @@ function resolveInstallCommand(pkg: string): string {
   return `npm install -g ${pkg}`;
 }
 
-async function fetchLatestVersionForCommand(): Promise<string | null> {
+async function fetchLatestVersionForCommand(registryUrl: string = UPDATE_REGISTRY_URL): Promise<string | null> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS);
 
   try {
-    const res = await fetch(UPDATE_REGISTRY_URL, { signal: controller.signal });
+    const res = await fetch(registryUrl, { signal: controller.signal });
     if (!res.ok) return null;
     const data = (await res.json()) as { version?: string };
     const latest = typeof data.version === "string" ? data.version.trim().replace(/^v/, "") : "";
@@ -79,6 +84,19 @@ async function fetchLatestVersionForCommand(): Promise<string | null> {
   }
 }
 
+function resolveInstalledPackageVersionForCommand(packageName: string): string | null {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    const packageJsonPath = requireFromHere.resolve(`${packageName}/package.json`);
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as { version?: unknown };
+    return typeof pkg.version === "string" && pkg.version.trim().length > 0
+      ? pkg.version.trim().replace(/^v/, "")
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
@@ -473,34 +491,81 @@ function compareSemverLocal(a: string, b: string): number {
   return 0
 }
 
-export async function handleUpdate(ctx: ExtensionCommandContext): Promise<void> {
+function formatCommandVersion(version: string | null): string {
+  return version ? `v${version}` : "unknown";
+}
+
+function pickHigherVersionForCommand(a: string | null, b: string | null): string | null {
+  if (!a) return b;
+  if (!b) return a;
+  return compareSemverLocal(a, b) >= 0 ? a : b;
+}
+
+// Mirrors resolveGsdBrowserPathVersion in src/update-check.ts — duplicated because
+// tsconfig.resources.json rootDir prevents importing from src/.
+function resolveGsdBrowserPathVersionForCommand(env: NodeJS.ProcessEnv = process.env): string | null {
+  const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
+  if (explicit) return explicit.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+  try {
+    const out = execFileSync("gsd-browser", ["--version"], {
+      encoding: "utf-8",
+      env,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    });
+    return out.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function handleUpdate(ctx: ExtensionCommandContext, args = ""): Promise<void> {
   const { execSync } = await import("node:child_process");
 
-  const NPM_PACKAGE = "@opengsd/gsd-pi";
-  const current = process.env.GSD_VERSION || "0.0.0";
+  const target = args.trim();
+  const browserUpdate = target === "browser" || target === "gsd-browser";
+  if (target && !browserUpdate) {
+    ctx.ui.notify("Usage: /gsd update [browser]", "warning");
+    return;
+  }
+
+  const NPM_PACKAGE = browserUpdate ? GSD_BROWSER_PACKAGE : GSD_PI_PACKAGE;
+  const registryUrl = browserUpdate ? BROWSER_UPDATE_REGISTRY_URL : UPDATE_REGISTRY_URL;
+  const bundledVersion = browserUpdate
+    ? resolveInstalledPackageVersionForCommand(GSD_BROWSER_PACKAGE)
+    : null;
+  const current = browserUpdate
+    ? pickHigherVersionForCommand(bundledVersion, resolveGsdBrowserPathVersionForCommand())
+    : process.env.GSD_VERSION || "0.0.0";
+  const label = browserUpdate ? "gsd-browser version" : "version";
 
-  ctx.ui.notify(`Current version: v${current}\nChecking npm registry...`, "info");
+  ctx.ui.notify(`Current ${label}: ${formatCommandVersion(current)}\nChecking npm registry...`, "info");
 
-  const latest = await fetchLatestVersionForCommand();
+  const latest = await fetchLatestVersionForCommand(registryUrl);
   if (!latest) {
     ctx.ui.notify("Failed to reach npm registry. Check your network connection.", "error");
     return;
   }
 
-  if (compareSemverLocal(latest, current) <= 0) {
-    ctx.ui.notify(`Already up to date (v${current}).`, "info");
+  if (current && compareSemverLocal(latest, current) <= 0) {
+    ctx.ui.notify(`Already up to date (${formatCommandVersion(current)}).`, "info");
     return;
   }
 
-  ctx.ui.notify(`Updating: v${current} → v${latest}...`, "info");
+  ctx.ui.notify(`Updating: ${formatCommandVersion(current)} → v${latest}...`, "info");
 
   const installCmd = resolveInstallCommand(`${NPM_PACKAGE}@latest`);
   try {
     execSync(installCmd, {
       stdio: ["ignore", "pipe", "ignore"],
     });
+    const newPathVersion = browserUpdate ? resolveGsdBrowserPathVersionForCommand() : null;
+    const pathReady = !browserUpdate || (!!newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0);
     ctx.ui.notify(
-      `Updated to v${latest}. Restart your GSD session to use the new version.`,
+      browserUpdate
+        ? `Updated gsd-browser to v${latest}. Restart your GSD session to use the new browser automation version.` +
+          (pathReady ? "" : "\nNote: Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+        : `Updated to v${latest}. Restart your GSD session to use the new version.`,
       "info",
     );
   } catch {

package/src/resources/extensions/gsd/commands-mcp-status.ts

@@ -72,7 +72,8 @@ export function formatMcpInitResult(
     `Project: ${targetPath}`,
     `Config:   ${configPath}`,
     "",
-    "MCP-capable clients can now load the GSD workflow MCP server from this folder.",
+    "MCP-capable clients can now load the GSD workflow and gsd-browser MCP servers from this folder.",
+    "Pi Providers use the managed gsd-browser engine directly; this project config is for External MCP Clients.",
     "Restart or reconnect any client that already has this project open.",
   ].join("\n");
 }

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -305,10 +305,18 @@ This config sets a parent workspace with two child repositories. The implicit `p
   - `max_cycles`: number — max times this hook fires per trigger (default: 1, max: 10).
   - `model`: string — optional model override.
   - `artifact`: string — expected output file name (relative to task/slice dir). Hook is skipped if file already exists (idempotent).
+  - `criticality`: `"advisory"` or `"blocking"` — advisory preserves current best-effort behavior; blocking requires clean hook completion plus a valid outcome verdict before auto-mode advances. Default: `"advisory"`.
   - `retry_on`: string — if this file is produced instead of the artifact, re-run the trigger unit then re-run hooks.
+  - `on_block`: object — optional routing for blocking findings:
+    - `action`: `"retry-unit"`, `"retry-task"`, `"queue-task"`, `"queue-slice"`, or `"pause"`.
+    - `artifact`: string — optional compatibility artifact for retry routing.
   - `agent`: string — agent definition file to use for hook execution.
   - `enabled`: boolean — toggle without removing (default: `true`).
 
+  Blocking hook artifacts must begin with YAML frontmatter containing either `verdict` or `outcome.verdict`.
+  Supported verdicts are `pass`, `advisory`, `needs-rework`, `needs-remediation`, and `needs-attention`.
+  `pass` and `advisory` continue; `needs-rework` retries the trigger unit when routed with `retry-unit`/`retry-task`; `needs-remediation` and `needs-attention` pause with recovery guidance.
+
 - `pre_dispatch_hooks`: array — hooks that fire before a unit is dispatched. Each entry has:
   - `name`: string — unique hook identifier.
   - `before`: string[] — unit types to intercept.

package/src/resources/extensions/gsd/doctor-runtime-checks.ts

@@ -269,14 +269,14 @@ export async function checkRuntimeHealth(
         } catch {
           count = MAX_UAT_ATTEMPTS + 1;
         }
-        if (count <= MAX_UAT_ATTEMPTS) continue;
+        if (count < MAX_UAT_ATTEMPTS) continue;
 
         issues.push({
           severity: "warning",
           code: "uat_retry_exhausted",
           scope: "slice",
           unitId: `${mid}/${sid}`,
-          message: `run-uat for ${mid}/${sid} exhausted ${count - 1} retry attempt(s) without an ASSESSMENT verdict. Reset the retry counter after fixing the underlying UAT/tool issue, then rerun /gsd auto.`,
+          message: `run-uat for ${mid}/${sid} exhausted ${count} attempt(s) without an ASSESSMENT verdict. Reset the retry counter after fixing the underlying UAT/tool issue, then rerun /gsd auto.`,
           file: `.gsd/runtime/${fileName}`,
           fixable: true,
         });