cb63edb8

feat: predicted echo — the keystroke paints before the RTT

a73x 2026-08-08 15:34

Commit message

feat: predicted echo — the keystroke paints before the RTT

The overlay meets the replica. A printable byte typed in a context the pty
has vouched for is drawn underlined at the predicted cell immediately, the
cursor advances past it, and the bytes go to the daemon unchanged — the
shell receives exactly what it always did. When the answering frame lands
the prediction is judged against the replica and the daemon's own row
content replaces the guess.

The read that makes it work is prev_ch, and it comes from the PREDICTED
cursor rather than the replica's. Mid-burst those are different cells, and
reading the wrong one hands reconcile a prev_ch belonging to a cell nobody
predicted: the next frame then looks like a contradiction instead of
silence, and the burst flushes itself. That is the standing debt from Task
3 discharged — a real engine, fed real VT bytes, with the cursor parked on
one character and a different one beside it, which is the only shape in
which the two reads disagree. The mutation fails it twice over: at the
prev_ch value, and again at the verdict.

Predictions are re-laid after every authoritative paint, because a delta
rewrites whole rows and would otherwise wipe a glyph whose prediction is
still outstanding — the burst would flicker away one frame after being
drawn. That repaint asks the same visibility question the keystroke path
does, so an unearned prediction cannot appear through the back door.

Flushed on snapshot, resize, scroll entry and reconnect; expired off the
idle path, which is the only thing that can retire a prediction an
application answered by going quiet. MUX_PREDICT_STATS=1 prints one
greppable line, its format pinned by a test rather than by whatever the
process happened to emit.

Verified live, not merely by unit test: typing into a real session paints
`\e[1;2H\e[4mi\e[0m\e[1;3H` before the daemon's own `hi` arrives, and the
counters read made=1 displayed=1 confirmed=1 contradicted=0. The first
keystroke of that run was suppressed — it was typed before the pty_mode
frame arrived, which is the safe default doing its job.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

build.zig

Old		New
@@ -144,6 +144,9 @@ pub fn build(b: *std.Build) void {
144	client_mod.addImport("protocol", protocol_mod);	144	client_mod.addImport("protocol", protocol_mod);
145	client_mod.addImport("testtmp", testtmp_mod);	145	client_mod.addImport("testtmp", testtmp_mod);
146	client_mod.addImport("quic_client", quic_client_mod);	146	client_mod.addImport("quic_client", quic_client_mod);
		147	// The client is the only thing that predicts: the overlay is a local
		148	// display decision and never becomes state anybody else can see.
		149	client_mod.addImport("predict", predict_mod);
147		150
148	const mux_mod = b.createModule(.{	151	const mux_mod = b.createModule(.{
149	.root_source_file = b.path("src/mux_main.zig"),	152	.root_source_file = b.path("src/mux_main.zig"),

src/client.zig

@@ @@ -10,6 +10,7 @@ const Engine = @import("engine").Engine; @@
+const proto = @import("protocol");
+const TmpDir = @import("testtmp").TmpDir;
+const quic_client = @import("quic_client");
+const predict = @import("predict");
+var winch_flag = std.atomic.Value(bool).init(false);
@@ @@ -457,6 +458,16 @@ fn session( @@
+    var exit_msg: ?[]const u8 = null;
+    defer if (exit_msg) |m| std.debug.print("{s}\n", .{m});
+    // Speculative echo. Born `.never` and stays there until a daemon tells
+    // it otherwise, so an old daemon that has never heard of pty_mode gets a
+    // client that predicts nothing at all.
+    //
+    // Registered here so the stats line lands after the terminal has been
+    // put back and on the normal screen, like every other message.
+    var overlay = predict.Overlay.init(alloc, size.cols, size.rows);
+    defer overlay.deinit();
+    defer dumpPredictStats(overlay.counters);
+    // Raw mode when we own a terminal. The alternate screen is NOT entered
+    // here — see the first-frame gate in the loop below.
+    var orig_termios: ?std.posix.termios = null;
@@ @@ -591,6 +602,10 @@ fn session( @@
+                reconnect_grace_until = std.time.milliTimestamp() + reconnect_grace_ms;
+            repaint_after_resync = true;
+            // Whatever was outstanding was predicted against a connection
+            // that no longer exists. Dropping it is not an accusation, so
+            // the counters stay where they are.
+            overlay.flush();
+            continue;
+        if (winch_flag.swap(false, .acq_rel)) {
@@ @@ -609,6 +624,9 @@ fn session( @@
+                        needs_reconnect = true;
+                        continue;
+                    };
+                    // The grid this would be painted on is about to stop
+                    // existing; cleared when the answering snapshot lands.
+                    overlay.setResizePending(true);
@@ @@ -620,6 +638,14 @@ fn session( @@
+        _ = try std.posix.poll(&fds, transport.timeoutMs(100));
+        transport.service();
+        // The idle path, and the only thing that can retire a prediction the
+        // application answered by going quiet: no frame is coming, so
+        // reconcile will never run again and the glyph would otherwise stay
+        // on screen for the rest of the session.
+        if (overlay.expire(std.time.milliTimestamp()) == .contradicted and scroll_pages == 0) {
+            try renderClipped(alloc, replica, size, stdout_fd);
+        }
+        // Labelled, because "no whole frame yet" must leave the REST of this
+        // iteration running. Everything below — the detach chord, keystrokes,
+        // resize — lives in the same pass, so jumping straight back to the
@@ @@ -677,6 +703,15 @@ fn session( @@
+                    // scrolled, so leaving scroll mode paints current state.
+                    replica.reset();
+                    replica.feed(frame.payload[proto.snapshot_prefix_len..]);
+                    // A snapshot answers a resize, ends a reconnect, and
+                    // rebuilds the screen under anything outstanding. None
+                    // of that says a prediction was wrong — it says we can
+                    // no longer find out, so the queue goes and the counters
+                    // do not move.
+                    overlay.setGrid(grid.cols, grid.rows);
+                    overlay.setResizePending(false);
+                    overlay.flush();
+                    overlay.noteSeq(prefix.seq);
+                    if (scroll_pages == 0) {
+                        try renderClipped(alloc, replica, size, stdout_fd);
+                        repaint_after_resync = false; // banner painted over
@@ @@ -708,19 +743,52 @@ fn session( @@
+                    history_rows = composed.header.history_rows;
+                    last_seq = composed.header.seq;
+                    replica.feed(composed.bytes);
+                    // Judged against the replica the frame has just been fed
+                    // into, which is the only authority there is.
+                    const verdict = reconcileOverlay(
+                        alloc,
+                        &overlay,
+                        replica,
+                        last_seq,
+                        std.time.milliTimestamp(),
+                    );
+                    // While scrolled the replica still tracks live output; the
+                    // repaint on scroll exit comes from it.
+                    if (scroll_pages == 0) {
+                        if (repaint_after_resync or verdict == .contradicted) {
+                            // First frame back after a reconnect. The daemon
+                            // sent only what changed, which is correct — but
+                            // the screen still carries the banner, so repaint
+                            // the whole thing from the replica instead.
+                            //
+                            // A contradiction (or an expiry) takes the same
+                            // route: the whole queue has just been abandoned,
+                            // and repainting everything from the replica is
+                            // the simplest rollback that is certainly right.
+                            // It is affordable precisely because reconcile v2
+                            // made contradictions rare — a burst outrunning
+                            // the round trip is no longer one.
+                            try renderClipped(alloc, replica, size, stdout_fd);
+                            repaint_after_resync = false;
+                        } else {
+                            try paintDeltaClipped(alloc, frame.payload, size, stdout_fd);
+                        // Last, and after either paint: the rows the daemon
+                        // just sent have overwritten anything drawn on them,
+                        // including predictions that are still outstanding.
+                        paintOverlay(alloc, &overlay, replica.cursorPos(), size, stdout_fd);
+                    }
+                },
+                .pty_mode => {
+                    const flags = proto.decodePtyMode(frame.payload) catch continue;
+                    // Mode churn is ordinary — readline hands the terminal
+                    // back and forth around every command — so the repaint
+                    // is spent only when the flush actually took something
+                    // off the screen.
+                    const had_pending = overlay.pendingCount() > 0;
+                    overlay.setMode(flags);
+                    if (had_pending and overlay.pendingCount() == 0 and scroll_pages == 0) {
+                        try renderClipped(alloc, replica, size, stdout_fd);
+                },
+                .scrollback_chunk => {
@@ @@ -775,6 +843,10 @@ fn session( @@
+                    if (history_rows > 0) {
+                        const max_pages: u32 = (history_rows + size.rows - 1) / size.rows;
+                        if (scroll_pages < max_pages) scroll_pages += 1;
+                        // The cursor is no longer where the user is looking,
+                        // so a prediction painted at it would land in the
+                        // middle of history.
+                        overlay.setScrollMode(true);
+                        requestScrollPage(transport, scroll_pages, history_rows, size) catch {
+                            needs_reconnect = true;
+                            continue;
@@ @@ -783,6 +855,7 @@ fn session( @@
+                } else if (std.mem.eql(u8, buf[0..n], scroll_dn)) {
+                    if (scroll_pages > 0) scroll_pages -= 1;
+                    if (scroll_pages == 0) {
+                        overlay.setScrollMode(false);
+                        try renderClipped(alloc, replica, size, stdout_fd);
+                    } else {
+                        requestScrollPage(transport, scroll_pages, history_rows, size) catch {
@@ @@ -793,8 +866,13 @@ fn session( @@
+                } else if (scroll_pages > 0) {
+                    // Any other key exits scroll mode (swallowed, not forwarded).
+                    scroll_pages = 0;
+                    overlay.setScrollMode(false);
+                    try renderClipped(alloc, replica, size, stdout_fd);
+                } else {
+                    // Speculate before sending, so the glyph is on screen
+                    // while the keystroke is still in flight. The bytes that
+                    // go out are unchanged either way.
+                    offerKeystroke(alloc, &overlay, replica, buf[0..n], size, stdout_fd);
+                    transport.writeFrame(.input, buf[0..n]) catch {
+                        // These keystrokes are lost with the transport, by
+                        // the same policy that drops what is typed while
+    try proto.writeAllFd(out_fd, paint.items);
+// ---- prediction --------------------------------------------------------
+//
+// The overlay is a display decision and nothing else. It never writes to
+// the replica, so the replica keeps meaning exactly "what the daemon said"
+// and stays comparable to `muxd dump` at every instant. Everything below
+// either reads the replica or paints on top of it.
+/// What the replica shows at one cell — the `prev_ch` a prediction is
+/// judged against later.
+///
+/// Read at the PREDICTED cursor, not the replica's own: mid-burst those are
+/// different cells, and reading the wrong one hands reconcile a `prev_ch`
+/// that belongs to somebody else's cell, which turns "the frame has not
+/// answered yet" into "we were contradicted" and flushes the queue. That is
+/// the failure the real-Engine test below exists to catch.
+fn replicaCellChar(alloc: std.mem.Allocator, replica: *Engine, at: predict.CursorPos) u8 {
+    const plain = replica.dumpPlain(alloc) catch return ' ';
+    defer alloc.free(plain);
+    const grid: predict.PlainGrid = .{ .text = plain, .cols = @intCast(replica.term.cols) };
+    return grid.cellChar(at.y, at.x) orelse ' ';
+}
+/// Judge the overlay against the replica as it now stands. Call after the
+/// replica has taken the frame, never before: the whole question is what
+/// the authoritative state says now.
+fn reconcileOverlay(
+    alloc: std.mem.Allocator,
+    overlay: *predict.Overlay,
+    replica: *Engine,
+    seq: u64,
+    now_ms: i64,
+) predict.Verdict {
+    const plain = replica.dumpPlain(alloc) catch return .none;
+    defer alloc.free(plain);
+    return overlay.reconcile(
+        predict.PlainGrid{ .text = plain, .cols = @intCast(replica.term.cols) },
+        seq,
+        now_ms,
+    );
+}
+/// Paint every pending prediction on top of whatever is on screen, and
+/// leave the cursor where the typist believes it is.
+///
+/// Idempotent and called after every authoritative paint as well as on each
+/// keystroke, because a delta repaints whole rows: the row content the
+/// daemon sent would otherwise wipe an underlined glyph whose prediction is
+/// still outstanding, and the burst would flicker away one frame after it
+/// was drawn.
+fn paintOverlay(
+    alloc: std.mem.Allocator,
+    overlay: *predict.Overlay,
+    base: Engine.CursorPos,
+    tty: proto.Size,
+    out_fd: std.posix.fd_t,
+) void {
+    if (!overlay.confident or overlay.pendingCount() == 0) return;
+    var paint: std.ArrayList(u8) = .empty;
+    defer paint.deinit(alloc);
+    paint.appendSlice(alloc, "\x1b[?2026h\x1b[?25l") catch return;
+    var i: usize = 0;
+    while (i < overlay.pendingCount()) : (i += 1) {
+        const cell = overlay.pendingAt(i).cell;
+        if (cell.row >= tty.rows or cell.col >= tty.cols) continue;
+        var b: [32]u8 = undefined;
+        // Underlined, so a prediction is visibly a prediction until the
+        // daemon's own row content replaces it.
+        const s = std.fmt.bufPrint(&b, "\x1b[{d};{d}H\x1b[4m{c}\x1b[0m", .{
+            cell.row + 1,
+            cell.col + 1,
+            cell.ch,
+        }) catch continue;
+        paint.appendSlice(alloc, s) catch return;
+    }
+    const pc = overlay.predictedCursor(.{ .x = base.x, .y = base.y });
+    const cur = clampCursor(.{ .x = pc.x, .y = pc.y }, tty);
+    var cbuf: [32]u8 = undefined;
+    const tail = std.fmt.bufPrint(&cbuf, "\x1b[{d};{d}H\x1b[?25h\x1b[?2026l", .{
+        cur.y + 1,
+        cur.x + 1,
+    }) catch return;
+    paint.appendSlice(alloc, tail) catch return;
+    proto.writeAllFd(out_fd, paint.items) catch {};
+}
+/// Offer one chunk of typed bytes to the overlay. The chunk goes to the
+/// daemon unchanged whatever happens here — prediction never alters what
+/// the shell receives, only what the screen shows before it answers.
+fn offerKeystroke(
+    alloc: std.mem.Allocator,
+    overlay: *predict.Overlay,
+    replica: *Engine,
+    chunk: []const u8,
+    tty: proto.Size,
+    out_fd: std.posix.fd_t,
+) void {
+    if (chunk.len != 1) {
+        // An escape sequence, a multi-byte character, or a paste. None is
+        // one cell's worth of change and M9 speculates about none of them.
+        // Offering the lead byte records the refusal in the same counter as
+        // every other refusal, which covers the two shapes that actually
+        // arrive this way — both have a non-printable lead byte.
+        if (chunk[0] < 0x20 or chunk[0] >= 0x7f) {
+            _ = overlay.predictAt(.{
+                .cursor = .{},
+                .ch = chunk[0],
+                .prev_ch = 0,
+                .now_ms = std.time.milliTimestamp(),
+            });
+        }
+        return;
+    }
+    const base = replica.cursorPos();
+    const at = overlay.predictedCursor(.{ .x = base.x, .y = base.y });
+    const out = overlay.predictAt(.{
+        .cursor = at,
+        .ch = chunk[0],
+        .prev_ch = replicaCellChar(alloc, replica, at),
+        .now_ms = std.time.milliTimestamp(),
+    });
+    switch (out) {
+        .display => paintOverlay(alloc, overlay, base, tty, out_fd),
+        // Queued but unearned, or refused outright: either way nothing is
+        // drawn, which is the entire safety property.
+        .hidden, .suppressed => {},
+    }
+}
+/// The one machine-readable line `MUX_PREDICT_STATS=1` produces. A pure
+/// function so the format the e2e greps for is pinned by a test rather than
+/// by whatever the process happened to print.
+fn formatPredictStats(buf: []u8, c: predict.Counters) ![]const u8 {
+    return std.fmt.bufPrint(
+        buf,
+        "predict made={d} displayed={d} confirmed={d} contradicted={d}" ++
+            " expired={d} suppressed={d}",
+        .{ c.made, c.displayed, c.confirmed, c.contradicted, c.expired, c.suppressed },
+    );
+}
+pub const predict_stats_len = 192;
+fn dumpPredictStats(c: predict.Counters) void {
+    const want = std.posix.getenv("MUX_PREDICT_STATS") orelse return;
+    if (!std.mem.eql(u8, want, "1")) return;
+    var buf: [predict_stats_len]u8 = undefined;
+    const line = formatPredictStats(&buf, c) catch return;
+    std.debug.print("{s}\n", .{line});
+}
+fn requestScrollPage(
+    transport: *Transport,
+    pages_up: u32,
@@ @@ -1033,6 +1264,249 @@ fn renderScrollback( @@
+    try proto.writeAllFd(out_fd, paint.items);
+fn devNull() !std.posix.fd_t {
+    return std.posix.open("/dev/null", .{ .ACCMODE = .WRONLY }, 0);
+}
+test "prediction: prev_ch is read at the predicted cursor, not the replica's" {
+    const alloc = std.testing.allocator;
+    const null_fd = try devNull();
+    defer std.posix.close(null_fd);
+    // A real engine, fed real VT bytes — the one part of the prediction
+    // contract no test inside predict.zig can reach, because that module
+    // has never heard of an engine.
+    const replica = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer replica.deinit();
+    // Content with the cursor parked ON a character and a DIFFERENT
+    // character in the cell after it. That difference is the whole test:
+    // with nothing pending the replica's cursor and the predicted one agree,
+    // and mid-burst they do not.
+    replica.feed("abcXY\x1b[1;4H");
+    try std.testing.expectEqual(@as(u16, 3), replica.cursorPos().x);
+    var ov = predict.Overlay.init(alloc, 80, 24);
+    defer ov.deinit();
+    ov.setMode(.{ .icanon = true, .echo = true });
+    ov.noteSeq(1);
+    const tty = proto.Size{ .cols = 80, .rows = 24 };
+    offerKeystroke(alloc, &ov, replica, "d", tty, null_fd);
+    offerKeystroke(alloc, &ov, replica, "e", tty, null_fd);
+    try std.testing.expectEqual(@as(usize, 2), ov.pendingCount());
+    try std.testing.expectEqual(@as(u8, 'X'), ov.pendingAt(0).prev_ch);
+    // The second keystroke lands in the cell AFTER the first prediction,
+    // and takes that cell's content as its prev_ch.
+    try std.testing.expectEqual(@as(u16, 4), ov.pendingAt(1).cell.col);
+    try std.testing.expectEqual(@as(u8, 'Y'), ov.pendingAt(1).prev_ch);
+    // A frame that changed neither cell: the daemon has not seen the
+    // keystrokes yet, so it has said nothing about them and both
+    // predictions must survive it. Read prev_ch from the wrong cell and
+    // this is where it shows — the second cell holds 'Y', which is neither
+    // the prediction nor the 'X' a cursor-based read would have recorded,
+    // so the frame reads as a contradiction and the burst is flushed.
+    try std.testing.expectEqual(
+        predict.Verdict.none,
+        reconcileOverlay(alloc, &ov, replica, 2, 0),
+    );
+    try std.testing.expectEqual(@as(usize, 2), ov.pendingCount());
+    try std.testing.expectEqual(@as(u64, 0), ov.counters.contradicted);
+    // And when the daemon does answer, they confirm against the real grid.
+    replica.feed("\x1b[1;4Hde");
+    try std.testing.expectEqual(
+        predict.Verdict.confirmed,
+        reconcileOverlay(alloc, &ov, replica, 3, 0),
+    );
+    try std.testing.expectEqual(@as(usize, 0), ov.pendingCount());
+    try std.testing.expectEqual(@as(u64, 2), ov.counters.confirmed);
+}
+test "prediction: a burst advances the predicted cursor one cell per keystroke" {
+    const alloc = std.testing.allocator;
+    const null_fd = try devNull();
+    defer std.posix.close(null_fd);
+    const replica = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer replica.deinit();
+    var ov = predict.Overlay.init(alloc, 80, 24);
+    defer ov.deinit();
+    ov.setMode(.{ .icanon = true, .echo = true });
+    const tty = proto.Size{ .cols = 80, .rows = 24 };
+    for ("hello") |ch| offerKeystroke(alloc, &ov, replica, &.{ch}, tty, null_fd);
+    // The replica's own cursor has not moved — the daemon has answered
+    // nothing — so every one of these came from the overlay.
+    try std.testing.expectEqual(@as(u16, 0), replica.cursorPos().x);
+    try std.testing.expectEqual(@as(usize, 5), ov.pendingCount());
+    for ("hello", 0..) |ch, i| {
+        const p = ov.pendingAt(i);
+        try std.testing.expectEqual(@as(u16, @intCast(i)), p.cell.col);
+        try std.testing.expectEqual(ch, p.cell.ch);
+        try std.testing.expectEqual(@as(u8, ' '), p.prev_ch);
+    }
+    try std.testing.expectEqual(
+        predict.CursorPos{ .x = 5, .y = 0 },
+        ov.predictedCursor(.{ .x = 0, .y = 0 }),
+    );
+}
+test "prediction paints underlined, and parks the cursor past what it drew" {
+    const alloc = std.testing.allocator;
+    const p = try std.posix.pipe();
+    defer std.posix.close(p[0]);
+    const replica = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer replica.deinit();
+    replica.feed("\x1b[1;4H"); // cursor at column 3 (0-based)
+    var ov = predict.Overlay.init(alloc, 80, 24);
+    defer ov.deinit();
+    ov.setMode(.{ .icanon = true, .echo = true });
+    offerKeystroke(alloc, &ov, replica, "z", .{ .cols = 80, .rows = 24 }, p[1]);
+    std.posix.close(p[1]);
+    var out: std.ArrayList(u8) = .empty;
+    defer out.deinit(alloc);
+    var rbuf: [4096]u8 = undefined;
+    while (true) {
+        const n = try std.posix.read(p[0], &rbuf);
+        if (n == 0) break;
+        try out.appendSlice(alloc, rbuf[0..n]);
+    }
+    // Drawn at the predicted cell, underlined so a speculation is visibly
+    // one, and with the SGR closed again so it cannot bleed into the rest.
+    try std.testing.expect(std.mem.indexOf(u8, out.items, "\x1b[1;4H\x1b[4mz\x1b[0m") != null);
+    // Cursor left one past it: the typist's next character goes there, and
+    // if it did not the shell's own cursor would appear to lag a column
+    // behind everything they typed.
+    try std.testing.expect(std.mem.endsWith(u8, out.items, "\x1b[1;5H\x1b[?25h\x1b[?2026l"));
+    // Wrapped in one synchronized update, so no terminal ever shows the
+    // half-drawn state.
+    try std.testing.expect(std.mem.startsWith(u8, out.items, "\x1b[?2026h"));
+}
+test "prediction: nothing is drawn for a context that has not earned it" {
+    const alloc = std.testing.allocator;
+    const p = try std.posix.pipe();
+    defer std.posix.close(p[0]);
+    const replica = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer replica.deinit();
+    var ov = predict.Overlay.init(alloc, 80, 24);
+    defer ov.deinit();
+    ov.setMode(.{ .icanon = false, .echo = false }); // raw: display is earned
+    offerKeystroke(alloc, &ov, replica, "z", .{ .cols = 80, .rows = 24 }, p[1]);
+    std.posix.close(p[1]);
+    // Queued, so it can be judged and earn the next one its visibility...
+    try std.testing.expectEqual(@as(usize, 1), ov.pendingCount());
+    try std.testing.expectEqual(@as(u64, 0), ov.counters.displayed);
+    // ...and not one byte went to the terminal. The effect, not the counter:
+    // this is the assertion that a password prompt depends on.
+    var rbuf: [64]u8 = undefined;
+    try std.testing.expectEqual(@as(usize, 0), try std.posix.read(p[0], &rbuf));
+}
+test "prediction: a chunk that is not one printable byte is never speculated about" {
+    const alloc = std.testing.allocator;
+    const null_fd = try devNull();
+    defer std.posix.close(null_fd);
+    const replica = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer replica.deinit();
+    var ov = predict.Overlay.init(alloc, 80, 24);
+    defer ov.deinit();
+    ov.setMode(.{ .icanon = true, .echo = true });
+    const tty = proto.Size{ .cols = 80, .rows = 24 };
+    // An arrow key: three bytes, and predicting its lead byte would paint an
+    // escape character on the screen.
+    offerKeystroke(alloc, &ov, replica, "\x1b[A", tty, null_fd);
+    // A multi-byte character, whose display width we do not know.
+    offerKeystroke(alloc, &ov, replica, "é", tty, null_fd);
+    // And a lone control byte, which goes down the single-byte path and is
+    // refused there.
+    offerKeystroke(alloc, &ov, replica, "\r", tty, null_fd);
+    try std.testing.expectEqual(@as(usize, 0), ov.pendingCount());
+    try std.testing.expectEqual(@as(u64, 0), ov.counters.made);
+    try std.testing.expectEqual(@as(u64, 3), ov.counters.suppressed);
+    // A paste: several printable bytes in one read. This is the shape whose
+    // lead byte would sail through the printability check, so the length
+    // guard is the only thing refusing it — and M9 refuses it, because a
+    // paste can carry newlines and bracketed-paste markers that are not one
+    // cell's worth of change each.
+    offerKeystroke(alloc, &ov, replica, "abc", tty, null_fd);
+    try std.testing.expectEqual(@as(usize, 0), ov.pendingCount());
+    try std.testing.expectEqual(@as(u64, 0), ov.counters.made);
+    // Not counted, and deliberately asserted as not counted rather than
+    // left unsaid: a printable-lead chunk is the one refusal the overlay
+    // has no way to record, since predictAt only counts refusals it makes
+    // itself. Recorded in the M9 notes as an interface gap.
+    try std.testing.expectEqual(@as(u64, 3), ov.counters.suppressed);
+}
+test "prediction: a repaint never reveals what was never shown" {
+    const alloc = std.testing.allocator;
+    const p = try std.posix.pipe();
+    defer std.posix.close(p[0]);
+    const replica = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer replica.deinit();
+    const null_fd = try devNull();
+    defer std.posix.close(null_fd);
+    var ov = predict.Overlay.init(alloc, 80, 24);
+    defer ov.deinit();
+    ov.setMode(.{ .icanon = false, .echo = false }); // raw: unconfident
+    const tty = proto.Size{ .cols = 80, .rows = 24 };
+    offerKeystroke(alloc, &ov, replica, "a", tty, null_fd);
+    offerKeystroke(alloc, &ov, replica, "b", tty, null_fd);
+    try std.testing.expectEqual(@as(usize, 2), ov.pendingCount());
+    try std.testing.expectEqual(@as(u64, 0), ov.counters.displayed);
+    // Every authoritative paint is followed by re-laying the overlay on top,
+    // because a delta's row content wipes anything drawn over it. That
+    // repaint is a second, quieter chance to show a prediction that was
+    // never displayed in the first place — so it asks the same question the
+    // keystroke path did, and gets the same answer.
+    paintOverlay(alloc, &ov, replica.cursorPos(), tty, p[1]);
+    std.posix.close(p[1]);
+    var rbuf: [64]u8 = undefined;
+    try std.testing.expectEqual(@as(usize, 0), try std.posix.read(p[0], &rbuf));
+}
+test "the predict stats line is one greppable row of counters" {
+    var buf: [predict_stats_len]u8 = undefined;
+    const line = try formatPredictStats(&buf, .{
+        .made = 5,
+        .displayed = 4,
+        .confirmed = 3,
+        .contradicted = 2,
+        .expired = 1,
+        .suppressed = 6,
+    });
+    // Pinned exactly: test/e2e.sh greps these key=value pairs, so a rename
+    // or a reorder is a broken suite rather than a cosmetic change.
+    try std.testing.expectEqualStrings(
+        "predict made=5 displayed=4 confirmed=3 contradicted=2 expired=1 suppressed=6",
+        line,
+    );
+}
+test "Transport.close is idempotent: the abort path closes what reconnect already closed" {
+    const alloc = std.testing.allocator;