rcf-lite 0.16.0 → 0.18.0

package/src/cli/init.js

@@ -31,6 +31,11 @@ import {
   writeAgentInstructions,
   writeMcpConfig,
 } from '../setup/agent-setup.js';
+import {
+  findProjectPlaywrightKey,
+  probeClaudeCodeMcp,
+} from '../setup/playwright-checks.js';
+import { PLAYWRIGHT_MCP_VERSION } from '../verify/engine/launcher.js';
 import { writeKnowledgeSeed } from '../setup/knowledge-seed.js';
 import { writeIdentityTemplate } from '../setup/identity-seed.js';
 import {
@@ -46,6 +51,7 @@ const OPTION_SPEC = {
   'project-name': { type: 'string' },
   'non-interactive': { type: 'boolean' },
   'no-agent-setup': { type: 'boolean' },
+  'no-playwright-mcp': { type: 'boolean' },
   quiet: { type: 'boolean' },
   help: { type: 'boolean' },
 };
@@ -70,6 +76,11 @@ Options:
                             not on a TTY or when piped)
   --no-agent-setup          Scaffold the tree only; print the manual
                             harness-wiring instructions instead
+  --no-playwright-mcp       Skip the Playwright MCP entry step. The probe
+                            still runs so the print-out remains honest, but
+                            init writes no Playwright entry and touches no
+                            existing one. Use when a user-scope Playwright
+                            entry is declared in a harness init cannot probe.
   --quiet                   Suppress non-error stdout
   --help                    Print this help
 `;
@@ -172,6 +183,26 @@ export async function main(argv, deps = {}) {
     return 2;
   }
 
+  // Step 1a: Playwright MCP entry (spec 2026-09-03, section 4). Writes a
+  // distinctly named 'playwright-rcf' entry ONLY when init can prove no
+  // Playwright entry exists at any scope the harness can report. Detection
+  // is by command tail (spec 4.1). Cross-scope probe of the Claude Code
+  // harness via `claude mcp list` (spec 4.2). Where the harness cannot be
+  // probed non-interactively, init falls back to the distinctly-named entry
+  // with a notice (spec 4.3). --no-playwright-mcp suppresses the write
+  // entirely; the probe still runs so the print-out remains honest.
+  const playwrightPass = await runPlaywrightMcpPass({
+    projectRoot: cwd,
+    stdout,
+    quiet: Boolean(flags.quiet),
+    optOut: Boolean(flags['no-playwright-mcp']),
+    probeClaudeCodeMcp: deps.probeClaudeCodeMcp ?? probeClaudeCodeMcp,
+  });
+  if (playwrightPass && 'kind' in playwrightPass && 'message' in playwrightPass) {
+    stderr.write(`[error] ${playwrightPass.kind} ${playwrightPass.message}\n`);
+    return 2;
+  }
+
   // Step 2: agent-instructions managed block inside rcf markers (idempotent).
   // Source is the 0.6.0 canonical asset, not the harness-template fenced
   // fragment (which is now regenerated from the same canonical text at
@@ -297,3 +328,138 @@ function countLocal(haystack, needle) {
     i = at + needle.length;
   }
 }
+
+/**
+ * Init's Playwright MCP pass (spec 2026-09-03, section 4). Decision tree:
+ *
+ *   1. If --no-playwright-mcp: probe still runs so the print-out is honest,
+ *      but no .mcp.json entry is written or touched.
+ *   2. If the project-scope .mcp.json carries a Playwright signature under
+ *      any key (spec 4.1): print the 'left alone' line and return.
+ *   3. Probe the Claude Code harness (spec 4.2):
+ *      - 'found': print the 'already registered at <scope> scope' line and
+ *        return (no shadowing).
+ *      - 'none': write the distinctly-named 'playwright-rcf' entry.
+ *      - 'inconclusive' (claude absent, non-zero, or unparseable): write the
+ *        distinctly-named 'playwright-rcf' entry with the 'could not probe'
+ *        notice.
+ *
+ * A distinct project-scope entry keeps init's "never write outside the
+ * project root" discipline; a coexisting user-scope entry the operator has
+ * that init could not see is not shadowed by naming convention.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {NodeJS.WritableStream} args.stdout
+ * @param {boolean} args.quiet
+ * @param {boolean} args.optOut
+ * @param {import('../setup/playwright-checks.js').probeClaudeCodeMcp} args.probeClaudeCodeMcp
+ * @returns {Promise<{ action: 'left-alone-project'|'left-alone-harness'|'written'|'skipped-opt-out', name?: string, scope?: string } | import('../core/errors/index.js').RcfError>}
+ */
+async function runPlaywrightMcpPass({ projectRoot, stdout, quiet, optOut, probeClaudeCodeMcp: probeImpl }) {
+  const mcpPath = join(projectRoot, '.mcp.json');
+  let mcpJson = null;
+  try {
+    const raw = await readFile(mcpPath, 'utf8');
+    try {
+      mcpJson = JSON.parse(raw);
+    } catch {
+      // writeMcpConfig already refused unparseable with a distinct error and
+      // returned before us; if we somehow reach here with a corrupt file,
+      // stay out and let doctor surface it. Return silently.
+      return { action: 'skipped-opt-out' };
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    // .mcp.json does not exist yet (rcf mcp write above would have created
+    // it; if that step ran we should not hit ENOENT). Treat as no project
+    // entry and continue to the probe.
+  }
+
+  const projectKey = mcpJson ? findProjectPlaywrightKey(mcpJson) : null;
+  // Gate finding 8 (2026-09-03): when --no-playwright-mcp is set, print the
+  // opt-out notice on EVERY terminal branch of this pass, in addition to the
+  // honest probe line. The probe still runs (spec 4.4) so the print-out is
+  // always honest about what init could see; the notice makes the reason a
+  // write did not happen unambiguous on the branches that would otherwise
+  // have written.
+  const optOutLine = 'Playwright MCP: --no-playwright-mcp set; nothing written.\n';
+
+  if (projectKey) {
+    if (!quiet) {
+      stdout.write(
+        `Playwright MCP: already registered in .mcp.json under key '${projectKey}' at project scope, left alone.\n`,
+      );
+      if (optOut) stdout.write(optOutLine);
+    }
+    return { action: 'left-alone-project', name: projectKey };
+  }
+
+  // Probe the harness even when --no-playwright-mcp so the print-out remains
+  // honest about what init can see.
+  const probeResult = await probeImpl();
+  if (probeResult.kind === 'found') {
+    if (!quiet) {
+      stdout.write(
+        `Playwright MCP: already registered under key '${probeResult.name}' at ${probeResult.scope} scope in Claude Code, left alone.\n`,
+      );
+      if (optOut) stdout.write(optOutLine);
+    }
+    return { action: 'left-alone-harness', name: probeResult.name, scope: probeResult.scope };
+  }
+
+  if (optOut) {
+    if (!quiet) {
+      // The honest probe line first, then the opt-out notice.
+      if (probeResult.kind === 'inconclusive') {
+        stdout.write(
+          `Playwright MCP: could not probe user-scope entries (${probeResult.reason}).\n`,
+        );
+      } else {
+        stdout.write(
+          'Playwright MCP: no ambient Playwright entry found at any scope this init could probe.\n',
+        );
+      }
+      stdout.write(optOutLine);
+    }
+    return { action: 'skipped-opt-out' };
+  }
+
+  // Compose the distinctly-named entry. Distinct from 'playwright' (the
+  // common name a user-scope entry uses) and from any name Claude Code
+  // writes by default. If init could not see a user-scope entry that
+  // actually exists, both coexist and no shadowing has occurred; verify
+  // provisions its OWN MCP config anyway.
+  const distinctEntry = {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', `@playwright/mcp@${PLAYWRIGHT_MCP_VERSION}`],
+    env: {},
+  };
+  const nextBody = mcpJson ?? {};
+  const servers = (nextBody.mcpServers && typeof nextBody.mcpServers === 'object' && !Array.isArray(nextBody.mcpServers))
+    ? nextBody.mcpServers
+    : {};
+  const nextConfig = {
+    ...nextBody,
+    mcpServers: {
+      ...servers,
+      'playwright-rcf': distinctEntry,
+    },
+  };
+  await writeFile(mcpPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
+
+  if (!quiet) {
+    if (probeResult.kind === 'inconclusive') {
+      stdout.write(
+        `Playwright MCP: could not probe user-scope entries (${probeResult.reason}). Wrote 'playwright-rcf' at project scope; remove with \`rcf init --no-playwright-mcp\` or delete the entry by hand.\n`,
+      );
+    } else {
+      stdout.write(
+        "Playwright MCP: wrote 'playwright-rcf' at project scope (no ambient Playwright entry found at any scope this init could probe). Remove with `rcf init --no-playwright-mcp` or delete the entry by hand.\n",
+      );
+    }
+  }
+  return { action: 'written' };
+}
+

package/src/setup/playwright-checks.js

@@ -0,0 +1,426 @@
+// Doctor's browser-facing project checks (spec 2026-09-03, section 3) plus
+// init-time Playwright signature detection and the Claude Code cross-scope
+// probe (spec sections 4.1-4.3). All probes are injectable via a `deps`
+// argument so the unit suite runs with none of these tools installed.
+//
+// A project is browser-facing exactly when its rcf/manifest.json carries at
+// least one blueprint in manifest.blueprints[] whose loaded blueprint.json
+// declares `browserSurface`. Detection is a manifest fact, not string grammar:
+// doctor loads the manifest, walks manifest.blueprints[].source, reads each
+// blueprint.json, and evaluates the flag. Blueprints not shipping the field
+// are treated as not-browser-facing, and no per-slug allowlist exists.
+//
+// The 15-second cap on the reachability probe is a diagnostic ceiling; on a
+// warm cache the probe returns in well under a second, and the ceiling only
+// matters where npx would be doing a fresh network fetch it should not be
+// doing on a diagnostic run.
+
+import { existsSync } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join, resolve as pathResolve } from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { PLAYWRIGHT_MCP_VERSION } from '../verify/engine/launcher.js';
+
+/**
+ * The three fix lines emitted per check, verbatim from the spec's fix-line
+ * table. Tests assert the strings; changing them requires a spec amendment.
+ */
+export const FIX_LINES = Object.freeze({
+  'playwright-present':
+    'Install the peer dependency: npm i -D playwright@^1.50.0 (or the pnpm/yarn equivalent for your project).',
+  'browser-present':
+    'Install a browser: npx @playwright/mcp install-browser chromium (Playwright-managed) or install system Google Chrome (used by @playwright/mcp by default).',
+  'playwright-mcp-reachable':
+    `Install @playwright/mcp: npm i -D @playwright/mcp@${PLAYWRIGHT_MCP_VERSION} (the pinned version rcf verify runs).`,
+  'playwright-mcp-redundant':
+    "project-scope .mcp.json carries a Playwright MCP entry that is also declared at user scope. The project entry shadows the user entry. Remove the project entry with `rcf init --no-playwright-mcp` (which re-runs init without writing it), or delete the entry from .mcp.json by hand.",
+});
+
+/**
+ * The single skip line for non-browser-facing projects. Not suppressed by
+ * --quiet (spec 3.4).
+ */
+export const SKIP_LINE_NON_BROWSER_FACING =
+  'rcf doctor: skipping playwright-present, browser-present, playwright-mcp-reachable (no applied blueprint declares a browser surface).';
+
+/**
+ * Is the manifest a browser-facing project per spec 3.1?
+ *
+ * @param {string} projectRoot
+ * @param {object} [deps]
+ * @param {(source: string) => Promise<object|null>} [deps.readBlueprintManifest] - test seam
+ * @returns {Promise<{ browserFacing: boolean, sources: string[] }>}
+ */
+export async function loadBrowserFacingSources(projectRoot, deps = {}) {
+  const readManifest = deps.readBlueprintManifest ?? defaultReadBlueprintManifest;
+  const rootManifestPath = join(projectRoot, 'rcf', 'manifest.json');
+  let manifest = null;
+  try {
+    manifest = JSON.parse(await readFile(rootManifestPath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return { browserFacing: false, sources: [] };
+    throw err;
+  }
+  const applied = Array.isArray(manifest?.blueprints) ? manifest.blueprints : [];
+  const sources = [];
+  for (const record of applied) {
+    if (!record || typeof record.source !== 'string') continue;
+    const resolved = isAbsolute(record.source)
+      ? record.source
+      : pathResolve(projectRoot, record.source);
+    let bp;
+    try {
+      bp = await readManifest(resolved);
+    } catch {
+      bp = null;
+    }
+    if (bp && bp.browserSurface && bp.browserSurface.declared === true) {
+      sources.push(resolved);
+    }
+  }
+  return { browserFacing: sources.length > 0, sources };
+}
+
+async function defaultReadBlueprintManifest(source) {
+  const metaPath = join(source, 'blueprint.json');
+  try {
+    return JSON.parse(await readFile(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check that `playwright` is resolvable from the project root.
+ *
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, resolvedFrom: (string|null) }}
+ */
+export function checkPlaywrightPresent(projectRoot) {
+  const req = createRequire(join(projectRoot, '__rcf-require-anchor__'));
+  try {
+    const resolvedFrom = req.resolve('playwright');
+    return { ok: true, resolvedFrom };
+  } catch {
+    return { ok: false, resolvedFrom: null };
+  }
+}
+
+/**
+ * Check that some Chromium is available to @playwright/mcp: system Chrome on
+ * PATH first, then a Playwright-managed cache directory, then the tool's own
+ * first-party status probe.
+ *
+ * @param {object} [deps]
+ * @param {(name: string) => boolean} [deps.pathHas]
+ * @param {(path: string) => boolean} [deps.dirExists]
+ * @param {() => Promise<{ ok: boolean, source: string }>} [deps.probeMcpBrowserStatus]
+ * @param {() => string} [deps.homedir]
+ * @returns {Promise<{ ok: boolean, source: (string|null) }>}
+ */
+export async function checkBrowserPresent(deps = {}) {
+  const pathHas = deps.pathHas ?? defaultPathHas;
+  const dirExists = deps.dirExists ?? existsSync;
+  const home = deps.homedir ?? homedir;
+  for (const bin of ['google-chrome-stable', 'chromium', 'chrome', 'Google Chrome']) {
+    if (pathHas(bin)) return { ok: true, source: `path:${bin}` };
+  }
+  const playwrightCache = join(home(), '.cache', 'ms-playwright');
+  if (dirExists(playwrightCache)) {
+    try {
+      const entries = await readdir(playwrightCache);
+      if (entries.some((e) => /^chromium/i.test(e))) {
+        return { ok: true, source: `cache:${playwrightCache}` };
+      }
+    } catch {
+      // fall through to first-party probe
+    }
+  }
+  const probe = deps.probeMcpBrowserStatus ?? defaultProbeMcpBrowserStatus;
+  try {
+    const res = await probe();
+    if (res && res.ok) return { ok: true, source: `mcp:${res.source ?? 'ok'}` };
+  } catch {
+    // treat any probe failure as no browser
+  }
+  return { ok: false, source: null };
+}
+
+function defaultPathHas(binName) {
+  const path = process.env.PATH ?? '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  for (const dir of path.split(sep)) {
+    if (!dir) continue;
+    try {
+      const p = join(dir, binName);
+      if (existsSync(p)) return true;
+    } catch {
+      /* ignore */
+    }
+  }
+  return false;
+}
+
+async function defaultProbeMcpBrowserStatus() {
+  return runNpxProbe(['--no-install', '@playwright/mcp', 'browser-status', '--json'], 15000)
+    .then((r) => (r.exitCode === 0 ? { ok: true, source: 'browser-status' } : { ok: false }))
+    .catch(() => ({ ok: false }));
+}
+
+/**
+ * Check that `npx --no-install @playwright/mcp --help` runs and exits 0 in
+ * under 15 seconds. `--no-install` so the check does not silently pull the
+ * package during a diagnostic run.
+ *
+ * @param {object} [deps]
+ * @param {(args: string[], timeoutMs: number) => Promise<{ exitCode: number, timedOut: boolean }>} [deps.runNpx]
+ * @param {number} [deps.timeoutMs]
+ * @returns {Promise<{ ok: boolean, exitCode: (number|null), timedOut: boolean }>}
+ */
+export async function checkPlaywrightMcpReachable(deps = {}) {
+  const runNpx = deps.runNpx ?? runNpxProbe;
+  const timeoutMs = deps.timeoutMs ?? 15000;
+  try {
+    const res = await runNpx(['--no-install', '@playwright/mcp', '--help'], timeoutMs);
+    return {
+      ok: res.exitCode === 0,
+      exitCode: res.exitCode ?? null,
+      timedOut: Boolean(res.timedOut),
+    };
+  } catch (err) {
+    return { ok: false, exitCode: null, timedOut: false, error: err.message };
+  }
+}
+
+function runNpxProbe(args, timeoutMs) {
+  return new Promise((resolvePromise) => {
+    let child;
+    try {
+      child = spawn('npx', args, { stdio: 'ignore' });
+    } catch (err) {
+      resolvePromise({ exitCode: null, timedOut: false, error: err.message });
+      return;
+    }
+    let done = false;
+    const timer = setTimeout(() => {
+      done = true;
+      try { child.kill('SIGKILL'); } catch { /* ignore */ }
+      resolvePromise({ exitCode: null, timedOut: true });
+    }, timeoutMs);
+    child.on('close', (code) => {
+      if (done) return;
+      clearTimeout(timer);
+      done = true;
+      resolvePromise({ exitCode: code ?? null, timedOut: false });
+    });
+    child.on('error', (err) => {
+      if (done) return;
+      clearTimeout(timer);
+      done = true;
+      resolvePromise({ exitCode: null, timedOut: false, error: err.message });
+    });
+  });
+}
+
+/* ================================================================== */
+/* Playwright signature detection (spec 4.1) + probe (spec 4.2/4.3).  */
+/* ================================================================== */
+
+/** Regex naming a @playwright/mcp args token (any pinning suffix accepted). */
+const PLAYWRIGHT_MCP_TOKEN = /^@playwright\/mcp(?:@|$)/;
+
+/**
+ * True iff a parsed mcpServers[<name>] entry has a Playwright signature by
+ * command tail: any `args` string matching /^@playwright\/mcp(@|$)/, or a
+ * `command` path whose basename is `mcp` and lives under a @playwright/mcp
+ * package directory.
+ *
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+export function hasPlaywrightSignature(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  const args = Array.isArray(entry.args) ? entry.args : [];
+  if (args.some((a) => typeof a === 'string' && PLAYWRIGHT_MCP_TOKEN.test(a))) return true;
+  if (typeof entry.command === 'string') {
+    const cmd = entry.command;
+    if (basename(cmd) === 'mcp' && /@playwright\/mcp/.test(cmd)) return true;
+  }
+  return false;
+}
+
+/**
+ * Look up the first project-scope entry key carrying a Playwright signature
+ * in a parsed .mcp.json body. Returns null when no entry matches.
+ *
+ * @param {object|null|undefined} mcpJson - the parsed .mcp.json body
+ * @returns {string|null}
+ */
+export function findProjectPlaywrightKey(mcpJson) {
+  const servers = mcpJson?.mcpServers;
+  if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return null;
+  for (const [key, entry] of Object.entries(servers)) {
+    if (hasPlaywrightSignature(entry)) return key;
+  }
+  return null;
+}
+
+/**
+ * Probe the Claude Code harness for a Playwright entry at any scope by
+ * shelling out to `claude mcp list` and parsing its text output. `list`
+ * itself does not name the scope column (as of Claude Code 1.x); when the
+ * list surfaces a Playwright entry, follow up with `claude mcp get <name>`
+ * to read the scope. Result shapes:
+ *
+ * - { kind: 'found', name, scope } - list matched signature and get named scope
+ * - { kind: 'none' } - claude ran cleanly and reported no Playwright entry
+ * - { kind: 'inconclusive', reason } - probe could not prove either way
+ *
+ * @param {object} [deps]
+ * @param {(cmd: string, args: string[], timeoutMs: number) => Promise<{ exitCode: number, stdout: string, timedOut: boolean, error?: string }>} [deps.runProbe]
+ * @param {number} [deps.timeoutMs]
+ * @returns {Promise<{ kind: 'found', name: string, scope: string }
+ *   | { kind: 'none' } | { kind: 'inconclusive', reason: string }>}
+ */
+export async function probeClaudeCodeMcp(deps = {}) {
+  const run = deps.runProbe ?? defaultRunProbeText;
+  const timeoutMs = deps.timeoutMs ?? 5000;
+  let res;
+  try {
+    res = await run('claude', ['mcp', 'list'], timeoutMs);
+  } catch (err) {
+    return { kind: 'inconclusive', reason: `claude probe threw: ${err.message}` };
+  }
+  if (res.timedOut) return { kind: 'inconclusive', reason: 'claude mcp list timed out' };
+  if (res.error) return { kind: 'inconclusive', reason: `claude probe error: ${res.error}` };
+  if (res.exitCode !== 0) return { kind: 'inconclusive', reason: `claude mcp list exited ${res.exitCode}` };
+  const parsed = parseClaudeMcpListOutput(res.stdout ?? '');
+  if (parsed.kind === 'unparseable') {
+    return { kind: 'inconclusive', reason: 'claude mcp list output did not parse' };
+  }
+  if (parsed.kind === 'none') return { kind: 'none' };
+  // parsed.kind === 'found': list has a Playwright line but the shipping
+  // `claude mcp list` format does not carry an explicit scope column. Ask
+  // for the per-server detail so we can name the scope on the print-out.
+  let scope = parsed.scope;
+  if (!scope || scope === 'unknown') {
+    try {
+      const detail = await run('claude', ['mcp', 'get', parsed.name], timeoutMs);
+      if (detail.exitCode === 0 && typeof detail.stdout === 'string') {
+        scope = parseClaudeMcpGetScope(detail.stdout) ?? 'unknown';
+      } else {
+        scope = 'unknown';
+      }
+    } catch {
+      scope = 'unknown';
+    }
+  }
+  return { kind: 'found', name: parsed.name, scope };
+}
+
+/**
+ * Read the Scope line out of `claude mcp get <name>` output. Format observed
+ * on Claude Code 1.x: `  Scope: User config (available in all your projects)`
+ * for user, `  Scope: Local config` / `  Scope: Project config` otherwise.
+ * Returns 'user' | 'project' | 'local', or null when the format is not
+ * recognised (the caller then reports scope as 'unknown').
+ *
+ * @param {string} text
+ * @returns {'user'|'project'|'local'|null}
+ */
+export function parseClaudeMcpGetScope(text) {
+  if (typeof text !== 'string') return null;
+  const m = text.match(/Scope:\s*(User|Project|Local)/i);
+  if (!m) return null;
+  return m[1].toLowerCase();
+}
+
+/**
+ * Parse `claude mcp list` text output for a Playwright signature. Claude
+ * Code 1.x prints each server on its own line as
+ * `<name>: <command line> - <status>`; there is no scope column on the
+ * list output (per-server scope is available via `claude mcp get <name>`),
+ * so this parser returns the name and leaves the scope as 'unknown' for
+ * the caller to resolve if it wants one.
+ *
+ * Accepted line shapes:
+ * - `<name>: <command line> - <status>` (Claude Code 1.x)
+ * - `<name>  <scope>  <command line>` (older columnar form, kept for
+ *    tolerance)
+ *
+ * @param {string} text
+ * @returns {{ kind: 'found', name: string, scope: string } | { kind: 'none' } | { kind: 'unparseable' }}
+ */
+export function parseClaudeMcpListOutput(text) {
+  if (typeof text !== 'string') return { kind: 'unparseable' };
+  const lines = text.split('\n');
+  let sawAnyEntry = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0) continue;
+    if (/^(No |No MCP servers|Usage:|Error:|Checking |name\b)/i.test(line)) continue;
+    // Recognise a non-Playwright entry so we can distinguish "parseable but
+    // no Playwright" from "unparseable output".
+    if (/^[A-Za-z0-9_.\/@-]+:\s+/.test(line) || /\b(user|project|local)\b/.test(line)) {
+      sawAnyEntry = true;
+    }
+    if (!/@playwright\/mcp/.test(line)) continue;
+
+    // Extract the name. Both accepted shapes start with the name; the
+    // 1.x shape ends the name with a colon, the older shape is space-
+    // separated.
+    let name;
+    const colonForm = line.match(/^([A-Za-z0-9_.\/@-]+):\s+/);
+    if (colonForm) {
+      name = colonForm[1];
+    } else {
+      name = line.split(/\s+/)[0];
+    }
+    if (!name) continue;
+    // Older columnar shape may name the scope inline; keep that when present.
+    const scopeMatch = line.match(/\b(user|project|local)\b/);
+    const scope = scopeMatch ? scopeMatch[1] : 'unknown';
+    return { kind: 'found', name, scope };
+  }
+  if (sawAnyEntry) return { kind: 'none' };
+  if (lines.every((l) => l.trim().length === 0)) return { kind: 'none' };
+  return { kind: 'none' };
+}
+
+async function defaultRunProbeText(cmd, args, timeoutMs) {
+  return new Promise((resolvePromise) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      resolvePromise({ exitCode: null, stdout: '', timedOut: false, error: err.message });
+      return;
+    }
+    let stdout = '';
+    child.stdout?.on('data', (d) => { stdout += d.toString(); });
+    let done = false;
+    const timer = setTimeout(() => {
+      done = true;
+      try { child.kill('SIGKILL'); } catch { /* ignore */ }
+      resolvePromise({ exitCode: null, stdout, timedOut: true });
+    }, timeoutMs);
+    child.on('close', (code) => {
+      if (done) return;
+      clearTimeout(timer);
+      done = true;
+      resolvePromise({ exitCode: code ?? null, stdout, timedOut: false });
+    });
+    child.on('error', (err) => {
+      if (done) return;
+      clearTimeout(timer);
+      done = true;
+      resolvePromise({ exitCode: null, stdout, timedOut: false, error: err.message });
+    });
+  });
+}
+
+// Silence unused import warnings for values consumed only via names.
+void stat;

package/src/verify/cli/run.js

@@ -12,6 +12,7 @@ import { parseArgs } from 'node:util';
 import { formatError, isRcfError } from '#core/errors';
 
 import { runVerification } from '../engine/index.js';
+import { isSemverString, PLAYWRIGHT_MCP_VERSION } from '../engine/launcher.js';
 import { serialiseReport } from '../report/index.js';
 import { gateTripped, FINDING_SEVERITIES } from '../verdict/index.js';
 
@@ -26,6 +27,7 @@ const OPTION_SPEC = {
   'severity-gate': { type: 'string' },
   'provision-mode': { type: 'string' },
   persona: { type: 'string' },
+  'playwright-mcp-version': { type: 'string' },
   help: { type: 'boolean' },
 };
 
@@ -51,6 +53,12 @@ Optional:
                             PASS | COSMETIC | DEGRADED | BROKEN
   --provision-mode <m>      run | skip (default: run)
   --persona <name>          Adversarial persona flavour (default: generic-sceptic)
+  --playwright-mcp-version <semver>
+                            Override the pinned Playwright MCP version for
+                            one run (emergency use only; a loud stderr notice
+                            fires and the report records the overridden pin
+                            as runStats.playwrightMcpVersion). Must be an
+                            exact semver X.Y.Z.
   --help                    Print this help
 
 Exit codes:
@@ -119,6 +127,25 @@ export async function main(argv, deps = {}) {
     return 2;
   }
 
+  // --playwright-mcp-version override (spec 2026-09-03, section 1.4). Semver
+  // only; anything else refuses exit 2 with the spec-named message. When set,
+  // the effective pin fires a loud stderr override notice on preflight; when
+  // unset, preflight prints the pinned default.
+  const overrideRaw = flags['playwright-mcp-version'];
+  if (overrideRaw !== undefined && !isSemverString(overrideRaw)) {
+    // Spec sections 1.4 and 6 name the message without a prefix. The
+    // module's other refusals prefix with `[error] usage`, but this one
+    // is the spec-verbatim line and stands on its own.
+    stderr.write(`--playwright-mcp-version expects a semver string, got '${overrideRaw}'\n`);
+    return 2;
+  }
+  if (overrideRaw !== undefined) {
+    // Loud override notice on stderr (spec 1.4: not silenceable with quiet).
+    stderr.write(`Playwright MCP: OVERRIDE @playwright/mcp@${overrideRaw} (pinned default: ${PLAYWRIGHT_MCP_VERSION})\n`);
+  } else {
+    stderr.write(`Playwright MCP: pinned to @playwright/mcp@${PLAYWRIGHT_MCP_VERSION}\n`);
+  }
+
   const result = await runVerification({
     repo: flags.repo,
     chainRef: flags.chain,
@@ -129,6 +156,7 @@ export async function main(argv, deps = {}) {
     provisionMode,
     persona: flags.persona,
     severityGate: gate,
+    playwrightMcpVersion: overrideRaw,
   }, deps);
 
   if (isRcfError(result)) {