muse-crew 0.7.9 → 0.7.11

package/lib/crew-api.js

@@ -16,13 +16,14 @@
 //   create-project, update-project, delete-project, list-projects,
 //   get-project, kill-switch, get-config, update-config,
 //   set-provenance, get-provenance, acknowledge-poll,
+//   scan-verification-pending, resolve-publish-unknown,
 //   record-phase (composite), migrate (one-time import)
 //
 // Output is JSON on stdout. Errors are JSON on stderr.
 // Exit codes: 0 ok · 2 usage/validation · 3 not found · 4 conflict/guard.
 
-import { readFileSync, existsSync, statSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { readFileSync, existsSync, statSync, readlinkSync, readdirSync, appendFileSync } from "node:fs";
+import { join, resolve, sep, basename } from "node:path";
 import { randomUUID } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
 import { homedir } from "node:os";
@@ -1063,6 +1064,284 @@ commands["get-events"] = (db, args) => {
   return { events: rows.map(mapEvent) };
 };
 
+// Parent publish verification: scan + atomic claim + reconcile.
+//
+// Finds parked tasks whose latest parent publish note is
+// "publish: verification-requested" (the publisher parks instead of
+// stamping, per docs/publish-verification.md) with no terminal parent
+// verdict and no unexpired verification claim. Each returned task is
+// ATOMICALLY claimed by logging a "publish: verification-claimed"
+// note-event with a lease expiry, so two concurrent scanners (or a
+// retrying tick) cannot start a second verification for the same task.
+// The claim is a note, not a state change: the task stays parked, so the
+// dispatcher never dispatches QA mid-verification.
+//
+// Also reconciles the verified-but-still-parked gap: a parked task whose
+// latest parent verdict is "publish: verified" is re-queued to in_progress
+// (the verdict was recorded but the re-queue was lost to a crash).
+// Failure verdicts are left parked for human attention (fail-closed).
+//
+// Returns { to_verify: [...], reconciled: [...] }.
+// Each to_verify entry: { task_id, commit, build_agent_id, project_id,
+// repo_path, deploy_slug, crew_release, claim_expires_at }.
+//
+// crew_release is resolved through the crew home's `current` symlink (the
+// immutable active release the release manager maintains) and cross-checked
+// against this code's own realpath (the release it is actually running
+// from). Unresolvable or disputed => throw fail-closed BEFORE the claim
+// transaction: provenance is never stamped with an unknown release.
+function resolveActiveRelease(crewHome) {
+  let linkTarget;
+  try {
+    linkTarget = readlinkSync(join(crewHome, "current"));
+  } catch (e) {
+    throw usageError(
+      `scan-verification-pending: cannot resolve the active release: ${join(crewHome, "current")} is not a readable symlink (${e.message}). Refusing to verify.`
+    );
+  }
+  const activeRelease = basename(resolve(crewHome, linkTarget));
+  const selfPath = new URL(import.meta.url).pathname;
+  const selfMatch = selfPath.match(/releases\/([^/]+)\/lib\/crew-api\.js$/);
+  if (!selfMatch) {
+    throw usageError(
+      `scan-verification-pending: running code is not inside a releases/<name>/lib path (${selfPath}). Refusing to verify.`
+    );
+  }
+  if (selfMatch[1] !== activeRelease) {
+    throw usageError(
+      `scan-verification-pending: running release ${selfMatch[1]} != active release ${activeRelease} (stale cron body or mid-deploy). Refusing to verify.`
+    );
+  }
+  return activeRelease;
+}
+commands["scan-verification-pending"] = (db, args, ctx) => {
+  const CLAIM_LEASE_MS = 60 * 60 * 1000; // 1 hour
+  const nowMs = Date.now();
+  const claimExpiry = new Date(nowMs + CLAIM_LEASE_MS).toISOString();
+  const releaseName = resolveActiveRelease(ctx.crewHome);
+
+  const parked = db.prepare(
+    `SELECT t.id AS task_id, t.project AS project_id,
+            p.repo_path AS repo_path, p.deploy_slug AS deploy_slug
+     FROM tasks t LEFT JOIN projects p ON p.id = t.project
+     WHERE t.state = 'parked'`
+  ).all();
+
+  const toVerify = [];
+  const reconciled = [];
+
+  db.exec("BEGIN");
+  try {
+    for (const row of parked) {
+      const notes = db.prepare(
+        `SELECT message, timestamp FROM events
+         WHERE task_id = ? AND type = 'note' AND message LIKE '%publish:%'
+         ORDER BY timestamp DESC LIMIT 20`
+      ).all(row.task_id);
+      if (notes.length === 0) continue;
+      const latest = notes[0].message;
+
+      // Reconcile first: verdict recorded but the re-queue was lost to a
+      // crash (verified-but-still-parked). Failure verdicts stay parked.
+      // Contained-string matching: the workflow's parkTask prepends
+      // "Parked: " to the reason, so a verification request is stored as
+      // "Parked: publish: verification-requested ..." (observed 2026-09-14).
+      // Prefix anchors would never match; see tests/verify-publish.test.js.
+      if (latest.includes("publish: verified")) {
+        db.prepare("UPDATE tasks SET state = 'in_progress', updated_at = ? WHERE id = ?")
+          .run(now(), row.task_id);
+        db.prepare(
+          `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+           VALUES (?, 'note', ?, NULL, ?, ?)`
+        ).run(uuid(), row.task_id,
+          "publish: reconciled verified-but-parked -> in_progress (re-queue lost to a crash)",
+          now());
+        reconciled.push({ task_id: row.task_id });
+        continue;
+      }
+
+      // Terminal parent verdicts (anything the parent decided, except a
+      // fresh request, a procedural error, or an active claim) — never re-verify.
+      const isRequest = latest.includes("publish: verification-requested");
+      const isClaim = latest.includes("publish: verification-claimed");
+      // Procedural errors (worker botched the procedure, not a content
+      // failure) are retryable — treat like a fresh request. Content
+      // failures (verification-failed) stay terminal.
+      const isProceduralError = latest.includes("publish: verification-procedural-error");
+      if (!isRequest && !isClaim && !isProceduralError) continue; // failed / blocked / mismatch: terminal, fail-closed
+
+      if (isClaim) {
+        // Unexpired claim -> another verifier owns it. Expired -> re-claim below.
+        const m = latest.match(/publish: verification-claimed (\S+)/);
+        if (m && Date.parse(m[1]) > nowMs) continue;
+      }
+
+      // Candidate: find the original verification-requested note to extract
+      // the commit and build agent id (the latest note may be an expired claim
+      // or a procedural error).
+      const req = notes.find((n) => n.message.includes("publish: verification-requested"));
+      if (!req) continue;
+      const commitMatch = req.message.match(/verification-requested ([0-9a-f]{40})/);
+      // Fallback: procedural error note carries the commit too.
+      const procMatch = !commitMatch ? latest.match(/verification-procedural-error ([0-9a-f]{40})/) : null;
+      const commit = commitMatch ? commitMatch[1] : (procMatch ? procMatch[1] : null);
+      const buildMatch = req.message.match(/\(build ([0-9a-f-]{36})\)/);
+      if (!commit) continue; // malformed request: cannot verify mechanically, leave parked
+      db.prepare(
+        `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+         VALUES (?, 'note', ?, NULL, ?, ?)`
+      ).run(uuid(), row.task_id, `publish: verification-claimed ${claimExpiry}`, now());
+      toVerify.push({
+        task_id: row.task_id,
+        commit: commit,
+        build_agent_id: buildMatch ? buildMatch[1] : null,
+        project_id: row.project_id,
+        repo_path: row.repo_path,
+        deploy_slug: row.deploy_slug,
+        crew_release: releaseName,
+        claim_expires_at: claimExpiry,
+      });
+    }
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  return { to_verify: toVerify, reconciled };
+};
+
+// Recovery contract for publish attempts parked with an UNKNOWN outcome
+// (2026-09-14). The structured-output fallback parked the task because no
+// build could be observed — but the edit may still have gone through (the
+// in-flight-only fallback could not see a completed build; fixed
+// in-workflow the same day with the durable audit-dir check). When durable
+// evidence later shows the build DID complete — a platform audit directory
+// created inside the publish window (between Integrate completion and the
+// park event) — this action routes the task to the parent's independent
+// content verification WITHOUT re-issuing the edit and WITHOUT stamping
+// provenance. The original unknown ledger entry and park event are
+// preserved; the resolution is appended to the ledger and the event log.
+// The parent's read-back (docs/publish-verification.md) remains the real
+// verification and can still fail terminally. Never: blind retry, manual
+// stamp, silent state change.
+commands["resolve-publish-unknown"] = (db, args, ctx) => {
+  const taskId = args.task_id;
+  if (!taskId) throw usageError("task_id is required.");
+  requireTask(db, taskId);
+  const task = db.prepare("SELECT id, state, project FROM tasks WHERE id = ?").get(taskId);
+  if (task.state !== "parked") {
+    return { resolved: false, reason: `task is not parked (state=${task.state})` };
+  }
+  const project = db.prepare("SELECT deploy_slug FROM projects WHERE id = ?").get(task.project);
+  const slug = project && project.deploy_slug;
+  if (!slug) return { resolved: false, reason: "project has no deploy_slug" };
+
+  // The latest publish ledger entry for this task must be outcome "unknown".
+  const ledgerPath = join(ctx.crewHome, ".publish-ledger", slug + ".jsonl");
+  let entries = [];
+  try {
+    entries = readFileSync(ledgerPath, "utf8").split("\n")
+      .filter((l) => l.trim().length > 0)
+      .map((l) => JSON.parse(l))
+      .filter((e) => e.task_id === taskId);
+  } catch (e) {
+    return { resolved: false, reason: `cannot read publish ledger: ${e.message}` };
+  }
+  if (entries.length === 0) return { resolved: false, reason: "no publish ledger entries for this task" };
+  const latest = entries[entries.length - 1];
+  if (latest.outcome === "unknown-resolved") {
+    return { resolved: false, reason: "already resolved (unknown-resolved ledger entry present)" };
+  }
+  if (latest.outcome !== "unknown") {
+    return { resolved: false, reason: `latest ledger outcome is '${latest.outcome}', not unknown` };
+  }
+  if (!latest.commit || !/^[0-9a-f]{40}$/.test(latest.commit)) {
+    return { resolved: false, reason: "unknown ledger entry carries no usable commit hash" };
+  }
+
+  // The publish window: Integrate completion -> the unknown-outcome park.
+  // Nothing else touches the artifact during Publish, so an audit dir
+  // created inside this window belongs to this publish attempt.
+  const events = db.prepare(
+    "SELECT type, message, timestamp FROM events WHERE task_id = ? ORDER BY timestamp ASC"
+  ).all(taskId);
+  const integrateDone = [...events].reverse().find((e) =>
+    e.type === "completed" && /integrate completed/i.test(e.message || ""));
+  const parkEvent = [...events].reverse().find((e) =>
+    e.type === "note" && (e.message || "").includes("Publish outcome unknown"));
+  if (!integrateDone || !parkEvent) {
+    return { resolved: false, reason: "cannot determine publish window (missing integrate-completion or unknown-outcome park event)" };
+  }
+  const winStart = Date.parse(integrateDone.timestamp);
+  const winEnd = Date.parse(parkEvent.timestamp);
+  if (!(winStart < winEnd)) {
+    return { resolved: false, reason: "publish window is empty or inverted" };
+  }
+
+  // Audit dirs are named <UTC-timestamp>-<id>; the timestamp is the build's.
+  const auditsDir = join(homedir(), "workspace", "ts-spaces", slug, "audits");
+  let evidenceDirs = [];
+  try {
+    evidenceDirs = readdirSync(auditsDir).filter((name) => {
+      const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})Z-/.exec(name);
+      if (!m) return false;
+      const t = Date.parse(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`);
+      return t > winStart && t <= winEnd;
+    }).sort();
+  } catch (e) {
+    return { resolved: false, reason: `cannot list audit dirs: ${e.message}` };
+  }
+  if (evidenceDirs.length === 0) {
+    return { resolved: false, reason: "no audit build completed inside the publish window — still unknown" };
+  }
+  const evidenceDir = evidenceDirs[0];
+
+  // Corroboration, observation only: the audit harness's own verdict.
+  let auditOk = null;
+  try {
+    auditOk = JSON.parse(readFileSync(join(auditsDir, evidenceDir, "report.json"), "utf8")).ok === true;
+  } catch (e) { auditOk = null; }
+
+  const ts = now();
+  // The verification-requested note must sort strictly after the
+  // unknown-resolved note: scan-verification-pending reads the LATEST
+  // publish: note, and equal timestamps would leave the order undefined.
+  const tsLater = new Date(Date.parse(ts) + 1000).toISOString();
+  db.exec("BEGIN");
+  try {
+    db.prepare(
+      "INSERT INTO events (id, type, task_id, identity, message, timestamp) VALUES (?, 'note', ?, NULL, ?, ?)"
+    ).run(uuid(), taskId,
+      `publish: unknown-resolved ${latest.commit} (audit ${evidenceDir}, report ok=${auditOk}) — durable build evidence inside the publish window; routing to parent content verification. No re-trigger issued, no provenance stamped, original unknown outcome preserved.`,
+      ts);
+    // Mirror the workflow's verification-requested park note so
+    // scan-verification-pending claims it on the next tick.
+    db.prepare(
+      "INSERT INTO events (id, type, task_id, identity, message, timestamp) VALUES (?, 'note', ?, NULL, ?, ?)"
+    ).run(uuid(), taskId,
+      `Parked: publish: verification-requested ${latest.commit} (build agent_id unobserved) — recovered from publish-unknown via resolve-publish-unknown; durable evidence ${evidenceDir}. Parent: run docs/publish-verification.md.`,
+      tsLater);
+    db.prepare("UPDATE tasks SET state = 'parked', updated_at = ? WHERE id = ?").run(tsLater, taskId);
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+
+  // Append-only audit trail: the resolution lands in the ledger next to the
+  // original unknown entry (which is never rewritten).
+  try {
+    appendFileSync(ledgerPath, JSON.stringify({
+      ts: new Date(ts).toISOString(),
+      task_id: taskId,
+      workflow: latest.workflow || "unknown",
+      slug,
+      commit: latest.commit,
+      attempt: latest.attempt,
+      agent_id: null,
+      applied_report: null,
+      outcome: "unknown-resolved",
+      detail: `durable build evidence ${evidenceDir} (audit report ok=${auditOk}) inside publish window; routed to parent verification without re-trigger`,
+    }) + "\n");
+  } catch (e) { /* best-effort observability */ }
+
+  return { resolved: true, task_id: taskId, commit: latest.commit, evidence_dir: evidenceDir, audit_report_ok: auditOk };
+};
+
 // Composite: record a phase's session verdict AND its event in one
 // transaction. This is the operation that used to crash the workflow when the
 // two writes went to different contracts: the session stored, the event

package/lib/edit-image.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""edit-image.py — deterministic image editing for experiential evidence.
+
+The see-act driver captures full frames; this tool derives closer looks
+from them without a browser: crop a region, zoom into a point, caption a
+frame, or compose an n-up grid. Pillow only — no network, no randomness,
+no timestamps; same inputs always produce byte-identical outputs.
+
+Usage:
+  python3 edit-image.py crop  --in <png> --out <png> --region x,y,w,h
+  python3 edit-image.py zoom  --in <png> --out <png> --factor <f> [--center x,y]
+  python3 edit-image.py label --in <png> --out <png> --text <caption>
+  python3 edit-image.py nup   --out <png> --cols <n> --in <png> [--in <png> ...]
+                              [--labels "first|second|third"]
+
+  crop:  extract the pixel region (x, y, width, height). Out of bounds -> error.
+  zoom:  crop a (w/f, h/f) box centered at --center (default: image center),
+         then scale it back up to the original frame size with NEAREST
+         (pixel-crisp, so wrapped text vs single-line text stays unambiguous).
+  label: append a caption bar under the image with --text.
+  nup:   arrange --in frames left-to-right, top-to-bottom in --cols columns;
+         cells are padded to the largest frame; --labels are drawn as caption
+         bars, one per frame, in order (| separated).
+
+Stdout is one JSON line: {"ok": true, "out": <path>, "size": [w, h]}.
+Errors print {"ok": false, "error": <msg>} and exit 2.
+
+Every derived frame is evidence: the caller must log it (append-ooda-step.js
+--action crop|zoom|label|nup) — a frame produced but not logged is not evidence.
+"""
+
+import json
+import sys
+
+try:
+    from PIL import Image, ImageDraw, ImageFont
+except ImportError:
+    Image = None
+
+CAPTION_PX = 30
+CAPTION_BG = (24, 24, 24)
+CAPTION_FG = (245, 245, 245)
+GRID_BG = (240, 240, 240)
+GRID_GAP = 8
+
+
+def fail(msg):
+    sys.stdout.write(json.dumps({"ok": False, "error": msg}) + "\n")
+    sys.exit(2)
+
+
+def parse_pair(text, name):
+    try:
+        x, y = text.split(",")
+        return int(x), int(y)
+    except Exception:
+        fail("--%s must be x,y in pixels, got: %s" % (name, text))
+
+
+def parse_region(text):
+    try:
+        x, y, w, h = text.split(",")
+        x, y, w, h = int(x), int(y), int(w), int(h)
+    except Exception:
+        fail("--region must be x,y,w,h in pixels, got: " + text)
+    if w < 1 or h < 1:
+        fail("--region width and height must be positive, got: " + text)
+    return x, y, w, h
+
+
+def load(path):
+    try:
+        return Image.open(path).convert("RGB")
+    except Exception as e:
+        fail("cannot read input " + path + ": " + str(e))
+
+
+def save(img, path):
+    try:
+        img.save(path, format="PNG")
+    except Exception as e:
+        fail("cannot write output " + path + ": " + str(e))
+    sys.stdout.write(json.dumps({"ok": True, "out": path, "size": [img.width, img.height]}) + "\n")
+
+
+def cmd_crop(args):
+    x, y, w, h = parse_region(args.region)
+    img = load(args.in_path)
+    if x < 0 or y < 0 or x + w > img.width or y + h > img.height:
+        fail("region %s is outside the %dx%d frame" % (args.region, img.width, img.height))
+    save(img.crop((x, y, x + w, y + h)), args.out)
+
+
+def cmd_zoom(args):
+    try:
+        f = float(args.factor)
+    except Exception:
+        fail("--factor must be a number, got: " + args.factor)
+    if f < 1.01:
+        fail("--factor must be > 1, got: " + args.factor)
+    img = load(args.in_path)
+    cx, cy = parse_pair(args.center, "center") if args.center else (img.width // 2, img.height // 2)
+    bw, bh = int(img.width / f), int(img.height / f)
+    if bw < 1 or bh < 1:
+        fail("--factor %s is too large for a %dx%d frame" % (args.factor, img.width, img.height))
+    x, y = cx - bw // 2, cy - bh // 2
+    if x < 0 or y < 0 or x + bw > img.width or y + bh > img.height:
+        fail("zoom box (%d,%d %dx%d) is outside the %dx%d frame" % (x, y, bw, bh, img.width, img.height))
+    box = img.crop((x, y, x + bw, y + bh))
+    # NEAREST keeps source pixels crisp — a zoom for inspection must not blur
+    # the very pixels (wrapped vs single-line text) under judgment.
+    save(box.resize((img.width, img.height), Image.NEAREST), args.out)
+
+
+def caption_bar(img, text):
+    bar = Image.new("RGB", (img.width, CAPTION_PX), CAPTION_BG)
+    draw = ImageDraw.Draw(bar)
+    font = ImageFont.load_default()
+    draw.text((8, 8), text, font=font, fill=CAPTION_FG)
+    canvas = Image.new("RGB", (img.width, img.height + CAPTION_PX), GRID_BG)
+    canvas.paste(img, (0, 0))
+    canvas.paste(bar, (0, img.height))
+    return canvas
+
+
+def cmd_label(args):
+    if not args.text:
+        fail("--text must not be empty")
+    save(caption_bar(load(args.in_path), args.text), args.out)
+
+
+def cmd_nup(args):
+    if not args.ins:
+        fail("nup needs at least one --in <png>")
+    try:
+        cols = int(args.cols)
+    except Exception:
+        fail("--cols must be a positive integer, got: " + args.cols)
+    if cols < 1:
+        fail("--cols must be a positive integer, got: " + args.cols)
+    labels = args.labels.split("|") if args.labels else []
+    if labels and len(labels) != len(args.ins):
+        fail("--labels has %d entries for %d inputs" % (len(labels), len(args.ins)))
+    frames = [load(p) for p in args.ins]
+    if labels:
+        frames = [caption_bar(fr, tx) for fr, tx in zip(frames, labels)]
+    cw, ch = max(fr.width for fr in frames), max(fr.height for fr in frames)
+    rows = (len(frames) + cols - 1) // cols
+    canvas = Image.new(
+        "RGB",
+        (cols * cw + (cols - 1) * GRID_GAP, rows * ch + (rows - 1) * GRID_GAP),
+        GRID_BG,
+    )
+    for i, fr in enumerate(frames):
+        r, c = divmod(i, cols)
+        ox = c * (cw + GRID_GAP) + (cw - fr.width) // 2
+        oy = r * (ch + GRID_GAP) + (ch - fr.height) // 2
+        canvas.paste(fr, (ox, oy))
+    save(canvas, args.out)
+
+
+def main():
+    if Image is None:
+        fail("Pillow (PIL) is required but not installed")
+    if len(sys.argv) < 2:
+        fail("usage: edit-image.py <crop|zoom|label|nup> [flags]")
+    cmd = sys.argv[1]
+    rest = sys.argv[2:]
+
+    # Minimal flag parser (no argparse: keep the tool dependency-free and the
+    # surface identical to the other lib scripts).
+    flags = {"in": [], "labels": None, "text": None, "region": None,
+             "factor": None, "center": None, "cols": None, "out": None}
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a == "--in":
+            i += 1
+            flags["in"].append(rest[i])
+        elif a in ("--out", "--region", "--factor", "--center", "--cols", "--text", "--labels"):
+            i += 1
+            flags[a[2:]] = rest[i]
+        else:
+            fail("unknown flag: " + a)
+        i += 1
+
+    class Args:  # noqa: too few public methods — simple namespace
+        pass
+    args = Args()
+    args.in_path = flags["in"][0] if flags["in"] else None
+    args.ins = flags["in"]
+    args.out = flags["out"]
+    args.region = flags["region"]
+    args.factor = flags["factor"]
+    args.center = flags["center"]
+    args.cols = flags["cols"]
+    args.text = flags["text"]
+    args.labels = flags["labels"]
+
+    if cmd in ("crop", "zoom", "label"):
+        if not args.in_path:
+            fail(cmd + " needs --in <png>")
+        if not args.out:
+            fail(cmd + " needs --out <png>")
+    if cmd == "crop" and not args.region:
+        fail("crop needs --region x,y,w,h")
+    if cmd == "zoom" and not args.factor:
+        fail("zoom needs --factor <f>")
+    if cmd == "nup" and not args.out:
+        fail("nup needs --out <png>")
+
+    {"crop": cmd_crop, "zoom": cmd_zoom, "label": cmd_label, "nup": cmd_nup}.get(cmd, lambda a: fail("unknown command: " + cmd))(args)
+
+
+if __name__ == "__main__":
+    main()

package/lib/render-html.js

@@ -0,0 +1,142 @@
+// render-html.js — render an HTML evidence layout to PNG via headless Chromium.
+//
+// The reef-qa pattern (2026-09-14): the agent composes evidence as HTML —
+// before/after pairs, annotated callouts, n-up grids with real typography —
+// and renders it with the same Chromium the see-act driver uses. Pillow
+// covers pixel ops (crop/zoom); HTML covers composition. This tool is the
+// deterministic renderer: fixed viewport width, system fonts only, hermetic.
+//
+// Usage:
+//   node render-html.js --in <page.html> --out <shot.png> [--width <px>]
+//
+// The HTML references images by relative path (resolved against the HTML
+// file's directory) or file:// URL. No http(s) subresources: the render is
+// hermetic, so any http(s) request is aborted and the render fails loudly
+// (exit 2) listing the blocked URLs — a composition that silently drops a
+// remote asset is not evidence.
+//
+// Stdout is one JSON line: {ok:true, out, size:[w,h]}.
+// Exit codes: 0 = ok, 2 = usage/render error, 3 = NOT POSSIBLE (environment:
+// missing playwright-core or Chromium).
+//
+// Determinism: fixed --width (default 1200), deviceScaleFactor 1, full-page
+// screenshot, no wall-clock reads, no randomness, no network. Same HTML +
+// same assets = byte-identical PNG on this host.
+//
+// The rendered composition is evidence: log it with append-ooda-step.js
+// (--action compose) and READ it — a composition you did not read is not
+// evidence.
+"use strict";
+
+const { existsSync, readFileSync } = require("node:fs");
+const { resolve, dirname } = require("node:path");
+const { pathToFileURL } = require("node:url");
+
+const DEFAULT_WIDTH = 1200;
+
+function fail(code, obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = { width: DEFAULT_WIDTH };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--in") out.in = argv[++i];
+    else if (a === "--out") out.out = argv[++i];
+    else if (a === "--width") out.width = parseInt(argv[++i], 10);
+    else fail(2, { ok: false, error: "unknown flag: " + a });
+  }
+  return out;
+}
+
+function loadPlaywright() {
+  try {
+    return require("playwright-core");
+  } catch (e) { /* fall through */ }
+  const envDir = (process.env.PLAYWRIGHT_CORE_DIR || "").trim();
+  if (envDir) {
+    try {
+      return require(envDir + "/playwright-core");
+    } catch (e) { /* fall through */ }
+    try {
+      return require(envDir);
+    } catch (e) { /* fall through */ }
+  }
+  const conventional = "/home/hatch/workspace/crew-tools/node_modules/playwright-core";
+  if (existsSync(conventional)) {
+    try {
+      return require(conventional);
+    } catch (e) { /* fall through */ }
+  }
+  fail(3, {
+    ok: false,
+    not_possible: "NOT POSSIBLE: playwright-core is not installed or not resolvable. " +
+      "Install it (npm install playwright-core) or set PLAYWRIGHT_CORE_DIR.",
+  });
+}
+
+function findChromium() {
+  const envPath = (process.env.CHROME_PATH || "").trim();
+  if (envPath && existsSync(envPath)) return envPath;
+  const sysPath = "/opt/meta-chromium/chrome";
+  if (existsSync(sysPath)) return sysPath;
+  fail(3, {
+    ok: false,
+    not_possible: "NOT POSSIBLE: no Chromium binary found. " +
+      "Set CHROME_PATH to a Chromium/Chrome executable.",
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.in) fail(2, { ok: false, error: "missing --in <page.html>" });
+  if (!args.out) fail(2, { ok: false, error: "missing --out <shot.png>" });
+  if (!Number.isFinite(args.width) || args.width < 200 || args.width > 4000) {
+    fail(2, { ok: false, error: "--width must be 200..4000, got: " + args.width });
+  }
+  const htmlPath = resolve(args.in);
+  if (!existsSync(htmlPath)) fail(2, { ok: false, error: "input not found: " + htmlPath });
+  void readFileSync(htmlPath, "utf8"); // fail fast on unreadable input
+
+  const { chromium } = loadPlaywright();
+  const exePath = findChromium();
+
+  let browser = null;
+  try {
+    browser = await chromium.launch({ executablePath: exePath, args: ["--no-sandbox"] });
+    const page = await browser.newPage({
+      viewport: { width: args.width, height: 900 },
+      deviceScaleFactor: 1,
+    });
+    // Hermetic render: abort any remote subresource. A composition that
+    // silently drops a remote asset is not evidence — fail loudly instead.
+    const blocked = [];
+    await page.route(/^(https?:)?\/\//, (route) => {
+      const url = route.request().url();
+      if (url.startsWith("file://")) return route.continue();
+      blocked.push(url.slice(0, 200));
+      return route.abort();
+    });
+    await page.goto(pathToFileURL(htmlPath).href, { waitUntil: "networkidle", timeout: 30000 });
+    await page.waitForTimeout(500);
+    if (blocked.length > 0) {
+      fail(2, { ok: false, error: "blocked remote subresources (render must be hermetic): " + blocked.join(", ") });
+    }
+    await page.screenshot({ path: resolve(args.out), fullPage: true });
+    const size = await page.evaluate(() => ({
+      w: document.documentElement.scrollWidth,
+      h: document.documentElement.scrollHeight,
+    }));
+    await browser.close();
+    process.stdout.write(JSON.stringify({ ok: true, out: resolve(args.out), size: [size.w, size.h] }) + "\n");
+  } catch (e) {
+    if (browser) await browser.close().catch(() => {});
+    fail(2, { ok: false, error: "render failed: " + ((e && e.message) || String(e)).slice(0, 500) });
+  }
+}
+
+main().catch((e) => {
+  fail(2, { ok: false, error: "driver error: " + ((e && e.message) || String(e)).slice(0, 500) });
+});