@elalfner/relevo 0.6.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "relevo",
   "displayName": "Relevo",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "An automatic issue-to-merge workflow where an agent builds and people verify.",
   "author": {
     "name": "Elias Alfaro"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elalfner/relevo",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Relevo: an automatic issue-to-merge workflow where an agent builds and people verify.",
   "type": "module",
   "license": "MIT",

package/scripts/dev-server-guard.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Says whether the working tree may switch branches: a dev server of the address under review that runs from it
+// would lose its files. Usage:
+//   node scripts/dev-server-guard.mjs --url http://localhost:5173
+// Prints { code, servers, reason } as JSON.
+//   exit 0: no server of that address runs from the working tree   exit 1: one does (stop it before switching)
+//   exit 3: it cannot tell (no lsof, or the folder cannot be read): do not switch   exit 2: bad arguments
+
+import { realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { guard } from './lib/dev-server-guard.mjs';
+
+const i = process.argv.indexOf('--url');
+const url = i === -1 ? undefined : process.argv[i + 1];
+try {
+  if (!url || !/^https?:$/.test(new URL(url).protocol)) throw new Error();
+} catch {
+  console.error('usage: dev-server-guard.mjs --url <http address>');
+  process.exit(2);
+}
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0) {
+  console.error('not inside a git repository');
+  process.exit(2);
+}
+const lsof = (args) => {
+  const r = spawnSync('lsof', args, { encoding: 'utf8' });
+  return { status: r.error ? 127 : r.status ?? 1, stdout: r.stdout ?? '' };
+};
+const result = guard({ url, repoRoot: top.stdout.trim() }, { lsof, realpath: realpathSync });
+console.log(JSON.stringify(result));
+process.exit(result.code);

package/scripts/extra-server.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Starts, checks and stops the dev servers the agent needs for lines that require another configuration. Usage:
+//   node scripts/extra-server.mjs start --port 5174 [--set NAME=value ...] [--unset NAME ...] -- npx vite --port 5174 --strictPort
+//   node scripts/extra-server.mjs check --port 5174     after web-preflight.mjs --wait: the port is served by that server
+//   node scripts/extra-server.mjs stop --port 5174 | --all
+// Each server runs in a process group of its own, logs to evidence/servers/<port>.log and is recorded in
+// evidence/servers.json (override the folder with --dir). Only recorded servers are ever stopped, so the person's own
+// server is never touched. The environment files are never read; their names only decide whether --unset can work.
+//   exit 0: done   exit 1: not recorded, or the port is not served by the recorded server (it was stopped)
+//   exit 2: bad arguments   exit 3: the port is busy   exit 4: --unset with environment files present   exit 5: no lsof
+
+import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { checkServer, parseSet, startServer, stopServers } from './lib/extra-server.mjs';
+
+const dash = process.argv.indexOf('--');
+const argv = dash === -1 ? process.argv.slice(2) : process.argv.slice(2, dash);
+const command = dash === -1 ? [] : process.argv.slice(dash + 1);
+const [action] = argv;
+const values = (name) => argv.flatMap((a, i) => (a === `--${name}` ? [argv[i + 1]] : []));
+const usage = (message) => {
+  if (message) console.error(message);
+  console.error('usage: extra-server.mjs start --port <p> [--set NAME=value] [--unset NAME] -- <command>\n       extra-server.mjs check --port <p>\n       extra-server.mjs stop --port <p> | --all');
+  process.exit(2);
+};
+
+const dir = values('dir')[0] ?? 'evidence';
+const file = join(dir, 'servers.json');
+const port = values('port')[0] === undefined ? null : Number(values('port')[0]);
+const lsof = (args) => {
+  const r = spawnSync('lsof', args, { encoding: 'utf8' });
+  return { status: r.error ? 127 : r.status ?? 1, stdout: r.stdout ?? '' };
+};
+const deps = {
+  lsof,
+  dir,
+  baseEnv: process.env,
+  listDir: () => readdirSync(process.cwd()),
+  load: () => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : []),
+  save: (records) => {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, `${JSON.stringify(records, null, 2)}\n`);
+  },
+  spawn: (cmd, env, log) => {
+    mkdirSync(join(dir, 'servers'), { recursive: true });
+    const fd = openSync(log, 'a');
+    const child = spawn(cmd[0], cmd.slice(1), { detached: true, stdio: ['ignore', fd, fd], env });
+    child.unref();
+    return child.pid;
+  },
+  pgidOf: (pid) => Number(spawnSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).stdout.trim()),
+  kill: (pgid) => {
+    try {
+      process.kill(-pgid, 'SIGTERM');
+    } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+  },
+};
+
+let result;
+try {
+  if (action === 'start') {
+    if (port === null) usage('start needs --port');
+    result = startServer({ port, set: parseSet(values('set')), unset: values('unset'), command }, deps);
+  } else if (action === 'check') {
+    if (port === null) usage('check needs --port');
+    result = checkServer({ port }, deps);
+  } else if (action === 'stop') {
+    if (port === null && !argv.includes('--all')) usage('stop needs --port or --all');
+    result = stopServers({ port, all: argv.includes('--all') }, deps);
+  } else usage();
+} catch (error) {
+  usage(error.message);
+}
+(result.code === 0 ? console.log : console.error)(result.message);
+process.exit(result.code);

package/scripts/init.mjs

@@ -11,7 +11,7 @@ import { execFileSync } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { gatherFacts, readOnlyGh, WORKFLOW_FILES } from './lib/doctor.mjs';
+import { gatherFacts, readOnlyGh, vueWebFacts, WORKFLOW_FILES } from './lib/doctor.mjs';
 import { applyPlan, planInit, renderPlan, skipItems } from './lib/init.mjs';
 
 const arg = (name) => {
@@ -50,6 +50,8 @@ const facts = gatherFacts({
   repo,
 });
 
+facts.vueWeb = vueWebFacts(facts.config?.platforms ?? answers.platforms ?? {}, { tool, exists: existsSync });
+
 let admin = false;
 try {
   admin = JSON.parse(run('gh', ['api', `repos/${repo}`])).permissions?.admin === true;

package/scripts/lib/can-edit-issue.mjs

@@ -14,8 +14,11 @@ const REASON = {
   'qa-failed': 'a branch already exists and the text would no longer match what was built',
   'changes-requested': 'a branch already exists and the text would no longer match what was built',
   'needs-reviewer': 'it is built and waiting for a reviewer',
+  ship: 'its pull request is being merged',
+  // Not a state: it travels next to one, so the state decides whether the text may change.
+  urgent: 'the label asks for an early start and does not commit the issue to a build',
 };
-export const EDITABLE_LABELS = ['needs-spec'];
+export const EDITABLE_LABELS = ['needs-spec', 'urgent'];
 
 /**
  * @param {{state?: string, labels?: Array<string|{name: string}>}} issue  `gh issue view --json state,labels`

package/scripts/lib/config.mjs

@@ -20,6 +20,8 @@ export const SETTINGS = [
   { path: 'review.merger', type: 'enum', allowed: ['author', 'approver'], default: 'approver' },
   { path: 'review.autopilot', type: 'enum', allowed: ['off', 'precheck', 'verify'], default: 'off' },
   { path: 'review.allowed_origins', type: 'origin-list', default: [] },
+  // Whether the ship workflow may merge when no check ran on any commit; /relevo:ship asks the person instead.
+  { path: 'review.ship_without_ci', type: 'bool', default: false },
   { path: 'limits.built_unreviewed_per_person', type: 'int', min: 1, default: 2 },
   { path: 'limits.concurrent_agents', type: 'int', min: 1, default: 3 },
   { path: 'limits.review_sla_hours', type: 'int', min: 1, default: 8 },
@@ -29,6 +31,8 @@ export const SETTINGS = [
   { path: 'limits.run_max_cost', type: 'number', exclusiveMin: 0, required: true, default: null, requiredFor: 'claude', missing: 'unattended runs must always have a cost limit (amount in US dollars per run)', rejectedFor: 'antigravity', rejection: 'the agent has no cost limit; set limits.run_max_tokens instead, and note that the quota of the Google Cloud project that owns the key is the ceiling that really holds' },
   { path: 'limits.run_max_tokens', type: 'int', min: 1000, default: null, required: true, requiredFor: 'antigravity', missing: 'unattended runs must always have a limit, and for this agent it is a number of tokens per run', rejectedFor: 'claude', rejection: 'the run is limited by limits.run_max_cost' },
   { path: 'agent.build', type: 'enum', allowed: ['claude', 'antigravity'], default: 'claude' },
+  // The runner of every Relevo workflow: runs-on is read before any step, so init writes these labels into the files.
+  { path: 'runner.labels', type: 'label-list', default: ['ubuntu-latest'] },
   { path: 'qa.retries', type: 'int', min: 0, default: 1 },
   { path: 'qa.rules_from', type: 'path-list', default: [] },
   { path: 'skills.allow_scripts', type: 'string[]', default: [] },
@@ -79,6 +83,15 @@ function checkType(setting, value, errors) {
         errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
       }
       break;
+    case 'label-list':
+      if (!Array.isArray(value)) {
+        errors.push({ path, message: `${path} must be a list of runner labels, for example [self-hosted, Front] (got ${JSON.stringify(value)})` });
+      } else if (value.length === 0) {
+        errors.push({ path, message: `${path} needs at least one label; leave the setting out to use ubuntu-latest` });
+      } else if (value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
+      }
+      break;
     case 'path-list':
       if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
         errors.push({ path, message: `${path} must be a file name or a list of file names (got ${JSON.stringify(value)})` });
@@ -161,7 +174,12 @@ export function validateConfig(raw, { knownTargets = null, knownChecks = null }
     }
     const known = new Set(SETTINGS.filter((s) => s.path.startsWith(`${group}.`)).map((s) => s.path.split('.')[1]));
     Object.keys(value).forEach((k) => {
-      if (!known.has(k)) errors.push({ path: `${group}.${k}`, message: `unknown setting "${group}.${k}"` });
+      if (known.has(k)) return;
+      // Relevo cannot verify what a runner is, so it offers no such key: a runner is assumed to persist.
+      const message = `${group}.${k}` === 'runner.ephemeral'
+        ? 'unknown setting "runner.ephemeral": Relevo does not ask whether a runner is ephemeral, it assumes every runner persists between jobs'
+        : `unknown setting "${group}.${k}"`;
+      errors.push({ path: `${group}.${k}`, message });
     });
   });
 

package/scripts/lib/dev-server-guard.mjs

@@ -0,0 +1,49 @@
+// Which processes listen on a port and where they run from, through lsof. A review does not switch branches under a
+// dev server that runs from the working tree, because the server would lose its files.
+// Implements "Review restores the base branch upon completion" of openspec/specs/review/spec.md.
+
+import { sep } from 'node:path';
+
+/** The pids listening on a TCP port; null when lsof cannot be run. `lsof(args)` returns { status, stdout }. */
+export function listeners(port, lsof) {
+  const r = lsof(['-nP', `-tiTCP:${port}`, '-sTCP:LISTEN']);
+  if (r.status === 127) return null;
+  // lsof exits 1 with nothing printed when no process matches.
+  return String(r.stdout ?? '').split('\n').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n > 0);
+}
+
+/** The current folder of a process; null when lsof cannot tell. */
+export function cwdOf(pid, lsof) {
+  const r = lsof(['-a', '-p', String(pid), '-d', 'cwd', '-Fn']);
+  if (r.status !== 0) return null;
+  const line = String(r.stdout ?? '').split('\n').find((l) => l.startsWith('n'));
+  return line ? line.slice(1) : null;
+}
+
+/** The port of an http address, with the default of its scheme. */
+export function portOf(url) {
+  const u = new URL(url);
+  return Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+}
+
+/**
+ * May the working tree switch branches? Looks at the processes listening on the port of `url`.
+ * Returns { code, servers }: 0 none runs from the repository, 1 one does, 3 it cannot tell.
+ * deps: lsof(args) -> { status, stdout }, realpath(path) -> path.
+ */
+export function guard({ url, repoRoot }, { lsof, realpath }) {
+  const pids = listeners(portOf(url), lsof);
+  if (pids === null) return { code: 3, servers: [], reason: 'lsof is not available, so the folder of the server cannot be known' };
+  const root = realpath(repoRoot);
+  const servers = pids.map((pid) => {
+    const cwd = cwdOf(pid, lsof);
+    let real = null;
+    try {
+      real = cwd ? realpath(cwd) : null;
+    } catch { /* a folder that no longer exists is outside the repository */ }
+    return { pid, cwd, inside: real !== null && (real === root || real.startsWith(`${root}${sep}`)) };
+  });
+  if (servers.some((s) => s.inside)) return { code: 1, servers, reason: 'a server of the address under review runs from the working tree' };
+  if (servers.some((s) => s.cwd === null)) return { code: 3, servers, reason: 'the folder of a server on that port cannot be read' };
+  return { code: 0, servers, reason: null };
+}

package/scripts/lib/doctor.mjs

@@ -25,7 +25,10 @@ export const SKILL_INSTALL = {
   'supabase-postgres-best-practices': 'run `npx skills add supabase/agent-skills --skill supabase-postgres-best-practices`',
 };
 export const OPENSPEC_INSTALL = 'npm install --global @fission-ai/openspec (needs Node.js 20.19 or newer)';
-export const WORKFLOW_FILES = ['relevo-go.yml', 'relevo-queue.yml', 'relevo-review.yml', 'relevo-sla.yml', 'relevo-digest.yml'];
+export const WORKFLOW_FILES = ['relevo-go.yml', 'relevo-queue.yml', 'relevo-review.yml', 'relevo-sla.yml', 'relevo-digest.yml', 'relevo-ship.yml'];
+// The repository variable that pauses the ship workflow, and the secrets of the GitHub App it pushes with.
+export const SHIP_VARIABLE = 'RELEVO_CLOUD_SHIP';
+export const SHIP_APP_SECRETS = ['RELEVO_SHIP_APP_ID', 'RELEVO_SHIP_APP_KEY'];
 const REQUIRED_WORKFLOWS = new Set(['relevo-go.yml']);
 // How to ask a tool that it is there (most answer --version), and how to install the ones Relevo knows.
 const TOOL_PROBE = { adb: ['version'] };
@@ -70,10 +73,10 @@ export function refMatches(pattern, branch, defaultBranch) {
 
 /**
  * What the repository enforces on a branch, from its rulesets and its classic protection.
- * Returns { protected, pullRequestRequired, approvals, dismissStale, blocksDeletion, blocksForcePush }.
+ * Returns { protected, pullRequestRequired, approvals, dismissStale, lastPushApproval, requiredChecks, blocksDeletion, blocksForcePush }.
  */
 export function summarizeProtection({ rulesets = [], classic = null, branch, defaultBranch }) {
-  const out = { protected: false, pullRequestRequired: false, approvals: 0, dismissStale: false, blocksDeletion: false, blocksForcePush: false };
+  const out = { protected: false, pullRequestRequired: false, approvals: 0, dismissStale: false, lastPushApproval: false, requiredChecks: false, blocksDeletion: false, blocksForcePush: false };
   rulesets.filter((r) => r.target === 'branch' && r.enforcement === 'active').forEach((r) => {
     const include = r.conditions?.ref_name?.include ?? [];
     const exclude = r.conditions?.ref_name?.exclude ?? [];
@@ -84,7 +87,9 @@ export function summarizeProtection({ rulesets = [], classic = null, branch, def
         out.pullRequestRequired = true;
         out.approvals = Math.max(out.approvals, rule.parameters?.required_approving_review_count ?? 0);
         if (rule.parameters?.dismiss_stale_reviews_on_push) out.dismissStale = true;
+        if (rule.parameters?.require_last_push_approval) out.lastPushApproval = true;
       }
+      if (rule.type === 'required_status_checks') out.requiredChecks = true;
       if (rule.type === 'deletion') out.blocksDeletion = true;
       if (rule.type === 'non_fast_forward') out.blocksForcePush = true;
     });
@@ -96,13 +101,45 @@ export function summarizeProtection({ rulesets = [], classic = null, branch, def
       out.pullRequestRequired = true;
       out.approvals = Math.max(out.approvals, pr.required_approving_review_count ?? 0);
       if (pr.dismiss_stale_reviews) out.dismissStale = true;
+      if (pr.require_last_push_approval) out.lastPushApproval = true;
     }
+    if (classic.required_status_checks) out.requiredChecks = true;
     if (classic.allow_deletions?.enabled === false) out.blocksDeletion = true;
     if (classic.allow_force_pushes?.enabled === false) out.blocksForcePush = true;
   }
   return out;
 }
 
+// ---------- Playwright of a platform
+
+/** Is the platform a Vue platform reviewed in a browser? `web` is the only target of Vue, and its default. */
+export const isVueWeb = (platform) => platform?.stack === 'vue' && (!platform.targets?.length || platform.targets.includes('web'));
+
+/**
+ * Does Playwright resolve from the folder of a platform, and is its Chromium installed? Resolving from the folder, not
+ * from where the command runs, finds the node_modules of a platform in a subfolder. `tool(name, args)` throws when the
+ * command fails; `exists(path)`.
+ */
+export function playwrightFacts(dir, { tool, exists }) {
+  const where = "require.resolve('playwright', { paths: [require('node:path').resolve(process.argv[1])] })";
+  try {
+    tool('node', ['-e', where, dir || '.']);
+  } catch {
+    return { playwright: false, chromium: false };
+  }
+  try {
+    const path = String(tool('node', ['-e', `process.stdout.write(require(${where}).chromium.executablePath())`, dir || '.'])).trim();
+    return { playwright: true, chromium: path !== '' && Boolean(exists(path)) };
+  } catch {
+    return { playwright: true, chromium: false };
+  }
+}
+
+/** playwrightFacts of each Vue platform with a web target, by platform name. */
+export function vueWebFacts(platforms, deps) {
+  return Object.fromEntries(Object.entries(platforms ?? {}).filter(([, p]) => isVueWeb(p)).map(([name, p]) => [name, playwrightFacts(p.path, deps)]));
+}
+
 // ---------- gather
 
 /**
@@ -160,6 +197,8 @@ export function gatherFacts(p) {
   f.openspecRootTracked = tryRun(() => String(p.tool('git', ['ls-files', 'openspec'])).trim().length > 0, false);
   f.evidenceIgnored = p.exists('.gitignore') && /^\/?evidence\/?\s*$/m.test(p.read('.gitignore'));
   f.pluginDeclared = pluginDeclaration(p);
+  f.webHook = webHookDeclaration(p);
+  f.remoteSession = process.env.CLAUDE_CODE_REMOTE === 'true';
 
   // Workflows: what runs on GitHub is what is on the default branch, not what is in the working copy, so once the
   // repository is known they are read from there. `present` says whether the file is where it has to be; `local`
@@ -210,6 +249,7 @@ export function gatherFacts(p) {
     f.canApprove = tryRun(() => api(`repos/${f.repo}/actions/permissions/workflow`).can_approve_pull_request_reviews, null);
     f.secrets = tryRun(() => api(`repos/${f.repo}/actions/secrets`).secrets.map((s) => s.name));
     f.cloudVariable = tryRun(() => api(`repos/${f.repo}/actions/variables/${CLOUD_VARIABLE}`).value, null);
+    f.shipVariable = tryRun(() => api(`repos/${f.repo}/actions/variables/${SHIP_VARIABLE}`).value, null);
     // The repositories this one may depend on: can they be read, and are they private (then a token is needed)?
     f.links = (f.config?.links ?? []).map((link) => {
       const info = tryRun(() => api(`repos/${link}`), null);
@@ -286,6 +326,28 @@ export function pluginDeclaration(p) {
   }
 }
 
+// The one-line `SessionStart` hook that installs OpenSpec in a session of Claude Code on the web. It does nothing
+// outside a remote session, and nothing when `openspec` already runs; `|| true` keeps a failed install from failing the hook.
+export const WEB_HOOK_COMMAND = '[ "$CLAUDE_CODE_REMOTE" = "true" ] && ! command -v openspec >/dev/null 2>&1 && OPENSPEC_TELEMETRY=0 npm install --global @fission-ai/openspec || true';
+
+/** Does a `SessionStart` entry install OpenSpec? The package name is what is matched, so a hook written by hand counts. */
+const installsOpenspec = (entry) => (entry?.hooks ?? []).some((h) => typeof h?.command === 'string' && h.command.includes('@fission-ai/openspec'));
+
+/**
+ * Whether the committed settings file has a `SessionStart` hook that installs OpenSpec: { declared } or, when the file
+ * is not valid JSON, { unreadable: true }. A missing file is { declared: false }.
+ */
+export function webHookDeclaration(p) {
+  const path = '.claude/settings.json';
+  if (!p.exists(path)) return { declared: false };
+  try {
+    const settings = JSON.parse(p.read(path));
+    return { declared: Array.isArray(settings?.hooks?.SessionStart) && settings.hooks.SessionStart.some(installsOpenspec) };
+  } catch {
+    return { unreadable: true };
+  }
+}
+
 /** Reads a file: the plugin's own files from disk, the repository's through the probes. Null when absent. */
 function readerFor(p, tryRun) {
   const pluginRoot = p.pluginRoot ?? PLUGIN_ROOT;
@@ -363,7 +425,7 @@ function gatherPlatforms(f, p, tryRun) {
           const pubspec = p.exists(join(platform.path, 'pubspec.yaml')) ? tryRun(() => p.read(join(platform.path, 'pubspec.yaml')), '') : '';
           entry.driverDependency = /^\s*flutter_driver\s*:/m.test(pubspec ?? '');
         } else if (platform.stack === 'vue') {
-          entry.playwright = tryRun(() => Boolean(p.tool('node', ['-e', "require.resolve('playwright')"])), false);
+          entry.playwright = playwrightFacts(platform.path, { tool: p.tool, exists: p.exists }).playwright;
         }
         return entry;
       }),
@@ -532,7 +594,7 @@ function platformChecks(f) {
       if (!e.driverDependency) r.push(warn(`autopilot.${e.name}.dependency`, `platform ${e.name} does not depend on flutter_driver (dev_dependencies), which the driven review needs`, 'add flutter_driver: { sdk: flutter } under dev_dependencies in pubspec.yaml'));
       else r.push(pass(`autopilot.${e.name}.dependency`, `platform ${e.name} depends on flutter_driver`));
     } else if (e.stack === 'vue') {
-      if (!e.playwright) r.push(warn(`autopilot.${e.name}.playwright`, `review.autopilot is ${f.autopilot.mode} but Playwright cannot be resolved from this project (platform ${e.name})`, 'npm install -D playwright && npx playwright install chromium'));
+      if (!e.playwright) r.push(warn(`autopilot.${e.name}.playwright`, `review.autopilot is ${f.autopilot.mode} but Playwright cannot be resolved from this project (platform ${e.name})`, `run /relevo:init, which offers it, or \`${e.path && e.path !== '.' ? `cd ${e.path} && ` : ''}npm install -D playwright && npx playwright install chromium\` and commit package.json and the lock file`));
       else r.push(pass(`autopilot.${e.name}.playwright`, `Playwright is available for platform ${e.name}`));
     } else {
       r.push(warn(`autopilot.${e.name}.adapter`, `review.autopilot is ${f.autopilot.mode}, but a driven review of the stack ${e.stack} (platform ${e.name}) is not available`, 'set review.autopilot to off, or review that platform by hand'));
@@ -576,6 +638,7 @@ export function runChecks(f) {
   else r.push(fail('openspec.root', 'the OpenSpec root is missing or not tracked by git, so a clean checkout (and the runner) has no `openspec/`', 'run /relevo:init, then commit openspec/config.yaml and the .gitkeep files'));
   r.push(f.evidenceIgnored ? pass('evidence.ignored', 'evidence/ is ignored by git') : fail('evidence.ignored', 'evidence/ is not in .gitignore; `review` would put screenshots in git', 'add the line `evidence/` to .gitignore (or run /relevo:init)'));
   r.push(...pluginDeclaredChecks(f));
+  r.push(...webHookChecks(f));
 
   // GitHub side
   if (!f.repo || !f.ghAuth) {
@@ -602,6 +665,7 @@ export function runChecks(f) {
       else if (f.config?.review?.mode !== 'none' && p.approvals < 1) r.push(fail(`repo.protection.${key}`, `${name} requires a pull request but no approval`, `require at least 1 approving review on ${name}`));
       else r.push(pass(`repo.protection.${key}`, `${name} requires a pull request${p.approvals ? ` with ${p.approvals} approval(s)` : ''}`));
       if (p?.dismissStale) r.push(fail(`repo.dismiss-stale.${key}`, `${name} dismisses approvals when new commits are pushed; the spec archive commit pushed by \`ship\` would dismiss the approval`, `turn off "dismiss stale pull request approvals when new commits are pushed" on ${name}`));
+      if (p?.lastPushApproval) r.push(fail(`repo.last-push.${key}`, `${name} requires the most recent push to be approved by someone else; the spec archive commit pushed by \`ship\` would need a new approval`, `turn off "require approval of the most recent reviewable push" on ${name}`));
     });
   }
   if (!f.protectionUnavailable && !f.protectionError) {
@@ -637,11 +701,13 @@ export function runChecks(f) {
 
   r.push(...pluginInstallChecks(f));
   r.push(...toolchainChecks(f));
+  r.push(...runnerChecks(f));
   if (f.pluginMarketplace && f.pluginRepoPrivate === true && !f.pluginMarketplaceHasToken) {
     r.push(fail('automation.plugin-clone', `the plugin repository (${f.pluginMarketplace}) is private, so the runner cannot clone it without a credential`, 'store a read-only token as RELEVO_PLUGIN_TOKEN and use the private-repository line in relevo-go.yml'));
   }
   r.push(...linkChecks(f));
   r.push(...executionChecks(f));
+  r.push(...shipChecks(f));
   if (f.pluginRepoPrivate === true && Array.isArray(f.secrets)) {
     if (f.secrets.includes('RELEVO_PLUGIN_TOKEN')) r.push(pass('automation.plugin-secret', 'the RELEVO_PLUGIN_TOKEN secret exists for the private plugin repository'));
     else r.push(fail('automation.plugin-secret', 'the plugin repository is private and the repository has no RELEVO_PLUGIN_TOKEN secret, so the workflows fall back to the default token and fail at checkout', 'store a read-only fine-grained token that can read the plugin repository as the repository secret RELEVO_PLUGIN_TOKEN; a secret defined at organization level is not visible to this check'));
@@ -649,6 +715,27 @@ export function runChecks(f) {
   return r;
 }
 
+/**
+ * What the ship workflow needs, when it is on the default branch: the App secrets when the base branch requires checks
+ * (a push with the workflow token starts none, so the archive commit would never get them), and whether it is paused.
+ * Its label is checked with the other labels, and it needs no model credential.
+ */
+function shipChecks(f) {
+  const r = [];
+  if (!f.workflows?.['relevo-ship.yml']?.present) return r;
+  const base = f.config?.branches?.base ?? 'base';
+  if (f.protectionError || f.protectionUnavailable) return r;
+  if (f.protection?.base?.requiredChecks) {
+    if (f.secrets === null) r.push(warn('ship.app', `${base} requires status checks and the secrets could not be listed, so the ship App was not checked`, `check that ${SHIP_APP_SECRETS.join(' and ')} exist`));
+    else if (SHIP_APP_SECRETS.every((s) => f.secrets.includes(s))) r.push(pass('ship.app', `${base} requires status checks and the ship App secrets exist, so the relevo:ship label pushes with the App and the checks run on the archive commit`));
+    else r.push(fail('ship.app', `${base} requires status checks, so the relevo:ship label cannot ship here: the archive commit pushed with the workflow token would never get its checks`, `create a GitHub App for this repository and store its id and private key as ${SHIP_APP_SECRETS.join(' and ')} (docs/execution.md, "Shipping with a label"), or ship with /relevo:ship`));
+  } else {
+    r.push(pass('ship.app', `${base} requires no status checks, so the checks of the approved head carry over to the archive commit and the ship workflow needs no App`));
+  }
+  if (String(f.shipVariable ?? '').trim().toLowerCase() === 'off') r.push(warn('ship.paused', `the relevo:ship label is paused (${SHIP_VARIABLE} is off)`, `delete the repository variable ${SHIP_VARIABLE}, or set it to on, to ship with the label again`));
+  return r;
+}
+
 // The action that sets up the toolchain of a stack in the build job of the go workflow. Vue needs only Node, which the
 // job installs for Relevo itself, and a stack that is not listed here is not judged.
 const TOOLCHAIN_ACTIONS = { flutter: { action: 'subosito/flutter-action', step: 'the Flutter step' }, laravel: { action: 'shivammathur/setup-php', step: 'the Laravel step' } };
@@ -670,6 +757,38 @@ function toolchainChecks(f) {
   });
 }
 
+const HOSTED_RUNNER = ['ubuntu-latest'];
+
+/** The labels written in a `runs-on` line: `[self-hosted, Front]` or `ubuntu-latest`; null for an expression we cannot judge. */
+function parseRunsOn(value) {
+  if (value.includes('${{')) return null;
+  const inner = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value;
+  return inner.split(',').map((l) => l.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+
+/**
+ * Does every Relevo workflow run on the runner that relevo.yml names (`runner.labels`, else ubuntu-latest)? A workflow
+ * edited by hand to another runner is reported with the file, because the next copy of the template would undo it. A
+ * runner that is not GitHub's is only assumed to persist: Relevo cannot tell, and says so instead of claiming.
+ */
+function runnerChecks(f) {
+  const wanted = f.config?.runner?.labels ?? HOSTED_RUNNER;
+  const same = (a, b) => a.length === b.length && [...a].sort().every((l, i) => l === [...b].sort()[i]);
+  const r = [];
+  let judged = 0;
+  Object.entries(f.workflows ?? {}).forEach(([file, w]) => {
+    if (!w.present || typeof w.text !== 'string') return;
+    judged += 1;
+    const found = [...w.text.matchAll(/^[ \t]+runs-on:[ \t]*(.+?)[ \t]*(?:#.*)?$/gm)].map((m) => parseRunsOn(m[1])).filter((l) => l !== null);
+    const other = found.find((labels) => !same(labels, wanted));
+    if (other) r.push(fail(`automation.runner.${file}`, `${file} runs on [${other.join(', ')}] and relevo.yml says [${wanted.join(', ')}]`, same(wanted, HOSTED_RUNNER) ? `set runner.labels: [${other.join(', ')}] in relevo.yml if that is the runner you want, or restore runs-on: ubuntu-latest in ${file}` : `change runs-on in ${file} to [${wanted.join(', ')}], or change runner.labels in relevo.yml`));
+  });
+  if (r.length > 0) return r;
+  if (judged > 0) r.push(pass('automation.runner', `the Relevo workflows run on [${wanted.join(', ')}]`));
+  if (!same(wanted, HOSTED_RUNNER)) r.push(warn('automation.runner.persistence', `the runner [${wanted.join(', ')}] is not GitHub's: Relevo assumes it keeps its files between jobs, and the code the agent writes runs with the permissions of the runner's user`, 'an ephemeral runner (created for one job) or a container is the real barrier; Relevo installs its tools under the temporary folder of the job and removes what it adds, but cannot make the machine a sandbox (docs/security.md)'));
+  return r;
+}
+
 /** Does the committed settings file declare the plugin? It is a local fact, so it needs no GitHub sign-in. */
 function pluginDeclaredChecks(f) {
   const r = [];
@@ -679,6 +798,18 @@ function pluginDeclaredChecks(f) {
   return r;
 }
 
+/**
+ * Does the repository install OpenSpec in the sessions of Claude Code on the web? The hook has no use on a terminal,
+ * where OpenSpec stays installed, so it is judged only when doctor itself runs in a remote session. It warns: the
+ * project can run without it, but every new session starts without OpenSpec.
+ */
+function webHookChecks(f) {
+  if (!f.remoteSession || !f.webHook) return [];
+  if (f.webHook.unreadable) return [warn('web.openspec-hook', '.claude/settings.json is not valid JSON, so it cannot be checked whether it installs OpenSpec in web sessions', 'fix the file; /relevo:init then offers the hook')];
+  if (f.webHook.declared) return [pass('web.openspec-hook', 'the repository installs OpenSpec at the start of a web session (SessionStart hook in .claude/settings.json)')];
+  return [warn('web.openspec-hook', 'this is a web session and the repository has no SessionStart hook that installs OpenSpec, so every new session starts without it and go cannot run', `run /relevo:init to add the hook, commit .claude/settings.json, or install it now: ${OPENSPEC_INSTALL}`)];
+}
+
 /**
  * The installed plugin and what the workflows pin. A package that lost a folder cannot run; a workflow that clones
  * the plugin repository for its scripts (the layout before the package) or has no pin is told to be replaced; a pin

package/scripts/lib/extra-server.mjs

@@ -0,0 +1,84 @@
+// Dev servers the agent starts for a line that needs the app with another configuration. Each one runs in a process
+// group of its own on a port that was free, is recorded, and is the only kind of server the agent may stop.
+// Implements "Servers started by the agent are its own" and "Environment files of a reviewed app are never read" of
+// openspec/specs/review/spec.md.
+
+import { join } from 'node:path';
+import { listeners } from './dev-server-guard.mjs';
+
+export const EXIT = { refused: 1, busy: 3, envFiles: 4, noLsof: 5 };
+
+// Example files hold no values the app loads.
+const EXAMPLES = new Set(['.env.example', '.env.sample', '.env.template']);
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The environment files a dev server loads by itself, by name only: `.env` and `.env.*`, without the examples. */
+export function envFiles(names) {
+  return names.filter((n) => /^\.env(\..+)?$/.test(n) && !EXAMPLES.has(n)).sort();
+}
+
+/** The environment of the server: the current one with `set` applied and `unset` removed. */
+export function serverEnv(base, { set = {}, unset = [] }) {
+  const env = { ...base, ...set };
+  unset.forEach((n) => { delete env[n]; });
+  return env;
+}
+
+/** Parse `NAME=value` pairs of --set; throws on a bad name. */
+export function parseSet(pairs) {
+  return Object.fromEntries(pairs.map((p) => {
+    const i = p.indexOf('=');
+    const name = i === -1 ? p : p.slice(0, i);
+    if (i === -1 || !NAME_RE.test(name)) throw new Error(`--set needs NAME=value (got ${p})`);
+    return [name, p.slice(i + 1)];
+  }));
+}
+
+const fail = (code, message) => ({ code, message });
+
+/**
+ * Start a server. deps: lsof(args), listDir() -> names in the project folder, spawn(command, env, logFile) -> pgid,
+ * load() -> records, save(records), baseEnv, dir (the evidence folder, for the log).
+ */
+export function startServer({ port, set = {}, unset = [], command }, deps) {
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) return fail(2, 'the port must be a number between 1024 and 65535');
+  if (!command || command.length === 0) return fail(2, 'give the command that starts the server after --');
+  const busy = listeners(port, deps.lsof);
+  if (busy === null) return fail(EXIT.noLsof, 'lsof is not available, so a free port cannot be told apart: leave this line for the person');
+  if (busy.length > 0) return fail(EXIT.busy, `port ${port} is busy (pid ${busy.join(', ')}): choose another; the server already there is not touched`);
+  const files = envFiles(deps.listDir());
+  if (unset.length > 0 && files.length > 0) {
+    return fail(EXIT.envFiles, `a variable cannot be removed while ${files.join(', ')} exist${files.length === 1 ? 's' : ''}: the dev server loads them by itself. Pre-check this line by reading the code, or leave it for the person`);
+  }
+  const records = deps.load();
+  const log = join(deps.dir ?? 'evidence', 'servers', `${port}.log`);
+  const pgid = deps.spawn(command, serverEnv(deps.baseEnv, { set, unset }), log);
+  records.push({ port, pgid, command: command.join(' '), set: Object.keys(set), unset });
+  deps.save(records);
+  return { code: 0, message: `started on port ${port} (process group ${pgid}); log in ${log}`, pgid };
+}
+
+/**
+ * Confirm that the process listening on the port belongs to the recorded server; when it does not (the server moved
+ * to another port, or failed), stop the recorded group and forget it.
+ */
+export function checkServer({ port }, deps) {
+  const records = deps.load();
+  const record = records.find((r) => r.port === port);
+  if (!record) return fail(EXIT.refused, `no server started by this script is recorded on port ${port}`);
+  const pids = listeners(port, deps.lsof) ?? [];
+  if (pids.some((pid) => deps.pgidOf(pid) === record.pgid)) return { code: 0, message: `port ${port} is served by the recorded server` };
+  deps.kill(record.pgid);
+  deps.save(records.filter((r) => r !== record));
+  return fail(EXIT.refused, `port ${port} is not served by the server that was started (it may have moved to another port): it was stopped`);
+}
+
+/** Stop recorded servers only: one port, or all of them. A port with no record stops nothing. */
+export function stopServers({ port = null, all = false }, deps) {
+  const records = deps.load();
+  const chosen = all ? records : records.filter((r) => r.port === port);
+  if (!all && chosen.length === 0) return fail(EXIT.refused, `no server started by this script is recorded on port ${port}: nothing was stopped`);
+  chosen.forEach((r) => deps.kill(r.pgid));
+  deps.save(records.filter((r) => !chosen.includes(r)));
+  return { code: 0, message: chosen.length === 0 ? 'no server to stop' : `stopped ${chosen.map((r) => `port ${r.port}`).join(', ')}` };
+}