@elalfner/relevo 0.5.0 → 0.7.0

package/scripts/lib/web-preflight.mjs

@@ -0,0 +1,87 @@
+// What a browser review checks before it drives: the project's dependencies, Playwright and its browser, and the
+// address under review with the module scripts its page loads. Everything that touches the machine is injected.
+// Implements "A browser review checks its tools and the app before driving" of openspec/specs/review/spec.md.
+
+export const EXIT = { node_modules: 3, playwright: 4, browser: 5, url: 6 };
+
+const START_SCRIPTS = ['dev', 'serve', 'start'];
+
+/** The command that starts the app, from the scripts of package.json; null when there is none. */
+export function startCommand(pkgText) {
+  let scripts = {};
+  try {
+    scripts = JSON.parse(pkgText ?? '{}').scripts ?? {};
+  } catch { /* an unreadable package.json names no command */ }
+  const name = START_SCRIPTS.find((s) => typeof scripts[s] === 'string');
+  return name ? `npm run ${name}` : null;
+}
+
+/** The variable names of an example environment file (`NAME=value` lines); values are ignored. */
+export function envNames(text) {
+  return [...String(text ?? '').matchAll(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)].map((m) => m[1]);
+}
+
+/** The same-origin module scripts that an HTML page loads, as absolute URLs. */
+export function moduleScripts(html, pageUrl) {
+  const origin = new URL(pageUrl).origin;
+  return [...String(html ?? '').matchAll(/<script\b[^>]*>/gi)]
+    .map((m) => m[0])
+    .filter((tag) => /\btype\s*=\s*["']?module\b/i.test(tag))
+    .map((tag) => tag.match(/\bsrc\s*=\s*["']([^"']+)["']/i)?.[1])
+    .filter(Boolean)
+    .map((src) => new URL(src, pageUrl))
+    .filter((u) => u.origin === origin)
+    .map((u) => u.href);
+}
+
+/** Does the page answer below 400 after redirects, and so do its module scripts? Returns { ok, detail }. */
+export async function checkUrl(url, { fetch, timeout = 5000 }) {
+  const get = async (address) => {
+    try {
+      const response = await fetch(address, { redirect: 'follow', signal: AbortSignal.timeout(timeout) });
+      return { status: response.status, text: response.status < 400 ? await response.text() : '' };
+    } catch (error) {
+      return { status: null, error: String(error?.cause?.code ?? error?.name ?? error?.message ?? error) };
+    }
+  };
+  const page = await get(url);
+  if (page.status === null) return { ok: false, detail: `${url} does not answer (${page.error})` };
+  if (page.status >= 400) return { ok: false, detail: `${url} answered ${page.status}` };
+  for (const script of moduleScripts(page.text, url)) {
+    const r = await get(script);
+    if (r.status === null) return { ok: false, detail: `${script} does not answer (${r.error})` };
+    if (r.status >= 400) return { ok: false, detail: `${script} answered ${r.status}` };
+  }
+  return { ok: true, detail: null };
+}
+
+/**
+ * Runs the checks in order and stops at the first failure. Returns { ok, check, detail, start, env, code }.
+ * deps: exists(path), readFile(path) (null when missing), loadPlaywright(), fetch, sleep(ms), now().
+ * Only `.env.example` is read for variable names; the real environment files never are.
+ * With `wait`, the address is retried every 500 ms until it answers or the time is over.
+ */
+export async function webPreflight({ cwd, url, timeout = 5000, wait = 0 }, deps) {
+  const { exists, readFile, loadPlaywright, fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now } = deps;
+  const at = (name) => `${cwd}/${name}`;
+  const start = startCommand(readFile(at('package.json')));
+  const env = envNames(readFile(at('.env.example')));
+  const result = (check, detail) => ({ ok: check === null, check, detail, start, env, code: check === null ? 0 : EXIT[check] });
+
+  if (!exists(at('node_modules'))) return result('node_modules', 'the project has no node_modules: run npm install first');
+  const playwright = loadPlaywright();
+  if (!playwright) return result('playwright', 'Playwright does not resolve from the project');
+  let executable = null;
+  try {
+    executable = playwright.chromium.executablePath();
+  } catch { /* an unknown browser build has no path */ }
+  if (!executable || !exists(executable)) return result('browser', 'the Chromium of Playwright is not installed');
+
+  const deadline = now() + wait;
+  for (;;) {
+    const answer = await checkUrl(url, { fetch, timeout });
+    if (answer.ok) return result(null, null);
+    if (now() >= deadline) return result('url', answer.detail);
+    await sleep(500);
+  }
+}

package/scripts/lib/web-review.mjs

@@ -1,10 +1,25 @@
 // The rules of a driven web review that must not vary: which origins a page may reach, what a review script may
 // contain, how a secret is kept out of the output, and the log the audit reads.
 // Implements "The agent operates the app only within fixed limits", "A web review script is reviewed before it runs",
-// "Credentials of a driven review are names, not values" and "The audit understands a browser" of openspec/specs/review/spec.md.
+// "Credentials of a driven review are names, not values", "The audit understands a browser",
+// "A browser review takes captures through the runner" and "A failing page is reported as such" of openspec/specs/review/spec.md.
+
+import { createRequire } from 'node:module';
+import { isAbsolute, join, relative } from 'node:path';
+import { safeCaptureName } from './device.mjs';
 
 export const WEB_PACKAGE = 'web';
 
+/** Playwright as the project resolves it, else as the plugin does; null when neither has it. */
+export function loadPlaywright(cwd = process.cwd()) {
+  for (const base of [join(cwd, 'package.json'), import.meta.url]) {
+    try {
+      return createRequire(base)('playwright');
+    } catch { /* try the next place */ }
+  }
+  return null;
+}
+
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 // URLs that do not reach the network.
 const OFFLINE_PROTOCOLS = new Set(['data:', 'blob:', 'about:']);
@@ -41,6 +56,15 @@ const FORBIDDEN = [
   [/\bglobalThis\s*\.\s*process\b/, 'it reaches the process'],
   [/\bfetch\s*\(/, 'it makes a request outside the browser with fetch'],
   [/\brequire\.resolve\b|\bimport\.meta\b/, 'it inspects the module system'],
+  [/\bscreenshot\s*\(|\[\s*['"`]screenshot['"`]\s*\]/, 'it takes a screenshot itself; take it with capture(name, check), which saves it in the output folder'],
+  [/\.\s*pdf\s*\(/, 'it saves a PDF of the page'],
+  [/\btracing\b/, 'it records a trace'],
+  [/\brecord(?:Video|Har)\b/, 'it records a video or a HAR'],
+  [/\brouteFromHAR\b/, 'it reads a HAR file'],
+  [/\.\s*saveAs\s*\(/, 'it saves a download'],
+  [/\.\s*storageState\s*\(/, 'it saves the storage state'],
+  [/\.\s*setInputFiles\s*\(/, 'it uploads a local file to the page'],
+  [/(?:^|[{,\s])['"]?path['"]?\s*:/m, 'it passes a file path to a browser call (a "path:" option)'],
 ];
 
 /**
@@ -63,6 +87,63 @@ export function scanReviewScript(text) {
   return problems;
 }
 
+/**
+ * The capture(name, check, { fullPage }) helper given to a review script. `check` asserts the state the shot shows and
+ * runs first: when it fails no screenshot is taken and the capture is recorded as failed, without throwing into the
+ * script. A good capture is saved as <out>/<name>.png. Nothing is returned, so the image never reaches the script.
+ * `captures` collects { name, ok, path | error }, the path relative to `cwd` when the file is under it; a repeated
+ * name replaces the earlier entry, as its file does.
+ */
+export function makeCapture({ page, out, captures, cwd = process.cwd() }) {
+  const keep = (entry) => {
+    const i = captures.findIndex((c) => c.name === entry.name);
+    if (i === -1) captures.push(entry);
+    else captures[i] = entry;
+  };
+  return async (name, check, options = {}) => {
+    const safe = safeCaptureName(name);
+    if (typeof check !== 'function') throw new Error(`capture("${safe}", check): check is the assertion of the state the shot shows, and it is required`);
+    const unknown = Object.keys(options ?? {}).filter((k) => k !== 'fullPage');
+    if (unknown.length > 0) throw new Error(`capture("${safe}"): the only option is fullPage (got ${unknown.join(', ')})`);
+    try {
+      await check();
+    } catch (error) {
+      keep({ name: safe, ok: false, error: String(error?.message ?? error).split('\n')[0] });
+      return undefined;
+    }
+    const file = join(out, `${safe}.png`);
+    await page.screenshot({ path: file, fullPage: options?.fullPage === true });
+    const near = relative(cwd, file);
+    keep({ name: safe, ok: true, path: near && !near.startsWith('..') && !isAbsolute(near) ? near : file });
+    return undefined;
+  };
+}
+
+/**
+ * The page's own failure during a run, to name before a script error: the first uncaught error of the page or the
+ * first response of 400 or more from the origin under review. `events` are those of formatBrowserLog. Returns a
+ * string or null.
+ */
+export function probableCause(events, baseUrl) {
+  let origin;
+  try {
+    origin = new URL(baseUrl).origin;
+  } catch {
+    return null;
+  }
+  const hit = events.find((e) => {
+    if (e.type === 'pageerror') return true;
+    if (e.type !== 'response') return false;
+    try {
+      return new URL(String(e.text).split(' ').pop()).origin === origin;
+    } catch {
+      return false;
+    }
+  });
+  if (!hit) return null;
+  return hit.type === 'pageerror' ? `uncaught ${hit.text}` : `response ${hit.text}`;
+}
+
 /** Replace the value of every secret by [redacted:NAME]. `secrets` maps a variable name to its value. */
 export function redact(text, secrets = {}) {
   let out = String(text ?? '');

package/scripts/lib/worktree-path.mjs

@@ -0,0 +1,11 @@
+// Where the worktree of an issue lives: next to the repository, never inside it. Shared by `go-local` and
+// `go-worktree` so that the two cannot name it differently.
+
+import { basename, dirname, join } from 'node:path';
+
+export const WORKTREES_FOLDER = '.relevo-worktrees';
+
+/** The worktree of an issue: `<parent of the repository>/.relevo-worktrees/<repository>-<issue>`. Pure. */
+export function worktreePath(repoRoot, issue) {
+  return join(dirname(repoRoot), WORKTREES_FOLDER, `${basename(repoRoot)}-${issue}`);
+}

package/scripts/review-adapter.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Prints how `review` works for a platform of relevo.yml, as JSON. Usage:
 //   node scripts/review-adapter.mjs --platform web [--target web] [--config relevo.yml]
-// Output: { supported, stack, target, kind, log, capture, driver, needs, reason, platform, needs_autopilot }
+// Output: { supported, stack, target, kind, log, capture, driver, needs, reason, platform, needs_autopilot, advice }
+// `advice` is what to tell the person, in the language of relevo.yml, when a browser review cannot start with review.autopilot off.
 //   exit 0: supported   exit 1: no adapter for this platform and target (the reason is in the output)   exit 2: bad usage or invalid relevo.yml
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { loadConfig } from './lib/config.mjs';
-import { adapterFor, needsAutopilot, targetOf } from './lib/review-adapters.mjs';
+import { adapterFor, autopilotAdvice, needsAutopilot, targetOf } from './lib/review-adapters.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -28,5 +29,6 @@ if (!platform) fail(`there is no platform "${name}" in relevo.yml (platforms: ${
 
 const target = arg('target') ?? targetOf(platform);
 const adapter = adapterFor({ stack: platform.stack, target });
-console.log(JSON.stringify({ ...adapter, platform: name, needs_autopilot: needsAutopilot(adapter) }));
+const advice = autopilotAdvice(adapter, { autopilot: loaded.config.review?.autopilot, language: loaded.config.language });
+console.log(JSON.stringify({ ...adapter, platform: name, needs_autopilot: needsAutopilot(adapter), advice }));
 process.exit(adapter.supported ? 0 : 1);

package/scripts/review-brief.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Prints a short brief of an issue for the person who reviews it. Usage:
 //   node scripts/review-brief.mjs --issue 42 --title "Birthday list" --body-file issue.md [--built-file comment.md] [--language en|es]
+//        [--autopilot off|precheck|verify]
 // exit 0: printed   exit 2: bad arguments
 
 import { readFileSync } from 'node:fs';
@@ -14,7 +15,7 @@ const number = arg('issue');
 const title = arg('title');
 const bodyFile = arg('body-file');
 if (!number || title === undefined || !bodyFile) {
-  console.error('usage: review-brief.mjs --issue <n> --title "<title>" --body-file <file> [--built-file <file>] [--language en|es]');
+  console.error('usage: review-brief.mjs --issue <n> --title "<title>" --body-file <file> [--built-file <file>] [--language en|es] [--autopilot off|precheck|verify]');
   process.exit(2);
 }
 const read = (f) => {
@@ -26,4 +27,4 @@ const read = (f) => {
   }
 };
 const built = arg('built-file') ? read(arg('built-file')) : '';
-console.log(reviewBrief({ issue: { number, title, body: read(bodyFile) }, built, language: arg('language') ?? 'en' }));
+console.log(reviewBrief({ issue: { number, title, body: read(bodyFile) }, built, language: arg('language') ?? 'en', autopilot: arg('autopilot') ?? 'off' }));

package/scripts/review-state.mjs

@@ -3,7 +3,8 @@
 //   review-state.mjs init <change-dir> [--autopilot off|precheck|verify]   build the checklist from the change's scenarios
 //   review-state.mjs set <id> <ok|fail|pending> [note ...]
 //   review-state.mjs sync <change-dir>            after a fix: keep confirmed lines, retest failed ones, add new scenarios
-//   review-state.mjs capture <path>               record a screenshot that was taken
+//   review-state.mjs capture <path>               record a screenshot that was taken (refused after "agree")
+//   review-state.mjs qa-pass <script>             QA passed this browser review script; the runner runs only this exact content
 //   review-state.mjs audit [<log-file>|-] [--package <id>] [--pid <n>]
 //                                                 audit the device log (stdin by default), write the report;
 //                                                 with --package only that app's lines are audited
@@ -24,7 +25,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } fr
 import { dirname, join } from 'node:path';
 import { checklistFromChange } from './lib/checklist.mjs';
 import { auditLog, auditReport, filterByApp } from './lib/logaudit.mjs';
-import { applyWaivers, autoItem, autoSection, confirmEnv, decidePr, newState, precheckItem, setItem, syncState, waivedSection, waiveFinding } from './lib/review-state.mjs';
+import { applyWaivers, autoItem, autoSection, confirmEnv, decidePr, newState, precheckItem, qaPass, recordCapture, setItem, syncState, waivedSection, waiveFinding } from './lib/review-state.mjs';
 
 const argv = process.argv.slice(2);
 const si = argv.indexOf('--state');
@@ -72,12 +73,18 @@ try {
     }
     case 'capture': {
       if (!rest[0]) fail('usage: review-state.mjs capture <path>');
-      const state = load();
-      state.captures.push(rest[0]);
+      const state = recordCapture(load(), rest[0]);
       save(state);
       console.log(`recorded ${rest[0]}`);
       break;
     }
+    case 'qa-pass': {
+      if (!rest[0] || !existsSync(rest[0])) fail('usage: review-state.mjs qa-pass <script>');
+      const state = qaPass(load(), rest[0], readFileSync(rest[0], 'utf8'));
+      save(state);
+      console.log(`QA passed ${rest[0]} (sha256 ${state.qaScript.sha256.slice(0, 12)}); any change to it needs a new pass`);
+      break;
+    }
     case 'drain': {
       const file = join(dirname(statePath), 'device.log');
       const text = readFileSync(0, 'utf8');
@@ -164,7 +171,7 @@ try {
       break;
     }
     default:
-      fail('usage: review-state.mjs <init|set|sync|capture|drain|audit|waive|waived|confirm-env|precheck|auto|auto-list|agree|show|decide> [...]');
+      fail('usage: review-state.mjs <init|set|sync|capture|qa-pass|drain|audit|waive|waived|confirm-env|precheck|auto|auto-list|agree|show|decide> [...]');
   }
 } catch (err) {
   fail(err.message);

package/scripts/web-preflight.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Checks that a browser review can drive: the project's dependencies, Playwright and its Chromium, and the address
+// under review with the module scripts its page loads. Usage:
+//   node scripts/web-preflight.mjs --url http://localhost:5173 [--timeout 5000] [--wait 30000]
+// With --wait it is also the readiness probe of a server the agent started: the address is retried until it answers.
+// Prints { ok, check, detail, start, env } as JSON: `start` is the command that starts the app, `env` the variable
+// names of .env.example (the real environment files are never read).
+//   exit 0: ready   exit 3: no node_modules (run npm install)   exit 4: Playwright does not resolve
+//   exit 5: the Chromium of Playwright is missing   exit 6: the address or one of its modules does not answer below 400
+//   exit 2: bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { loadPlaywright } from './lib/web-review.mjs';
+import { webPreflight } from './lib/web-preflight.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const number = (name, fallback) => {
+  const v = arg(name);
+  if (v === undefined) return fallback;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0) {
+    console.error(`--${name} must be a number of milliseconds`);
+    process.exit(2);
+  }
+  return n;
+};
+
+const url = arg('url');
+try {
+  if (!url || !/^https?:$/.test(new URL(url).protocol)) throw new Error();
+} catch {
+  console.error('usage: web-preflight.mjs --url <http address> [--timeout 5000] [--wait 30000]');
+  process.exit(2);
+}
+const cwd = process.cwd();
+const result = await webPreflight({ cwd, url, timeout: number('timeout', 5000), wait: number('wait', 0) }, {
+  exists: existsSync,
+  readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+  loadPlaywright: () => loadPlaywright(cwd),
+  fetch: globalThis.fetch,
+});
+const { code, ...shown } = result;
+console.log(JSON.stringify(shown));
+process.exit(code);

package/scripts/web-review.mjs

@@ -1,23 +1,34 @@
 #!/usr/bin/env node
 // Runs a review script in a browser of its own and reports what it checked. Usage:
 //   node scripts/web-review.mjs --script evidence/review-web.mjs --url http://localhost:5173 \
-//        [--allow-origins https://staging.example.com] [--secret-env TEST_USER,TEST_PASS] [--out evidence] [--headed]
+//        [--allow-origins https://staging.example.com] [--secret-env TEST_USER,TEST_PASS] [--out evidence]
+//        [--state evidence/review-state.json] [--headed]
 // The script is the agent's, written from the scenarios and reviewed by QA. Its default export receives
-// { page, context, baseUrl, line, credentials }: line(n, how, fn) runs fn and records the checklist line n as
+// { page, context, baseUrl, line, credentials, capture }: line(n, how, fn) runs fn and records the checklist line n as
 // auto-ok or auto-fail; credentials(name) gives a test credential taken from the environment variable `name`,
-// which must be in --secret-env. The browser has a clean profile and can reach only localhost, the page under
-// review and the allowed origins; every secret value is redacted from what is written.
-// Writes <out>/web-log.txt (the log the audit reads, with --package web) and <out>/web-result.json.
-//   exit 0: the script ran (lines can still have failed)   exit 1: the script was refused, Playwright is missing,
-//   the browser could not start, or the script failed outside a line   exit 2: bad arguments
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
+// which must be in --secret-env; capture(name, check, { fullPage }) runs the assertion `check` and, when it holds,
+// saves <out>/<name>.png and records it in the review state (nothing of the image is given back or printed).
+// Before anything runs, the review state must say the autopilot is on, the data was confirmed, the review is not
+// agreed yet, and QA passed this exact script (review-state.mjs qa-pass). The browser has a clean profile and can
+// reach only localhost, the page under review and the allowed origins; every secret value is redacted from what is
+// written, and the script's own console goes to <out>/script-console.txt, never to this output.
+// Writes <out>/web-log.txt (the log the audit reads, with --package web) and <out>/web-result.json. Each run against
+// another server uses an --out of its own; only the log of the normal run is audited.
+//   exit 0: the script ran (lines and captures can still have failed)   exit 1: the review state refused the run,
+//   the script was refused, Playwright is missing, the browser could not start, or the script failed outside a line
+//   exit 2: bad arguments
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { formatBrowserLog, isAllowedOrigin, redact, scanReviewScript } from './lib/web-review.mjs';
+import { format } from 'node:util';
+import { assertDriving, recordCapture, scriptHash } from './lib/review-state.mjs';
+import { formatBrowserLog, isAllowedOrigin, loadPlaywright, makeCapture, probableCause, redact, scanReviewScript } from './lib/web-review.mjs';
 
 const RUN_LIMIT_MS = 120000;
+// The runner's own output. The script's console is taken over while it runs, so these are kept apart.
+const say = console.log.bind(console);
+const tell = console.error.bind(console);
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -25,13 +36,13 @@ const arg = (name) => {
 };
 const list = (name) => (arg(name) ?? '').split(',').map((s) => s.trim()).filter(Boolean);
 const stop = (code, message) => {
-  console.error(message);
+  tell(message);
   process.exit(code);
 };
 
 const scriptPath = arg('script');
 const baseUrl = arg('url');
-if (!scriptPath || !baseUrl || !existsSync(scriptPath)) stop(2, 'usage: web-review.mjs --script <file> --url <url> [--allow-origins a,b] [--secret-env A,B] [--out evidence] [--headed]');
+if (!scriptPath || !baseUrl || !existsSync(scriptPath)) stop(2, 'usage: web-review.mjs --script <file> --url <url> [--allow-origins a,b] [--secret-env A,B] [--out evidence] [--state evidence/review-state.json] [--headed]');
 let origin;
 try {
   origin = new URL(baseUrl);
@@ -41,26 +52,38 @@ try {
 const allowed = list('allow-origins');
 const secretNames = list('secret-env');
 const out = resolve(arg('out') ?? 'evidence');
+const statePath = resolve(arg('state') ?? 'evidence/review-state.json');
+
+const readState = () => JSON.parse(readFileSync(statePath, 'utf8'));
+if (!existsSync(statePath)) stop(1, `no review in progress (${statePath} not found): the runner drives only a review started with review-state.mjs init`);
+try {
+  assertDriving(readState(), { open: true });
+} catch (error) {
+  stop(1, `the review state refused the run before any browser started: ${error.message}`);
+}
 
-const problems = scanReviewScript(readFileSync(scriptPath, 'utf8'));
+const source = readFileSync(scriptPath, 'utf8');
+const problems = scanReviewScript(source);
 if (problems.length > 0) stop(1, `the review script was refused before any browser started:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+if (readState().qaScript?.sha256 !== scriptHash(source)) {
+  stop(1, `the review script is not the one QA passed: launch relevo:qa on it, and after QA PASSED run review-state.mjs qa-pass ${scriptPath}`);
+}
 
 const secrets = Object.fromEntries(secretNames.filter((n) => process.env[n]).map((n) => [n, process.env[n]]));
 const hide = (text) => redact(text, secrets);
 
-function loadPlaywright() {
-  for (const base of [join(process.cwd(), 'package.json'), import.meta.url]) {
-    try {
-      return createRequire(base)('playwright');
-    } catch { /* try the next place */ }
-  }
-  return null;
-}
 const playwright = loadPlaywright();
-if (!playwright) stop(1, 'Playwright cannot be resolved from this project: install it with "npm install -D playwright" and "npx playwright install chromium"');
+if (!playwright) stop(1, 'Playwright cannot be resolved from this project: with the person\'s permission, install it with "npm install --no-save playwright" and "npx playwright install chromium", then restore package-lock.json if npm changed it');
+
+if (arg('out') === undefined && existsSync(join(out, 'web-log.txt'))) {
+  tell(`warning: ${join(out, 'web-log.txt')} is replaced; a run against another server uses an --out of its own (evidence/run-<port>)`);
+}
+mkdirSync(out, { recursive: true });
 
 const events = [];
 const results = [];
+const captures = [];
+const scriptConsole = [];
 let scriptError = null;
 let pagesLoaded = 0;
 let browser;
@@ -80,6 +103,13 @@ const credentials = (name) => {
   return secrets[name];
 };
 
+// From here on the script's console goes to a file, also after a timeout: the runner prints with say and tell.
+function takeOverConsole() {
+  ['log', 'info', 'warn', 'error', 'debug', 'trace', 'dir', 'table'].forEach((level) => {
+    console[level] = (...args) => { scriptConsole.push(`${level} ${format(...args)}`); };
+  });
+}
+
 async function run() {
   try {
     browser = await playwright.chromium.launch({ headless: !process.argv.includes('--headed') });
@@ -105,11 +135,14 @@ async function run() {
     if (r.request().isNavigationRequest() && r.request().frame() === page.mainFrame() && r.status() < 400) pagesLoaded += 1;
   });
   page.on('response', (r) => { if (r.status() >= 400) events.push({ type: 'response', text: `${r.status()} ${r.request().method()} ${r.url()}` }); });
+  // The real path, so a capture is recorded relative to the working directory even through a symbolic link.
+  const capture = makeCapture({ page, out: realpathSync(out), captures });
 
   try {
+    takeOverConsole();
     const mod = await import(pathToFileURL(resolve(scriptPath)).href);
     if (typeof mod.default !== 'function') throw new Error('the script must export a default async function');
-    await mod.default({ page, context, baseUrl, line, credentials });
+    await mod.default({ page, context, baseUrl, line, credentials, capture });
   } catch (error) {
     scriptError = String(error?.message ?? error).split('\n')[0];
   }
@@ -124,11 +157,29 @@ clearTimeout(timer);
 clearTimeout(backstop);
 if (browser) await browser.close().catch(() => {});
 
-mkdirSync(out, { recursive: true });
 // A browser that never loaded a page proves nothing: the log is left empty so the audit is inconclusive.
 writeFileSync(join(out, 'web-log.txt'), pagesLoaded === 0 ? '' : hide(formatBrowserLog(events, { origin: origin.host })));
-writeFileSync(join(out, 'web-result.json'), hide(`${JSON.stringify({ url: baseUrl, lines: results, blocked: events.filter((e) => e.type === 'blocked').length, pagesLoaded, scriptError }, null, 2)}\n`));
-results.sort((a, b) => a.n - b.n).forEach((r) => console.log(hide(`line ${r.n}: ${r.status} - ${r.how}${r.error ? ` (${r.error})` : ''}`)));
-console.log(`${events.length} event(s) written to ${join(out, 'web-log.txt')}; audit it with: review-state.mjs audit --package web`);
-if (scriptError) stop(1, hide(`the script failed outside a line: ${scriptError}`));
+writeFileSync(join(out, 'web-result.json'), hide(`${JSON.stringify({ url: baseUrl, lines: results, captures, blocked: events.filter((e) => e.type === 'blocked').length, pagesLoaded, scriptError }, null, 2)}\n`));
+writeFileSync(join(out, 'script-console.txt'), hide(scriptConsole.map((l) => `${l}\n`).join('')));
+
+// The state is read again, so a line set while the browser ran is not lost.
+const saved = captures.filter((c) => c.ok);
+if (saved.length > 0) {
+  try {
+    const state = readState();
+    saved.forEach((c) => recordCapture(state, c.path));
+    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  } catch (error) {
+    tell(`the captures could not be recorded in ${statePath}: ${error.message}`);
+  }
+}
+
+results.sort((a, b) => a.n - b.n).forEach((r) => say(hide(`line ${r.n}: ${r.status} - ${r.how}${r.error ? ` (${r.error})` : ''}`)));
+captures.forEach((c) => say(hide(c.ok ? `captured ${c.path}` : `capture ${c.name}: failed (${c.error})`)));
+say(`${events.length} event(s) written to ${join(out, 'web-log.txt')}; audit it with: review-state.mjs audit --package web`);
+if (scriptError) {
+  const cause = probableCause(events, baseUrl);
+  if (cause) tell(hide(`the page itself failed: ${cause}`));
+  stop(1, hide(`the script failed outside a line: ${scriptError}`));
+}
 process.exit(0);

package/skills/go/SKILL.md

@@ -27,10 +27,22 @@ Launch `relevo:dev` and `relevo:qa` in the foreground and wait for each report b
 
 ## Where it runs
 
-In the cloud the workflow starts this skill with the decision already made. A person can also start it on their machine: `node ${CLAUDE_PLUGIN_ROOT}/scripts/go-local.mjs <issue>` runs it in a separate git worktree, with the same limits and tool lists as the workflow, and removes the worktree when it ends cleanly. Started by hand without that script, it needs a clean working tree (the preflight below stops otherwise).
+In the cloud the workflow starts this skill with the decision already made. A person can also start it on their machine: `node ${CLAUDE_PLUGIN_ROOT}/scripts/go-local.mjs <issue>` runs it in a separate git worktree, with the same limits and tool lists as the workflow, and removes the worktree when it ends cleanly.
 
 **When `$ARGUMENTS` has `--local`**, do not build in this session: run `node ${CLAUDE_PLUGIN_ROOT}/scripts/go-local.mjs <issue>`, show what it prints, and stop. The build happens in the process that script starts, in its own worktree and with the closed tool lists, which a plain session does not have.
 
+**In an interactive session** (started by hand without `--decision` and without `--local`), do not build in the folder you were started in: another session may be building another issue there, and the person may have changes of their own. Before step 0, make a worktree for the issue:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/go-worktree.mjs create <issue>
+```
+
+- Exit 0: it prints `{"worktree": "<path>", "base": "<base>"}`. Enter it with `EnterWorktree` and its `path` (never its `name`, which would branch from the default branch and not from the base of the project). From then on every step, command and agent works in that folder.
+- Exit 4: the session is already in a linked worktree (a run of `go-local.mjs`, or one the person made). Build where you are, make no worktree, and skip the exit below.
+- Any other exit (for example 3, the worktree of this issue already exists because another run is building it or a failed one left it): show its message and stop without changing anything.
+
+At the end of the run, before the final report, leave the worktree: call `ExitWorktree` with `keep`. Then, from the folder you came from, remove it with `node ${CLAUDE_PLUGIN_ROOT}/scripts/go-worktree.mjs remove <issue>` when the outcome is `built` or a gate decision that stopped before step 2 (nothing was built, so nothing is lost). After the failure path, or if the run stopped for any other reason, leave the worktree on disk and say its path in the report.
+
 ## OpenSpec commands
 
 Use these OpenSpec commands and no others:

package/skills/init/SKILL.md

@@ -36,7 +36,7 @@ If `relevo.yml` already exists and is valid, skip this step. Otherwise ask, in s
 - the platforms: for each one a name, its stack (look at the project to propose one: the profiles in `${CLAUDE_PLUGIN_ROOT}/stacks/` are the stacks Relevo ships with: `flutter`, `vue`, `laravel` and `supabase`), the folder where it lives (`.` for a repository with one platform, `apps/web` in a monorepo) and, for a stack that has targets, which ones (for Flutter: `android`, `ios`, `web`; for Vue: `web`; Laravel and Supabase have none). Several platforms in one repository are written down, but `go` builds only a repository with one for now;
 - where `go` builds: in the cloud, on each person's machine, or both (the default), and, for the cloud, with an API key from the Anthropic Console (the default) or with a subscription token. A subscription's quota is shared by every run and by the interactive use of the account, so `init` sets `limits.concurrent_agents` to 1 for it. Nothing about this goes in `relevo.yml` apart from that number: the installed workflows, the secret that exists and the repository variable `RELEVO_CLOUD_GO` (`off` pauses the cloud at once, with no pull request) decide it;
 - the repositories this one depends on, if any (`owner/repo`, for example the back end of a front end): they are written to `links`, the closed list that `Depends-on: owner/repo#N` is checked against;
-- whether to create a commented `.relevo/stacks/<stack>.md` for each stack, where the project can add its own hygiene to the plugin's profile (optional; it is not committed);
+- whether to create a commented `.relevo/stacks/<stack>.md` for each stack, where the project can add its own hygiene to the plugin's profile (optional; `init` creates it but does not commit it: it is left for the person to commit, because the cloud and teammates read it from git);
 - which agent builds in the cloud, only when the person says they use Antigravity: `claude` (the default) or `antigravity`. With `antigravity` the model key is `GEMINI_API_KEY`, a key made only for Relevo in its own Google Cloud project with a quota, and the limit asked below is a number of tokens (`limits.run_max_tokens`) because that agent has no cost limit; `docs/security.md` says what else it cannot enforce;
 - the cost limit per unattended run in US dollars: the template's 5 is a placeholder the person must accept or change (with `antigravity`, the token limit instead).
 
@@ -72,4 +72,4 @@ Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs` and show its output.
 
 ## Report
 
-Finish with: what was created, what was left alone, what the person must still do by hand (always the model credential in the repository secrets, with all whitespace removed from a subscription token, and committing and pushing the new files to the default branch, because a workflow only runs from there), and the doctor result.
+Finish with: what was created, what was left alone, what the person must still do by hand (always the model credential in the repository secrets, with all whitespace removed from a subscription token, and committing and pushing the new files to the default branch, because a workflow only runs from there; name each `.relevo/stacks/<stack>.md` it created among them), and the doctor result.