muse-crew 0.7.10 → 0.7.12

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/read-ooda-verdict.js

@@ -0,0 +1,94 @@
+// read-ooda-verdict.js — deterministic cross-checker for the OODA terminal
+// verdict (2026-09-15).
+//
+// The prose VERDICT: line in an agent's report is the routing signal, but
+// verdict.json is the reason-carrying record the workflow closeout actually
+// reads. This script cross-checks the two: the caller passes the verdict it
+// read from prose (--expect) and the script fails loudly when the
+// machine-readable record disagrees or cannot back the verdict.
+//
+// Usage:
+//   node read-ooda-verdict.js --dir <phase-dir> --expect <PASS|FAIL>
+//
+// Reads <phase-dir>/verdict.json and prints exactly one JSON line to stdout.
+//
+// Exit 0 with {ok:true, verdict, reason, summary, expected, actual, attempt}
+// when the record exists, parses, has a verdict field, the verdict equals
+// --expect, and a FAIL carries a non-empty reason.
+//
+// Exit 2 with {ok:false, code, error} when:
+//   missing      — verdict.json is absent (the agent never wrote one)
+//   corrupt      — unparseable JSON, or parsed but no verdict field
+//   contradiction — the record's verdict !== --expect (NOT_POSSIBLE can
+//                  never equal PASS or FAIL, so it lands here)
+//   no_reason    — the record is FAIL with an empty or missing reason
+//
+// Determinism: no wall-clock reads, no randomness. The script never judges
+// report content — the agent states the reason; the machine enforces its
+// presence and its agreement with the prose verdict.
+"use strict";
+
+const { readFileSync, existsSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+
+function fail(code, error) {
+  process.stdout.write(JSON.stringify({ ok: false, code: code, error: error }) + "\n");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dir") out.dir = argv[++i];
+    else if (a === "--expect") out.expect = argv[++i];
+    else fail("bad_input", "unknown flag: " + a);
+  }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.dir) fail("bad_input", "missing --dir <phase-dir>");
+  if (!args.expect) fail("bad_input", "missing --expect <PASS|FAIL>");
+  if (args.expect !== "PASS" && args.expect !== "FAIL") {
+    fail("bad_input", "unknown --expect: " + args.expect + " (PASS|FAIL)");
+  }
+
+  const verdictPath = join(resolve(args.dir), "verdict.json");
+  if (!existsSync(verdictPath)) {
+    fail("missing", "verdict.json not found: " + verdictPath);
+  }
+
+  let record;
+  try {
+    record = JSON.parse(readFileSync(verdictPath, "utf8"));
+  } catch (e) {
+    fail("corrupt", "verdict.json is unparseable: " + e.message);
+  }
+  if (!record || typeof record.verdict !== "string" || record.verdict === "") {
+    fail("corrupt", "verdict.json has no verdict field: " + verdictPath);
+  }
+
+  if (record.verdict !== args.expect) {
+    fail("contradiction", "verdict.json verdict is " + record.verdict + " but prose verdict was " + args.expect);
+  }
+
+  if (record.verdict === "FAIL") {
+    if (record.reason === undefined || String(record.reason).trim() === "") {
+      fail("no_reason", "verdict.json verdict is FAIL with no machine-readable reason");
+    }
+  }
+
+  process.stdout.write(JSON.stringify({
+    ok: true,
+    verdict: record.verdict,
+    reason: record.reason === undefined ? "" : record.reason,
+    summary: record.summary === undefined ? "" : record.summary,
+    expected: record.expected === undefined ? "" : record.expected,
+    actual: record.actual === undefined ? "" : record.actual,
+    attempt: record.attempt === undefined ? "" : record.attempt,
+  }) + "\n");
+}
+
+main();

package/lib/readback-disk.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// readback-disk.js — deterministic disk read-back sensor for parent publish
+// verification (docs/publish-verification.md).
+//
+// The read-back gap (2026-09-14): the platform removed `artifact_inspect`
+// and no agent-callable content read-back existed, so every artifact publish
+// parked at `publish: verification-requested` permanently. The platform's
+// artifact edits land in its on-disk working copy of the artifact source
+// (~/workspace/ts-spaces/<slug>/ — verified empirically 2026-09-15: added
+// lines present, removed lines absent across real platform commits), so a
+// deterministic local sensor can replace the removed inspection tool: no
+// LLM, no async handoff, no prose to parse.
+//
+// This script is the SENSOR; lib/verify-publish.js stays the judge. It
+// emits the exact machine-readable findings block the verifier already
+// parses:
+//
+//   FILE: <path>
+//   ADDED: <exact added line from the diff> :: PRESENT|ABSENT
+//   REMOVED: <exact removed line from the diff> :: PRESENT|ABSENT
+//   END_FILE
+//
+// one ADDED line per (+) diff line and one REMOVED line per (-) diff line,
+// in diff order. The verdict is PRESENT iff that exact line occurs in the
+// file's CURRENT on-disk source (whole-line match), ABSENT otherwise.
+//
+// Authority boundary: the sensor reads the platform's working copy of the
+// artifact source — the tree the hosted artifact is built/served from. If
+// the working copy is stale relative to a just-applied edit, the findings
+// honestly report ABSENT and the verifier fails CLOSED (parked, never a
+// false stamp). Staleness can only park, never certify.
+//
+// Usage:
+//   node readback-disk.js --repo-path <path> --commit <sha> --base <sha>
+//       --slug <artifact-slug> --task-id <uuid> [--spaces-root <dir>]
+//
+// --base is the previously-stamped provenance source_commit (or the
+// empty-tree sha 4b825dc642cb6eb9a060e54bf8d69288fbee4904 for a first
+// publish) — the SAME base the verifier uses. --spaces-root defaults to
+// ~/workspace/ts-spaces.
+//
+// Exit codes: 0 ok (findings block on stdout) · 2 usage/validation ·
+// 1 git/diff/read failure. On non-zero exit NOTHING is printed to stdout,
+// so a caller must never save stdout as a findings file.
+//
+// Security: the slug is charset-validated and the resolved space directory
+// must stay under the spaces root (realpath containment); every file path
+// from the diff is likewise contained before reading. A path that escapes
+// is a validation failure (exit 2), never a read.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+function arg(name) {
+  const i = process.argv.indexOf(name);
+  if (i < 0 || i + 1 >= process.argv.length) {
+    fail("usage", `${name} is required.`, 2);
+  }
+  return process.argv[i + 1];
+}
+function fail(code, message, exitCode) {
+  // stderr only — stdout must stay empty on failure.
+  process.stderr.write(JSON.stringify({ ok: false, error: code, message }) + "\n");
+  process.exit(exitCode);
+}
+
+const repoPath = arg("--repo-path");
+const commit = arg("--commit");
+const base = arg("--base");
+const slug = arg("--slug");
+const taskId = arg("--task-id");
+const spacesRoot = process.argv.includes("--spaces-root")
+  ? arg("--spaces-root")
+  : join(homedir(), "workspace", "ts-spaces");
+
+if (!/^[0-9a-f]{40}$/.test(commit)) fail("usage", "commit must be a 40-char hex sha.", 2);
+if (!/^[0-9a-f]{40}$/.test(base)) fail("usage", "base must be a 40-char hex sha.", 2);
+if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(slug)) {
+  fail("usage", `slug ${JSON.stringify(slug)} is not a safe artifact slug.`, 2);
+}
+
+// Resolve the space directory with realpath containment: the slug must not
+// escape the spaces root (no "..", no symlinks pointing out).
+let spaceDir;
+try {
+  const rootReal = realpathSync(spacesRoot);
+  const candReal = realpathSync(join(spacesRoot, slug));
+  if (candReal !== rootReal && !candReal.startsWith(rootReal + "/")) {
+    fail("usage", `slug ${JSON.stringify(slug)} resolves outside the spaces root.`, 2);
+  }
+  spaceDir = candReal;
+} catch (e) {
+  fail("usage", `cannot resolve space dir for slug ${JSON.stringify(slug)}: ${e.message}`, 2);
+}
+try {
+  if (!statSync(spaceDir).isDirectory()) fail("usage", `space dir ${spaceDir} is not a directory.`, 2);
+} catch (e) {
+  fail("usage", `space dir ${spaceDir} unreadable: ${e.message}`, 2);
+}
+
+// The publish delta is base..commit — the same diff the verifier checks the
+// findings against. Refuse a base that is not an ancestor: certifying a
+// diff against an unrelated tree is worse than no read-back.
+if (base !== EMPTY_TREE) {
+  try {
+    execFileSync("git", ["-C", repoPath, "merge-base", "--is-ancestor", base, commit], { stdio: "ignore" });
+  } catch (e) {
+    fail("usage", `base ${base} is not an ancestor of commit ${commit} — refusing to read back an unrelated tree.`, 2);
+  }
+}
+
+let diff;
+try {
+  diff = execFileSync("git", ["-C", repoPath, "diff", base, commit, "--"], {
+    encoding: "utf8", maxBuffer: 4 * 1024 * 1024,
+  });
+} catch (e) {
+  fail("git", `git diff failed: ${e.message}`, 1);
+}
+if (!diff.trim()) {
+  fail("git", "empty diff for commit — nothing to read back.", 1);
+}
+
+// Parse the diff into per-file added/removed lines (byte-identical parser
+// to build-readback-request.js and verify-publish.js: the verifier looks
+// the raw lines up verbatim, so all three must agree on the split).
+const files = [];
+let current = null;
+for (const line of diff.split("\n")) {
+  if (line.startsWith("diff --git")) {
+    const m = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+    current = { path: m ? m[2] : "unknown", added: [], removed: [] };
+    files.push(current);
+  } else if (current && line.startsWith("+") && !line.startsWith("+++")) {
+    current.added.push(line.slice(1));
+  } else if (current && line.startsWith("-") && !line.startsWith("---")) {
+    current.removed.push(line.slice(1));
+  }
+}
+
+// Whole-line content of a disk file, normalized for the membership test.
+// Trailing-newline artifact popped (same convention as verify-publish.js
+// oldTreeLines); one trailing CR stripped per line so CRLF working copies
+// compare honestly against LF diffs. The RAW diff lines are still what get
+// emitted — the verifier looks those up verbatim.
+const norm = (s) => (s.endsWith("\r") ? s.slice(0, -1) : s);
+function diskLines(absPath) {
+  if (!existsSync(absPath)) return new Set(); // missing file: every line ABSENT
+  let text;
+  try {
+    text = readFileSync(absPath, "utf8");
+  } catch (e) {
+    fail("read", `cannot read ${absPath}: ${e.message}`, 1);
+  }
+  const lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return new Set(lines.map(norm));
+}
+
+const out = [];
+for (const f of files) {
+  // Contain every diff path inside the space dir before reading.
+  const abs = resolve(spaceDir, f.path);
+  if (abs !== spaceDir && !abs.startsWith(spaceDir + "/")) {
+    fail("usage", `diff path ${JSON.stringify(f.path)} escapes the space dir.`, 2);
+  }
+  const present = diskLines(abs);
+  out.push(`FILE: ${f.path}`);
+  for (const line of f.added) {
+    out.push(`ADDED: ${line} :: ${present.has(norm(line)) ? "PRESENT" : "ABSENT"}`);
+  }
+  for (const line of f.removed) {
+    out.push(`REMOVED: ${line} :: ${present.has(norm(line)) ? "PRESENT" : "ABSENT"}`);
+  }
+  out.push("END_FILE");
+}
+
+process.stdout.write(out.join("\n") + "\n");
+process.stderr.write(JSON.stringify({
+  ok: true, slug, task_id: taskId, commit, base,
+  files: files.map((f) => f.path),
+} ) + "\n");

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) });
+});