@mediadatafusion/pi-workflow-suite 0.0.10 → 0.0.13

package/extensions/workflow-validation-classifier.ts

@@ -45,11 +45,14 @@ export function validationReportHasRepairableIssue(text?: string): boolean {
     .replace(/\bno automated repair is needed\b/g, " ")
     .replace(/\bno specific missing requirements? (?:is |are )?identified\b/g, " ")
     .replace(/\bmanual[-\s]only\b/g, " ");
-  return /\b(needs? repair|needs? revision|repair pass|repairable (issue|failure|defect)|concrete (issue|failure|defect|regression)|blocking issues?|critical issues?|must fix|required (fixes?|actions?)|fixes required|remaining (fixes?|issues?|gaps?)|should be fixed before advancing|apply (the )?(two |[0-9]+ )?remaining fixes?|needs? to be (replaced|updated|expanded|corrected)|missing requirements?|not fully meet|does not fully meet|not (a )?full final artifact|acceptable as (a )?checkpoint baseline but not (a )?(full )?final artifact|unexpected changes?|regression introduced|build (failed|error)|type error|tests? failed|new lint error|incomplete (file|artifact|implementation|coverage)|persistent artifact|structured artifact|risk register artifact|artifact required|(?:produce|create|add|write) (a )?(structured |persistent )?(risk register )?artifact|missing (file|config|import|export|declaration|function|module|dependency))\b/.test(actionable);
+  return /\b(needs? repair|needs? revision|repair pass|repairable (issue|failure|defect)|concrete (issue|failure|defect|regression)|blocking issues?|critical issues?|must fix|required (fixes?|actions?)|fixes required|fix(?:es)? needed|fix\s*:\s*\S|one fix needed|remaining (fixes?|issues?|gaps?)|should be fixed before advancing|apply (the )?(two |[0-9]+ )?remaining fixes?|needs? to be (replaced|updated|expanded|corrected)|missing requirements?|not fully meet|does not fully meet|not (a )?full final artifact|acceptable as (a )?checkpoint baseline but not (a )?(full )?final artifact|unexpected changes?|regression introduced|build (failed|error)|type error|tests? failed|new lint error|incomplete (file|artifact|implementation|coverage)|persistent artifact|structured artifact|risk register artifact|artifact required|(?:produce|create|add|write) (a )?(structured |persistent )?(risk register )?artifact|missing (file|config|import|export|declaration|function|module|dependency)|add\s+\S+\s+(?:attribute|to\s+(?:the\s+)?form|to\s+(?:the\s+)?element)|change\s+\S+\s+to\s+\S+|update\s+\S+\s+to\s+\S+|single\s+(?:non[- ]destructive|safe|trivial)\s+(?:attribute\s+)?change|the fix is\s)\b/.test(actionable);
 }
 
 export function validationReportIsEvidenceGap(text?: string): boolean {
   const report = text ?? "";
+  // If the report body contains a concrete repairable issue, it is not
+  // purely an evidence gap — route to repair so the fix can be applied.
+  if (validationReportHasRepairableIssue(report)) return false;
   const evidenceGap = structuredValidationYes(report, "Evidence Gap");
   const repairable = structuredValidationYes(report, "Concrete Repairable Issue");
   if (evidenceGap === true && repairable !== true) return true;
@@ -58,17 +61,30 @@ export function validationReportIsEvidenceGap(text?: string): boolean {
     && !validationReportHasRepairableIssue(report);
 }
 
+/**
+ * Patterns that indicate the report describes automatable evidence that was
+ * NOT gathered, rather than genuinely human-only verification. These must
+ * classify as repairable/evidence-acquisition failures, not manual_only.
+ */
+const AUTOMATABLE_EVIDENCE_MISSING_RE = /\b(browser qa not performed|dev server not (run|started|launched)|localstorage not verified|automated runtime evidence missing|runtime checks? not (run|performed|executed)|preview server not (run|started)|app not launched|endpoint not (tested|verified|checked)|api not (tested|verified|checked)|server not (started|tested|verified)|e2e (test|check|suite) not run|integration test not run|smoke test not (run|performed)|not fully verified|not (fully |independently )?(verified|checked|tested|confirmed)|no (browser|headless|automated) (runner|test|check|verification)|(could not|cannot|unable to) (verify|check|test|confirm|run|start|launch|access)|(was |were )?not (attempted|performed|executed|run|gathered|available)|manual (qa|check|inspection|review) (is |may be )?(still )?required|evidence gaps?)\b/i;
+
 /**
  * Check whether a validation report represents only a manual/visual QA caveat
  * with no concrete repairable code issue.
+ *
+ * IMPORTANT: Reports that mention automatable evidence not being gathered
+ * (browser QA, dev server, localStorage, runtime checks) are NOT manual-only.
+ * They represent evidence-acquisition failures that should route to repair.
  */
 export function validationReportIsManualOnlyCaveat(text?: string): boolean {
   const report = text ?? "";
   const manual = structuredValidationYes(report, "Manual Verification Required");
   const repairable = structuredValidationYes(report, "Concrete Repairable Issue");
-  if (manual === true && repairable === false) return true;
+  if (manual === true && repairable === false && !AUTOMATABLE_EVIDENCE_MISSING_RE.test(report)) return true;
   const normalized = report.toLowerCase();
   if (!normalized.trim()) return false;
+  // Automatable evidence patterns must not classify as manual_only
+  if (AUTOMATABLE_EVIDENCE_MISSING_RE.test(normalized)) return false;
   const manualCaveat = /(manual|visual|browser).{0,50}(verification|qa|inspection|confirmation)|visual[-\s]?verification caveat|pass with.{0,40}caveat|manual verification needed/.test(normalized);
   const noConcreteRepairableIssue = /no (actual |concrete )?(code |repairable )?(failure|failures|issue|issues|defect|defects)|no (code |repairable )?failures exist|no concrete (code |repairable )?issues?|only remaining validation item is manual|only incomplete item is manual|cannot be performed through (code )?repair|out of scope for (code )?repair/.test(normalized);
   return manualCaveat && noConcreteRepairableIssue && !validationReportHasRepairableIssue(normalized);
@@ -77,10 +93,36 @@ export function validationReportIsManualOnlyCaveat(text?: string): boolean {
 /**
  * Classify a validation failure as manual-only, repairable, or ambiguous.
  */
-export function classifyValidationFailure(verdict: WorkflowState["validationVerdict"], report: string): ValidationFailureClassification {
-  if (validationReportIsManualOnlyCaveat(report)) return "manual_only";
+export function classifyValidationFailure(
+  verdict: WorkflowState["validationVerdict"],
+  report: string,
+  opts?: { concreteRepairableIssue?: boolean; manualVerificationRequired?: boolean },
+): ValidationFailureClassification {
+  const manualField = structuredValidationYes(report, "Manual Verification Required");
+  const repairableField = structuredValidationYes(report, "Concrete Repairable Issue");
+
+  // Positive repairability signals win over manual caveats.
+  if (opts?.concreteRepairableIssue === true || repairableField === true) return "repairable";
+
+  // Automatable evidence not gathered is repairable/evidence-acquisition work,
+  // even if a legacy report also marks manual verification as required.
+  if (AUTOMATABLE_EVIDENCE_MISSING_RE.test(report)) return "repairable";
+
+  // Manual-only is valid only when no automatable or concrete repair signal exists.
+  if (opts?.manualVerificationRequired === true && opts?.concreteRepairableIssue === false) return "manual_only";
+  if (manualField === true && repairableField === false) return "manual_only";
+
+  // Evidence gaps without a concrete repairable issue are ambiguous, not repair loops.
   if (validationReportIsEvidenceGap(report)) return "ambiguous";
+
+  // FAIL or concrete repairable issues → repairable.
   if (verdict === "FAIL" || validationReportHasRepairableIssue(report)) return "repairable";
+
+  if (verdict === "PARTIAL PASS") {
+    if (validationReportIsManualOnlyCaveat(report)) return "manual_only";
+    return "ambiguous";
+  }
+
   return "ambiguous";
 }
 

package/extensions/workflow-web-tools.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { type ExtensionAPI, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { execSync } from "node:child_process";
 import { Type } from "typebox";
 
 type RuntimeToolInfo = {
@@ -32,9 +33,44 @@ export interface WorkflowWebFetchDetails {
   fetchedAt: string;
 }
 
+export interface WorkflowBrowserAction {
+  action: "click" | "type" | "wait" | "waitForSelector" | "select" | "evaluate" | "screenshot" | "reload" | "readText" | "readAttr";
+  selector?: string;
+  value?: string;
+  timeout?: number;
+  label?: string;
+}
+
+export interface WorkflowBrowserActionResult {
+  label?: string;
+  action: string;
+  ok: boolean;
+  error?: string;
+  text?: string;
+  attrValue?: string | null;
+  result?: unknown;
+  found?: boolean;
+}
+
+export interface WorkflowBrowserCheckDetails {
+  url: string;
+  title: string;
+  consoleMessages: string[];
+  pageErrors: string[];
+  elementCounts: Record<string, number>;
+  localStorageValues: Record<string, string | null>;
+  screenshotPath?: string;
+  loadTimeMs: number;
+  error?: string;
+  actionResults?: WorkflowBrowserActionResult[];
+}
+
 const WORKFLOW_WEB_SEARCH_TOOL = "workflow_web_search";
 const WORKFLOW_WEB_FETCH_TOOL = "workflow_web_fetch";
-const WORKFLOW_WEB_TOOLS = [WORKFLOW_WEB_SEARCH_TOOL, WORKFLOW_WEB_FETCH_TOOL];
+const WORKFLOW_BROWSER_CHECK_TOOL = "workflow_browser_check";
+const WORKFLOW_STOP_SERVER_TOOL = "workflow_stop_server";
+const WORKFLOW_WEB_TOOLS = [WORKFLOW_WEB_SEARCH_TOOL, WORKFLOW_WEB_FETCH_TOOL, WORKFLOW_BROWSER_CHECK_TOOL, WORKFLOW_STOP_SERVER_TOOL];
+const workflowWebErrorMessage = (error: unknown): string => error instanceof Error ? error.message : String(error ?? "");
 const SEARCH_TIMEOUT_MS = 12_000;
 const FETCH_TIMEOUT_MS = 12_000;
 const MAX_SEARCH_RESULTS = 10;
@@ -73,6 +109,24 @@ const WorkflowWebFetchParams = Type.Object({
   maxChars: Type.Optional(Type.Number({ description: "Maximum extracted text characters to return, 1000-18000. Default 12000.", minimum: 1000, maximum: 18000 })),
 });
 
+const WorkflowBrowserCheckParams = Type.Object({
+  url: Type.String({ description: "Full URL to check in a headless browser, e.g. http://localhost:8017." }),
+  selectors: Type.Optional(Type.Array(Type.String(), { description: "CSS selectors to count matching elements." })),
+  localStorageKeys: Type.Optional(Type.Array(Type.String(), { description: "localStorage keys to retrieve values for." })),
+  screenshot: Type.Optional(Type.Boolean({ description: "Take a full-page screenshot saved to /tmp/validator_screenshot.png." })),
+  actions: Type.Optional(Type.Array(Type.Object({
+    action: Type.String({ description: "Interaction type: click, type, wait, waitForSelector, select, evaluate, screenshot, reload, readText, readAttr." }),
+    selector: Type.Optional(Type.String({ description: "CSS selector for the target element (required for click, type, waitForSelector, readText, readAttr)." })),
+    value: Type.Optional(Type.String({ description: "Text to type (type action), JS expression (evaluate action), or attribute name (readAttr action)." })),
+    timeout: Type.Optional(Type.Number({ description: "Timeout in ms. Default 5000." })),
+    label: Type.Optional(Type.String({ description: "Human-readable label for this step in results." })),
+  }), { description: "Sequential browser interaction steps to perform after page load." })),
+});
+
+const WorkflowStopServerParams = Type.Object({
+  port: Type.Number({ description: "Port number to kill any process listening on (1-65535).", minimum: 1, maximum: 65535 }),
+});
+
 function normalizeToolName(name: string): string {
   return name.trim().toLowerCase();
 }
@@ -270,6 +324,211 @@ export async function workflowWebFetch(rawUrl: string, maxChars = 12_000): Promi
   }
 }
 
+export async function workflowBrowserCheck(
+  url: string,
+  selectors?: string[],
+  localStorageKeys?: string[],
+  screenshot?: boolean,
+  actions?: WorkflowBrowserAction[],
+): Promise<WorkflowBrowserCheckDetails> {
+  const startTime = Date.now();
+  const cleanUrl = url.trim();
+  if (!cleanUrl) throw new Error("URL is required.");
+  let puppeteer: typeof import("puppeteer");
+  try {
+    puppeteer = (await import("puppeteer")).default as typeof import("puppeteer");
+  } catch {
+    return {
+      url: cleanUrl, title: "", consoleMessages: [], pageErrors: [],
+      elementCounts: {}, localStorageValues: {}, loadTimeMs: Date.now() - startTime,
+      error: "Puppeteer is not available in this environment.",
+    };
+  }
+  const browser = await puppeteer.launch({ headless: "shell", args: ["--no-sandbox"] });
+  try {
+    const page = await browser.newPage();
+    const consoleMessages: string[] = [];
+    const pageErrors: string[] = [];
+    page.on("console", (msg) => consoleMessages.push(`${msg.type()}: ${msg.text()}`));
+    page.on("pageerror", (err) => pageErrors.push(workflowWebErrorMessage(err)));
+    await page.goto(cleanUrl, { waitUntil: "networkidle2", timeout: 15000 });
+    const title = await page.title();
+    const elementCounts: Record<string, number> = {};
+    if (selectors && selectors.length > 0) {
+      for (const sel of selectors) {
+        try {
+          elementCounts[sel] = await page.$$eval(sel, (els) => els.length);
+        } catch {
+          elementCounts[sel] = 0;
+        }
+      }
+    }
+    const localStorageValues: Record<string, string | null> = {};
+    if (localStorageKeys && localStorageKeys.length > 0) {
+      for (const key of localStorageKeys) {
+        try {
+          localStorageValues[key] = await page.evaluate((k) => localStorage.getItem(k), key);
+        } catch {
+          localStorageValues[key] = null;
+        }
+      }
+    }
+    let screenshotPath: string | undefined;
+    if (screenshot) {
+      screenshotPath = "/tmp/validator_screenshot.png";
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+    }
+    const actionResults: WorkflowBrowserActionResult[] = [];
+    if (actions && actions.length > 0) {
+      for (const act of actions) {
+        const result: WorkflowBrowserActionResult = { label: act.label, action: act.action, ok: false };
+        const timeout = act.timeout ?? 5000;
+        try {
+          switch (act.action) {
+            case "click":
+              if (!act.selector) throw new Error("selector required for click");
+              await page.waitForSelector(act.selector, { timeout });
+              await page.click(act.selector);
+              result.ok = true;
+              break;
+            case "type":
+              if (!act.selector) throw new Error("selector required for type");
+              if (act.value === undefined) throw new Error("value required for type");
+              await page.waitForSelector(act.selector, { timeout });
+              await page.type(act.selector, act.value, { delay: 20 });
+              result.ok = true;
+              break;
+            case "wait":
+              await new Promise((r) => setTimeout(r, timeout));
+              result.ok = true;
+              break;
+            case "waitForSelector":
+              if (!act.selector) throw new Error("selector required for waitForSelector");
+              await page.waitForSelector(act.selector, { timeout });
+              result.found = true;
+              result.ok = true;
+              break;
+            case "select":
+              if (!act.selector) throw new Error("selector required for select");
+              if (act.value === undefined) throw new Error("value required for select");
+              await page.waitForSelector(act.selector, { timeout });
+              await page.select(act.selector, act.value);
+              result.ok = true;
+              break;
+            case "evaluate":
+              if (act.value === undefined) throw new Error("value (JS expression) required for evaluate");
+              result.result = await page.evaluate(act.value);
+              result.ok = true;
+              break;
+            case "screenshot": {
+              const stepPath = `/tmp/validator_step_${actionResults.length}.png`;
+              await page.screenshot({ path: stepPath, fullPage: true });
+              result.result = stepPath;
+              result.ok = true;
+              break;
+            }
+            case "reload":
+              await page.reload({ waitUntil: "networkidle2", timeout });
+              result.ok = true;
+              break;
+            case "readText":
+              if (!act.selector) throw new Error("selector required for readText");
+              await page.waitForSelector(act.selector, { timeout });
+              result.text = await page.$eval(act.selector, (el) => (el as HTMLElement).innerText?.trim() ?? el.textContent?.trim() ?? "");
+              result.ok = true;
+              break;
+            case "readAttr":
+              if (!act.selector) throw new Error("selector required for readAttr");
+              if (!act.value) throw new Error("value (attribute name) required for readAttr");
+              await page.waitForSelector(act.selector, { timeout });
+              result.attrValue = await page.$eval(act.selector, (el, attr) => el.getAttribute(attr as string), act.value);
+              result.ok = true;
+              break;
+            default:
+              result.error = `Unknown action type: ${act.action}`;
+          }
+        } catch (err) {
+          result.error = err instanceof Error ? err.message : String(err);
+        }
+        actionResults.push(result);
+      }
+    }
+    return {
+      url: cleanUrl, title, consoleMessages, pageErrors,
+      elementCounts, localStorageValues, screenshotPath,
+      loadTimeMs: Date.now() - startTime,
+      ...(actionResults.length > 0 ? { actionResults } : {}),
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+
+// ── Cross-platform port-kill utility ──────────────────────────
+
+function killOnPortUnix(port: number): boolean {
+  // Primary: lsof — works on macOS (built-in) and most Linux systems
+  try {
+    const out = execSync("lsof -ti :" + port + " 2>/dev/null", { timeout: 3000, encoding: "utf8" });
+    const pids = out.trim().split("\n").map(Number).filter(pid => pid > 0);
+    if (pids.length > 0) {
+      for (const pid of pids) {
+        try { process.kill(pid, "SIGTERM"); } catch { /* already dead */ }
+      }
+      return true;
+    }
+  } catch { /* lsof unavailable or port free */ }
+  // Fallback 1: fuser — Linux psmisc
+  try {
+    execSync("fuser -k " + port + "/tcp 2>/dev/null || true", { timeout: 3000 });
+    return true;
+  } catch { /* fuser unavailable */ }
+  // Fallback 2: ss — Linux iproute2 (always available, even in minimal containers)
+  try {
+    const out = execSync("ss -tlnp 'sport = :" + port + "' 2>/dev/null", { timeout: 3000, encoding: "utf8" });
+    const match = out.match(/pid=(\d+)/);
+    if (match) {
+      try { process.kill(parseInt(match[1], 10), "SIGTERM"); } catch { /* already dead */ }
+      return true;
+    }
+  } catch { /* ss unavailable */ }
+  return false;
+}
+
+function killOnPortWindows(port: number): boolean {
+  try {
+    const out = execSync("netstat -ano | findstr :" + port, { timeout: 3000, encoding: "utf8", shell: "cmd.exe" });
+    const lines = out.split("\n");
+    let killed = false;
+    for (const line of lines) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length >= 5 && parts[1] && parts[1].endsWith(":" + port)) {
+        const pid = parseInt(parts[parts.length - 1], 10);
+        if (pid > 0) {
+          try {
+            execSync("taskkill /PID " + pid + " /F", { timeout: 3000, shell: "cmd.exe" });
+            killed = true;
+          } catch { /* taskkill failed */ }
+        }
+      }
+    }
+    return killed;
+  } catch { return false; }
+}
+
+function killProcessOnPort(port: number): boolean {
+  try {
+    if (process.platform === "win32") {
+      return killOnPortWindows(port);
+    } else {
+      return killOnPortUnix(port);
+    }
+  } catch {
+    return false;
+  }
+}
+
 export function refreshRuntimeWebTools(pi: ExtensionAPI): string[] {
   const tools = pi.getAllTools() as RuntimeToolInfo[];
   discoveredRuntimeWebTools = Array.from(new Set(
@@ -351,6 +610,107 @@ export function registerWorkflowWebTools(pi: ExtensionAPI): void {
       }
     },
   } as ToolDefinition<typeof WorkflowWebFetchParams, WorkflowWebFetchDetails>);
+
+  pi.registerTool({
+    name: WORKFLOW_BROWSER_CHECK_TOOL,
+    label: "Workflow Browser Check",
+    description: "Launch a headless browser to verify a web app. Supports passive checks (console errors, DOM elements, localStorage) and interactive actions (click, type, wait, read text, read attributes, screenshots, page reload). Use for browser-level validation evidence when dev server or static HTTP server is running.",
+    promptSnippet: "Launch headless browser for passive checks and interactive actions at a URL",
+    promptGuidelines: [
+      "Use workflow_browser_check to gather browser-level validation evidence. For passive checks, pass selectors and localStorageKeys. For interactive testing, pass an actions array with click, type, waitForSelector, readText, readAttr, screenshot, reload, evaluate, wait, or select steps.",
+      "Start a dev server or python3 http.server first, then pass the URL to workflow_browser_check.",
+      "After browser checks complete, stop the server with workflow_stop_server({ port: PORT }) — do not rely on platform-specific shell commands.",
+      "Actions execute sequentially after page load. Each action returns ok/error and type-specific results (text, attrValue, result, found). Failed actions do not abort remaining actions.",
+      "Use readText to extract visible text from elements. Use readAttr to read attribute values like 'value', 'class', 'disabled'. Use evaluate for arbitrary JS like document.title or localStorage.getItem('key').",
+      "Set screenshot: true for initial page, or use a screenshot action step after interactions.",
+    ],
+    parameters: WorkflowBrowserCheckParams,
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal): Promise<AgentToolResult<WorkflowBrowserCheckDetails>> {
+      if (signal?.aborted) throw new Error("Browser check aborted.");
+      try {
+        const p = params as { url?: unknown; selectors?: unknown; localStorageKeys?: unknown; screenshot?: unknown; actions?: unknown };
+        const rawActions = Array.isArray(p.actions) ? p.actions : undefined;
+        const parsedActions: WorkflowBrowserAction[] | undefined = rawActions?.map((a: unknown) => {
+          const item = a as Record<string, unknown>;
+          return {
+            action: String(item.action ?? ""),
+            selector: typeof item.selector === "string" ? item.selector : undefined,
+            value: typeof item.value === "string" ? item.value : undefined,
+            timeout: typeof item.timeout === "number" ? item.timeout : undefined,
+            label: typeof item.label === "string" ? item.label : undefined,
+          } as WorkflowBrowserAction;
+        });
+        const details = await workflowBrowserCheck(
+          String(p.url ?? ""),
+          Array.isArray(p.selectors) ? p.selectors.map(String) : undefined,
+          Array.isArray(p.localStorageKeys) ? p.localStorageKeys.map(String) : undefined,
+          Boolean(p.screenshot),
+          parsedActions,
+        );
+        const lines: string[] = [
+          `URL: ${details.url}`,
+          `Title: ${details.title || "(none)"}`,
+          `Load time: ${details.loadTimeMs}ms`,
+        ];
+        if (details.error) {
+          lines.push(`Error: ${details.error}`);
+        } else {
+          lines.push(`Console messages: ${details.consoleMessages.length}`);
+          for (const msg of details.consoleMessages.slice(0, 20)) lines.push(`  ${msg}`);
+          if (details.consoleMessages.length > 20) lines.push(`  ... and ${details.consoleMessages.length - 20} more`);
+          lines.push(`Page errors: ${details.pageErrors.length}`);
+          for (const err of details.pageErrors) lines.push(`  ${err}`);
+          if (details.elementCounts && Object.keys(details.elementCounts).length > 0) {
+            lines.push("Element counts:");
+            for (const [sel, count] of Object.entries(details.elementCounts)) lines.push(`  ${sel}: ${count}`);
+          }
+          if (details.localStorageValues && Object.keys(details.localStorageValues).length > 0) {
+            lines.push("localStorage:");
+            for (const [key, val] of Object.entries(details.localStorageValues)) lines.push(`  ${key}: ${val ?? "(null)"}`);
+          }
+          if (details.screenshotPath) lines.push(`Screenshot: ${details.screenshotPath}`);
+          if (details.actionResults && details.actionResults.length > 0) {
+            lines.push(`Actions: ${details.actionResults.length} step(s)`);
+            for (const r of details.actionResults) {
+              const label = r.label ? `[${r.label}] ` : "";
+              const parts = [`  ${label}${r.action}: ${r.ok ? "OK" : "FAILED"}`];
+              if (r.error) parts.push(`| error: ${r.error}`);
+              if (r.text !== undefined) parts.push(`| text: "${r.text.slice(0, 200)}"`);
+              if (r.attrValue !== undefined) parts.push(`| attr: ${r.attrValue}`);
+              if (r.found !== undefined) parts.push(`| found: ${r.found}`);
+              if (r.result !== undefined) parts.push(`| result: ${typeof r.result === "string" ? r.result : JSON.stringify(r.result)}`);
+              lines.push(parts.join(" "));
+            }
+          }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }], details };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: `Workflow browser check failed: ${message}` }], details: { url: String((params as { url?: unknown }).url ?? ""), title: "", consoleMessages: [], pageErrors: [], elementCounts: {}, localStorageValues: {}, loadTimeMs: 0, error: message } };
+      }
+    },
+  } as ToolDefinition<typeof WorkflowBrowserCheckParams, WorkflowBrowserCheckDetails>);
+
+  pi.registerTool({
+    name: WORKFLOW_STOP_SERVER_TOOL,
+    label: "Workflow Stop Server",
+    description: "Kill any process listening on the given port. Cross-platform (macOS, Windows, Linux). Use to stop dev servers, static HTTP servers, or any background process started for validation.",
+    promptSnippet: "Stop a server process on a port",
+    promptGuidelines: [
+      "Use workflow_stop_server to reliably stop dev servers or static servers after validation instead of shell commands.",
+      "Pass the port number the server is listening on (e.g., 3017 for a server started on port 3017).",
+      "This works cross-platform and does not require fuser, lsof, or other platform-specific tools installed.",
+    ],
+    parameters: WorkflowStopServerParams,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, signal): Promise<AgentToolResult<{ port: number; killed: boolean }>> {
+      if (signal?.aborted) throw new Error("Server stop aborted.");
+      const port = (params as { port: number }).port;
+      const killed = killProcessOnPort(port);
+      return { content: [{ type: "text", text: killed ? "Stopped process on port " + port + "." : "No process found on port " + port + " (already free or unable to kill)." }], details: { port, killed } };
+    },
+  } as ToolDefinition<typeof WorkflowStopServerParams, { port: number; killed: boolean }>);
 }
 
 export default function workflowWebToolsNoopExtension(): void {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediadatafusion/pi-workflow-suite",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "description": "Structured workflow orchestration suite for Pi with Standard, Plan, Mission, compaction, diagrams, web access, repo lock, and safety gates.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,6 +36,7 @@
   "type": "module",
   "files": [
     "extensions/",
+    "!extensions/*.bak",
     "skills/",
     "agents/",
     "config/",
@@ -49,6 +50,8 @@
     "scripts/bootstrap-project.sh",
     "scripts/check-clean-release-tree.sh",
     "scripts/check-package-size.mjs",
+    "scripts/check-package-media.mjs",
+    "scripts/package-media-config.mjs",
     "scripts/prepare-package-readme.mjs",
     "scripts/build-package-export.mjs",
     "README.md",
@@ -77,8 +80,8 @@
     "themes": [
       "./themes"
     ],
-    "image": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.6/docs/assets/pi-workflow-suite-header.png",
-    "video": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.6/docs/assets/pi-workflow-suite-demo.mp4"
+    "image": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/pi-workflow-suite-header.png",
+    "video": "https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/pi-workflow-suite-demo.mp4"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -103,9 +106,10 @@
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "check:ts": "tsc --noEmit --noCheck",
+    "check:ts": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run check:ts && ./scripts/check-clean-release-tree.sh && npm run check:package-size && git diff --check",
+    "validate": "npm run check:ts && npm run check:package-media && npm run check:package-size && git diff --check",
+    "check:package-media": "node scripts/check-package-media.mjs",
     "check:package-size": "node scripts/check-package-size.mjs",
     "prepack": "node scripts/prepare-package-readme.mjs apply",
     "postpack": "node scripts/prepare-package-readme.mjs restore --pack",

package/scripts/audit-live.sh

@@ -28,7 +28,7 @@ while IFS= read -r rel; do
     printf 'MISSING: %s\n' "$rel"
     missing=1
   fi
-done < <(cd "$REPO_DIR" && find agents skills extensions config -type f ! -name '.DS_Store' ! -name '*.backup.*' ! -name '*.broken.*' | sort)
+done < <(cd "$REPO_DIR" && find agents skills extensions config -type f ! -name '.DS_Store' ! -name '*.bak' ! -name '*.backup.*' ! -name '*.broken.*' | sort)
 if [[ "$missing" -eq 0 ]]; then
   printf 'OK: no missing canonical managed files\n'
 fi

package/scripts/build-package-export.mjs

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { packageMediaUrl, packageMediaUrls } from './package-media-config.mjs';
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(scriptDir, '..');
@@ -39,20 +40,14 @@ function parseArgs(argv) {
   return args;
 }
 
-const mediaVersion = '0.0.6';
-
-function mediaCdn(assetPath) {
-  return `https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@${mediaVersion}/${assetPath}`;
-}
-
 function buildPackageReadme(sourceReadme, version) {
   const headerBlock = `# Pi Workflow Suite\n\n${
-    `![Pi Workflow Suite — structured workflow orchestration for Pi](${mediaCdn('docs/assets/pi-workflow-suite-header.png')})`
+    `![Pi Workflow Suite — structured workflow orchestration for Pi](${packageMediaUrls.header})`
   }\n\n${[
-    `[![Install](${mediaCdn('docs/assets/readme-link-install.svg')})](#installation)`,
-    `[![Quick Start](${mediaCdn('docs/assets/readme-link-quick-start.svg')})](#quick-start)`,
-    `[![Commands](${mediaCdn('docs/assets/readme-link-commands.svg')})](#core-commands)`,
-    `[![Settings](${mediaCdn('docs/assets/readme-link-settings.svg')})](#settings-reference)`,
+    `[![Install](${packageMediaUrls.readmeInstall})](#installation)`,
+    `[![Quick Start](${packageMediaUrls.readmeQuickStart})](#quick-start)`,
+    `[![Commands](${packageMediaUrls.readmeCommands})](#core-commands)`,
+    `[![Settings](${packageMediaUrls.readmeSettings})](#settings-reference)`,
   ].join(' ')}\n\n**Workflow Suite Version:** `;
 
   let readme = sourceReadme.replace(
@@ -60,7 +55,7 @@ function buildPackageReadme(sourceReadme, version) {
     headerBlock,
   );
 
-  const packageMediaBlock = `## Quick Demo\n\nSee Pi Workflow Suite in action: structured workflow modes, settings, runtime status, and guided execution inside Pi.\n\n[![Watch the Pi Workflow Suite quick demo](${mediaCdn('docs/assets/pi-workflow-suite-demo.gif')})](${mediaCdn('docs/assets/pi-workflow-suite-demo.mp4')})\n\n## Screenshots\n\n${[
+  const packageMediaBlock = `## Quick Demo\n\nSee Pi Workflow Suite in action: structured workflow modes, settings, runtime status, and guided execution inside Pi.\n\n[![Watch the Pi Workflow Suite quick demo](${packageMediaUrls.demoGif})](${packageMediaUrls.demoMp4})\n\n## Screenshots\n\n${[
     ['Pi Workflow Suite Mission Home with workflow graphs', 'docs/assets/screenshots/00-mission-home.png'],
     ['Pi Workflow Suite startup logo', 'docs/assets/screenshots/01-startup-Logo.png'],
     ['Workflow Suite theme settings', 'docs/assets/screenshots/02-theme-settings.png'],
@@ -68,7 +63,7 @@ function buildPackageReadme(sourceReadme, version) {
     ['Workflow Suite shared sub-agent settings', 'docs/assets/screenshots/04-SharedSubAgentsSettings.png'],
     ['Mission Mode milestone progress', 'docs/assets/screenshots/05-mission-mode.png'],
     ['Workflow Suite Mermaid diagram output', 'docs/assets/screenshots/06-diagram-mermaid.png'],
-  ].map(([alt, path]) => `![${alt}](${mediaCdn(path)})`).join('\n\n')}\n\n`;
+  ].map(([alt, path]) => `![${alt}](${packageMediaUrl(path)})`).join('\n\n')}\n\n`;
 
   readme = readme.replace(/## Quick Demo[\s\S]*?## Contents\n/, `${packageMediaBlock}## Contents\n`);
   return readme;

package/scripts/check-clean-release-tree.sh

@@ -11,6 +11,7 @@ report() {
 }
 
 if [[ -e AGENTS.md && -n "$(git ls-files AGENTS.md)" ]]; then report 'AGENTS.md must not be present on clean release main'; fi
+if [[ -e CLAUDE.md && -n "$(git ls-files CLAUDE.md)" ]]; then report 'CLAUDE.md must not be present on clean release main'; fi
 if [[ -e .github && -n "$(git ls-files .github)" ]]; then report '.github/ must not be tracked on clean release main'; fi
 if [[ -e .factory && -n "$(git ls-files .factory)" ]]; then report '.factory/ must not be tracked on clean release main'; fi
 if [[ -e .kilo && -n "$(git ls-files .kilo)" ]]; then report '.kilo/ must not be tracked on clean release main'; fi
@@ -18,7 +19,7 @@ if [[ -e .cursor && -n "$(git ls-files .cursor)" ]]; then report '.cursor/ must
 
 while IFS= read -r path; do
   case "$path" in
-    agents/*|config/*|extensions/*|skills/*|docs/assets/*|themes/*|scripts/install-to-live.sh|scripts/verify-live.sh|scripts/audit-live.sh|scripts/quarantine-live-junk.sh|scripts/backup-live.sh|scripts/audit-settings.sh|scripts/bootstrap-project.sh|scripts/check-clean-release-tree.sh|scripts/check-package-size.mjs|scripts/prepare-package-readme.mjs|scripts/build-package-export.mjs|README.md|CHANGELOG.md|CONTRIBUTING.md|LICENSE.md|NOTICE|SECURITY.md|SUPPORT.md|TRADEMARKS.md|VERSION|package.json|package-lock.json|tsconfig.json|.gitignore)
+    agents/*|config/*|extensions/*|skills/*|docs/assets/*|themes/*|scripts/install-to-live.sh|scripts/verify-live.sh|scripts/audit-live.sh|scripts/quarantine-live-junk.sh|scripts/backup-live.sh|scripts/audit-settings.sh|scripts/bootstrap-project.sh|scripts/check-clean-release-tree.sh|scripts/check-package-size.mjs|scripts/check-package-media.mjs|scripts/package-media-config.mjs|scripts/prepare-package-readme.mjs|scripts/build-package-export.mjs|README.md|CHANGELOG.md|CONTRIBUTING.md|LICENSE.md|NOTICE|SECURITY.md|SUPPORT.md|TRADEMARKS.md|VERSION|package.json|package-lock.json|tsconfig.json|.gitignore)
       ;;
     docs/*)
       report "non-asset docs file is not allowed: $path"
@@ -26,7 +27,7 @@ while IFS= read -r path; do
     scripts/test-*|scripts/sync-from-live.sh)
       report "internal script is not allowed: $path"
       ;;
-    .github/*|AGENTS.md|.factory/*|.kilo/*|.cursor/*)
+    .github/*|AGENTS.md|CLAUDE.md|.factory/*|.kilo/*|.cursor/*)
       report "internal path is not allowed: $path"
       ;;
     *auth.json|*settings.json|*workflow-settings.json|*active.json|workflows/*|*sessions/*|*missions/*|*plans/*|*logs/*|*.env|*.env.*|*.DS_Store)