@muggleai/works 4.9.2 → 4.10.1

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-6N7OIBAS.js';
-import './chunk-4KQZLF56.js';
+import { runCli } from './chunk-Q7WNEMN4.js';
+import './chunk-ZKRHFTIC.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-6N7OIBAS.js';
-export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-4KQZLF56.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-Q7WNEMN4.js';
+export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-ZKRHFTIC.js';

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.9.2",
+  "version": "4.10.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "4.9.2",
+  "version": "4.10.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/README.md

@@ -15,7 +15,7 @@ For npm installs:
 npm install -g @muggleai/works
 ```
 
-This updates the CLI, configures Cursor MCP (`~/.cursor/mcp.json`), and syncs `muggle-*` skills into `~/.cursor/skills/`. Claude slash commands remain plugin-managed, so use `/plugin update muggleai@muggle-works` to refresh them.
+This updates the CLI, configures Cursor MCP (`~/.cursor/mcp.json`), and syncs `muggle-*` skills (plus their short `m*` aliases) into `~/.cursor/skills/`. Claude slash commands remain plugin-managed, so use `/plugin update muggleai@muggle-works` to refresh them.
 
 ## Skills
 
@@ -23,7 +23,7 @@ Type `muggle` to discover the full command family.
 
 | Skill | What it does |
 |:---|:---|
-| `/muggle:muggle` | Router and menu for all Muggle commands. |
+| `/muggle:muggle` | Router and menu for all Muggle Test commands. |
 | `/muggle:muggle-do` | Autonomous dev pipeline: requirements, code, unit tests, E2E acceptance tests, PR. |
 | `/muggle:muggle-test` | Change-driven E2E acceptance router: detects code changes, maps to use cases, runs test generation locally or remotely, publishes to dashboard, opens in browser, posts E2E acceptance results to PR. |
 | `/muggle:muggle-test-feature-local` | Test a feature on localhost with AI-driven browser automation. Offers publish to cloud after each run. |
@@ -33,6 +33,8 @@ Type `muggle` to discover the full command family.
 | `/muggle:muggle-repair` | Diagnose and fix broken installation automatically. |
 | `/muggle:muggle-upgrade` | Update Electron browser test runner and MCP server to latest version. |
 
+Each skill above also ships a short alias to save typing — `m` (router), `mtest`, `mdo`, `mpr`, `mprefs`, `mstatus`, `mrepair`, `mupgrade`, `mfeedback`, `mimport`, `mtestlocal`, `mtestprep`, `mregen`, `mrelease`. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`).
+
 ## MCP Tools
 
 The plugin ships an MCP server with 70+ tools for project management, test case generation, browser automation, and reporting. The server starts automatically when the plugin is enabled.

package/dist/plugin/agents/acceptance-tester.md

@@ -1,12 +1,12 @@
 ---
 name: acceptance-tester
-description: "E2E acceptance testing agent — runs real-browser tests against web apps and reports structured results with blocking issues and suggested fixes. Also imports existing test artifacts, manages Muggle preferences, and operates the Muggle AI suite (status checks, repairs). Dispatch this agent when the team needs acceptance test feedback, test coverage for a feature, or Muggle suite operations."
+description: "E2E acceptance testing agent — runs real-browser tests against web apps and reports structured results with blocking issues and suggested fixes. Also imports existing test artifacts, manages Muggle Test preferences, and operates the Muggle AI suite (status checks, repairs). Dispatch this agent when the team needs acceptance test feedback, test coverage for a feature, or Muggle Test suite operations."
 model: sonnet
 ---
 
 # Acceptance Tester
 
-You are the team's acceptance testing specialist. You run real-browser end-to-end tests against web apps using Muggle AI and report structured results that coding agents can act on. You also manage test artifacts, user preferences, and the Muggle installation itself.
+You are the team's acceptance testing specialist. You run real-browser end-to-end tests against web apps using Muggle AI and report structured results that coding agents can act on. You also manage test artifacts, user preferences, and the Muggle Test installation itself.
 
 You operate through skills — never call raw MCP tools directly.
 
@@ -16,9 +16,9 @@ You operate through skills — never call raw MCP tools directly.
 |-------|-------------|
 | `muggle-test` | Run acceptance tests. Auto-routes between local (Electron browser on localhost) and remote (cloud execution on preview/staging URL). Handles change detection, test case selection, execution, and result collection. |
 | `muggle-test-import` | Import existing test artifacts into Muggle Test — Playwright specs, Cypress tests, PRDs, Gherkin feature files, test plan documents. |
-| `muggle-preferences` | View, set, or reset the 12 preference knobs that control Muggle behavior. |
-| `muggle-repair` | Diagnose and fix broken Muggle installation components. |
-| `muggle-status` | Check health of the Muggle installation — Electron app, MCP server, auth, CLI version. |
+| `muggle-preferences` | View, set, or reset the 12 preference knobs that control Muggle Test behavior. |
+| `muggle-repair` | Diagnose and fix broken Muggle Test installation components. |
+| `muggle-status` | Check health of the Muggle Test installation — Electron app, MCP server, auth, CLI version. |
 
 Select the skill based on what the orchestrator asks you to do. If the task doesn't clearly map to one skill, ask for clarification.
 
@@ -36,20 +36,27 @@ The orchestrator provides a dispatch prompt with:
 
 ### When Running Tests
 
-Always return two sections:
+Always return two sections. **This is the agent's text report back to the orchestrator — it is NOT the PR comment.** The PR comment is rendered separately by `muggle build-pr-section` via the `muggle-pr-visual-walkthrough` skill, and it has its own formatting (don't paste this template into a PR comment, don't add a "Verdict" line to a hand-written PR comment, don't add a "Project:" footer or `Tested on:` line — the CLI emits none of those).
 
 **Section 1 — Test Summary**
 
 ```
 ## Test Summary
-- **Tests:** {total} total — {passed} passed, {failed} failed
-- **Verdict:** PASS | FAIL
-- **Dashboard:** {link to Muggle dashboard, if results were published}
+- **Tests:** {total} total — {passed} passed, {failed} failed, {inconclusive} inconclusive
+- **Verdict:** PASS | FAIL | INCONCLUSIVE
+- **Dashboard:** {link to Muggle Test dashboard, if results were published}
 ```
 
+Verdict policy (matches the CLI's `computeVerdict`):
+- Any failed → **FAIL**.
+- No failures but any inconclusive → **INCONCLUSIVE**.
+- All passed → **PASS**.
+
+A test is **inconclusive** when the run could not yield a pass/fail signal for reasons outside the product itself: no replayable script, environment precondition unmet, infra error blocked execution, agent stalled before reaching the assertion (auth/cookie banner, missing secret). The product is not implicated. If you are tempted to call a run "passed except for one that didn't really run," that one is inconclusive.
+
 **Section 2 — Per-Test Highlights**
 
-Order failures first, then passes.
+Order failures first, then inconclusives, then passes.
 
 For each **failed** test:
 
@@ -59,6 +66,13 @@ For each **failed** test:
 - **Suggested fix:** {What the coding agent should investigate. Reference UI flows and components, not specific file paths — the acceptance tester operates at the UI layer.}
 ```
 
+For each **inconclusive** test:
+
+```
+### {Test Name} — INCONCLUSIVE
+- **Reason:** {Why the run could not yield a pass/fail signal — one short sentence.}
+```
+
 For each **passed** test, list the name only:
 
 ```

package/dist/plugin/commands/m.md

@@ -0,0 +1,7 @@
+---
+description: Muggle AI command router and menu (alias for /muggle)
+argument-hint: [optional sub-request]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mdo.md

@@ -0,0 +1,7 @@
+---
+description: Run a browser automation task on a website in natural language (alias for /muggle-do-task)
+argument-hint: [task description and target site]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-do-task` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mfeedback.md

@@ -0,0 +1,7 @@
+---
+description: Submit, list, or delete Muggle Test feedback (alias for /muggle-feedback)
+argument-hint: [optional feedback text or action]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-feedback` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mimport.md

@@ -0,0 +1,7 @@
+---
+description: Import existing tests/PRDs/specs INTO Muggle Test (alias for /muggle-test-import)
+argument-hint: [path or source of tests to import]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-test-import` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mpr.md

@@ -0,0 +1,7 @@
+---
+description: Post the Muggle E2E visual walkthrough to a PR (alias for /muggle-pr-visual-walkthrough)
+argument-hint: [optional PR number]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-pr-visual-walkthrough` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mprefs.md

@@ -0,0 +1,7 @@
+---
+description: View, set, or reset Muggle AI preferences (alias for /muggle-preferences)
+argument-hint: [optional preference key or action]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-preferences` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mregen.md

@@ -0,0 +1,7 @@
+---
+description: Bulk-regenerate test scripts for test cases missing one (alias for /muggle-test-regenerate-missing)
+argument-hint: [optional project hint]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-test-regenerate-missing` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mrelease.md

@@ -0,0 +1,7 @@
+---
+description: Cut a @muggleai/works npm release (alias for /muggle-works-npm-release)
+argument-hint: [major|minor|patch]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-works-npm-release` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mrepair.md

@@ -0,0 +1,7 @@
+---
+description: Diagnose and fix a broken Muggle AI installation (alias for /muggle-repair)
+argument-hint: [no args]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-repair` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mstatus.md

@@ -0,0 +1,7 @@
+---
+description: Check Muggle AI installation health (alias for /muggle-status)
+argument-hint: [no args]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-status` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mtest.md

@@ -0,0 +1,7 @@
+---
+description: Run change-driven E2E acceptance tests on your changes (alias for /muggle-test)
+argument-hint: [optional context, e.g. "on staging"]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-test` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mtestlocal.md

@@ -0,0 +1,7 @@
+---
+description: Run a real-browser E2E acceptance test against localhost (alias for /muggle-test-feature-local)
+argument-hint: [feature or flow to test]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-test-feature-local` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mtestprep.md

@@ -0,0 +1,7 @@
+---
+description: Prepare local dev servers and sibling services for E2E testing (alias for /muggle-test-prepare)
+argument-hint: [no args]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-test-prepare` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/commands/mupgrade.md

@@ -0,0 +1,7 @@
+---
+description: Update Muggle AI to the latest version (alias for /muggle-upgrade)
+argument-hint: [no args]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-upgrade` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -77,10 +77,14 @@ if [ -f "$prefs_global_file" ]; then
     try {
       const g = JSON.parse(fs.readFileSync('${prefs_global_file}', 'utf-8')).preferences || {};
       const defaults = {
-        autoLogin:'ask', autoSelectProject:'ask', showElectronBrowser:'ask',
-        openTestResultsAfterRun:'ask', defaultExecutionMode:'ask', autoPublishLocalResults:'ask',
+        autoLogin:'ask', autoSelectProject:'ask', autoSelectLocalHost:'ask',
+        showElectronBrowser:'ask', openTestResultsAfterRun:'ask',
+        defaultExecutionMode:'ask', autoPublishLocalResults:'ask',
         suggestRelatedUseCases:'ask', suggestRelatedTestCases:'ask', autoDetectChanges:'ask',
-        postPRVisualWalkthrough:'ask', checkForUpdates:'ask', verboseOutput:'ask'
+        postPRVisualWalkthrough:'ask', autoCreatePR:'ask',
+        checkForUpdates:'ask', verboseOutput:'ask',
+        autoUseWorktree:'ask', autoRebase:'ask', autoCleanup:'ask',
+        autoE2ETest:'always'
       };
       const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
       const pPath = require('path').join(cwd, '.muggle-ai', 'preferences.json');
@@ -90,17 +94,63 @@ if [ -f "$prefs_global_file" ]; then
       const hasProject = Object.keys(p).length > 0;
       const note = hasProject ? ', project overrides active' : '';
       const line = Object.entries(merged).map(([k,v]) => k+'='+v).join(' ');
-      console.log('Muggle Preferences (~/.muggle-ai/preferences.json' + note + '):\\\\n' + line);
+      console.log('Muggle Test Preferences (~/.muggle-ai/preferences.json' + note + '):\\\\n' + line);
     } catch { console.log(''); }
   " 2>/dev/null || true)
   if [ -n "$prefs_line" ]; then
     prefs_file_note="\\n\\n${prefs_line}"
   fi
 else
-  prefs_file_note="\\n\\nMuggle Preferences: not configured. Run \\\`muggle setup\\\` or tell the agent to set preferences."
+  prefs_file_note="\\n\\nMuggle Test Preferences: not configured. Run \\\`muggle setup\\\` or tell the agent to set preferences."
 fi
 
-context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}${prefs_file_note}"
+# --- Last-project cache injection ---
+# Per-repo "last used Muggle Test project" cache. Lives at <cwd>/.muggle-ai/last-project.json
+# and is honored by skills when autoSelectProject = always.
+last_project_line=""
+last_project_note=""
+last_project_line=$(node -e "
+  const fs = require('fs');
+  const path = require('path');
+  try {
+    const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
+    const lpPath = path.join(cwd, '.muggle-ai', 'last-project.json');
+    if (!fs.existsSync(lpPath)) { console.log(''); return; }
+    const raw = JSON.parse(fs.readFileSync(lpPath, 'utf-8'));
+    const lp = raw && raw.lastProject;
+    if (!lp || !lp.projectId) { console.log(''); return; }
+    const safeName = String(lp.projectName || '').replace(/\"/g, '\\\\\"');
+    console.log('Muggle Test Last Project: id=' + lp.projectId + ' url=' + lp.projectUrl + ' name=\"' + safeName + '\"');
+  } catch { console.log(''); }
+" 2>/dev/null || true)
+if [ -n "$last_project_line" ]; then
+  last_project_note="\\n\\n${last_project_line}"
+fi
+
+# --- Last-host cache injection ---
+# Per-repo cache of the local dev server URL the user picked on the previous
+# run. Lives at <cwd>/.muggle-ai/last-host.json. Skills silently reuse it
+# when the user has set the autoSelectLocalHost preference to "always".
+last_host_line=""
+last_host_note=""
+last_host_line=$(node -e "
+  const fs = require('fs');
+  const path = require('path');
+  try {
+    const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
+    const lhPath = path.join(cwd, '.muggle-ai', 'last-host.json');
+    if (!fs.existsSync(lhPath)) { console.log(''); return; }
+    const raw = JSON.parse(fs.readFileSync(lhPath, 'utf-8'));
+    const lh = raw && raw.lastHost;
+    if (!lh || !lh.host) { console.log(''); return; }
+    console.log('Muggle Test Last Host: ' + lh.host);
+  } catch { console.log(''); }
+" 2>/dev/null || true)
+if [ -n "$last_host_line" ]; then
+  last_host_note="\\n\\n${last_host_line}"
+fi
+
+context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle Test launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}${prefs_file_note}${last_project_note}${last_host_note}"
 
 escaped_context=$(escape_for_json "$context")
 

package/dist/plugin/skills/_aliases.json

@@ -0,0 +1,18 @@
+{
+    "aliases": [
+        "m",
+        "mtest",
+        "mdo",
+        "mpr",
+        "mprefs",
+        "mstatus",
+        "mrepair",
+        "mupgrade",
+        "mfeedback",
+        "mimport",
+        "mtestlocal",
+        "mtestprep",
+        "mregen",
+        "mrelease"
+    ]
+}

package/dist/plugin/skills/_shared/dev-server-readiness.md

@@ -0,0 +1,231 @@
+# Dev Server Readiness
+
+**Goal:** Help any skill or agent (a) detect whether a local development server is already running, and (b) start one and confirm it is ready to receive requests before issuing them.
+
+**Scope:** Generic guidance for any local development server. This document is OS-agnostic, programming-language-agnostic, and framework-agnostic. Nothing here is repo-, toolchain-, runtime-, port-, or skill-specific. Callers provide concrete details.
+
+**How to read this doc:** The core algorithm is platform-neutral. The OS-specific commands below are examples you can copy directly or adapt.
+
+## Port detection — is a dev server already running?
+
+Common dev ports: `3000 3001 4200 5173 8080`. Callers may add repo-specific ports.
+
+Use any local networking utility available on the current OS to check whether one of the expected ports is listening.
+
+For each listening candidate, probe its base URL and verify it returns a successful status code (typically `2xx`).
+
+### Examples by OS
+
+#### Linux / macOS (bash/zsh)
+
+```bash
+# Detect listeners on common dev ports
+lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)\b'
+
+# Probe one candidate URL (returns HTTP status code)
+curl -sS -o /dev/null -w "%{http_code}" "http://localhost:3000/"
+```
+
+#### Windows PowerShell
+
+```powershell
+# Detect listeners on common dev ports
+Get-NetTCPConnection -State Listen |
+  Where-Object { $_.LocalPort -in 3000,3001,4200,5173,8080 } |
+  Select-Object -Property LocalAddress, LocalPort, OwningProcess
+
+# Probe one candidate URL (shows status code)
+(Invoke-WebRequest -Uri "http://localhost:3000/" -Method Get -TimeoutSec 3).StatusCode
+```
+
+#### Windows CMD
+
+```bat
+:: Detect listeners on common dev ports
+netstat -ano | findstr /R /C:":3000 " /C:":3001 " /C:":4200 " /C:":5173 " /C:":8080 "
+```
+
+## Backend health (when the dev server depends on one)
+
+If the app declares a backend URL in its env file, probe the backend's health endpoint before treating the dev server as usable. 5xx or unreachable → halt; the frontend may render but its data layer is dead, so any query against it is meaningless.
+
+## Two-stage readiness — after starting a dev server
+
+Network reachability is necessary but not sufficient. Many dev servers bind to a port before build/startup work is complete. Wait for **both** network readiness and application readiness before issuing requests.
+
+**Stage 1 — Network check.** Poll the target URL until it responds successfully. Use a short request timeout, a fixed retry interval (for example, every 3 seconds), and a hard overall timeout (for example, 5 minutes).
+
+**Stage 2 — Startup completion check.** Inspect captured process output for a known "ready" signal defined by the caller.
+
+The caller should provide:
+- a ready pattern (for example, `ready`, `started`, `listening`, `compiled successfully`)
+- one or more failure patterns (for example, `failed`, `error`, `module not found`, `unable to`)
+- the number of trailing log lines to surface on failure
+
+Before declaring ready, check for failure patterns in logs. If present, surface the trailing log lines and halt. Do not issue requests against a broken startup.
+
+For long-lived servers, re-check logs before each execution cycle and fail if new errors appear after the latest ready signal.
+
+## Reading the log
+
+The server start command must capture process output to a retrievable location (file, buffer, or managed process stream). Implementation details are environment-specific and should be supplied by the caller.
+
+### Start command examples by OS
+
+#### Linux / macOS (bash/zsh)
+
+```bash
+# Start in background and capture logs
+npm start > "/tmp/dev-server-3000.log" 2>&1 &
+```
+
+#### Windows PowerShell
+
+```powershell
+# Start detached and capture both stdout/stderr
+Start-Process -FilePath "npm" -ArgumentList "start" `
+  -RedirectStandardOutput "$env:TEMP\dev-server-3000.log" `
+  -RedirectStandardError "$env:TEMP\dev-server-3000.log"
+```
+
+#### Windows CMD
+
+```bat
+:: Start in background and capture logs
+start "" cmd /c "npm start > "%TEMP%\dev-server-3000.log" 2>&1"
+```
+
+## Generic algorithm (pseudocode)
+
+```text
+FUNCTION wait_for_dev_server(input):
+  REQUIRE input.url
+  REQUIRE input.logSource
+  REQUIRE input.readyPattern
+  REQUIRE input.failurePatterns
+  REQUIRE input.requestTimeoutSeconds
+  REQUIRE input.retryIntervalSeconds
+  REQUIRE input.maxWaitSeconds
+  REQUIRE input.failureTailLineCount
+
+  deadline = now() + input.maxWaitSeconds
+
+  WHILE now() <= deadline:
+    responseOk = probe_url(
+      url = input.url,
+      timeoutSeconds = input.requestTimeoutSeconds
+    )
+    IF responseOk:
+      BREAK
+    sleep(input.retryIntervalSeconds)
+
+  IF now() > deadline:
+    RETURN failure_with_log_tail(input.logSource, input.failureTailLineCount)
+
+  logText = read_log(input.logSource)
+
+  IF contains_any(logText, input.failurePatterns):
+    RETURN failure_with_log_tail(input.logSource, input.failureTailLineCount)
+
+  IF NOT contains(logText, input.readyPattern):
+    RETURN failure_with_log_tail(input.logSource, input.failureTailLineCount)
+
+  RETURN success
+```
+
+A failure result means the server is not ready. Callers decide how to surface the blocked state.
+
+## Practical implementation notes (important)
+
+- Prefer polling both conditions until deadline (network responds **and** ready pattern appears), instead of checking logs only once.
+- Avoid stale-log false positives by recording a start marker (timestamp, byte offset, or unique token) and scanning only new log content.
+- When checking for failure after ready, evaluate failures that appear **after** the latest ready signal.
+- If your app redirects `/` (for example to auth), treat expected `3xx` as acceptable in Stage 1.
+
+## End-to-end examples by OS (drop-in scripts)
+
+### Linux / macOS (bash/zsh)
+
+```bash
+URL="http://localhost:3000/"
+LOG="/tmp/dev-server-3000.log"
+READY_PATTERN='Compiled successfully|ready in|Ready in|ready - started server|listening'
+FAIL_PATTERN='Failed to compile|Module not found|Error:|EADDRINUSE|ERR!'
+DEADLINE=$(( $(date +%s) + 300 ))
+
+npm start > "$LOG" 2>&1 &
+START_LINE=$(wc -l < "$LOG" 2>/dev/null || echo 0)
+
+while [ "$(date +%s)" -le "$DEADLINE" ]; do
+  STATUS=$(curl -sS -o /dev/null -w "%{http_code}" "$URL" || echo 000)
+  NEW_LOG=$(tail -n +"$((START_LINE + 1))" "$LOG" 2>/dev/null)
+
+  if echo "$NEW_LOG" | grep -qE "$FAIL_PATTERN"; then
+    tail -20 "$LOG"
+    exit 1
+  fi
+
+  if [ "$STATUS" -ge 200 ] && [ "$STATUS" -lt 400 ] && echo "$NEW_LOG" | grep -qiE "$READY_PATTERN"; then
+    echo "Server ready"
+    exit 0
+  fi
+
+  sleep 3
+done
+
+tail -20 "$LOG"
+exit 1
+```
+
+### Windows PowerShell
+
+```powershell
+$url = "http://localhost:3000/"
+$log = Join-Path $env:TEMP "dev-server-3000.log"
+$readyPattern = "Compiled successfully|ready in|Ready in|ready - started server|listening"
+$failPattern = "Failed to compile|Module not found|Error:|EADDRINUSE|ERR!"
+$deadline = (Get-Date).AddMinutes(5)
+
+if (Test-Path $log) {
+  $startLine = (Get-Content $log | Measure-Object -Line).Lines
+} else {
+  $startLine = 0
+}
+
+Start-Process -FilePath "npm" -ArgumentList "start" `
+  -RedirectStandardOutput $log `
+  -RedirectStandardError $log
+
+while ((Get-Date) -le $deadline) {
+  $status = 0
+  try {
+    $response = Invoke-WebRequest -Uri $url -Method Get -TimeoutSec 3 -MaximumRedirection 0 -ErrorAction Stop
+    $status = [int]$response.StatusCode
+  } catch {
+    if ($_.Exception.Response -and $_.Exception.Response.StatusCode) {
+      $status = [int]$_.Exception.Response.StatusCode
+    } else {
+      $status = 0
+    }
+  }
+
+  $allLines = if (Test-Path $log) { Get-Content $log } else { @() }
+  $newLines = if ($allLines.Count -gt $startLine) { $allLines[$startLine..($allLines.Count - 1)] } else { @() }
+  $newLog = ($newLines -join "`n")
+
+  if ($newLog -match $failPattern) {
+    Get-Content $log -Tail 20
+    exit 1
+  }
+
+  if ($status -ge 200 -and $status -lt 400 -and $newLog -match $readyPattern) {
+    Write-Host "Server ready"
+    exit 0
+  }
+
+  Start-Sleep -Seconds 3
+}
+
+Get-Content $log -Tail 20
+exit 1
+```