path: root/test/snapshot.zig

// pardes-snap: drive a pardes binary with a scripted input trace in a pty and
// capture the rendered grid at named sync points. The same script run against
// the prototype and the rewrite must produce byte-identical captures — this is
// the old-vs-new parity oracle for the rewrite.
//
//   zig build snap                        run all snapshots/*.snap, diff goldens
//   zig build snap -- --update            regenerate goldens serially
//   zig build snap -- snapshots/boot.snap one script
//   zig build snap -- --jobs=1            serial (default: 1.25 per cpu)
//   zig build snap -- --trace-stable      show what every `stable` waited on
//
// Scripts run one per forked child, in parallel; each child's report is held
// in a temp file and printed in script order at the end. The runner takes its
// own lockfile, so `zig build snap` never needs an `flock` wrapper: a second
// run waits for the first instead of trampling the fixed /tmp paths that the
// goldens record verbatim. A script that fails in the parallel pass is re-run
// alone before it counts as a failure.
//
// `stable` no longer burns its wall-clock window: it returns as soon as the
// app is provably done — screen unchanged, pty empty, and every process it
// forked asleep (see waitStable). That, the fan-out, and building the vendored
// C optimized (build.zig's c_optimize: 90% of a Debug startup used to be
// tree-sitter's query analyser at -O0) took the suite from 7m54s to ~4s. The
// app now reaches first paint in ~25ms, so what is left is mostly real work:
// bash spawns, their output, and the 40 `settle`s after `key esc`.
//
// Script commands (line-oriented, # comments):
//   file <name> <content>     create file in the script's cwd (before start)
//   lines <name> <n> [tail]   create file with n numbered lines, tail on each
//   dirmk <name>              create a subdirectory
//   run <shell...>            run a command in the script's cwd (NOT in a pane)
//   start <rows> <cols> [arg] fork the app in a pty (optional extra CLI arg)
//   wait <ms> <needle...>     pump until needle appears on the grid (fails hard)
//   settle <ms>               pump for a fixed duration
//   stable <quiet_ms> <timeout_ms>  pump until the grid stops changing
//   text <literal>            send literal bytes
//   send <escaped>            send with \e \r \n \t \\ \xNN escapes
//   key <names...>            enter esc tab bs space up down left right home end
//                             pgup pgdn c-<ch> a-<ch>   (after esc: settle, or
//                             vaxis reads the next byte in the same batch and
//                             parses it as alt-<ch>. The scripts said 700ms and
//                             it cost the suite 28s; there is no timer in vaxis
//                             to outlast — 20ms passes, they use 100ms)
//   press|release <[ctrl-]left|middle|right> <col> <row>   SGR mouse, 1-based
//   drag <btn> <col> <row>    motion with button held
//   motion <col> <row>        button-less motion (hover)
//   wheel <up|down> <col> <row>
//   resize <rows> <cols>
//   snap <label>              capture grid text + cursor
//   snapstyle <label>         capture per-cell style runs (fg,bg,attrs)
//   snap9p <label>            read core cells/styles over the child's 9P socket
//
// Any <col> above may be `@Word`, `@Word#2` or `@Word+4` instead of a number:
// the column of a word on that row of the live grid (see resolveCol). Chrome
// words move, and a frozen column silently clicks whatever moved into it.
//
// A capture is a DELTA against the previous capture of the same kind in the
// same script: the first one (and any after a resize) is the whole screen as
// `|<row>`, the rest are only the rows that changed, as `|<n>: <row>`. Before
// this, every frame restated every row, so 82% of golden lines were a copy of
// the line above and one added builtin word rewrote 78 goldens (see Prev).
const std = @import("std");
const libc = std.c;
const ghostty_vt = @import("ghostty-vt");
const eh = @import("e2e_harness.zig");
const Client = @import("9p_io").Client;

// This harness parses the app's output with its OWN ghostty-vt, which narrates
// every sequence it does not implement — vaxis's startup capability probes
// alone cost four `debug(stream)`/`warning(stream)`/`debug(kitty_gfx)` lines
// per script, burying the PASS/FAIL report under 200 lines of chatter. Cut the
// libraries back to errors; the report itself goes through std.debug, so a
// failure stays loud either way.
pub const std_options: std.Options = .{ .log_level = .err };

extern "c" fn setenv(name: [*:0]const u8, value: [*:0]const u8, overwrite: c_int) c_int;
extern "c" fn execvp(file: [*:0]const u8, argv: [*:null]const ?[*:0]const u8) c_int;
extern "c" fn system(cmd: [*:0]const u8) c_int;
extern "c" fn mkdtemp(template: [*:0]u8) ?[*:0]u8;

const SNAP_BASE = "/tmp/pardes-snap";
var trace_stable = false;
/// set for the serial re-run pass; children widen their probes (see beCareful)
var careful = false;
/// abs path of the deterministic mock language server the build handed over
/// (--lspmock=); null leaves the protocol client fully disabled for the run
var lspmock_bin: ?[:0]const u8 = null;
var record_dir: ?[]const u8 = null;
const gpa = std.heap.page_allocator;

pub fn main(init: std.process.Init) !void {
    var arena_state = std.heap.ArenaAllocator.init(gpa);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    const args = try init.minimal.args.toSlice(init.arena.allocator());
    if (args.len == 2 and std.mem.eql(u8, args[1], "--self-test")) return testCli(init);

    // argv: exe-under-test, then flags/scripts. All paths made absolute up
    // front because runScript chdirs into a per-script workdir.
    var cwd_buf: [4096]u8 = undefined;
    const cwd_p = libc.getcwd(&cwd_buf, cwd_buf.len) orelse fatal("getcwd failed", .{});
    const orig_cwd = std.mem.span(@as([*:0]u8, @ptrCast(cwd_p)));

    var exe: ?[]const u8 = null;
    var update = false;
    var retry_failures = true;
    // Slight oversubscription: a script spends most of its life waiting on a
    // shell, not computing. Measured on 16 cores: 16 jobs 4.4s, 20 jobs 3.9s,
    // 24 jobs 3.7s but losing the idle-probe bet often enough that the re-run
    // pass costs more than the extra parallelism saves.
    const cpus = std.Thread.getCpuCount() catch 4;
    var jobs: usize = cpus + cpus / 4;
    var script_count: usize = 0;
    var lspmock: ?[]const u8 = null;
    for (args[1..]) |a| {
        if (std.mem.eql(u8, a, "--update")) {
            update = true;
        } else if (std.mem.eql(u8, a, "--no-retry")) {
            retry_failures = false;
        } else if (std.mem.eql(u8, a, "--trace-stable")) {
            trace_stable = true;
        } else if (std.mem.startsWith(u8, a, "--lspmock=")) {
            lspmock = try absPath(arena, orig_cwd, a["--lspmock=".len..]);
        } else if (std.mem.startsWith(u8, a, "--record=")) {
            record_dir = try absPath(arena, orig_cwd, a["--record=".len..]);
        } else if (std.mem.startsWith(u8, a, "--jobs=")) {
            jobs = @max(1, try std.fmt.parseInt(usize, a["--jobs=".len..], 10));
        } else if (exe == null) {
            exe = try absPath(arena, orig_cwd, a);
        } else {
            script_count += 1;
        }
    }
    // Updating used to be serial, because update mode has no expected bytes and
    // so cannot tell a transient capture from behaviour. Serial was a proxy for
    // that, and an expensive one (77s against 6s). What it was reaching for is
    // available directly: capture at the WIDEST probe settings the harness has
    // (beCareful, as if every script had already failed once), then run the
    // ordinary verify pass over what was just written. A golden that does not
    // reproduce is reported instead of blessed, and the parallel pass keeps its
    // retry machinery, which serial update never had.
    var scripts = try arena.alloc([]const u8, script_count);
    var script_i: usize = 0;
    var saw_exe = false;
    for (args[1..]) |a| {
        if (std.mem.eql(u8, a, "--update") or
            std.mem.eql(u8, a, "--no-retry") or
            std.mem.eql(u8, a, "--trace-stable") or
            std.mem.startsWith(u8, a, "--lspmock=") or
            std.mem.startsWith(u8, a, "--record=") or
            std.mem.startsWith(u8, a, "--jobs=")) continue;
        if (!saw_exe) {
            saw_exe = true;
            continue;
        }
        scripts[script_i] = try absPath(arena, orig_cwd, a);
        script_i += 1;
    }
    if (exe == null) fatal("usage: pardes-snap <exe> [scripts...] [--update] [--jobs=N]", .{});
    const exe_z = try arena.dupeZ(u8, exe.?);
    lspmock_bin = if (lspmock) |p| try arena.dupeZ(u8, p) else null;

    if (scripts.len == 0) {
        scripts = try listSnaps(arena, try absPath(arena, orig_cwd, "test/snapshots"));
        std.mem.sort([]const u8, scripts, {}, struct {
            fn lt(_: void, x: []const u8, y: []const u8) bool {
                return std.mem.lessThan(u8, x, y);
            }
        }.lt);
    }
    if (scripts.len == 0) fatal("no .snap scripts found", .{});
    for (scripts, 0..) |script, i| for (scripts[0..i]) |previous| {
        if (std.mem.eql(u8, std.fs.path.stem(script), std.fs.path.stem(previous))) {
            std.debug.print("snapshot scripts share a work directory: {s} and {s}\n", .{ previous, script });
            return error.DuplicateScriptName;
        }
    };
    if (record_dir) |dir| {
        if (update) fatal("--record and --update are separate modes", .{});
        try mkdir(arena, dir, true);
    }

    try mkdir(arena, SNAP_BASE, true);
    // one run at a time (this is the flock that used to be typed by hand)
    _ = lockOrWait(SNAP_BASE ++ "/.run.lock", "another pardes-snap run");

    const codes = try arena.alloc(u8, scripts.len);
    if (update) {
        careful = true;
        try runBatch(arena, exe_z, try toBatch(arena, scripts), true, jobs, codes);
        var update_failed = false;
        for (scripts, codes) |script, code| if (code != 0) {
            update_failed = true;
            const report = readFileAlloc(arena, try reportPath(arena, script)) catch "child died without a report\n";
            std.debug.print("{s}", .{report});
        };
        if (update_failed) return error.SnapshotRegenerationFailed;
        careful = false;
        std.debug.print("verifying {d} regenerated golden(s)\n", .{scripts.len});
    }
    try runBatch(arena, exe_z, try toBatch(arena, scripts), false, jobs, codes);

    const attempts = try arena.alloc(u8, scripts.len);
    @memset(attempts, 0);
    var retry_dir: ?[]const u8 = null;
    if (jobs > 1 and retry_failures) {
        var round: usize = 0;
        while (round < 2) : (round += 1) {
            var retry_count: usize = 0;
            for (codes) |c| {
                if (c != 0) retry_count += 1;
            }
            if (retry_count == 0 or retry_count > 10) break;
            if (retry_dir == null) {
                var template = "/tmp/pardes-snap-retry-XXXXXX".* ++ [_:0]u8{0};
                const path = mkdtemp(&template) orelse return error.TempDirectoryFailed;
                retry_dir = try arena.dupe(u8, std.mem.span(path));
                std.debug.print("retry captures: {s}\n", .{retry_dir.?});
            }
            const retry = try arena.alloc(usize, retry_count);
            var retry_i: usize = 0;
            for (codes, 0..) |c, i| {
                if (c != 0) {
                    try archiveAttempt(init.io, arena, retry_dir.?, scripts[i], attempts[i]);
                    attempts[i] += 1;
                    retry[retry_i] = i;
                    retry_i += 1;
                }
            }
            const paths = try arena.alloc(Idx, retry.len);
            for (retry, paths, 0..) |i, *p, n| p.* = .{ .path = scripts[i], .code_idx = n };
            std.debug.print("re-running {d} failed script(s) serially{s}:", .{
                paths.len,
                if (round == 0) "" else " with wider settle probes",
            });
            for (paths) |p| std.debug.print(" {s}", .{std.fs.path.stem(p.path)});
            std.debug.print("\n", .{});
            careful = round > 0;
            const recodes = try arena.alloc(u8, paths.len);
            try runBatch(arena, exe_z, paths, false, 1, recodes);
            for (retry, recodes) |i, c| codes[i] = c;
        }
    }

    var failed: usize = 0;
    for (scripts, codes, attempts) |script_path, code, attempt| {
        if (attempt != 0) {
            try archiveAttempt(init.io, arena, retry_dir.?, script_path, attempt);
            std.debug.print("{s} required {d} retr{s}\n", .{ std.fs.path.stem(script_path), attempt, if (attempt == 1) "y" else "ies" });
        }
        const report = readFileAlloc(arena, reportPath(arena, script_path) catch "") catch "";
        std.debug.print("{s}", .{report});
        if (code != 0) {
            failed += 1;
            if (report.len == 0)
                std.debug.print("FAIL {s}: child died with no report\n", .{std.fs.path.stem(script_path)});
        }
    }
    if (failed > 0) {
        // In update mode the golden was written and then failed to reproduce:
        // the capture is not stable, so it is not a baseline.
        std.debug.print("{d}/{d} snapshot scripts {s}\n", .{
            failed, scripts.len, if (update) "UNSTABLE (regenerated, does not reproduce)" else "FAILED",
        });
        std.process.exit(1);
    }
    // Every retry passed: the captures of the failed attempts explain
    // nothing any more, and /tmp is not where they should pile up.
    if (retry_dir) |d| std.Io.Dir.cwd().deleteTree(init.io, d) catch {};
    std.debug.print("all {d} snapshot scripts ok\n", .{scripts.len});
}

fn testCli(init: std.process.Init) !void {
    const io = init.io;
    const arena = init.arena.allocator();
    const exe = try std.process.executablePathAlloc(io, arena);
    var template = "/tmp/pardes-snap-selftest-XXXXXX".* ++ [_:0]u8{0};
    const root = std.mem.span(mkdtemp(&template) orelse return error.TempDirectoryFailed);
    const prefix = std.fs.path.basename(root);
    var dir = try std.Io.Dir.cwd().openDir(io, root, .{});
    defer dir.close(io);
    var archives: std.ArrayList([]const u8) = .empty;
    var passed = false;
    defer {
        if (passed) {
            for (archives.items) |path| std.Io.Dir.cwd().deleteTree(io, path) catch {};
            for ([_][]const u8{ "bad", "good", "error", "unwritable" }) |name| {
                const work = std.fmt.allocPrint(arena, "{s}/{s}-{s}", .{ SNAP_BASE, prefix, name }) catch continue;
                std.Io.Dir.cwd().deleteTree(io, work) catch {};
                const report = std.fmt.allocPrint(arena, "{s}.report", .{work}) catch continue;
                std.Io.Dir.cwd().deleteFile(io, report) catch {};
            }
            std.Io.Dir.cwd().deleteTree(io, root) catch {};
        } else std.debug.print("snapshot driver test evidence: {s}\n", .{root});
    }
    var scripts: [4][]const u8 = undefined;
    for ([_][]const u8{ "bad", "good", "error", "unwritable" }, 0..) |name, i| {
        const path = try std.fmt.allocPrint(arena, "{s}-{s}.snap", .{ prefix, name });
        try dir.writeFile(io, .{ .sub_path = path, .data = if (i == 2) "run false\n" else "file marker content\n" });
        scripts[i] = try std.fmt.allocPrint(arena, "{s}/{s}", .{ root, path });
        const golden = try std.fmt.allocPrint(arena, "{s}-{s}.golden", .{ prefix, name });
        try dir.writeFile(io, .{ .sub_path = golden, .data = if (i == 0 or i == 3) "expected capture\n" else "" });
    }
    try dir.createDir(io, "other", .default_dir);
    const duplicate = try std.fmt.allocPrint(arena, "{s}/other/{s}", .{ root, std.fs.path.basename(scripts[1]) });
    try std.Io.Dir.cwd().writeFile(io, .{ .sub_path = duplicate, .data = "file marker content\n" });
    const stale_actual = try std.fmt.allocPrint(arena, "{s}/{s}-error.actual", .{ root, prefix });
    try std.Io.Dir.cwd().writeFile(io, .{ .sub_path = stale_actual, .data = "older verification evidence\n" });
    const unwritable = try std.fmt.allocPrint(arena, "{s}-unwritable.actual", .{prefix});
    try dir.createDir(io, unwritable, .default_dir);
    const record_arg = try std.fmt.allocPrint(arena, "--record={s}/recorded", .{root});
    const fixtures = [_]struct {
        name: []const u8,
        args: []const []const u8,
        status: u8 = 1,
        message: []const u8,
        archived: ?usize = null,
        actual: bool = false,
    }{
        .{ .name = "retry", .args = &.{ scripts[0], scripts[1], "--jobs=2" }, .message = "required 2 retries", .archived = 0, .actual = true },
        .{ .name = "no-retry", .args = &.{ scripts[0], scripts[1], "--jobs=2", "--no-retry" }, .message = "1/2 snapshot scripts FAILED" },
        .{ .name = "duplicate", .args = &.{ scripts[1], duplicate, "--jobs=2" }, .message = "DuplicateScriptName" },
        .{ .name = "record", .args = &.{ scripts[2], scripts[1], "--jobs=2", record_arg }, .message = "1/2 snapshot scripts FAILED", .archived = 2 },
        .{ .name = "update", .args = &.{ scripts[2], "--jobs=2", "--update", "--no-retry" }, .message = "SnapshotRegenerationFailed" },
        .{ .name = "actual-write", .args = &.{ scripts[3], "--no-retry" }, .message = "cannot write" },
        .{ .name = "pass", .args = &.{ scripts[1], "--jobs=2" }, .status = 0, .message = "all 1 snapshot scripts ok" },
    };
    for (fixtures) |fixture| {
        const argv = try arena.alloc([]const u8, fixture.args.len + 2);
        argv[0] = exe;
        argv[1] = exe;
        @memcpy(argv[2..], fixture.args);
        const result = try std.process.run(arena, io, .{
            .argv = argv,
            .stdout_limit = .limited(1024 * 1024),
            .stderr_limit = .limited(1024 * 1024),
            .timeout = .{ .duration = .{ .clock = .awake, .raw = .fromSeconds(30) } },
        });
        try dir.writeFile(io, .{ .sub_path = try std.fmt.allocPrint(arena, "{s}.log", .{fixture.name}), .data = result.stderr });
        if (result.term != .exited or result.term.exited != fixture.status or std.mem.indexOf(u8, result.stderr, fixture.message) == null) {
            std.debug.print("snapshot CLI fixture {s}:\n{s}\n", .{ fixture.name, result.stderr });
            return error.SnapshotDriverTestFailed;
        }
        const archive_marker = "retry captures: ";
        const archive_start = std.mem.indexOf(u8, result.stderr, archive_marker);
        if (fixture.archived) |script| {
            const rest = result.stderr[(archive_start orelse return error.MissingRetryArchive) + archive_marker.len ..];
            const archive = rest[0 .. std.mem.indexOfScalar(u8, rest, '\n') orelse return error.MissingRetryArchive];
            const archive_prefix = "/tmp/pardes-snap-retry-";
            if (!std.mem.startsWith(u8, archive, archive_prefix) or archive.len == archive_prefix.len or
                std.mem.indexOfScalar(u8, archive[archive_prefix.len..], '/') != null)
                return error.IncorrectRetryArchive;
            try archives.append(arena, archive);
            if (std.mem.count(u8, result.stderr, "re-running ") != 2) return error.IncorrectRetryCount;
            for (0..3) |attempt| {
                const report = try std.fmt.allocPrint(arena, "{s}/{s}.{d}.report", .{ archive, std.fs.path.stem(scripts[script]), attempt });
                const report_bytes = try std.Io.Dir.cwd().readFileAlloc(io, report, arena, .limited(1024 * 1024));
                const failure = try std.fmt.allocPrint(arena, "FAIL {s}:", .{std.fs.path.stem(scripts[script])});
                if (std.mem.indexOf(u8, report_bytes, failure) == null) return error.MissingAttemptReport;
                const actual = try std.fmt.allocPrint(arena, "{s}/{s}.{d}.actual", .{ archive, std.fs.path.stem(scripts[script]), attempt });
                const actual_bytes = std.Io.Dir.cwd().readFileAlloc(io, actual, arena, .limited(1024 * 1024)) catch |err| {
                    if (err == error.FileNotFound and !fixture.actual) continue;
                    return err;
                };
                if (!fixture.actual or actual_bytes.len != 0) return error.IncorrectAttemptActual;
            }
        } else if (archive_start != null or std.mem.indexOf(u8, result.stderr, "re-running ") != null) return error.UnexpectedRetry;
        if (std.mem.eql(u8, fixture.name, "update") and std.mem.indexOf(u8, result.stderr, "verifying ") != null)
            return error.VerifiedFailedRegeneration;
        if (std.mem.eql(u8, fixture.name, "actual-write") and std.mem.indexOf(u8, result.stderr, "actual written") != null)
            return error.FalseActualReport;
        if (std.mem.eql(u8, fixture.name, "retry") or std.mem.eql(u8, fixture.name, "no-retry")) {
            const good = try std.fmt.allocPrint(arena, "PASS {s}", .{std.fs.path.stem(scripts[1])});
            if (std.mem.indexOf(u8, result.stderr, good) == null) return error.OmittedPassingScript;
        }
        if (std.mem.eql(u8, fixture.name, "record")) {
            const good = try std.fmt.allocPrint(arena, "RECORDED {s}", .{std.fs.path.stem(scripts[1])});
            if (std.mem.indexOf(u8, result.stderr, good) == null) return error.OmittedPassingScript;
            const stale = try std.Io.Dir.cwd().readFileAlloc(io, stale_actual, arena, .limited(1024));
            if (!std.mem.eql(u8, stale, "older verification evidence\n")) return error.ChangedStaleActual;
        }
    }
    passed = true;
    std.debug.print("snapshot driver: {d} CLI regression fixtures passed\n", .{fixtures.len});
}

/// Run `scripts` `jobs` at a time, one forked child each, filling `codes` with
/// their exit codes. Forking rather than threading because runScript owns
/// process-global state — chdir into its workdir, HOME/TERM/PARDES_DUMP in the
/// environment — which siblings must not see. Each child's report goes to its
/// own file and is replayed in script order by the caller, so parallelism
/// never interleaves a diff.
// Scripts run in the order given — alphabetical. Sorting longest-first (from
// the durations the previous run left in its reports) is the textbook makespan
// fix and it measured WORSE here: 3.0s when clean, but bunching the heavy
// scripts at t=0 makes them contend, the idle probes lose their bet, and the
// re-run pass costs more than the tail ever did (13-20s runs). Left alone.
const Idx = struct { path: []const u8, code_idx: usize };

fn toBatch(arena: std.mem.Allocator, scripts: []const []const u8) ![]const Idx {
    const out = try arena.alloc(Idx, scripts.len);
    for (scripts, out, 0..) |path, *o, i| o.* = .{ .path = path, .code_idx = i };
    return out;
}

fn runBatch(
    arena: std.mem.Allocator,
    exe_z: [:0]const u8,
    scripts: []const Idx,
    update: bool,
    jobs: usize,
    codes: []u8,
) !void {
    const Job = struct { pid: libc.pid_t, idx: usize };
    const running = try arena.alloc(Job, @min(jobs, scripts.len));
    var running_len: usize = 0;
    var next: usize = 0;
    while (next < scripts.len or running_len > 0) {
        while (next < scripts.len and running_len < running.len) : (next += 1) {
            const idx = next;
            const pid = libc.fork();
            if (pid == 0) std.process.exit(runOne(arena, exe_z, scripts[idx].path, update));
            if (pid < 0) fatal("fork failed", .{});
            running[running_len] = .{ .pid = pid, .idx = scripts[idx].code_idx };
            running_len += 1;
        }
        var status: c_int = 0;
        const pid = libc.waitpid(-1, &status, 0);
        for (running[0..running_len], 0..) |j, i| {
            if (j.pid != pid) continue;
            // a killed child (crash in the harness itself) counts as a failure
            codes[j.idx] = if (status == 0) 0 else 1;
            running_len -= 1;
            running[i] = running[running_len];
            break;
        }
    }
}

/// One script, in its own process: run it, then diff or update its golden.
/// Everything it prints lands in its report file (dup2'd over stdout/stderr).
/// Returns the child's exit code.
fn runOne(arena: std.mem.Allocator, exe_z: [:0]const u8, script_path: []const u8, update: bool) u8 {
    if (careful) beCareful();
    const stem = std.fs.path.stem(script_path);
    const report_z = arena.dupeZ(u8, reportPath(arena, script_path) catch return 1) catch return 1;
    const fd = libc.open(report_z, .{ .ACCMODE = .WRONLY, .CREAT = true, .TRUNC = true }, @as(libc.mode_t, 0o644));
    if (fd >= 0) {
        _ = libc.dup2(fd, 1);
        _ = libc.dup2(fd, 2);
        _ = libc.close(fd);
    }
    const base_path = script_path[0 .. script_path.len - ".snap".len];
    const golden_path = std.fmt.allocPrint(arena, "{s}.golden", .{base_path}) catch return 1;
    // `.actual` means THIS invocation failed. Passing runs used to leave an
    // ignored file from an older failure behind, making a clean suite look
    // dirty to every manual `cmp` audit. Unlink only this script's exact path
    // before it starts; a new mismatch below writes it back.
    const actual_path = std.fmt.allocPrint(arena, "{s}.actual", .{base_path}) catch return 1;
    const actual_path_z = arena.dupeZ(u8, actual_path) catch return 1;
    if (record_dir == null) _ = libc.unlink(actual_path_z);
    const golden: ?[]u8 = if (record_dir == null) readFileAlloc(arena, golden_path) catch null else null;
    const started = eh.nowMs();
    const out = runScript(arena, exe_z, script_path, stem) catch |e| {
        std.debug.print("FAIL {s}: script error {s} ({d}ms)\n", .{ stem, @errorName(e), eh.nowMs() - started });
        return 1;
    };
    const took = eh.nowMs() - started;
    if (record_dir) |dir| {
        const path = std.fmt.allocPrintSentinel(arena, "{s}/{s}.snapshot", .{ dir, stem }, 0) catch return 1;
        eh.writeFile(path, out) catch return 1;
        std.debug.print("RECORDED {s}\n", .{stem});
        return 0;
    }
    if (update) {
        eh.writeFile(arena.dupeZ(u8, golden_path) catch return 1, out) catch return 1;
        std.debug.print("UPDATED {s} ({d} bytes)\n", .{ stem, out.len });
        return 0;
    }
    if (golden == null) {
        std.debug.print("FAIL {s}: no golden (run with -- --update)\n", .{stem});
        return 1;
    }
    if (std.mem.eql(u8, golden.?, out)) {
        std.debug.print("PASS {s} ({d}ms)\n", .{ stem, took });
        return 0;
    }
    eh.writeFile(arena.dupeZ(u8, actual_path) catch return 1, out) catch |err| {
        std.debug.print("FAIL {s}: differs from golden; cannot write {s}: {s} ({d}ms)\n", .{ stem, actual_path, @errorName(err), took });
        printFirstDiff(golden.?, out);
        return 1;
    };
    std.debug.print("FAIL {s}: differs from golden (actual written to {s}, {d}ms)\n", .{ stem, actual_path, took });
    printFirstDiff(golden.?, out);
    return 1;
}

fn reportPath(arena: std.mem.Allocator, script_path: []const u8) ![]const u8 {
    return std.fmt.allocPrint(arena, "{s}/{s}.report", .{ SNAP_BASE, std.fs.path.stem(script_path) });
}

fn archiveAttempt(io: std.Io, arena: std.mem.Allocator, dir: []const u8, script_path: []const u8, attempt: u8) !void {
    const stem = std.fs.path.stem(script_path);
    for ([_][]const u8{ "report", "actual" }) |suffix| {
        if (record_dir != null and std.mem.eql(u8, suffix, "actual")) continue;
        const source = if (std.mem.eql(u8, suffix, "report"))
            try reportPath(arena, script_path)
        else
            try std.fmt.allocPrint(arena, "{s}.actual", .{script_path[0 .. script_path.len - ".snap".len]});
        const bytes = std.Io.Dir.cwd().readFileAlloc(io, source, arena, .limited(64 * 1024 * 1024)) catch |err| {
            if (err == error.FileNotFound) continue;
            return err;
        };
        const path = try std.fmt.allocPrint(arena, "{s}/{s}.{d}.{s}", .{ dir, stem, attempt, suffix });
        const file = try std.Io.Dir.cwd().createFile(io, path, .{ .exclusive = true });
        defer file.close(io);
        try file.writeStreamingAll(io, bytes);
    }
}

/// Exclusive flock on `path`, announcing the wait if someone else holds it.
/// The fd is deliberately leaked: the lock lives until the process exits.
///
/// CLOEXEC is load-bearing. flock lives on the open file description, so an
/// inherited fd keeps the lock — and this process forks a pty full of app and
/// shell processes that can outlive it. Without CLOEXEC an orphaned bash holds
/// the lock forever and every later script blocks in flock().
fn lockOrWait(path: [*:0]const u8, what: []const u8) libc.fd_t {
    const fd = libc.open(path, .{ .ACCMODE = .WRONLY, .CREAT = true, .CLOEXEC = true }, @as(libc.mode_t, 0o644));
    if (fd < 0) fatal("cannot open lockfile {s}", .{path});
    if (libc.flock(fd, std.posix.LOCK.EX | std.posix.LOCK.NB) == 0) return fd;
    // polled rather than a blocking flock so a stuck holder is reported instead
    // of hanging the run until someone notices. The cap clears a full serial
    // run (--jobs=1 is ~6 minutes) with room to spare.
    std.debug.print("waiting for {s}...\n", .{what});
    var waited_ms: i64 = 0;
    while (waited_ms < 600_000) : (waited_ms += 100) {
        var none: [0]std.posix.pollfd = .{};
        _ = std.posix.poll(&none, 100) catch {};
        if (libc.flock(fd, std.posix.LOCK.EX | std.posix.LOCK.NB) == 0) return fd;
    }
    fatal("gave up after 10 minutes waiting for {s} ({s})", .{ what, path });
}

fn runScript(arena: std.mem.Allocator, exe_z: [:0]const u8, script_path: []const u8, stem: []const u8) ![]u8 {
    const src = try readFileAlloc(arena, script_path);

    // Fixed, recreated-per-run workdir: its PATH shows up in pane tags, so it
    // must be identical across runs and across old/new binaries.
    const base = try std.fmt.allocPrint(arena, "{s}/{s}", .{ SNAP_BASE, stem });
    rmrf(base);
    try mkdir(arena, SNAP_BASE, true);
    try mkdir(arena, base, false);
    const home = try std.fmt.allocPrint(arena, "{s}/home", .{base});
    const work = try std.fmt.allocPrint(arena, "{s}/cwd", .{base});
    try mkdir(arena, home, false);
    try mkdir(arena, work, false);
    // deterministic shell: fixed prompt, no history, no user rc leakage
    try eh.writeFile(try std.fmt.allocPrintSentinel(arena, "{s}/.bashrc", .{home}, 0), "PS1='$ '\nHISTFILE=\n");
    _ = setenv("HOME", try arena.dupeZ(u8, home), 1);
    // Keep startup configuration hermetic even when the developer exports an
    // XDG directory that points outside this per-snapshot fake home.
    const config_home = try std.fmt.allocPrintSentinel(arena, "{s}/.config", .{home}, 0);
    _ = setenv("XDG_CONFIG_HOME", config_home, 1);
    // ...and it is not empty: the DEFAULT shell is $SHELL, whatever this
    // machine's user logs in with (fish's prompt carries a hostname and its
    // greeting a version), so a golden taken
    // against it would be a golden for this machine. Every script here runs
    // bash — the .bashrc above pins its prompt to `$ ` — and the fish path is
    // covered by host_io.Shell's unit tests instead. This is an ordinary
    // config init going through the ordinary startup-config path, so it also
    // proves `Shell <name>` is dispatchable from one.
    try mkdir(arena, config_home, false);
    const pardes_config = try std.fmt.allocPrint(arena, "{s}/pardes", .{config_home});
    try mkdir(arena, pardes_config, false);
    // Messages leave the moment they are dismissed, as goldens have always
    // recorded: a linger or a dissolve is time, and time cannot be a golden.
    try eh.writeFile(try std.fmt.allocPrintSentinel(arena, "{s}/init", .{pardes_config}, 0), "Shell bash\nMessageAnimation off\nMessageLinger 0\n");
    _ = setenv("TERM", "xterm-256color", 1);
    _ = setenv("LC_ALL", "C", 1);
    // a wall clock cannot live in a golden; everything that would print one
    // prints fixed characters instead when this is set — the lsp introspection
    // views' durations (lsp_zls.zig hideTime) and the transient message row's
    // time of day (message.zig stamp)
    _ = setenv("PARDES_NOTIME", "1", 1);
    // A virtual core clock: animation moves a frame per timed-out wait,
    // whatever the machine's load (host_io.testClock).
    _ = setenv("PARDES_TEST_CLOCK", "1", 1);
    // The protocol client must be HERMETIC under the harness: `.rs` files
    // speak to the deterministic mock when the build handed one over, and
    // every other spec is disabled outright — a script that opened a stray
    // `.c` or `.ts` file must never spawn whatever clangd this machine has.
    _ = setenv("PARDES_LSP_RS", lspmock_bin orelse "", 1);
    _ = setenv("PARDES_LSP_C", "", 1);
    _ = setenv("PARDES_LSP_GO", "", 1);
    _ = setenv("PARDES_LSP_TS", "", 1);
    _ = setenv("PARDES_LSP_PY", "", 1);
    // Pin the dump path: live runs use a timestamped file under the user data
    // dir (dump.outPath), which would make the dump/load/restore goldens
    // nondeterministic. Per-SCRIPT, not one shared /tmp/pardes-dump.zon: four
    // scripts write it and read it back, and sharing it meant they could only
    // take turns — which cost more wall clock than the other 51 scripts put
    // together. Scripts name it `$DUMP`.
    const dump_path = try std.fmt.allocPrint(arena, "{s}/dump.zon", .{base});
    _ = setenv("PARDES_DUMP", try arena.dupeZ(u8, dump_path), 1);
    if (chdirRc(try arena.dupeZ(u8, work)) < 0) return error.ChdirFailed;

    const chunks = try arena.alloc([]const u8, countCaptures(src));
    var chunk_len: usize = 0;
    var h: ?eh.Harness = null;
    defer if (h) |*hp| hp.deinit();
    // captures are deltas against the previous one of the same kind (see Prev)
    var prev: Prev = .{};

    var lines_it = std.mem.splitScalar(u8, src, '\n');
    var lineno: usize = 0;
    while (lines_it.next()) |raw_line| {
        lineno += 1;
        const trimmed = std.mem.trim(u8, raw_line, " \t\r");
        if (trimmed.len == 0 or trimmed[0] == '#') continue;
        // `$DUMP` is the script's own PARDES_DUMP file (see above)
        const line = if (std.mem.indexOf(u8, trimmed, "$DUMP") == null) trimmed else blk: {
            const buf = try arena.alloc(u8, std.mem.replacementSize(u8, trimmed, "$DUMP", dump_path));
            _ = std.mem.replace(u8, trimmed, "$DUMP", dump_path, buf);
            break :blk buf;
        };
        var tok = std.mem.tokenizeScalar(u8, line, ' ');
        const cmd = tok.next().?;
        errdefer std.debug.print("  at {s}:{d}: {s}\n", .{ script_path, lineno, line });

        if (std.mem.eql(u8, cmd, "config")) {
            // Appended to the startup config this script's fake home already
            // has, so a script can pin a setting instead of spelling out the
            // screen geometry a default implies. Must precede `start`.
            const setting = try std.fmt.allocPrint(arena, "{s}\n", .{tok.rest()});
            try eh.appendFile(try std.fmt.allocPrintSentinel(arena, "{s}/pardes/init", .{config_home}, 0), setting);
        } else if (std.mem.eql(u8, cmd, "file")) {
            const name = tok.next() orelse return error.BadScript;
            try eh.writeFile(try arena.dupeZ(u8, name), try unescape(arena, tok.rest()));
        } else if (std.mem.eql(u8, cmd, "lines")) {
            const name = tok.next() orelse return error.BadScript;
            const n = try std.fmt.parseInt(usize, tok.next() orelse return error.BadScript, 10);
            // anything after the count is glued onto every line (no separator:
            // `rest` eats the delimiter, so spell one in the tail if you want
            // one) — a file that is long AND wide, which is what a horizontal
            // scroll test needs and `file` can only give as one huge script line
            const tail = tok.rest();
            const buf = try numberedLines(arena, n, tail);
            try eh.writeFile(try arena.dupeZ(u8, name), buf);
        } else if (std.mem.eql(u8, cmd, "ppmdiag")) {
            // The diagonal-split test PPM from the old e2e (white over blue),
            // grown to 512x512 with the white half filled by a fixed LCG
            // noise. Both halves are load-bearing: the clean edge is what the
            // block/sextant glyphs match exactly, the noise is fine enough
            // (one source pixel per matcher subcell at this size) that the
            // ASCII bitmaps win instead — so the Ascii toggle visibly changes
            // the art, which a 64x64 image cannot show (its cells average
            // down to flat color and a block always wins).
            const name = tok.next() orelse return error.BadScript;
            const ppm = try ppmDiag(arena);
            try eh.writeFile(try arena.dupeZ(u8, name), ppm);
        } else if (std.mem.eql(u8, cmd, "dirmk")) {
            try mkdir(arena, tok.next() orelse return error.BadScript, false);
        } else if (std.mem.eql(u8, cmd, "run")) {
            // A writer that is NOT a pardes pane. `file` mid-script is already
            // one, but it cannot express the rename-over that is how a
            // formatter actually replaces a file — and the difference is a
            // different inotify event. This runs in the script's cwd, as a
            // child of the RUNNER, so nothing it does reaches the app's ptys:
            // whatever the app then shows, it woke up for by itself.
            if (system(try arena.dupeZ(u8, tok.rest())) != 0) return error.RunFailed;
        } else if (std.mem.eql(u8, cmd, "start")) {
            const rows = try std.fmt.parseInt(u16, tok.next() orelse return error.BadScript, 10);
            const cols = try std.fmt.parseInt(u16, tok.next() orelse return error.BadScript, 10);
            var extra: [6]?[*:0]const u8 = @splat(null);
            var nextra: usize = 0;
            while (tok.next()) |a| : (nextra += 1) {
                if (nextra >= extra.len) return error.BadScript;
                extra[nextra] = (try arena.dupeZ(u8, a)).ptr;
            }
            if (h) |*hp| hp.deinit(); // scripts may restart (e.g. dump then -l)
            // a new process is a new screen: capture it whole, or its first
            // frame would be a delta against a dead instance's rows
            prev = .{};
            h = try eh.Harness.initArgv(gpa, exe_z.ptr, rows, cols, extra[0..nextra]);
        } else if (std.mem.eql(u8, cmd, "snapfile")) {
            const label = tok.next() orelse return error.BadScript;
            const contents = try readFileAlloc(arena, tok.rest());
            // Elide base64 payloads: they encode raw pty byte HISTORY, whose
            // micro-timing (prompt redraw cycles) legitimately differs between
            // implementations; the cleaned text fields are the contract.
            try appendChunk(chunks, &chunk_len, try snapFile(arena, label, contents));
        } else if (std.mem.eql(u8, cmd, "wait")) {
            const ms = try std.fmt.parseInt(i64, tok.next() orelse return error.BadScript, 10);
            try live(&h).expectWaitFor(tok.rest(), ms, "snapshot wait");
        } else if (std.mem.eql(u8, cmd, "settle")) {
            try live(&h).pump(try std.fmt.parseInt(i64, tok.next() orelse return error.BadScript, 10));
        } else if (std.mem.eql(u8, cmd, "stable")) {
            const quiet = try std.fmt.parseInt(i64, tok.next() orelse return error.BadScript, 10);
            const timeout = try std.fmt.parseInt(i64, tok.next() orelse return error.BadScript, 10);
            try waitStable(live(&h), quiet, timeout);
        } else if (std.mem.eql(u8, cmd, "text")) {
            try live(&h).send(tok.rest());
        } else if (std.mem.eql(u8, cmd, "send")) {
            try live(&h).send(try unescape(arena, tok.rest()));
        } else if (std.mem.eql(u8, cmd, "key")) {
            while (tok.next()) |name| try live(&h).send(keyBytes(name) orelse return error.BadKey);
        } else if (std.mem.eql(u8, cmd, "press") or std.mem.eql(u8, cmd, "release") or std.mem.eql(u8, cmd, "drag")) {
            const btn = buttonCode(tok.next() orelse return error.BadScript) orelse return error.BadScript;
            const col_spec = tok.next() orelse return error.BadScript;
            const row = try std.fmt.parseInt(u16, tok.next() orelse return error.BadScript, 10);
            const col = try resolveCol(live(&h), col_spec, row);
            const b: u16 = if (std.mem.eql(u8, cmd, "drag")) btn + 32 else btn;
            const fin: u8 = if (std.mem.eql(u8, cmd, "release")) 'm' else 'M';
            try live(&h).send(try std.fmt.allocPrint(arena, "\x1b[<{d};{d};{d}{c}", .{ b, col, row, fin }));
        } else if (std.mem.eql(u8, cmd, "motion")) {
            const col_spec = tok.next() orelse return error.BadScript;
            const row = try std.fmt.parseInt(u16, tok.next() orelse return error.BadScript, 10);
            const col = try resolveCol(live(&h), col_spec, row);
            try live(&h).send(try std.fmt.allocPrint(arena, "\x1b[<35;{d};{d}M", .{ col, row }));
        } else if (std.mem.eql(u8, cmd, "wheel")) {
            const dir = tok.next() orelse return error.BadScript;
            const b: u16 = if (std.mem.eql(u8, dir, "up")) 64 else 65;
            const col_spec = tok.next() orelse return error.BadScript;
            const row = try std.fmt.parseInt(u16, tok.next() orelse return error.BadScript, 10);
            const col = try resolveCol(live(&h), col_spec, row);
            try live(&h).send(try std.fmt.allocPrint(arena, "\x1b[<{d};{d};{d}M", .{ b, col, row }));
        } else if (std.mem.eql(u8, cmd, "resize")) {
            const rows = try std.fmt.parseInt(u16, tok.next() orelse return error.BadScript, 10);
            const cols = try std.fmt.parseInt(u16, tok.next() orelse return error.BadScript, 10);
            try live(&h).resize(rows, cols);
        } else if (std.mem.eql(u8, cmd, "snap")) {
            try appendChunk(chunks, &chunk_len, try snapText(arena, live(&h), tok.rest(), &prev));
        } else if (std.mem.eql(u8, cmd, "snapstyle")) {
            try appendChunk(chunks, &chunk_len, try snapStyle(arena, live(&h), tok.rest(), &prev));
        } else if (std.mem.eql(u8, cmd, "snap9p")) {
            try appendChunk(chunks, &chunk_len, try snap9p(arena, live(&h), tok.rest(), &prev));
        } else {
            std.debug.print("unknown command {s}\n", .{cmd});
            return error.BadScript;
        }
    }
    return concatChunks(arena, chunks[0..chunk_len]);
}

fn countCaptures(src: []const u8) usize {
    var count: usize = 0;
    var lines = std.mem.splitScalar(u8, src, '\n');
    while (lines.next()) |raw_line| {
        const line = std.mem.trim(u8, raw_line, " \t\r");
        if (line.len == 0 or line[0] == '#') continue;
        var tok = std.mem.tokenizeScalar(u8, line, ' ');
        const cmd = tok.next().?;
        if (std.mem.eql(u8, cmd, "snap") or
            std.mem.eql(u8, cmd, "snapstyle") or
            std.mem.eql(u8, cmd, "snap9p") or
            std.mem.eql(u8, cmd, "snapfile")) count += 1;
    }
    return count;
}

fn appendChunk(chunks: [][]const u8, len: *usize, chunk: []const u8) !void {
    if (len.* == chunks.len) return error.BadScript;
    chunks[len.*] = chunk;
    len.* += 1;
}

fn concatChunks(arena: std.mem.Allocator, chunks: []const []const u8) ![]u8 {
    var total: usize = 0;
    for (chunks) |chunk| total += chunk.len;
    const out = try arena.alloc(u8, total);
    var pos: usize = 0;
    for (chunks) |chunk| copyBytes(out, &pos, chunk);
    return out;
}

fn copyBytes(out: []u8, pos: *usize, bytes: []const u8) void {
    @memcpy(out[pos.*..][0..bytes.len], bytes);
    pos.* += bytes.len;
}

fn decimalDigits(value: usize) usize {
    var v = value;
    var digits: usize = 1;
    while (v >= 10) : (digits += 1) v /= 10;
    return digits;
}

fn numberedLines(arena: std.mem.Allocator, n: usize, tail: []const u8) ![]u8 {
    var total: usize = 0;
    for (1..n + 1) |i| total += "line ".len + decimalDigits(i) + tail.len + 1;
    const out = try arena.alloc(u8, total);
    var pos: usize = 0;
    for (1..n + 1) |i| {
        const line = try std.fmt.bufPrint(out[pos..], "line {d}{s}\n", .{ i, tail });
        pos += line.len;
    }
    return out;
}

fn ppmDiag(arena: std.mem.Allocator) ![]u8 {
    const header = "P6\n512 512\n255\n";
    const out = try arena.alloc(u8, header.len + 512 * 512 * 3);
    @memcpy(out[0..header.len], header);
    var pos = header.len;
    var seed: u64 = 12345;
    var py: usize = 0;
    while (py < 512) : (py += 1) {
        var px: usize = 0;
        while (px < 512) : (px += 1) {
            seed = seed *% 1103515245 +% 12345;
            const v: u8 = @truncate(seed >> 16);
            const pixel: [3]u8 = if (px + py < 512) .{ v, v, v } else .{ 0, 0, 255 };
            @memcpy(out[pos..][0..pixel.len], &pixel);
            pos += pixel.len;
        }
    }
    return out;
}

fn snapFile(arena: std.mem.Allocator, label: []const u8, contents: []const u8) ![]u8 {
    const header = try std.fmt.allocPrint(arena, "== file {s}\n", .{label});
    var total = header.len + "== end file\n".len;
    var lines = std.mem.splitScalar(u8, contents, '\n');
    while (lines.next()) |line| {
        if (std.mem.indexOf(u8, line, "_b64 = \"") != null) {
            const eq = std.mem.indexOfScalar(u8, line, '=').?;
            total += eq + 1 + " <elided>\n".len;
        } else {
            total += line.len + 1;
        }
    }
    const out = try arena.alloc(u8, total);
    var pos: usize = 0;
    copyBytes(out, &pos, header);
    lines = std.mem.splitScalar(u8, contents, '\n');
    while (lines.next()) |line| {
        if (std.mem.indexOf(u8, line, "_b64 = \"") != null) {
            const eq = std.mem.indexOfScalar(u8, line, '=').?;
            copyBytes(out, &pos, line[0 .. eq + 1]);
            copyBytes(out, &pos, " <elided>\n");
        } else {
            copyBytes(out, &pos, line);
            copyBytes(out, &pos, "\n");
        }
    }
    copyBytes(out, &pos, "== end file\n");
    return out;
}

fn live(h: *?eh.Harness) *eh.Harness {
    if (h.*) |*v| return v;
    fatal("script used the app before `start`", .{});
}

/// Pump until the captured state — grid text AND cursor — has not changed for
/// `quiet` ms (bounded by `timeout`). The one sync primitive that needs no
/// needle: used before every snap so old and new binaries are compared at
/// rest, not mid-repaint.
///
/// Same oracle as before, timed continuously instead of in fixed windows. The
/// old loop pumped a whole `quiet` window, compared, and pumped another — so
/// even an app that fell silent immediately cost 2 × 700ms, and 446 `stable`s
/// cost the suite ten minutes. This one sleeps in poll until the app writes,
/// and returns `quiet` ms after the LAST change. Waiting on the change rather
/// than on silence is what keeps it honest: pardes finishes a repaint with a
/// late cursor move, hundreds of ms after its last burst of text.
fn waitStable(h: *eh.Harness, quiet: i64, timeout: i64) !void {
    const t0 = eh.nowMs();
    const deadline = t0 + timeout;
    var prev = try stateKey(h);
    defer h.gpa.free(prev);
    var last_change = t0;
    var asleep_since: i64 = 0;
    while (true) {
        const now = eh.nowMs();
        const since = now - last_change;
        if (since >= quiet) {
            if (trace_stable) std.debug.print("[stable q={d}] window: last change +{d}ms, cost {d}ms\n", .{ quiet, last_change - t0, now - t0 });
            return;
        }
        // Fast path: the screen has held still, the pty is empty in both
        // directions (so the app has CONSUMED everything the script just sent
        // — otherwise an app still asleep in its event loop looks finished),
        // and nothing in its process tree is runnable. Held across two probes,
        // because a pane's shell can write and sleep a scheduler tick before
        // the app wakes to read it.
        if (since >= probe_after_ms and h.pending() == 0 and treeAsleep(h.pid)) {
            if (asleep_since == 0) {
                asleep_since = now;
            } else if (now - asleep_since >= probe_hold_ms) {
                if (trace_stable) std.debug.print("[stable q={d}] asleep: last change +{d}ms, cost {d}ms\n", .{ quiet, last_change - t0, now - t0 });
                return;
            }
        } else if (since >= probe_after_ms) {
            asleep_since = 0;
        }
        if (now >= deadline) return error.NeverStable;
        const nap = if (since >= probe_after_ms) probe_every_ms else probe_after_ms - since;
        if (!try h.pumpOnce(@min(nap, deadline - now))) continue;
        while (try h.pumpOnce(0)) {} // drain the burst before comparing
        const cur = try stateKey(h);
        if (std.mem.eql(u8, cur, prev)) {
            h.gpa.free(cur);
            continue;
        }
        h.gpa.free(prev);
        prev = cur;
        if (trace_stable) std.debug.print("[stable q={d}]   change at +{d}ms (gap {d}ms)\n", .{ quiet, eh.nowMs() - t0, eh.nowMs() - last_change });
        last_change = eh.nowMs();
        asleep_since = 0;
    }
}

// How long the screen must hold still before the sleep probe is trusted at all,
// how often it is taken, and how long it must stay true.
//
// The hold is the one number that cannot be reasoned down to zero. When the app
// writes to a pane's pty the kernel parks the bytes in a flip buffer and leaves
// the hand-off to a kworker: until that runs, the app is asleep, the shell is
// asleep, nothing is runnable and no /proc or ioctl query can see the round trip
// in flight (a pty master cannot even be reopened through /proc/<pid>/fd — it
// mints a fresh pty). So the hold is a bet on kworker latency, and a loaded
// machine loses it. The parallel pass bets small; the serial re-run that decides
// the verdict bets big.
//
// Only the SUM is the safety margin: a return cannot happen before
// `probe_after_ms + probe_hold_ms` after the last change either way. The split
// is pure cost, and the two halves cost differently - the arm window is one
// `poll()` sleep, while every `probe_every_ms` of hold is a full `treeAsleep()`
// walk of the app's process tree. Measured across the suite: 796 armed probes,
// 54 of them saw a later change, none later than 11ms at 20 jobs. That is the
// scheduler-tick case. The number the sum is really sized for is bigger and
// found by adversarial measurement: a theme transition sleeps
// `animation.frame_ms` (16ms) between frames with the whole tree asleep, and
// under `taskset -c 0,1` those gaps stretch to 57ms. 60ms total stays.
var probe_after_ms: i64 = 50;
const probe_every_ms: i64 = 5;
var probe_hold_ms: i64 = 10;

/// Widen the probes for the re-run pass: nothing else is competing then, so the
/// extra wait is cheap, and its verdict is the one that gets reported.
fn beCareful() void {
    probe_after_ms = 40;
    probe_hold_ms = 300;
}

/// Is every process in the app's tree asleep? Walks /proc from the app's pid
/// through `children`, checking every thread's run state: `R` (runnable) or
/// `D` (uninterruptible) anywhere means work is still in flight — a repaint,
/// a fork, a shell mid-command — so a quiet pty proves nothing. Anything else
/// (`S`, or a zombie waiting to be reaped) is idle.
///
/// This is what replaces the wall-clock window: the app finishes a keystroke
/// in ~10ms, and the scripts' 400-700ms `stable` windows were insurance
/// against not being able to tell "finished" from "paused mid-fork".
fn treeAsleep(root: libc.pid_t) bool {
    var stack: [64]libc.pid_t = undefined;
    stack[0] = root;
    var n: usize = 1;
    var path_buf: [64:0]u8 = undefined;
    var buf: [4096]u8 = undefined;
    while (n > 0) {
        n -= 1;
        const pid = stack[n];
        const dir_path = std.fmt.bufPrintZ(&path_buf, "/proc/{d}/task", .{pid}) catch continue;
        const dir = libc.opendir(dir_path) orelse continue; // exited between steps
        defer _ = libc.closedir(dir);
        while (libc.readdir(dir)) |d| {
            const tid = std.mem.sliceTo(@as([*:0]const u8, @ptrCast(&d.name)), 0);
            if (tid[0] == '.') continue;
            const stat = readProc(&buf, std.fmt.bufPrintZ(&path_buf, "/proc/{d}/task/{s}/stat", .{ pid, tid }) catch continue) orelse continue;
            // "pid (comm) S ..." — comm can hold spaces and parens, so the
            // state is the char two past the LAST ')'
            const close = std.mem.lastIndexOfScalar(u8, stat, ')') orelse continue;
            if (close + 2 >= stat.len) continue;
            switch (stat[close + 2]) {
                // R/D: still working. Z: just exited, so its parent is about to
                // be woken to reap it and carry on — a pane's shell sitting in
                // wait4 over a zombie `ls` looks asleep, but the prompt it is
                // about to print is what hides the echoed command line in the
                // goldens.
                'R', 'D', 'Z' => return false,
                else => {},
            }
            const kids = readProc(&buf, std.fmt.bufPrintZ(&path_buf, "/proc/{d}/task/{s}/children", .{ pid, tid }) catch continue) orelse continue;
            var it = std.mem.tokenizeAny(u8, kids, " \n");
            while (it.next()) |k| {
                if (n >= stack.len) return false; // deeper than we can walk: assume busy
                stack[n] = std.fmt.parseInt(libc.pid_t, k, 10) catch continue;
                n += 1;
            }
        }
    }
    return true;
}

/// Read a small /proc file into `buf` (procfs needs one read, no stat).
fn readProc(buf: []u8, path: [*:0]const u8) ?[]const u8 {
    const fd = libc.open(path, .{ .ACCMODE = .RDONLY, .CLOEXEC = true });
    if (fd < 0) return null;
    defer _ = libc.close(fd);
    const got = libc.read(fd, buf.ptr, buf.len);
    if (got <= 0) return null;
    return buf[0..@intCast(got)];
}

/// What a capture is made of: grid text, cursor cell, and a compact digest of
/// every cell style. Style used not to matter to `stable`, which let a
/// color-only animation look idle while the TTY frontend was deliberately
/// asleep between frames; a following `snapstyle` then caught a midpoint.
fn stateKey(h: *eh.Harness) ![]u8 {
    const text = try h.screenText();
    defer h.gpa.free(text);
    const c = h.cursor();
    var styles = std.hash.Wyhash.init(0x5354_594c_4553_2121);
    var y: u16 = 0;
    while (y < h.rows) : (y += 1) {
        var x: u16 = 0;
        while (x < h.cols) : (x += 1) {
            var key_buf: [64]u8 = undefined;
            styles.update(cellKey(h, x, y, &key_buf));
            styles.update("\x00");
        }
    }
    return std.fmt.allocPrint(h.gpa, "{d},{d},{x}\n{s}", .{ c.x, c.y, styles.final(), text });
}

/// A mouse column: either a screen column, or `@Word` / `@Word#2` - the column
/// of a WORD found on that row of the LIVE grid.
///
/// Chrome words move. When `Newtty` was added to every tail and `Joincol` and
/// `Changelog` to the topbar, six scripts kept their frozen columns and started
/// clicking a different word: `tutor.snap` clicked `Grep` instead of `Tutor`,
/// `exec.snap`/`respawn.snap`/`tagalign.snap` clicked `Newtty` instead of `Del`,
/// `find.snap` clicked `Joincol` instead of `Find`, `windowops.snap` clicked
/// `Tutor` instead of `Debug` - and `--update` blessed all of it, so 256 golden
/// lines were green while asserting the opposite of their script's first line.
/// Naming the word instead of its column makes that class of drift impossible:
/// the word is either there to be clicked or the script fails loudly.
///
/// The match is boundary-anchored, which is not a detail: `New` is a prefix of
/// `Newcol` and of `Newtty`, and `@New` resolving to `Newcol` is exactly the bug
/// this is here to prevent. `#n` picks the nth occurrence for a row that holds
/// two panes' tags, and `+n`/`-n` addresses a column NEAR a word - which is how
/// a click that means "in the gap the right-aligned builtins leave after the
/// path" is spelled without depending on how wide those builtins are.
fn resolveCol(h: *eh.Harness, spec: []const u8, row: u16) !u16 {
    if (spec.len == 0 or spec[0] != '@') return std.fmt.parseInt(u16, spec, 10);
    var word = spec[1..];
    var want: usize = 1;
    var offset: i32 = 0;
    // parsed off the end, so a word may hold a `-` or a `#` itself
    if (std.mem.lastIndexOfAny(u8, word, "+-")) |sign| {
        if (sign > 0) {
            if (std.fmt.parseInt(i32, word[sign + 1 ..], 10)) |n| {
                offset = if (word[sign] == '-') -n else n;
                word = word[0..sign];
            } else |_| {}
        }
    }
    if (std.mem.lastIndexOfScalar(u8, word, '#')) |hash| {
        if (std.fmt.parseInt(usize, word[hash + 1 ..], 10)) |n| {
            want = n;
            word = word[0..hash];
        } else |_| {}
    }
    if (word.len == 0 or want == 0) return error.BadScript;
    if (row == 0 or row > h.rows) return error.WordRowMissing;
    // One byte per CELL, not per byte of UTF-8: a mouse column is a cell, and
    // a tag row can hold a wide glyph or the U+254E column divider left of the
    // word. Non-ASCII cells become 0xff, which is not a word byte, so they
    // read as boundaries - every chrome word is ASCII.
    var cells: [1024]u8 = undefined;
    const line = rowCells(h, row - 1, &cells);
    var seen: usize = 0;
    var from: usize = 0;
    while (std.mem.indexOfPos(u8, line, from, word)) |at| : (from = at + 1) {
        if (at > 0 and wordByte(line[at - 1])) continue;
        const after = at + word.len;
        if (after < line.len and wordByte(line[after])) continue;
        seen += 1;
        if (seen != want) continue;
        // SGR columns are 1-based
        const col = @as(i32, @intCast(at + 1)) + offset;
        if (col < 1 or col > @as(i32, h.cols)) return error.BadScript;
        return @intCast(col);
    }
    std.debug.print("  no \"{s}\" #{d} on row {d}: {s}\n", .{ word, want, row, std.mem.trimEnd(u8, line, " ") });
    return error.WordNotOnRow;
}

fn rowCells(h: *eh.Harness, y: u16, buf: *[1024]u8) []const u8 {
    const n = @min(h.cols, buf.len);
    var x: u16 = 0;
    while (x < n) : (x += 1) {
        const ci = h.term.screens.active.pages.getCell(.{ .viewport = .{ .x = x, .y = y } });
        buf[x] = blk: {
            const cell = (ci orelse break :blk ' ').cell;
            if (cell.content_tag != .codepoint and cell.content_tag != .codepoint_grapheme) break :blk ' ';
            const cp = cell.content.codepoint.data;
            break :blk if (cp == 0) ' ' else if (cp < 128) @intCast(cp) else 0xff;
        };
    }
    return buf[0..n];
}

fn wordByte(c: u8) bool {
    return std.ascii.isAlphanumeric(c) or c == '_';
}

/// A capture, kept so the NEXT capture of the same kind can be emitted as the
/// rows that changed instead of the whole screen again. 81.7% of re-captured
/// rows used to be byte-identical to the previous capture in the same script,
/// which is why one word added to a tagline rewrote 78 goldens: every frame
/// re-stated every row of chrome. The delta keeps the assertion (a row that
/// moves still shows up, and a capture whose only change is the cursor is
/// exactly the empty delta its script means) and drops the restatement.
const Prev = struct {
    snap: []const []const u8 = &.{},
    style: []const []const u8 = &.{},
    ninep: []const []const u8 = &.{},
    // per kind: one shared width let a `snapstyle` between a `resize` and the
    // next `snap` re-arm the guard, and the post-resize frame then came out as
    // a delta against rows of the old width - dropping every row whose text is
    // width-invariant, which is every left-aligned chrome row there is.
    snap_cols: u16 = 0,
    style_cols: u16 = 0,
    ninep_cols: u16 = 0,
};

const Screen9p = struct {
    cols: u16,
    rows: u16,
    cursor: ?struct { x: u16, y: u16, bar: bool },
    cells: []const struct { []const u8, usize },
    styles: []const struct {
        fg: Color,
        bg: Color,
        bold: bool,
        dim: bool,
        italic: bool,
        blink: bool,
        reverse: bool,
        invisible: bool,
        strikethrough: bool,
        ul: enum { off, single, double, curly, dotted, dashed },
        font_role: enum { body, tagline },
    },

    const Color = union(enum) {
        default,
        index: u8,
        rgb: [3]u8,

        fn text(color: Color, buf: *[16]u8) []const u8 {
            return switch (color) {
                .default => "d",
                .index => |index| std.fmt.bufPrint(buf, "p{d}", .{index}) catch unreachable,
                .rgb => |rgb| std.fmt.bufPrint(buf, "#{x:0>2}{x:0>2}{x:0>2}", .{ rgb[0], rgb[1], rgb[2] }) catch unreachable,
            };
        }
    };
};

fn snap9p(arena: std.mem.Allocator, h: *eh.Harness, label: []const u8, prev: *Prev) ![]u8 {
    var dial_buf: [24]u8 = undefined;
    const dial = try std.fmt.bufPrint(&dial_buf, "{d}", .{h.pid});
    const bytes = try Client.read(gpa, dial, "/screen", "/screen");
    defer gpa.free(bytes);
    const parsed = try std.json.parseFromSlice(Screen9p, gpa, bytes, .{});
    defer parsed.deinit();
    const screen = parsed.value;
    if (screen.cols != h.cols or screen.rows != h.rows or screen.cols == 0 or screen.rows == 0 or
        screen.cells.len != @as(usize, screen.cols) * screen.rows or screen.styles.len == 0)
        return error.Screen9pDimensions;
    if (screen.cursor) |cursor| {
        if (cursor.x >= screen.cols or cursor.y >= screen.rows) return error.Screen9pCursor;
    }
    for (screen.cells) |cell| {
        if (cell[1] >= screen.styles.len or !std.unicode.utf8ValidateSlice(cell[0])) return error.Screen9pCell;
    }

    const keys = try arena.alloc([]const u8, screen.styles.len);
    for (screen.styles, keys) |style, *key| {
        var flags: [8]u8 = undefined;
        var len: usize = 0;
        inline for (.{ "bold", "dim", "italic", "blink", "reverse", "invisible", "strikethrough" }, "bfikrvx") |field, flag| {
            if (@field(style, field)) {
                flags[len] = flag;
                len += 1;
            }
        }
        if (style.ul != .off) {
            flags[len] = switch (style.ul) {
                .off => unreachable,
                .single => 'u',
                .double => 'U',
                .curly => '~',
                .dotted => '.',
                .dashed => '-',
            };
            len += 1;
        }
        var fg_buf: [16]u8 = undefined;
        var bg_buf: [16]u8 = undefined;
        key.* = try std.fmt.allocPrint(arena, "{s},{s},{s},{s}", .{
            style.fg.text(&fg_buf), style.bg.text(&bg_buf), flags[0..len], @tagName(style.font_role),
        });
    }

    var out: std.ArrayList(u8) = .empty;
    try out.appendSlice(arena, try std.fmt.allocPrint(arena, "== 9p {s} grid={d}x{d} cursor=", .{ label, screen.cols, screen.rows }));
    try out.appendSlice(arena, if (screen.cursor) |c|
        try std.fmt.allocPrint(arena, "{d},{d},{s}\n", .{ c.x, c.y, if (c.bar) "bar" else "block" })
    else
        "none\n");

    const rows = try arena.alloc([]const u8, screen.rows);
    const delta = prev.ninep.len == rows.len and prev.ninep_cols == screen.cols;
    for (rows, 0..) |*row, y| {
        var text_row: std.ArrayList(u8) = .empty;
        const cells = screen.cells[y * screen.cols ..][0..screen.cols];
        for (cells) |cell| try text_row.appendSlice(arena, cell[0]);
        var capture: std.ArrayList(u8) = .empty;
        const trimmed = std.mem.trimEnd(u8, text_row.items, " ");
        try capture.appendSlice(arena, if (trimmed.len == 0)
            try std.fmt.allocPrint(arena, "|{d}:\n", .{y})
        else
            try std.fmt.allocPrint(arena, "|{d}: {s}\n", .{ y, trimmed }));
        var annotated = false;
        for (cells, 0..) |cell, x| {
            if (cell[0].len == 1) continue;
            if (!annotated) try capture.appendSlice(arena, try std.fmt.allocPrint(arena, "+{d}:", .{y}));
            const glyph = try std.json.Stringify.valueAlloc(arena, cell[0], .{});
            try capture.appendSlice(arena, try std.fmt.allocPrint(arena, " {d}={s}", .{ x, glyph }));
            annotated = true;
        }
        if (annotated) try capture.append(arena, '\n');
        try capture.appendSlice(arena, try std.fmt.allocPrint(arena, "@{d}:", .{y}));
        var start: usize = 0;
        for (1..cells.len + 1) |x| {
            const key = keys[cells[start][1]];
            if (x != cells.len and std.mem.eql(u8, key, keys[cells[x][1]])) continue;
            try capture.appendSlice(arena, try std.fmt.allocPrint(arena, " {d}-{d} {s}", .{ start, x - 1, key }));
            start = x;
        }
        try capture.append(arena, '\n');
        row.* = capture.items;
        if (!delta or !std.mem.eql(u8, row.*, prev.ninep[y])) try out.appendSlice(arena, row.*);
    }
    prev.ninep = rows;
    prev.ninep_cols = screen.cols;
    return out.items;
}

/// `== snap <label> grid=CxR cursor=X,Y` then either the whole screen as
/// `|<row text>` (first capture of a script, or after a resize) or just the
/// rows that changed as `|<n>: <row text>`. An indexed row is a patch against
/// the previous capture; an unindexed one is a frame.
fn snapText(arena: std.mem.Allocator, h: *eh.Harness, label: []const u8, prev: *Prev) ![]u8 {
    const text = try h.screenText();
    defer h.gpa.free(text);
    const c = h.cursor();
    const rows = try arena.alloc([]const u8, h.rows);
    var it = std.mem.splitScalar(u8, text, '\n');
    for (rows) |*r| r.* = try arena.dupe(u8, std.mem.trimEnd(u8, it.next() orelse "", " "));

    var out: std.ArrayList(u8) = .empty;
    try out.appendSlice(arena, try std.fmt.allocPrint(arena, "== snap {s} grid={d}x{d} cursor={d},{d}\n", .{
        label, h.cols, h.rows, c.x, c.y,
    }));
    if (prev.snap.len == rows.len and prev.snap_cols == h.cols) {
        for (rows, prev.snap, 0..) |now, was, i| {
            if (std.mem.eql(u8, now, was)) continue;
            // no trailing space when a row goes blank: a whitespace-trimming
            // editor or `git apply --whitespace=fix` would rewrite it and the
            // golden would then fail like a regression
            try out.appendSlice(arena, if (now.len == 0)
                try std.fmt.allocPrint(arena, "|{d}:\n", .{i})
            else
                try std.fmt.allocPrint(arena, "|{d}: {s}\n", .{ i, now }));
        }
    } else {
        // A full frame stops at the last row with anything on it: the blank
        // tail of the grid is the same information as the `grid=CxR` header.
        var end = rows.len;
        while (end > 0 and rows[end - 1].len == 0) end -= 1;
        for (rows[0..end]) |r| {
            try out.appendSlice(arena, "|");
            try out.appendSlice(arena, r);
            try out.appendSlice(arena, "\n");
        }
    }
    prev.snap = rows;
    prev.snap_cols = h.cols;
    return out.items;
}

/// Per-row style runs from the harness emulator: `|y: x0-x1 fg,bg,attrs ...`.
/// fg/bg: d (default) | pN (palette) | #rrggbb. attrs: b f i k r v x + u U ~ . -
/// for underline single/double/curly/dotted/dashed. Deltas the same way
/// `snapText` does - the row already carries its own index, so a patch and a
/// frame are spelled identically here. The header carries the grid because a
/// style capture has no cursor: without it an unchanged style would be a label
/// line asserting nothing at all.
fn snapStyle(arena: std.mem.Allocator, h: *eh.Harness, label: []const u8, prev: *Prev) ![]u8 {
    const rows = try styleRows(arena, h);
    var out: std.ArrayList(u8) = .empty;
    try out.appendSlice(arena, try std.fmt.allocPrint(arena, "== style {s} grid={d}x{d}\n", .{ label, h.cols, h.rows }));
    const delta = prev.style.len == rows.len and prev.style_cols == h.cols;
    for (rows, 0..) |now, i| {
        if (delta and std.mem.eql(u8, now, prev.style[i])) continue;
        try out.appendSlice(arena, "|");
        try out.appendSlice(arena, now);
        try out.appendSlice(arena, "\n");
    }
    prev.style = rows;
    prev.style_cols = h.cols;
    return out.items;
}

fn styleRows(arena: std.mem.Allocator, h: *eh.Harness) ![]const []const u8 {
    const out = try arena.alloc([]const u8, h.rows);
    for (out, 0..) |*dst, y_usize| {
        const y: u16 = @intCast(y_usize);
        var row: std.ArrayList(u8) = .empty;
        try row.appendSlice(arena, try std.fmt.allocPrint(arena, "{d}:", .{y}));
        var key_buf: [64]u8 = undefined;
        var run_key: [64]u8 = undefined;
        var run_len: usize = 0;
        var run_start: u16 = 0;
        // A blank's ink shows nowhere, and the tty leaves whatever ink the
        // terminal had there (tty.zig blankInk), so it depends on the frames
        // before: a blank is written with the ink of the cell before it.
        var ink_buf: [16]u8 = undefined;
        var ink: []const u8 = "d";
        var x: u16 = 0;
        while (x <= h.cols) : (x += 1) {
            var key: []const u8 = if (x == h.cols) "\x00end" else cellKey(h, x, y, &key_buf);
            if (x < h.cols) {
                const comma = std.mem.indexOfScalar(u8, key, ',') orelse key.len;
                if (inklessBlank(h, x, y)) {
                    var joined: [64]u8 = undefined;
                    const rest = key[comma..];
                    @memcpy(joined[0..ink.len], ink);
                    @memcpy(joined[ink.len..][0..rest.len], rest);
                    @memcpy(key_buf[0 .. ink.len + rest.len], joined[0 .. ink.len + rest.len]);
                    key = key_buf[0 .. ink.len + rest.len];
                } else {
                    @memcpy(ink_buf[0..comma], key[0..comma]);
                    ink = ink_buf[0..comma];
                }
            }
            if (x == 0) {
                @memcpy(run_key[0..key.len], key);
                run_len = key.len;
                continue;
            }
            if (std.mem.eql(u8, key, run_key[0..run_len])) continue;
            try row.appendSlice(arena, try std.fmt.allocPrint(arena, " {d}-{d} ", .{ run_start, x - 1 }));
            try row.appendSlice(arena, run_key[0..run_len]);
            @memcpy(run_key[0..key.len], key);
            run_len = key.len;
            run_start = x;
        }
        dst.* = row.items;
    }
    return out;
}

/// A cell whose ink shows nowhere: no text but a space, and no underline,
/// strike or reverse to draw with it.
fn inklessBlank(h: *eh.Harness, x: u16, y: u16) bool {
    const ci = h.term.screens.active.pages.getCell(.{ .viewport = .{ .x = x, .y = y } }) orelse return false;
    if (ci.cell.wide == .spacer_tail) return false;
    if (ci.cell.hasText() and ci.cell.codepoint() != ' ') return false;
    const flags = ci.style().flags;
    return !flags.inverse and !flags.strikethrough and flags.underline == .none;
}

fn cellKey(h: *eh.Harness, x: u16, y: u16, buf: *[64]u8) []const u8 {
    const ci = h.term.screens.active.pages.getCell(.{ .viewport = .{ .x = x, .y = y } }) orelse return "d,d,";
    if (ci.cell.wide == .spacer_tail) return "d,d,";
    const style = ci.style();
    var n: usize = 0;
    var tmp: [16]u8 = undefined;
    const fg = colorStr(style.fg_color, &tmp);
    @memcpy(buf[n..][0..fg.len], fg);
    n += fg.len;
    buf[n] = ',';
    n += 1;
    var tmp2: [16]u8 = undefined;
    const bg: []const u8 = switch (ci.cell.content_tag) {
        .bg_color_palette => std.fmt.bufPrint(&tmp2, "p{d}", .{ci.cell.content.color_palette.data}) catch "?",
        .bg_color_rgb => blk: {
            const rgb = ci.cell.content.color_rgb;
            break :blk std.fmt.bufPrint(&tmp2, "#{x:0>2}{x:0>2}{x:0>2}", .{ rgb.r, rgb.g, rgb.b }) catch "?";
        },
        else => colorStr(style.bg_color, &tmp2),
    };
    @memcpy(buf[n..][0..bg.len], bg);
    n += bg.len;
    buf[n] = ',';
    n += 1;
    if (style.flags.bold) {
        buf[n] = 'b';
        n += 1;
    }
    if (style.flags.faint) {
        buf[n] = 'f';
        n += 1;
    }
    if (style.flags.italic) {
        buf[n] = 'i';
        n += 1;
    }
    if (style.flags.blink) {
        buf[n] = 'k';
        n += 1;
    }
    if (style.flags.inverse) {
        buf[n] = 'r';
        n += 1;
    }
    if (style.flags.invisible) {
        buf[n] = 'v';
        n += 1;
    }
    if (style.flags.strikethrough) {
        buf[n] = 'x';
        n += 1;
    }
    const ul: []const u8 = switch (style.flags.underline) {
        .none => "",
        .single => "u",
        .double => "U",
        .curly => "~",
        .dotted => ".",
        .dashed => "-",
    };
    @memcpy(buf[n..][0..ul.len], ul);
    n += ul.len;
    return buf[0..n];
}

fn colorStr(color: ghostty_vt.Style.Color, buf: *[16]u8) []const u8 {
    return switch (color) {
        .none => "d",
        .palette => |idx| std.fmt.bufPrint(buf, "p{d}", .{idx}) catch "?",
        .rgb => |rgb| std.fmt.bufPrint(buf, "#{x:0>2}{x:0>2}{x:0>2}", .{ rgb.r, rgb.g, rgb.b }) catch "?",
    };
}

fn keyBytes(name: []const u8) ?[]const u8 {
    const map = .{
        .{ "enter", "\r" },     .{ "esc", "\x1b" },     .{ "tab", "\t" },
        .{ "bs", "\x7f" },      .{ "space", " " },      .{ "up", "\x1b[A" },
        .{ "down", "\x1b[B" },  .{ "right", "\x1b[C" }, .{ "left", "\x1b[D" },
        .{ "home", "\x1b[H" },  .{ "end", "\x1b[F" },   .{ "pgup", "\x1b[5~" },
        .{ "pgdn", "\x1b[6~" },
    };
    inline for (map) |e| if (std.mem.eql(u8, name, e[0])) return e[1];
    const S = struct {
        var buf: [2]u8 = undefined;
    };
    if (name.len == 1) {
        S.buf[0] = name[0];
        return S.buf[0..1];
    }
    if (name.len == 3 and name[1] == '-') {
        if (name[0] == 'c' and name[2] >= 'a' and name[2] <= 'z') {
            S.buf[0] = name[2] - 'a' + 1;
            return S.buf[0..1];
        }
        if (name[0] == 'a') {
            S.buf = .{ 0x1b, name[2] };
            return S.buf[0..2];
        }
    }
    return null;
}

/// SGR button code, with an optional `ctrl-` prefix folded in as bit 4 —
/// which is exactly how a terminal encodes a modified click, and how vaxis
/// decodes one (Parser.zig mouse_bits.ctrl = 0b00010000).
fn buttonCode(name: []const u8) ?u16 {
    if (std.mem.startsWith(u8, name, "ctrl-")) {
        const base = buttonCode(name["ctrl-".len..]) orelse return null;
        return base + 16;
    }
    if (std.mem.eql(u8, name, "left")) return 0;
    if (std.mem.eql(u8, name, "middle")) return 1;
    if (std.mem.eql(u8, name, "right")) return 2;
    return null;
}

fn unescape(arena: std.mem.Allocator, s: []const u8) ![]const u8 {
    var len: usize = 0;
    var i: usize = 0;
    while (i < s.len) : (i += 1) {
        if (s[i] != '\\' or i + 1 >= s.len) {
            len += 1;
            continue;
        }
        i += 1;
        switch (s[i]) {
            'e', 'r', 'n', 't', '\\' => len += 1,
            'x' => {
                if (i + 2 >= s.len) return error.BadEscape;
                _ = try std.fmt.parseInt(u8, s[i + 1 .. i + 3], 16);
                len += 1;
                i += 2;
            },
            else => return error.BadEscape,
        }
    }
    const out = try arena.alloc(u8, len);
    var pos: usize = 0;
    i = 0;
    while (i < s.len) : (i += 1) {
        if (s[i] != '\\' or i + 1 >= s.len) {
            out[pos] = s[i];
            pos += 1;
            continue;
        }
        i += 1;
        out[pos] = switch (s[i]) {
            'e' => 0x1b,
            'r' => '\r',
            'n' => '\n',
            't' => '\t',
            '\\' => '\\',
            'x' => value: {
                const value = try std.fmt.parseInt(u8, s[i + 1 .. i + 3], 16);
                i += 2;
                break :value value;
            },
            else => unreachable,
        };
        pos += 1;
    }
    return out;
}

fn absPath(arena: std.mem.Allocator, cwd: []const u8, p: []const u8) ![]const u8 {
    if (p.len > 0 and p[0] == '/') return try arena.dupe(u8, p);
    return try std.fmt.allocPrint(arena, "{s}/{s}", .{ cwd, p });
}

fn listSnaps(arena: std.mem.Allocator, dir_path: []const u8) ![][]const u8 {
    const dir_z = try arena.dupeZ(u8, dir_path);
    const count = countSnapEntries(dir_z, dir_path);
    const scripts = try arena.alloc([]const u8, count);
    const dir = libc.opendir(dir_z) orelse fatal("no snapshots/ dir at {s}", .{dir_path});
    defer _ = libc.closedir(dir);
    var i: usize = 0;
    while (libc.readdir(dir)) |d| {
        const name = std.mem.sliceTo(@as([*:0]const u8, @ptrCast(&d.name)), 0);
        if (!std.mem.endsWith(u8, name, ".snap")) continue;
        if (i == scripts.len) return error.DirectoryChanged;
        scripts[i] = try std.fmt.allocPrint(arena, "{s}/{s}", .{ dir_path, name });
        i += 1;
    }
    if (i != scripts.len) return error.DirectoryChanged;
    return scripts;
}

fn countSnapEntries(dir_z: [:0]const u8, dir_path: []const u8) usize {
    const dir = libc.opendir(dir_z) orelse fatal("no snapshots/ dir at {s}", .{dir_path});
    defer _ = libc.closedir(dir);
    var count: usize = 0;
    while (libc.readdir(dir)) |d| {
        const name = std.mem.sliceTo(@as([*:0]const u8, @ptrCast(&d.name)), 0);
        if (std.mem.endsWith(u8, name, ".snap")) count += 1;
    }
    return count;
}

fn readFileAlloc(arena: std.mem.Allocator, path: []const u8) ![]u8 {
    const path_z = try arena.dupeZ(u8, path);
    const fd = libc.open(path_z, .{ .ACCMODE = .RDONLY });
    if (fd < 0) return error.OpenFailed;
    defer _ = libc.close(fd);
    const end = libc.lseek(fd, 0, libc.SEEK.END);
    if (end < 0 or libc.lseek(fd, 0, libc.SEEK.SET) < 0) return error.ReadFailed;
    const buf = try arena.alloc(u8, @intCast(end));
    var pos: usize = 0;
    while (pos < buf.len) {
        const n = libc.read(fd, buf[pos..].ptr, buf.len - pos);
        if (n < 0) {
            if (libc.errno(n) == .INTR) continue;
            return error.ReadFailed;
        }
        if (n == 0) return error.ReadFailed;
        pos += @intCast(n);
    }
    var extra: [1]u8 = undefined;
    while (true) {
        const n = libc.read(fd, &extra, extra.len);
        if (n < 0 and libc.errno(n) == .INTR) continue;
        if (n != 0) return error.ReadFailed;
        break;
    }
    return buf;
}

fn mkdir(arena: std.mem.Allocator, path: []const u8, exist_ok: bool) !void {
    const path_z = try arena.dupeZ(u8, path);
    const rc = libc.mkdir(path_z, 0o755);
    if (rc != 0) {
        if (exist_ok and libc.errno(rc) == .EXIST) return;
        return error.MkdirFailed;
    }
}

fn chdirRc(path_z: [:0]const u8) c_int {
    return libc.chdir(path_z.ptr);
}

fn rmrf(path: []const u8) void {
    var path_buf: [4096:0]u8 = undefined;
    if (path.len >= path_buf.len) return;
    @memcpy(path_buf[0..path.len], path);
    path_buf[path.len] = 0;
    const pid = libc.fork();
    if (pid == 0) {
        const argv: [4:null]?[*:0]const u8 = .{ "rm", "-rf", @as([*:0]const u8, @ptrCast(&path_buf)), null };
        _ = execvp("rm", &argv);
        libc._exit(127);
    }
    if (pid < 0) return;
    var status: c_int = 0;
    _ = libc.waitpid(pid, &status, 0);
}

fn printFirstDiff(golden: []const u8, actual: []const u8) void {
    var gi = std.mem.splitScalar(u8, golden, '\n');
    var ai = std.mem.splitScalar(u8, actual, '\n');
    var n: usize = 1;
    while (true) : (n += 1) {
        const g = gi.next();
        const a = ai.next();
        if (g == null and a == null) return;
        if (g != null and a != null and std.mem.eql(u8, g.?, a.?)) continue;
        std.debug.print("  first diff at golden line {d}:\n  -{s}\n  +{s}\n", .{ n, g orelse "<eof>", a orelse "<eof>" });
        return;
    }
}

fn fatal(comptime fmt: []const u8, args: anytype) noreturn {
    std.debug.print(fmt ++ "\n", args);
    std.process.exit(1);
}