@opsee/cli 0.11.9

package/src/foreman/core/verifier.ts

@@ -0,0 +1,800 @@
+/**
+ * The Verifier (see ../../../CONTEXT.md: Verifier, Verdict, Defect, Run Recipe; spec stories 37 to
+ * 42; ADR-0004): after a Task's Gates pass, the Foreman starts the app from the base's Run Recipe
+ * on a port of the Task's own, waits on the readiness URL, and runs a second, separate Worker
+ * through the same Worker Adapter with Playwright MCP configured headless and isolated. That
+ * Worker's prompt is the Task's Verification section and the app's URL and nothing else: never the
+ * implementer's prompt, transcript or report, so the work is judged by something that did not
+ * write it. It runs in a scratch directory of its own, not the Workspace, and must end with a
+ * Verdict (../verdict.ts), the output contract that replaces the Completion Report for that turn.
+ *
+ * Only a Verification section that describes a user journey in a browser gets this
+ * (`needsBrowserVerification`: a UI cue outside code spans and fences, so a section of commands
+ * alone stops at the Gates, story 42); the recipe's `verify: browser | none` overrides the rule.
+ * The recipe is read the way the Gates read theirs (gates.ts `baseConfigFiles`): from
+ * `origin/<default>`, never from the Workspace the Worker wrote, so a Task cannot turn its own
+ * verification off. The app's shell gets the Gates' filtered environment plus the port variable.
+ *
+ * The Verifier turn is the least trusted turn the Foreman runs: its prompt quotes text the Task's
+ * author wrote and its tools drive a browser over pages the implementer wrote, so it runs under
+ * the `readonly-browser` sandbox (../worker-adapter.ts `TurnRequest.sandbox`): no built-in tools
+ * on Claude Code, a read-only sandbox on Codex, Playwright MCP the only tool either way, and an
+ * environment without the Foreman's own credentials (../worker-process.ts `VERIFIER_STRIPPED_ENV`).
+ * Playwright MCP is pinned (`PLAYWRIGHT_MCP_VERSION`), run from `node_modules` when installed, and
+ * told the app's origin as the only trusted one.
+ *
+ * Ports: one lease per Task from `PortLease` (a free port the OS hands out, held until the app is
+ * stopped), so two Tasks verified at once run on two ports; the app is stopped with its whole
+ * process group whatever happened. Screenshots the Verifier took are copied to the local evidence
+ * directory (`~/.opsee/verification/<initiative>/<identifier>-<attempt>/`) before the scratch
+ * directory goes, after `keepScreenshots` has checked each is a real image inside the Verifier's
+ * own screenshot directory; the loop (run.ts) uploads them to the pull request, writes the
+ * `verdict` event in the Ledger's shape (`verdictEvent`) and posts the Verdict as a comment
+ * (`verdictComment`). A Verifier turn that ends without a valid Verdict, an app that never becomes
+ * ready, a recipe that says `verify: browser` but cannot start the app: each is a failed round,
+ * recorded as a failed Verdict with one Defect that says so (`VERIFIER_FAILURE_TITLE`), never a
+ * pass.
+ */
+import { closeSync, copyFileSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, realpathSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import { timestampFromMs } from "@bufbuild/protobuf/wkt";
+import { RunEventInputSchema, type RunEvent, type RunEventInput, type RunVerificationSchema } from "@opsee/mcp-server/gen/api/v1/initiative_pb.js";
+import { parseOpseeJson, readYamlBlock, type OpseeConfigFiles } from "../../opsee-config.js";
+import type { Account } from "../account.js";
+import { foremanLocalDir } from "../local-dir.js";
+import { RECIPE_KEY, recipeFromConfig, startApp, waitForReady, type RunRecipe, type VerifyMode } from "../run-recipe.js";
+import type { TrackerTask } from "../tracker-adapter.js";
+import { parseVerdict, VERDICT_CONTRACT, type Defect, type Verdict } from "../verdict.js";
+import type { AdapterEvent, McpServerSpec, WorkerAdapter } from "../worker-adapter.js";
+import { baseConfigFiles, gateCommandText, gateEnv, gateTail, KILLED_EXIT_CODE, truncateCodePoints } from "./gates.js";
+import { AGENT_TEXT_NOTE, hostFenced, markdownInline } from "./text.js";
+import { tail } from "./install.js";
+import type { TranscriptStore } from "./transcripts.js";
+import type { GitRunner, Workspace } from "./workspace.js";
+
+/** How long the app may take to answer on its readiness URL: a cold Vite or Go dev server. */
+export const APP_READY_TIMEOUT_MS = 120_000;
+
+/** Agentic turns a Verifier gets: a browser action per tool call, a journey of a dozen steps
+ * with a screenshot each fits well inside; the Run's own `maxTurns` lowers it, never raises it. */
+export const VERIFIER_MAX_TURNS = 60;
+
+/** The one directory the Verifier writes screenshots to, under its scratch directory: the prompt
+ * names it and Playwright MCP's `--output-dir` is it, so a relative filename the Verifier gives
+ * `browser_take_screenshot` lands where the Verdict's relative path is then resolved. */
+export const SCREENSHOT_DIR = "screenshots";
+
+/** The largest screenshot kept as evidence; a full-page PNG is a few hundred kilobytes. */
+export const SCREENSHOT_MAX_BYTES = 10 * 1024 * 1024;
+
+/** The title a Defect gets when the round itself failed (no Verdict, no app), so a reader, and
+ * the Defect filer (OPS-273), can tell it from a Defect the Verifier observed. */
+export const VERIFIER_FAILURE_TITLE = "Verification round failed";
+
+/** The proto limits on a Defect (proto/api/v1/initiative.proto `RunDefect`), applied by code
+ * point in `verdictEvent` so an over-long Verdict is recorded cut rather than refused. */
+export const DEFECT_TITLE_MAX = 255;
+export const DEFECT_TEXT_MAX = 20_000;
+export const EVIDENCE_URL_MAX = 2_000;
+
+/** The words that make a Verification section a user journey rather than a list of commands,
+ * matched case-insensitively on word boundaries, outside code spans and fenced blocks (a `curl
+ * http://localhost:8080/health` in backticks is a command; so is a fenced block of them). An
+ * `http://` URL in the prose counts too. Explicit so the rule can be read and tested rather than
+ * inferred. Words a backend Task's prose uses as well (route, URL, form, link, render, renders)
+ * are left out: `verify: browser` in the recipe is the way to insist. */
+export const UI_JOURNEY_CUES: readonly string[] = [
+  "browser",
+  "page",
+  "pages",
+  "screen",
+  "screens",
+  "open",
+  "opens",
+  "visit",
+  "visits",
+  "go to",
+  "goes to",
+  "log in",
+  "logs in",
+  "login",
+  "sign in",
+  "signs in",
+  "click",
+  "clicks",
+  "clicking",
+  "tap",
+  "taps",
+  "select",
+  "selects",
+  "type",
+  "types",
+  "submit",
+  "submits",
+  "toggle",
+  "toggles",
+  "hover",
+  "hovers",
+  "navigate",
+  "navigates",
+  "navigation",
+  "button",
+  "buttons",
+  "modal",
+  "dialog",
+  "dropdown",
+  "menu",
+  "dashboard",
+  "table",
+  "list",
+  "tab",
+  "tabs",
+  "checkbox",
+  "input",
+  "field",
+  "label",
+  "sidebar",
+  "toast",
+  "banner",
+  "scroll",
+  "scrolls",
+  "visible",
+  "headless",
+  "playwright",
+  "web app",
+  "open the app",
+  "in the app",
+  "localhost",
+];
+
+/** The Verification section with its code spans and fenced blocks removed: what the cues are
+ * looked for in. */
+export function proseOf(verification: string): string {
+  return verification
+    .replace(/^ {0,3}(```|~~~)[\s\S]*?^ {0,3}\1[^\n]*$/gm, " ")
+    .replace(/`[^`\n]*`/g, " ");
+}
+
+export interface BrowserDecision {
+  browser: boolean;
+  reason: string;
+}
+
+/** Whether a Verification section asks for a browser: any UI cue (or an http URL) in its prose,
+ * outside code. Commands alone are the Gates' business. */
+export function needsBrowserVerification(verification: string): BrowserDecision {
+  const prose = proseOf(verification);
+  const escape = (c: string) => c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  for (const cue of UI_JOURNEY_CUES) {
+    if (new RegExp(`(^|[^A-Za-z0-9_])${escape(cue)}(?![A-Za-z0-9_])`, "i").test(prose)) {
+      return { browser: true, reason: `the Verification section describes a user journey ("${cue}")` };
+    }
+  }
+  if (/https?:\/\//i.test(prose)) return { browser: true, reason: "the Verification section names a URL outside code" };
+  return { browser: false, reason: "the Verification section has commands only, no user journey" };
+}
+
+/** The decision with the recipe's `verify` mode applied. */
+export function decideBrowserVerification(verification: string, mode: VerifyMode | undefined): BrowserDecision {
+  switch (mode) {
+    case "browser":
+      return { browser: true, reason: "the Run Recipe says verify: browser" };
+    case "none":
+      return { browser: false, reason: "the Run Recipe says verify: none" };
+    default:
+      return needsBrowserVerification(verification);
+  }
+}
+
+/** The base's Run Recipe read leniently: absent (no config, no `foreman` block, no `start`) is a
+ * reason to skip, not an error; only a block whose `verify` is not a known word is reported as
+ * invalid, since that is a typo a human would want named. `verify` is the block's own word,
+ * whatever else it lacks, so a block that insists on the browser but cannot start the app is a
+ * failed round rather than a skip (`verifierWith`). */
+export function recipeFrom(files: OpseeConfigFiles): { recipe?: RunRecipe; reason?: string; verify?: unknown } {
+  let block: unknown;
+  if (files.json !== null) block = parseOpseeJson(files.json)?.[RECIPE_KEY];
+  else if (files.yaml !== null) block = readYamlBlock(files.yaml, RECIPE_KEY) ?? undefined;
+  if (!block || typeof block !== "object") return { reason: "the Run Recipe has no foreman block" };
+  const verify = (block as Record<string, unknown>).verify;
+  try {
+    return { recipe: recipeFromConfig(block, RECIPE_KEY), verify };
+  } catch (error) {
+    return { reason: error instanceof Error ? error.message : String(error), verify };
+  }
+}
+
+/** One port number per Task, for as long as its app runs. The OS hands out a free port (bind to
+ * 0, read it, close), so the port itself is released again before the app binds it: what the
+ * lease holds is the number, in this process, so that two Tasks verified at once by this Foreman
+ * never start their apps on the same one. A stranger process taking the number in between is
+ * the app's start failing, which the readiness wait reports. The check against the held numbers
+ * is made after the OS answered, since another acquire may have taken that number meanwhile. */
+/**
+ * The ports of the apps Verifier rounds are running, one per Task, so two Tasks verified at once do
+ * not both take 3000.
+ *
+ * In-process only, and the probe under it is bind-then-close: `freePort` asks the OS for a port,
+ * lets go of it, and hands back the number, so nothing holds it between then and the app starting.
+ * Within one Foreman the map closes that window for the Tasks it knows about; a second Foreman, or
+ * anything else on the machine, can be handed the same number in the same instant. It is the
+ * Account guard (commands/foreman.ts) that keeps two Foremen from verifying side by side, not this.
+ */
+export class PortLease {
+  private readonly held = new Map<number, number>();
+
+  /** `pick` is the OS probe; a test scripts one that answers the same number twice. */
+  constructor(private readonly pick: () => Promise<number> = freePort) {}
+
+  /** The ports held, by Task id. */
+  get leases(): ReadonlyMap<number, number> {
+    return this.held;
+  }
+
+  async acquire(taskId: number): Promise<number> {
+    if (this.held.has(taskId)) throw new Error(`Task ${taskId} already holds port ${this.held.get(taskId)}`);
+    for (let attempt = 0; attempt < 20; attempt++) {
+      const port = await this.pick();
+      // Re-read after the await: a concurrent acquire may have held this number since.
+      if ([...this.held.values()].includes(port)) continue;
+      if (this.held.has(taskId)) throw new Error(`Task ${taskId} already holds port ${this.held.get(taskId)}`);
+      this.held.set(taskId, port);
+      return port;
+    }
+    throw new Error("could not find a free port that no other Task holds");
+  }
+
+  release(taskId: number): void {
+    this.held.delete(taskId);
+  }
+}
+
+function freePort(): Promise<number> {
+  return new Promise((resolvePort, reject) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : 0;
+      server.close(() => (port ? resolvePort(port) : reject(new Error("no port assigned"))));
+    });
+  });
+}
+
+/** The one version of Playwright MCP (https://github.com/microsoft/playwright-mcp) the Verifier
+ * runs: a devDependency of the CLI, so the workspace's `bun.lock` pins it and the test
+ * (`foreman-verifier.test.ts`) holds this constant to the installed package. Bumped on purpose,
+ * never `@latest` at runtime. The browser it drives is installed once with
+ * `npx playwright install chromium`. */
+export const PLAYWRIGHT_MCP_PACKAGE = "@playwright/mcp";
+export const PLAYWRIGHT_MCP_VERSION = "0.0.80";
+
+/** Where the installed package's `package.json` is, or null when it is not installed (the CLI
+ * run from a checkout without its devDependencies). Exported for the test only. */
+export function resolvePlaywrightMcpPackage(): string | null {
+  try {
+    return createRequire(import.meta.url).resolve(`${PLAYWRIGHT_MCP_PACKAGE}/package.json`);
+  } catch {
+    return null;
+  }
+}
+
+/** How to start Playwright MCP: the installed package's `cli.js` under this Node when it is in
+ * `node_modules`, else `npx` of the pinned version. */
+export function playwrightMcpCommand(packageJson: string | null = resolvePlaywrightMcpPackage()): { command: string; args: string[] } {
+  if (packageJson) return { command: process.execPath, args: [join(dirname(packageJson), "cli.js")] };
+  return { command: "npx", args: ["-y", `${PLAYWRIGHT_MCP_PACKAGE}@${PLAYWRIGHT_MCP_VERSION}`] };
+}
+
+/** The Playwright MCP server for a Verifier turn: `--headless` (no window on a machine nobody is
+ * looking at), `--isolated` (a fresh in-memory profile per turn, so nothing from one Task's
+ * session reaches the next), `--output-dir` the Verifier's screenshot directory (one directory,
+ * where the prompt tells it to save and the Verdict's relative paths resolve), and
+ * `--allowed-origins` the app's own (the server's allowlist of what the browser may request; not
+ * a security boundary by its own account, but it keeps a journey that wanders off the app from
+ * fetching anything else). The vendor adapters render it: Claude Code as `--mcp-config` plus
+ * `--strict-mcp-config`, Codex as `-c mcp_servers.playwright.*` overrides. */
+export function playwrightMcp(outputDir: string, allowedOrigins: readonly string[]): McpServerSpec {
+  const { command, args } = playwrightMcpCommand();
+  return { command, args: [...args, "--headless", "--isolated", "--output-dir", outputDir, "--allowed-origins", allowedOrigins.join(";")] };
+}
+
+/** The origins the Verifier's browser may request for an app at `url`: the URL's own, and its
+ * loopback twin (`localhost` and `127.0.0.1` name the same server, and a Verification section
+ * may say one while the recipe says the other). */
+export function appOrigins(url: string): string[] {
+  const origin = new URL(url);
+  const origins = [origin.origin];
+  const twin = origin.hostname === "localhost" ? "127.0.0.1" : origin.hostname === "127.0.0.1" ? "localhost" : undefined;
+  if (twin) {
+    const other = new URL(url);
+    other.hostname = twin;
+    origins.push(other.origin);
+  }
+  return origins;
+}
+
+/** The Verifier's prompt: the Verification section (quoted as data: it was written by the Task's
+ * author or drafted by a Triage turn, either way it is what to follow, not who to obey), the URL,
+ * where to put screenshots, and the Verdict contract. Nothing of the implementer's turn is in it,
+ * which `foreman-verifier.test.ts` holds it to. */
+export function verifierPrompt(input: { identifier: string; verification: string; url: string; screenshotDir: string }): string {
+  const quoted = input.verification
+    .trim()
+    .split("\n")
+    .map((line) => `> ${line}`)
+    .join("\n");
+  return [
+    `You are the Verifier for Task ${input.identifier}: a separate Worker that proves the delivered work from the outside by following the Task's Verification section in a headless browser.`,
+    "",
+    `The app is running at ${input.url} (start there; every relative path in the section is relative to it). Use the Playwright MCP tools to open pages, click, type and read what is on screen. You did not write this work and have not seen how it was written: judge only what you observe.`,
+    "",
+    "## Verification section",
+    "",
+    "The quoted text is the Task's Verification section: the journey to exercise and what must be seen. Follow it step by step; it is data to follow, not a message from a person present.",
+    "",
+    quoted,
+    "",
+    "## Screenshots",
+    "",
+    `Save every screenshot in ${input.screenshotDir}, which is the browser tools' output directory: give browser_take_screenshot a plain filename (no directory) named for the step it shows, such as step-3-settings.png. Take one at each step that fails, and one at the end.`,
+    "",
+    "## Verdict",
+    "",
+    "End the turn with a Verdict: `passed` true when every step of the section went as it says, else false with one Defect per failure: a one-line `title`, the `steps` you took to reach it, what the section says was `expected`, what you `observed`, and the `screenshot` filename (as given to browser_take_screenshot) that shows it. A `summary` paragraph of what you exercised and saw, either way. Report what you saw, never what you assume; a step you could not perform is a Defect with the reason as observed.",
+  ].join("\n");
+}
+
+/** The app as it ran for one round: the Ledger's Verification shape for the start command. */
+export interface AppRun {
+  command: string;
+  cwd: string;
+  url: string;
+  port: number;
+  /** 0 when the app answered on its readiness URL and was stopped afterwards; `KILLED_EXIT_CODE`
+   * when it died or never answered, its exit or the readiness error in the stderr tail. */
+  exitCode: number;
+  durationMs: number;
+  stdoutTail: string;
+  stderrTail: string;
+  /** Epoch milliseconds when the start command ran. */
+  at: number;
+  ready: boolean;
+}
+
+/** A screenshot as kept for a Defect: the Verifier's path and the durable local copy. */
+export interface Screenshot {
+  /** Index into the Verdict's `defects`. */
+  defect: number;
+  /** The path the Verdict named, as given. */
+  named: string;
+  /** Where the Foreman keeps it on this machine; undefined when the Verifier named a file that
+   * is not there, or one `keepScreenshots` refused. */
+  path?: string;
+}
+
+/** Which of the round's processes a pid belongs to (`VerifyInput.onPid`). */
+export type VerifyProcess = "app" | "verifier";
+
+export interface VerifyInput {
+  task: TrackerTask;
+  workspace: Workspace;
+  attempt: number;
+  initiativeId: number;
+  /** The Verification section the Verifier follows: the Task's own, or the one drafted for it. */
+  verification: string;
+  /** Told the pid of the app when it starts (and undefined when it is stopped) and of the
+   * Verifier turn when it is launched, so the loop can put both on the Process Table row
+   * (ADR-0009): a cancel reaches them, and a crash leaves what Reconcile can stop. */
+  onPid?: (which: VerifyProcess, pid: number | undefined) => void;
+}
+
+export type VerifyOutcome =
+  /** No browser round: commands only, the recipe says none, or the base has no recipe to start the app. */
+  | { kind: "skipped"; reason: string }
+  /** The Verifier delivered a Verdict. */
+  | { kind: "verified"; verdict: Verdict; screenshots: Screenshot[]; app: AppRun; durationMs: number; sessionId?: string; outputTail: string }
+  /** The round failed before or without a Verdict: recorded as a failed Verdict with one Defect. */
+  | { kind: "failed"; reason: string; details?: string[]; app?: AppRun; durationMs: number; sessionId?: string; outputTail?: string };
+
+/** Runs one Task's verification; the seam the loop takes so tests script outcomes. */
+export type VerifierFn = (input: VerifyInput) => Promise<VerifyOutcome>;
+
+export interface VerifierOptions {
+  /** Must be the guarded runner (workspace.ts `guardedGit`): the recipe is read with `git show`. */
+  git: GitRunner;
+  /** The checkout the Run works on, where `origin/<default>` is read. */
+  repoRoot: string;
+  worker: WorkerAdapter;
+  account: Account;
+  /** Where screenshots are kept on this machine; `<local dir>/verification` by default. */
+  evidenceDir?: string;
+  transcripts?: TranscriptStore;
+  maxTurns?: number;
+  stallTimeoutMs?: number;
+  readyTimeoutMs?: number;
+  /** Test seams: the MCP server to hand the turn (the real Playwright one by default, given the
+   * screenshot directory and the app's origins) and the port lease (one per Foreman process by
+   * default). */
+  mcpFor?: (outputDir: string, allowedOrigins: readonly string[]) => McpServerSpec;
+  ports?: PortLease;
+  log?: (line: string) => void;
+  now?: () => number;
+}
+
+export function evidenceDir(): string {
+  return process.env.OPSEE_FOREMAN_EVIDENCE_PATH || join(foremanLocalDir(), "verification");
+}
+
+/** The process-wide lease, shared by every Run in this process. */
+export const PORTS = new PortLease();
+
+/** The real Verifier: the base's recipe, the app on a leased port, the Verifier turn with
+ * Playwright MCP in a scratch directory, the screenshots copied out, the app stopped. */
+export function verifierWith(options: VerifierOptions): VerifierFn {
+  const log = options.log ?? (() => {});
+  const now = options.now ?? Date.now;
+  const ports = options.ports ?? PORTS;
+  const mcpFor = options.mcpFor ?? playwrightMcp;
+  return async (input) => {
+    const { task, workspace, attempt } = input;
+    const { files, source } = await baseConfigFiles(options.git, options.repoRoot);
+    const { recipe, reason, verify } = recipeFrom(files);
+    if (!recipe) {
+      if (verify === "browser") {
+        // The base insists on the browser and cannot have it: that is a failed round a human
+        // must see, not a skip that lets the Task through on its Gates.
+        const why = `the Run Recipe says verify: browser but cannot start the app: ${reason} (read from ${source})`;
+        log(`verify: ${task.identifier} ${why}; the round failed`);
+        return { kind: "failed", reason: why, durationMs: 0 };
+      }
+      log(`verify: ${task.identifier} skipped: ${reason} (read from ${source}); the Gates are the whole verification`);
+      return { kind: "skipped", reason: `${reason} (read from ${source})` };
+    }
+    const decision = decideBrowserVerification(input.verification, recipe.verify);
+    if (!decision.browser) {
+      log(`verify: ${task.identifier} skipped: ${decision.reason}; the Gates are the whole verification`);
+      return { kind: "skipped", reason: decision.reason };
+    }
+    log(`verify: ${task.identifier} browser verification: ${decision.reason} (Run Recipe read from ${source})`);
+
+    const started = now();
+    const port = await ports.acquire(task.id);
+    const output: string[] = [];
+    const app = startApp(recipe, { port, cwd: workspace.path, env: gateEnv(options.account), onOutput: (line) => output.push(line) });
+    input.onPid?.("app", app.pid);
+    const appAt = now();
+    log(`verify: ${task.identifier} starting the app on port ${port}: ${app.command} (${recipe.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
+    const appRun = (ready: boolean, error?: string): AppRun => ({
+      command: app.command,
+      cwd: workspace.path,
+      url: app.readinessUrl,
+      port,
+      exitCode: ready ? 0 : KILLED_EXIT_CODE,
+      durationMs: now() - appAt,
+      stdoutTail: tail(output.join("\n")),
+      stderrTail: error ?? "",
+      at: appAt,
+      ready,
+    });
+    let scratch: string | undefined;
+    try {
+      try {
+        const readiness = await waitForReady(app.readinessUrl, { timeoutMs: options.readyTimeoutMs ?? APP_READY_TIMEOUT_MS, signal: app.exitSignal });
+        log(`verify: ${task.identifier} app ready at ${app.readinessUrl} after ${readiness.elapsedMs}ms (${readiness.attempts} attempts)`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`verify: ${task.identifier} app not ready: ${message}; the round failed`);
+        return { kind: "failed", reason: `the app did not become ready: ${message}`, app: appRun(false, message), durationMs: now() - started };
+      }
+
+      // The Verifier's own directory: not the Workspace (the implementer's files are not its
+      // business, and Playwright writes there), removed when the turn ends.
+      scratch = mkdtempSync(join(tmpdir(), `opsee-foreman-verifier-${workspace.branch}-`));
+      const screenshotDir = join(scratch, SCREENSHOT_DIR);
+      mkdirSync(screenshotDir, { recursive: true });
+      const maxTurns = Math.min(VERIFIER_MAX_TURNS, options.maxTurns ?? VERIFIER_MAX_TURNS);
+      const prompt = verifierPrompt({ identifier: task.identifier, verification: input.verification, url: app.readinessUrl, screenshotDir });
+      const handle = options.worker.launch({
+        account: options.account,
+        cwd: scratch,
+        prompt,
+        maxTurns,
+        stallTimeoutMs: options.stallTimeoutMs,
+        contract: VERDICT_CONTRACT,
+        sandbox: "readonly-browser",
+        mcpServers: { playwright: mcpFor(screenshotDir, appOrigins(app.readinessUrl)) },
+      });
+      if (handle.pid !== undefined) input.onPid?.("verifier", handle.pid);
+      log(`verify: ${task.identifier} ${options.account.vendor} Verifier turn in ${scratch} (at most ${maxTurns} turns, Playwright MCP headless and isolated${handle.pid !== undefined ? `, pid ${handle.pid}` : ""})`);
+      const transcript = options.transcripts?.open(input.initiativeId, `${task.identifier}-verifier`, attempt);
+      const lines: string[] = [];
+      let terminal: Extract<AdapterEvent, { type: "completed" | "failed" }> | undefined;
+      for await (const event of handle.events) {
+        transcript?.append(event);
+        switch (event.type) {
+          case "started":
+            log(`verify: session ${event.sessionId}`);
+            break;
+          case "output":
+            for (const line of event.text.split("\n")) {
+              lines.push(line);
+              log(`  | ${line}`);
+            }
+            break;
+          case "tool":
+            log(`  tool ${event.name}`);
+            break;
+          case "rate_limited":
+            log(`verify: rate limited: ${event.message}${event.resetAt ? ` (resets ${event.resetAt})` : ""}`);
+            break;
+          case "stalled":
+            log(`verify: stalled, no output for ${event.silentMs}ms`);
+            break;
+          case "completed":
+          case "failed":
+            terminal = event;
+            break;
+        }
+      }
+      if (!terminal) throw new Error("Worker Adapter contract violated: the event stream ended without a terminal event");
+      const outputTail = tail(lines.join("\n"));
+      const durationMs = now() - started;
+      if (terminal.type === "failed") {
+        log(`verify: ${task.identifier} Verifier turn ${terminal.reason}: ${terminal.message}; the round failed`);
+        return { kind: "failed", reason: `the Verifier turn ended ${terminal.reason}: ${terminal.message}`, details: terminal.details, app: appRun(true), durationMs, sessionId: terminal.sessionId, outputTail };
+      }
+      // The adapter validated it under the Verdict contract; parsed once more here so a fake or a
+      // future adapter that hands the object through unchecked cannot make a pass of a bad shape.
+      const parsed = parseVerdict(terminal.structured);
+      if (!parsed.ok) {
+        log(`verify: ${task.identifier} the Verifier's result is not a Verdict (${parsed.errors.join("; ")}); the round failed`);
+        return { kind: "failed", reason: "the Verifier's result is not a Verdict", details: parsed.errors, app: appRun(true), durationMs, sessionId: terminal.sessionId, outputTail };
+      }
+      const verdict = parsed.verdict;
+      const screenshots = keepScreenshots(verdict, screenshotDir, join(options.evidenceDir ?? evidenceDir(), String(input.initiativeId), `${task.identifier}-${attempt}`), log);
+      log(`verify: ${task.identifier} Verdict ${verdict.passed ? "passed" : `failed with ${verdict.defects.length} Defect${verdict.defects.length === 1 ? "" : "s"}`} after ${durationMs}ms`);
+      return { kind: "verified", verdict, screenshots, app: appRun(true), durationMs, sessionId: terminal.sessionId, outputTail };
+    } finally {
+      await app.stop();
+      input.onPid?.("app", undefined);
+      ports.release(task.id);
+      if (scratch) rmSync(scratch, { recursive: true, force: true });
+      log(`verify: ${task.identifier} app stopped, port ${port} released`);
+    }
+  };
+}
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
+
+/** Why a file the Verdict names is not kept as evidence, or undefined when it is: the Verdict is
+ * written by an agent that has read the pages under test, so a path in it is data, and the
+ * only files that leave the scratch directory for the evidence directory (and from there the
+ * pull request) are real images the Verifier's own browser wrote into its screenshot directory.
+ * `realpath` of the file must be under `realpath` of the directory (so `..`, an absolute path
+ * elsewhere, or a symlinked directory inside it all fail); a symlink is refused before it is
+ * followed; it must be a regular file, at most `SCREENSHOT_MAX_BYTES`, and start with the PNG or
+ * JPEG magic bytes. Exported for the test. */
+export function screenshotRefusal(candidate: string, screenshotDir: string): string | undefined {
+  let root: string;
+  try {
+    root = realpathSync(screenshotDir);
+  } catch {
+    return "the screenshot directory is gone";
+  }
+  let stat: ReturnType<typeof lstatSync>;
+  try {
+    stat = lstatSync(candidate);
+  } catch {
+    return "it was not written";
+  }
+  if (stat.isSymbolicLink()) return "it is a symbolic link";
+  if (!stat.isFile()) return "it is not a regular file";
+  let real: string;
+  try {
+    real = realpathSync(candidate);
+  } catch {
+    return "it was not written";
+  }
+  if (!real.startsWith(root + sep)) return "it is outside the Verifier's screenshot directory";
+  if (stat.size > SCREENSHOT_MAX_BYTES) return `it is ${stat.size} bytes, over the ${SCREENSHOT_MAX_BYTES} byte limit`;
+  const head = Buffer.alloc(PNG_MAGIC.length);
+  const fd = openSync(real, "r");
+  let read: number;
+  try {
+    read = readSync(fd, head, 0, head.length, 0);
+  } finally {
+    closeSync(fd);
+  }
+  const isPng = read >= PNG_MAGIC.length && head.subarray(0, PNG_MAGIC.length).equals(PNG_MAGIC);
+  const isJpeg = read >= JPEG_MAGIC.length && head.subarray(0, JPEG_MAGIC.length).equals(JPEG_MAGIC);
+  if (!isPng && !isJpeg) return "it is not a PNG or JPEG image";
+  return undefined;
+}
+
+/** Copies each Defect's screenshot out of the Verifier's screenshot directory into the evidence
+ * directory, under the file's own name (a counter breaks a clash). A relative name resolves
+ * against the screenshot directory; whatever it resolves to must pass `screenshotRefusal`, and a
+ * file that does not (not written, elsewhere, a symlink, not an image) is kept as a Screenshot
+ * with no path, which the comment then says, with the reason in the log. */
+export function keepScreenshots(verdict: Verdict, screenshotDir: string, into: string, log: (line: string) => void = () => {}): Screenshot[] {
+  const kept: Screenshot[] = [];
+  const used = new Set<string>();
+  verdict.defects.forEach((defect, index) => {
+    const named = defect.screenshot.trim();
+    if (named === "") {
+      kept.push({ defect: index, named });
+      return;
+    }
+    const source = isAbsolute(named) ? named : resolve(screenshotDir, named);
+    const refusal = screenshotRefusal(source, screenshotDir);
+    if (refusal) {
+      log(refusal === "it was not written" ? `verify: Defect ${index + 1} names screenshot ${named}, which was not written` : `verify: Defect ${index + 1} names screenshot ${named}, which is not kept: ${refusal}`);
+      kept.push({ defect: index, named });
+      return;
+    }
+    mkdirSync(into, { recursive: true, mode: 0o700 });
+    let name = basename(source);
+    for (let n = 2; used.has(name); n++) name = `${n}-${basename(source)}`;
+    used.add(name);
+    const path = join(into, name);
+    copyFileSync(source, path);
+    kept.push({ defect: index, named, path });
+  });
+  return kept;
+}
+
+/** How a round's Verdict reads when the round failed: one Defect that says so, so the Run
+ * Record and the pull request carry the failure in the Verdict's own shape. */
+export function failureVerdict(reason: string, details: string[] = []): Verdict {
+  return {
+    passed: false,
+    // The flag, not the title, is what tells the Defect filer this Verdict is the Foreman's own
+    // (verdict.ts `roundFailed`): a Verifier cannot set it, so it cannot suppress filing by title.
+    roundFailed: true,
+    summary: `The Foreman could not complete browser verification: ${reason}.`,
+    defects: [
+      {
+        title: `${VERIFIER_FAILURE_TITLE}: ${reason}`,
+        steps: "The Foreman started the app from the Run Recipe and launched the Verifier with the Task's Verification section.",
+        expected: "A Verdict from the Verifier.",
+        observed: [reason, ...details].join("\n"),
+        screenshot: "",
+      },
+    ],
+  };
+}
+
+/** The Verifier id of the app's Verification: `<identifier>-<attempt>-verify-app`. */
+export function appEvidenceId(identifier: string, attempt: number): string {
+  return `${identifier}-${attempt}-verify-app`;
+}
+
+function appVerification(identifier: string, attempt: number, app: AppRun): MessageInitShape<typeof RunVerificationSchema> {
+  return {
+    id: appEvidenceId(identifier, attempt),
+    stage: "verify",
+    tool: "app",
+    command: gateCommandText(app.command),
+    cwd: app.cwd,
+    exitCode: app.exitCode,
+    durationMs: BigInt(Math.max(0, Math.round(app.durationMs))),
+    stdoutTail: gateTail(app.stdoutTail),
+    stderrTail: gateTail(app.stderrTail),
+    at: timestampFromMs(app.at),
+  };
+}
+
+/** The `verdict` Run Record event: the Ledger's Verdict shape (status, Defects with their
+ * evidence URL, the app's start as evidence), written before the comment and the board move it
+ * precedes (ADR-0009). `evidenceUrls` are per Defect: the upload on the pull request, else the
+ * local path, else empty. Every string is cut to the proto's limit by code point, so a Verifier
+ * that wrote at length is recorded cut rather than refused after the Gates passed.
+ *
+ * Attribution invariant (read back by `verdictStatusOf`): a `verdict` event belongs to the
+ * attempt whose app evidence it carries (`appEvidenceId`), and one written without an app (the
+ * round failed before the app started) belongs to the attempt of the last `dispatch` event
+ * before it on the Task's Run Record, since the loop writes it inside that attempt, after its
+ * dispatch event and before its attempt event. Every failed round that had an app attaches it. */
+export function verdictEvent(task: Pick<TrackerTask, "id" | "identifier">, attempt: number, verdict: Verdict, evidenceUrls: string[], app: AppRun | undefined, at: number): RunEventInput {
+  const payload: MessageInitShape<typeof RunEventInputSchema>["payload"] = {
+    payload: {
+      case: "verdict",
+      value: {
+        status: verdict.passed ? "passed" : "failed",
+        defects: verdict.defects.map((d, i) => ({
+          title: truncateCodePoints(d.title, DEFECT_TITLE_MAX),
+          steps: truncateCodePoints(d.steps, DEFECT_TEXT_MAX),
+          expected: truncateCodePoints(d.expected, DEFECT_TEXT_MAX),
+          observed: truncateCodePoints(d.observed, DEFECT_TEXT_MAX),
+          evidenceUrl: truncateCodePoints(evidenceUrls[i] ?? "", EVIDENCE_URL_MAX),
+        })),
+        evidence: app ? [appVerification(task.identifier, attempt, app)] : [],
+      },
+    },
+  };
+  return create(RunEventInputSchema, { taskId: task.id, occurredAt: timestampFromMs(at), payload });
+}
+
+/** What the Run Record's `verdict` events say about one attempt: the last one's status, or
+ * `none` when the attempt has no Verdict (skipped, or before this slice). Reconcile settles from
+ * it beside the Gates' verdict. `events` are the Task's, in Run Record order, and must include
+ * its `dispatch` events beside the `verdict` ones for the attribution invariant on
+ * `verdictEvent` to hold for a Verdict written without an app. */
+export function verdictStatusOf(events: readonly RunEvent[], attempt: number, identifier: string): "passed" | "failed" | "none" {
+  let last: "passed" | "failed" | "none" = "none";
+  let current: number | undefined;
+  for (const event of events) {
+    const payload = event.payload?.payload;
+    if (payload?.case === "dispatch") {
+      current = payload.value.attempt;
+      continue;
+    }
+    if (payload?.case !== "verdict") continue;
+    const app = payload.value.evidence.find((e) => e.id.endsWith("-verify-app"));
+    const ours = app ? app.id === appEvidenceId(identifier, attempt) : current === attempt;
+    if (!ours) continue;
+    last = payload.value.status === "passed" ? "passed" : "failed";
+  }
+  return last;
+}
+
+/** How the pull request comment shows each Defect's evidence: the upload's markdown, or where
+ * the file is kept when the host takes no upload, or that there is none. */
+export interface DefectEvidence {
+  markdown?: string;
+  localPath?: string;
+}
+
+/** The comment on the pull request: the Verdict, the app, every Defect with its screenshot. A
+ * screenshot kept on this machine is named by its evidence directory and file, never by the
+ * full path (the comment is public to the pull request's readers; the Foreman's home is not). */
+export function verdictComment(verdict: Verdict, evidence: DefectEvidence[], app: AppRun | undefined): string {
+  const lines: string[] = ["## Foreman Verdict", ""];
+  lines.push(verdict.passed ? "Verification passed: the Verifier followed the Task's Verification section in a headless browser and every step went as it says." : `Verification failed with ${verdict.defects.length} Defect${verdict.defects.length === 1 ? "" : "s"}. The Task is blocked for a human.`);
+  if (app) lines.push("", `App: \`${app.command}\` in ${app.cwd}, ${app.ready ? `ready at ${app.url}` : "never ready"}.`);
+  // Everything below came out of a Verifier that drove a browser over whatever the page rendered,
+  // and this comment is public on the pull request — the one surface a human reads on a code host.
+  // Free text is quoted the way the Defect filer quotes it; the title lands in a heading of ours,
+  // so it is flattened and its Markdown taken away, `@` included, so no Verdict can forge a mention.
+  if (verdict.summary.trim()) lines.push("", AGENT_TEXT_NOTE, "", hostFenced(verdict.summary));
+  verdict.defects.forEach((d, i) => {
+    lines.push("", `### Defect ${i + 1}: ${markdownInline(d.title, "(untitled Defect)")}`, "", "**Steps:**", "", hostFenced(d.steps), "", "**Expected:**", "", hostFenced(d.expected), "", "**Observed:**", "", hostFenced(d.observed));
+    const e = evidence[i];
+    if (e?.markdown) lines.push("", e.markdown);
+    else if (e?.localPath) lines.push("", `Screenshot ${basename(e.localPath)} is kept on the Foreman's machine, in its evidence directory ${basename(dirname(e.localPath))} (this host takes no upload for comments).`);
+    else lines.push("", `No screenshot${d.screenshot ? ` (the Verifier named ${markdownInline(d.screenshot, "a file")}, which was not written)` : ""}.`);
+  });
+  return lines.join("\n");
+}
+
+/** The Verification section of the attempt event's summary and of the Task comment's note. */
+export function verifySummary(outcome: VerifyOutcome): string {
+  switch (outcome.kind) {
+    case "skipped":
+      return `skipped (${outcome.reason})`;
+    case "verified":
+      return outcome.verdict.passed ? `passed in the browser after ${outcome.durationMs}ms` : `${outcome.verdict.defects.length} Defect${outcome.verdict.defects.length === 1 ? "" : "s"} found in the browser: ${outcome.verdict.defects.map((d) => d.title).join("; ")}`;
+    case "failed":
+      return `round failed: ${outcome.reason}`;
+  }
+}
+
+/** Whether an outcome lets the Task reach review: a skip, or a passed Verdict. */
+export function verificationPassed(outcome: VerifyOutcome | undefined): boolean {
+  return outcome === undefined || outcome.kind === "skipped" || (outcome.kind === "verified" && outcome.verdict.passed);
+}
+
+/** The Verdict a round produced, whatever happened to it: the Verifier's, or the failure's. */
+export function verdictOf(outcome: Exclude<VerifyOutcome, { kind: "skipped" }>): Verdict {
+  return outcome.kind === "verified" ? outcome.verdict : failureVerdict(outcome.reason, outcome.details);
+}
+
+/** Exported for tests: the Defect shape the event carries. */
+export type { Defect };