create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/state-sync/frame-emitter.js

@@ -4,24 +4,35 @@
 // shape, keyed PER CLIENT (a "delivery" = sessionId + clientId + socketGeneration) instead of
 // per-session, because CTM (unlike 0.9.33) fans one session out to more than one viewer.
 //
+// WP-1 (docs/state-sync-pipelined-deltas-echo-never-waits-for-ack-2026-10-31.html §5 D-1..D-5):
+// the single in-flight slot is replaced IN PLACE by a BOUNDED WINDOW of unacked frames per delivery
+// (Mosh's rule: diff each frame against the last state SENT, and let an ack advance only what is
+// assumed received). No flag: the window is the only code path.
+//
 // The whole state machine, per delivery:
-//   mirror updated  -> in flight?              dirty=true, refuse
-//                   -> else rate gate           refuse('rate')
-//                   -> owedKeyframe/dims changed -> keyframe   (else diff vs ackedGrid)
+//   mirror updated  -> window full (≥8 frames or ≥256 KiB)?  dirty=true, refuse('window-full')
+//                   -> else rate gate                         refuse('rate')
+//                   -> owedKeyframe/dims changed -> keyframe   (else diff vs sentGrid)
 //                   -> nothing changed (rows+cursor) -> nothing
-//   ack(seq)        -> seq === inFlightSeq -> advance base, retire acked scrollback, clear in
-//                      flight, flush one dirty catch-up (bypass rate). Any other seq -> ignore.
-//                      NO proofs, NO dispositions, NO suppression.
-//   keyframe req    -> ALWAYS served for a known delivery (reset base, clear in flight, force).
-//                      Unknown delivery -> attach it, then serve. Never refused.
-//   undeliverable   -> clear in flight; a dropped KEYFRAME owes one (owedKeyframe=true); a
-//                      dropped delta is simply dirty (next emit diffs losslessly against ackedGrid).
-//   sweep           -> in flight past stallMs -> clear in flight, force a keyframe. Nothing else.
+//   ack(seq)        -> an entry SEQUENCE === seq is in the window -> retire every entry with
+//                      seq ≤ seq in order (advance ackedSeq/ackedGridRevision/ackedGrid to that
+//                      entry, retire its scroll-out counts, sample RTT from THAT entry only,
+//                      never a resent one), then flush one dirty catch-up (bypass rate).
+//                      Any other seq -> ignore. NO proofs, NO dispositions, NO suppression.
+//   keyframe req    -> ALWAYS served for a known delivery (reset base, clear window, force) UNLESS
+//                      a KEYFRAME already in the window is newer than the client's haveSeq (WP-2
+//                      D-6: that keyframe IS the answer). Unknown delivery -> attach, then serve.
+//                      Never refused.
+//   undeliverable   -> the named seq is in the window: drop every entry with seq ≥ it, keep the
+//                      rest (they still reach the client, in order), owe ONE keyframe whose
+//                      scroll-out base is the newest kept grid (rows the client already has are not
+//                      re-donated). A seq not in the window is a no-op. Do not emit here.
+//   sweep           -> the OLDEST entry past stallMs -> clear the window, force a keyframe. Nothing else.
 //   attach/detach   -> create/delete the delivery. Nothing else remembers a client.
 //
 // No suppression latch, no no-audience stand-down, no nack-episode/content-fence bookkeeping, no
 // client-fault squelch, no interactive-supersession lane, no revision-store eviction/fencing. A
-// delivery either has a frame in flight or it doesn't; a keyframe either fixes it or the sweep does.
+// delivery has a bounded window of unacked frames; a keyframe either fixes it or the sweep does.
 
 const { computeAnsiPatch } = require('./cell-diff'); const { stripWrapPrefix } = require('./row-serializer');const { paintedFrameField } = require('./painted-frame-field');
 const { frameDue, noteEmit } = require('./frame-rate');
@@ -31,6 +42,12 @@ const { normalizeMouseTracking, normalizeMouseEncoding } = require('./surface-mo
 const EMPTY_GRID = { cols: 0, rows: 0, rowAnsi: [] };
 const DEFAULT_SCROLL_OUT_MAX = 400;
 const DEFAULT_MAX_ACTIVE_CLIENTS = 32;
+// WP-1 (§5 D-2, §6): the per-delivery unacked window. Module constants, never env flags -- the
+// rollback is branch isolation + git revert. Frames are 2–19 KB measured, so 8 frames ≈ 152 KB <
+// 256 KiB < the 1 MiB stream high-water; at the 16 ms frame floor 8 frames = 128 ms of output ahead
+// of the oldest ack. Overridable ONLY by the test injection (deps.windowFrames / deps.windowBytes).
+const STATE_SYNC_WINDOW_FRAMES = 8;
+const STATE_SYNC_WINDOW_BYTES = 262144;
 
 function parseScrollOutMax(value) {
   if (value === null || value === undefined || value === '') return DEFAULT_SCROLL_OUT_MAX;
@@ -173,10 +190,18 @@ function newDeliveryState() {
     ackedGrid: EMPTY_GRID,
     ackedSeq: 0,
     ackedGridRevision: 0,
+    // WP-1 (§5 D-1/D-2): the unacked window, ordered oldest→newest, and the last state SENT (the
+    // assumed receiver state a fresh delta diffs against). inFlightSeq/inFlightKind/inFlightAt are
+    // DERIVED from the OLDEST entry by syncOldest() and kept for readers/tests.
+    inFlight: [],
+    inFlightBytes: 0,
     inFlightSeq: 0,
-    inFlightGrid: null,
     inFlightAt: 0,
     inFlightKind: '', // report-only, for onRefused's gate name
+    sentGrid: EMPTY_GRID,
+    sentSeq: 0,
+    sentGridRevision: 0,
+    resetBaseGrid: null, // D-5: the scroll-out base for the keyframe after a mid-window drop
     dirty: false,
     owedKeyframe: false,
     fr: { lastEmitAt: 0 },
@@ -186,12 +211,17 @@ function newDeliveryState() {
     lastAckClientId: '',
     pendingScrollbackRows: [],
     pendingScrollbackElidedCount: 0,
-    inFlightScrollbackRowCount: 0,    // retire-on-ack: how much of the queue THIS in-flight frame carried
-    inFlightScrollbackElidedCount: 0,
-    pendingClearScrollback: false,    // a clearScrollback request coalesced behind an in-flight frame
+    pendingClearScrollback: false,    // a clearScrollback request coalesced behind a full window
     surfaceEpoch: 0,
     surfaceIdentity: null,
     sweepResends: 0, // how many times sweepStalledInFlight has re-emitted into this delivery since its last ack
+    // WP-2 (§5 D-5, docs/remote-relay-ack-rate-limit-typing-delay-2026-10-28.html): this delivery's
+    // own measured ack RTT (RFC 6298 §2 SRTT/RTTVAR), so the lost-ack watchdog is sized from the
+    // real round trip instead of one global 3 s constant. Per DELIVERY, so a slow viewer's history
+    // never inflates a fast viewer's stall.
+    srttMs: 0,
+    rttvarMs: 0,
+    rttSamples: 0,
   };
 }
 
@@ -199,17 +229,92 @@ function deliveryKey(clientId, socketGeneration) {
   return JSON.stringify([String(clientId || ''), Number(socketGeneration || 0)]);
 }
 
+// WP-1 (§5 D-1, §6): the ONE place the derived oldest-entry fields are maintained. Called after
+// every window change (push, retire, clear) so inFlightSeq/inFlightKind/inFlightAt always name the
+// OLDEST unacked entry (0/''/0 when the window is empty), which is what the sweep and the
+// diagnostics read.
+function syncOldest(s) {
+  const oldest = s.inFlight[0];
+  s.inFlightSeq = oldest ? oldest.seq : 0;
+  s.inFlightKind = oldest ? oldest.kind : '';
+  s.inFlightAt = oldest ? oldest.at : 0;
+}
+
+// WP-0 (D-4c): hand one lost-ack recovery to the caller's report-only hook. The recovery has
+// ALREADY happened by the time this runs, so a throwing hook is swallowed rather than allowed to
+// abort the sweep mid-loop.
+function _noteRecovered(opts, id, info) {
+  try {
+    if (opts && typeof opts.onRecovered === 'function') opts.onRecovered(id, info);
+  } catch {
+    // expected: diagnostics hook fault never breaks recovery
+  }
+}
+
+// WP-0 (D-5, docs/state-sync-pipelined-deltas-echo-never-waits-for-ack-2026-10-31.html §5 D-5,
+// §9 S-11): hand ONE matched ack's round trip to the caller's report-only hook, while both legs are
+// still knowable — the host leg is measured here (send -> ack), the main leg is passed through from
+// the worker (`ctx.mainRttMs`, the ledger's own sentAt delta). Diagnostics only: the ack has already
+// been applied by the time this runs, so a throwing hook is swallowed rather than allowed to abort
+// the delivery's ack path.
+function _noteAcked(deps, id, info) {
+  try {
+    if (deps && typeof deps.onAcked === 'function') deps.onAcked(id, info);
+  } catch {
+    /* expected: report-only diagnostics hook must never break the ack path */
+  }
+}
+
+// WP-2 (RFC 6298 §2, docs/remote-relay-ack-rate-limit-typing-delay-2026-10-28.html §5 D-5, §6):
+// fold one measured ack RTT into the delivery's SRTT/RTTVAR. The first sample seeds SRTT = R and
+// RTTVAR = R/2; every later sample uses  RTTVAR = 3/4·RTTVAR + 1/4·|SRTT − R|  then
+// SRTT = 7/8·SRTT + 1/8·R. A non-finite or negative sample (clock skew, a stale inFlightAt) is
+// dropped rather than allowed to poison the estimate.
+function noteAckRtt(state, sampleMs) {
+  if (!state) return;
+  const r = Number(sampleMs);
+  if (!Number.isFinite(r) || r < 0) return;
+  if (!Number(state.rttSamples)) {
+    state.srttMs = r;
+    state.rttvarMs = r / 2;
+  } else {
+    const srtt = Number(state.srttMs) || 0;
+    state.rttvarMs = 0.75 * (Number(state.rttvarMs) || 0) + 0.25 * Math.abs(srtt - r);
+    state.srttMs = 0.875 * srtt + 0.125 * r;
+  }
+  state.rttSamples = Number(state.rttSamples || 0) + 1;
+}
+
+// A delivery with no ack sample yet keeps the caller's CEILING (today's fixed 3 s), so the very
+// first attach can never be spuriously recovered. Once sampled, the stall is clamp(SRTT + 4·RTTVAR)
+// bounded below by the private-path floor (mosh's MIN_RTO intuition, §5 P3) and above by the same
+// ceiling (the CTM_STATE_SYNC_INFLIGHT_STALL_MS override).
+function stallMsFor(state, opts) {
+  const ceilingMs = Number(opts && opts.ceilingMs);
+  const ceiling = Number.isFinite(ceilingMs) ? ceilingMs : 0;
+  const rawFloor = Number(opts && opts.floorMs);
+  const floor = Number.isFinite(rawFloor) ? rawFloor : 250;
+  if (!state || !Number(state.rttSamples)) return ceiling;
+  const rto = (Number(state.srttMs) || 0) + 4 * (Number(state.rttvarMs) || 0);
+  return Math.min(ceiling, Math.max(floor, rto));
+}
+
 function createFrameEmitter(deps) {
   deps = deps || {};
   const send = deps.send || (() => {});
   // WP-0b (§5 D-2, §6): report-only hook so a caller can attribute a refused emit to its exact
-  // gate. WP-2 reduces the enum to the two gates that still exist: in-flight-delta |
-  // in-flight-keyframe | rate (see lib/typing-interaction-trace.js GATES).
+  // gate. WP-1 reduces the enum to the two gates that still exist: window-full | rate (see
+  // lib/typing-interaction-trace.js GATES; the old in-flight-* names are kept there so pre-WP-1
+  // rows still parse).
   const onRefused = deps.onRefused || (() => {});
   const log = deps.log || (() => {});
   const extractGrid = deps.extractGrid || (() => EMPTY_GRID);
   const now = deps.now || (() => Date.now());
   const frameOpts = deps.frameOpts || {};
+  // §5 D-2/D-8: the window bounds are module constants, overridable ONLY by the test injection --
+  // never an env flag.
+  const windowFrames = Math.max(1, Number(deps.windowFrames) || STATE_SYNC_WINDOW_FRAMES);
+  const windowBytes = Math.max(1, Number(deps.windowBytes) || STATE_SYNC_WINDOW_BYTES);
   const scrollOutMax = parseScrollOutMax(
     deps.scrollOutMax ?? frameOpts.scrollOutMax ?? process.env.CTM_STATE_SYNC_SCROLL_OUT_MAX
   );
@@ -277,36 +382,49 @@ function createFrameEmitter(deps) {
     return { rows, elided };
   }
 
-  // The one send path. Assumes the caller has already decided this delivery may emit right now
-  // (nothing in flight). Gate 2 budget: ≤60 lines / 8 ifs / 6 returns.
+  // The one send path. Gate 2 budget: ≤72 lines / 8 ifs / 6 returns.
   function emit(id, delivery, opts = {}) {
     const session = st(id);
     const s = delivery.state;
     const t = now();
     const grid = extractGrid(id) || EMPTY_GRID;
-    const ackedGrid = s.ackedGrid || EMPTY_GRID;
     const identityChanged = surfaceIdentityChanged(s, grid);
-    const keyframeFrame = !!opts.force || !!s.owedKeyframe || identityChanged || Number(s.ackedSeq || 0) === 0;
-    const cursorMoved = !cursorsEqual(grid.cursor, ackedGrid.cursor);
-    const hasPendingScrollback = s.pendingScrollbackRows.length > 0 || s.pendingScrollbackElidedCount > 0;
-    if (!keyframeFrame && !cursorMoved && !opts.clearScrollback && !hasPendingScrollback && gridsEqual(grid, ackedGrid)) {
+    // §5 D-1: a delta diffs against the last state SENT (the assumed receiver state), not the last
+    // acked one -- with a window, several frames can be unacked and each must build on its
+    // predecessor. The first frame of a delivery (or after any reset) is still a keyframe: the
+    // keyframe rule keys on sentSeq === 0, never ackedSeq (which stays 0 until the first ack, so
+    // every emit before it would otherwise be a keyframe).
+    const keyframeFrame = !!opts.force || !!s.owedKeyframe || identityChanged || Number(s.sentSeq || 0) === 0;
+    // §5 D-5: after a mid-window drop the next keyframe re-donates scroll-out rows against the
+    // newest KEPT entry's grid (the client already has those rows), then the override is consumed.
+    const baseGrid = keyframeFrame
+      ? (s.resetBaseGrid || s.ackedGrid || EMPTY_GRID)
+      : (s.sentGrid || EMPTY_GRID);
+    if (keyframeFrame) s.resetBaseGrid = null;
+    const cursorMoved = !cursorsEqual(grid.cursor, baseGrid.cursor);
+    // No pending-scrollback term: a refused update leaves nothing owed, because the next emit
+    // recomputes its scroll-out rows against sentGrid (and a drop forces a keyframe, D-5).
+    if (!keyframeFrame && !cursorMoved && !opts.clearScrollback && gridsEqual(grid, baseGrid)) {
       return false;
     }
-    // A keyframe still diffs its scroll-out recovery against the delivery's own last-known
-    // ackedGrid (a WIRE reset declares baseSeq 0, but internally the diff base is only actually
-    // discarded by resetDeliveryBaseline -- a snapshot/restore reset, where ackedGrid is already
-    // EMPTY_GRID here and scrollOutRecovery is naturally a no-op). This is "lossless by
-    // construction" (R-2): a dropped/coalesced frame never advances ackedGrid, so the NEXT
-    // successful emit recomputes the SAME recovery fresh against the unchanged base -- there is no
-    // separate multi-frame queue to lose track of or retire.
-    const recovery = scrollOutRecovery(id, ackedGrid, grid);
+    // Each frame carries exactly the scroll-out rows between ITS base and its grid. For a delta that
+    // is the predecessor frame's grid; for a keyframe it is the delivery's own last-known grid (a
+    // WIRE reset declares baseSeq 0, but the internal diff base is only discarded by
+    // resetDeliveryBaseline -- a snapshot/restore reset, where ackedGrid is already EMPTY_GRID here
+    // and scrollOutRecovery is naturally a no-op) or the kept base a drop left behind (D-5).
+    const recovery = scrollOutRecovery(id, baseGrid, grid);
+    const batch = recovery.delta > 0 ? scrollbackBatch(baseGrid, recovery.delta, recovery.rows, recovery.elided) : { rows: [], elided: 0 };
+    // The frame's (and its window entry's) scroll-out counts are THIS frame's batch only -- a later
+    // frame must never re-advertise rows/elision an earlier unacked frame carried (the client draws
+    // one elision marker per frame that reports scrollbackElidedCount > 0). pendingScrollback* is
+    // the queue of rows carried by the unacked frames; onAck retires each entry's share in order.
     if (keyframeFrame || opts.clearScrollback) { s.pendingScrollbackRows = []; s.pendingScrollbackElidedCount = 0; }
-    const batch = recovery.delta > 0 ? scrollbackBatch(ackedGrid, recovery.delta, recovery.rows, recovery.elided) : { rows: [], elided: 0 };
-    if (recovery.delta > 0) { s.pendingScrollbackRows = batch.rows; s.pendingScrollbackElidedCount = batch.elided; }
-    const pendingRowCount = s.pendingScrollbackRows.length;
-    const pendingElidedCount = s.pendingScrollbackElidedCount;
+    s.pendingScrollbackRows = s.pendingScrollbackRows.concat(batch.rows);
+    s.pendingScrollbackElidedCount += batch.elided;
+    const pendingRowCount = batch.rows.length;
+    const pendingElidedCount = batch.elided;
     const scrollbackDelta = recovery.delta;
-    let patch = computeAnsiPatch(ackedGrid, grid, {
+    let patch = computeAnsiPatch(baseGrid, grid, {
       scrolledOutRows: batch.rows, scrolledOutElidedCount: batch.elided,
       clearScrollback: opts.clearScrollback, keyframe: keyframeFrame,
     });
@@ -323,7 +441,7 @@ function createFrameEmitter(deps) {
     if (cursorMoved && !keyframeFrame) {
       const cursorRows = new Set(Array.isArray(patch.changedRows) ? patch.changedRows : []);
       const gridRows = Number(grid.rows) || 0;
-      for (const row of [Number(ackedGrid.cursor?.row || 0), Number(grid.cursor?.row || 0)]) {
+      for (const row of [Number(baseGrid.cursor?.row || 0), Number(grid.cursor?.row || 0)]) {
         if (row > 0 && row <= gridRows) cursorRows.add(row);
       }
       patch = { ...patch, changedRows: Array.from(cursorRows).sort((a, b) => a - b) };
@@ -331,14 +449,14 @@ function createFrameEmitter(deps) {
     }
     const authority = frameAuthority(s, grid, patch, keyframeFrame, identityChanged);
     const frame = {
-      type: 'frame', id, seq, gridRevision: seq, baseGridRevision: keyframeFrame ? 0 : Number(s.ackedGridRevision || 0),
+      type: 'frame', id, seq, gridRevision: seq, baseGridRevision: keyframeFrame ? 0 : Number(s.sentGridRevision || 0),
       ...authority,
       keyframe: keyframeFrame, displayStable: keyframeFrame,
-      ...paintedFrameField(deps, id, keyframeFrame, ackedGrid, grid), // D-6: the reader's painted-row position (and the rows this viewer lacks)
+      ...paintedFrameField(deps, id, keyframeFrame, baseGrid, grid), // D-6: the reader's painted-row position (and the rows this viewer lacks)
       scrollbackDelta,
       ...(pendingRowCount > 0 ? { scrollbackRowCount: pendingRowCount } : {}),
       ...(pendingElidedCount > 0 ? { scrollbackElidedCount: pendingElidedCount } : {}),
-      baseSeq: keyframeFrame ? 0 : s.ackedSeq,
+      baseSeq: keyframeFrame ? 0 : Number(s.sentSeq || 0),
       ansiPatch: patch.ansi,
       cursor: grid.cursor || null,
       rows: Number(grid.rows) || 0,
@@ -352,12 +470,19 @@ function createFrameEmitter(deps) {
       ...(opts.requestToken ? { requestToken: String(opts.requestToken) } : {}),
     };
     send(id, frame);
-    s.inFlightSeq = seq;
-    s.inFlightScrollbackRowCount = pendingRowCount;
-    s.inFlightScrollbackElidedCount = pendingElidedCount;
-    s.inFlightKind = keyframeFrame ? 'keyframe' : 'delta';
-    s.inFlightGrid = grid;
-    s.inFlightAt = t;
+    // §5 D-2/D-3: the entry is the retire-on-ack record -- its byte cost bounds the window, and its
+    // scroll-out counts are retired when (and only when) this seq is acked.
+    const bytes = Buffer.byteLength(String(patch.ansi || ''), 'utf8');
+    s.inFlight.push({
+      seq, at: t, kind: keyframeFrame ? 'keyframe' : 'delta', grid, bytes,
+      scrollbackRowCount: pendingRowCount,
+      scrollbackElidedCount: pendingElidedCount,
+    });
+    s.inFlightBytes += bytes;
+    s.sentGrid = grid;
+    s.sentSeq = seq;
+    s.sentGridRevision = seq;
+    syncOldest(s);
     return true;
   }
 
@@ -371,19 +496,25 @@ function createFrameEmitter(deps) {
     state.ackedGrid = EMPTY_GRID;
     state.ackedSeq = 0;
     state.ackedGridRevision = 0;
+    // §5 D-5: the SENT baseline is gone too -- the next emit is a keyframe (sentSeq 0 still fails
+    // the keyframe rule) and must not diff against a state the client never had.
+    state.sentGrid = EMPTY_GRID;
+    state.sentSeq = 0;
+    state.sentGridRevision = 0;
+    state.resetBaseGrid = null;
   }
 
   // A keyframe-req / lost-ack recovery is a WIRE reset (frame.baseSeq/baseGridRevision go to 0 --
-  // the client repaints everything) but internally keeps the delivery's own last-known ackedGrid as
-  // the scroll-out diff base, exactly like the sweep's lost-ack recovery always has -- otherwise a
-  // desync resync would silently drop whatever scrolled out of view since the last ack.
+  // the client repaints everything) but internally keeps the delivery's own last-known grid as the
+  // scroll-out diff base, exactly like the sweep's lost-ack recovery always has -- otherwise a
+  // desync resync would silently drop whatever scrolled out of view since the last ack. WP-1 (§5
+  // D-2): "clear in flight" now means EMPTY THE WHOLE WINDOW.
   function clearInFlightOnly(state) {
-    state.inFlightSeq = 0;
-    state.inFlightGrid = null;
-    state.inFlightScrollbackRowCount = 0;
-    state.inFlightScrollbackElidedCount = 0;
+    state.inFlight = [];
+    state.inFlightBytes = 0;
     state.pendingClearScrollback = false;
     state.dirty = false;
+    syncOldest(state);
   }
 
   // The clientId-less keyframe entry point (resize / set-visibility / restore-hold release / a
@@ -432,17 +563,22 @@ function createFrameEmitter(deps) {
       let sent = false;
       forEachDelivery(id, (delivery) => {
         const s = delivery.state;
-        if (s.inFlightSeq) {
+        // §5 D-2: refuse ONLY when the window is full -- one frame in flight no longer holds a
+        // newer echo back. The bound is frames OR bytes; nothing else refuses.
+        if (s.inFlight.length >= windowFrames || s.inFlightBytes >= windowBytes) {
           s.dirty = true;
           if (ctx.clearScrollback) s.pendingClearScrollback = true;
-          onRefused(id, s.inFlightKind === 'keyframe' ? 'in-flight-keyframe' : 'in-flight-delta', {
-            inFlightSeq: s.inFlightSeq, inFlightKind: s.inFlightKind,
-            inFlightAgeMs: Math.max(0, now() - Number(s.inFlightAt || now())),
+          onRefused(id, 'window-full', {
+            inFlightCount: s.inFlight.length, inFlightBytes: s.inFlightBytes,
+            oldestSeq: s.inFlightSeq, oldestKind: s.inFlightKind,
+            oldestAgeMs: Math.max(0, now() - Number(s.inFlightAt || now())),
           });
           return;
         }
         const t = now();
-        const forced = !!s.owedKeyframe || Number(s.ackedSeq || 0) === 0;
+        // §5 D-1: "the first frame of this delivery" is sentSeq === 0, not ackedSeq === 0 -- with a
+        // window, every emit before the first ack would otherwise be a forced keyframe.
+        const forced = !!s.owedKeyframe || Number(s.sentSeq || 0) === 0;
         if (!forced && !ctx.bypassRate && !frameDue(s.fr, t, { ...frameOpts, flooding: s.flooding })) {
           onRefused(id, 'rate', {});
           return;
@@ -458,43 +594,66 @@ function createFrameEmitter(deps) {
       return sent;
     },
 
-    // seq === inFlightSeq -> advance the diff base, flush one dirty catch-up. Any other seq is
-    // ignored: no proofs, no dispositions, no suppression. Gate 2 budget: ≤20 lines / 3 ifs / 3 returns.
+    // §5 D-3: a CUMULATIVE ack -- retire every in-flight entry with seq ≤ n in order, advance the
+    // committed base to entry n, flush one dirty catch-up. A seq with no matching entry is ignored:
+    // no proofs, no dispositions, no suppression. Gate 2 budget: ≤32 lines / 3 ifs / 3 returns.
     onAck(id, seq, ctx) {
       const session = st(id);
       const n = Number(seq || 0);
       const clientKey = deliveryKey(ctx && ctx.clientId, ctx && ctx.socketGeneration);
       const delivery = ctx && ctx.clientId ? session.clients.get(clientKey) : null;
-      if (!n || !delivery || n !== delivery.state.inFlightSeq) return false;
+      if (!n || !delivery) return false;
       const s = delivery.state;
+      const entry = s.inFlight.find((e) => e.seq === n);
+      if (!entry) return false; // stale/reordered/unknown seq: touch nothing
+      // WP-0 (D-5, §9 S-11): report this ack's two round-trip legs BEFORE the window is retired --
+      // `entry.at` names the send time of the seq just matched.
+      _noteAcked(deps, id, {
+        seq: n,
+        clientId: String((ctx && ctx.clientId) || ''),
+        socketGeneration: Number((ctx && ctx.socketGeneration) || 0),
+        hostRttMs: Math.max(0, now() - Number(entry.at || now())),
+        mainRttMs: (ctx && ctx.mainRttMs) ?? -1,
+        windowFrames: STATE_SYNC_WINDOW_FRAMES,
+      });
+      // WP-2 (D-5, P4/Karn): sample the RTT of EXACTLY the entry named. A sweep re-emit mints a NEW
+      // seq, so its ack is unambiguous and samples; a late ack for a swept seq matches no entry.
+      noteAckRtt(s, now() - Number(entry.at || now()));
+      // Retire every entry at or below n, in order: exactly the scroll-out rows/elision each of
+      // those frames carried are now represented in the client's own scrollback -- never more.
+      for (const retired of s.inFlight) {
+        if (retired.seq > n) break;
+        if (retired.scrollbackRowCount > 0) s.pendingScrollbackRows.splice(0, retired.scrollbackRowCount);
+        if (retired.scrollbackElidedCount > 0) {
+          s.pendingScrollbackElidedCount = Math.max(0, s.pendingScrollbackElidedCount - retired.scrollbackElidedCount);
+        }
+        s.inFlightBytes = Math.max(0, s.inFlightBytes - Number(retired.bytes || 0));
+      }
+      s.inFlight = s.inFlight.filter((e) => e.seq > n);
       s.ackedSeq = n;
       s.ackedGridRevision = n; // this module's own convention: gridRevision === the seq that minted it
-      s.ackedGrid = s.inFlightGrid || s.ackedGrid || EMPTY_GRID;
-      s.inFlightSeq = 0;
-      s.inFlightGrid = null;
-      // Retire-on-ack: exactly the scroll-out rows/elision THIS frame carried are now represented
-      // in the client's own scrollback -- never more (a later drop must not re-donate them).
-      if (s.inFlightScrollbackRowCount > 0) s.pendingScrollbackRows.splice(0, s.inFlightScrollbackRowCount);
-      if (s.inFlightScrollbackElidedCount > 0) {
-        s.pendingScrollbackElidedCount = Math.max(0, s.pendingScrollbackElidedCount - s.inFlightScrollbackElidedCount);
-      }
-      s.inFlightScrollbackRowCount = 0;
-      s.inFlightScrollbackElidedCount = 0;
+      s.ackedGrid = entry.grid || s.ackedGrid || EMPTY_GRID;
       s.sweepResends = 0;
       s.lastAckAt = now();
       s.lastAckClientId = String(ctx.clientId || '');
+      syncOldest(s);
       // holdCatchUp is pacing, not refusal: the caller is mid synchronized-output block and its
       // own held-emit retry calls onMirrorUpdated when the block closes; dirty stays set.
       if (!s.dirty || ctx.holdCatchUp) return false;
+      if (s.inFlight.length >= windowFrames || s.inFlightBytes >= windowBytes) return false;
       s.dirty = false;
       const clearScrollback = s.pendingClearScrollback;
       s.pendingClearScrollback = false;
-      return emit(id, delivery, { bypassRate: true, clearScrollback });
+      return emit(id, delivery, { bypassRate: true, clearScrollback, echoedThroughSeq: Number(session.latestEchoedThroughSeq || 0) });
     },
 
     // ALWAYS served for a known delivery. An unknown delivery is attached (subject to the same
-    // capacity cap any other attach honors), then served -- never refused. Gate 2 budget: ≤20
-    // lines / 2 ifs / 2 returns.
+    // capacity cap any other attach honors), then served -- never refused. WP-2 (D-6): a request
+    // naming the client's own baseline seq is a NO-OP when this delivery already has a KEYFRAME in
+    // flight whose seq is ABOVE that baseline -- that keyframe IS the answer, so forcing another
+    // would double-send. Any other shape (no haveSeq, a delta in flight, an older-or-equal
+    // baseline, an unknown delivery) is served exactly as before. Gate 2 budget: ≤20 lines /
+    // 3 ifs / 3 returns.
     onKeyframeReq(id, ctx) {
       ctx = ctx || {};
       if (!ctx.clientId) return keyframeAllDeliveries(id, ctx);
@@ -509,8 +668,13 @@ function createFrameEmitter(deps) {
         // double-send. A blank cold attach ships nothing, so fall through and force one below.
         // A worker bootstrap reservation for this client (reserveBootstrap) attaches without a
         // delivery -- the bootstrap's base IS its first keyframe; nothing to force here.
-        if (!delivery || delivery.state.inFlightSeq) return true;
+        if (!delivery || delivery.state.inFlight.length > 0) return true;
       }
+      // §5 D-6: a KEYFRAME anywhere in the window whose seq is above the client's baseline already
+      // answers this request (the client will apply it and move its baseline), so re-serving would
+      // double-send. Any other shape (no haveSeq, deltas only, an older-or-equal baseline) is served.
+      if (Number.isSafeInteger(ctx.haveSeq) && ctx.haveSeq >= 0
+          && delivery.state.inFlight.some((e) => e.kind === 'keyframe' && Number(e.seq) > ctx.haveSeq)) return true;
       clearInFlightOnly(delivery.state);
       return emit(id, delivery, {
         force: true, requestToken: ctx.requestToken,
@@ -541,33 +705,59 @@ function createFrameEmitter(deps) {
       if (!delivery) return false;
       resetDeliveryBaseline(delivery.state);
       if (ctx.deferIfBlank && gridIsBlankAtHome(extractGrid(id) || EMPTY_GRID)) return false;
-      return emit(id, delivery, { force: true });
+      return emit(id, delivery, { force: true, echoedThroughSeq: Number(session.latestEchoedThroughSeq || 0) });
     },
 
-    // Lost-ack watchdog: a frame in flight past stallMs is treated as lost. Clear the in-flight
-    // slot (does NOT advance ackedGrid -- the apply was never confirmed) and force a fresh
-    // keyframe of the LATEST grid. A session with no viewers (opts.hasViewers false) is not a lost
-    // frame: nothing is re-sent to it (primary 2026-09-28: 581 resends to a hidden tab); the slot is
-    // cleared with a keyframe owed, and regaining a viewer forces it. Gate 2 budget: ≤20 lines / 4 ifs / 2 returns.
+    // Lost-ack watchdog (§5 D-5b): the OLDEST unacked entry past its stall is treated as lost.
+    // Clear the WHOLE window (does NOT advance ackedGrid -- no apply was ever confirmed) and force a
+    // fresh keyframe of the LATEST grid under a NEW seq (Karn: no seq is ever re-sent). A
+    // session with no viewers (opts.hasViewers false) is not a lost frame: nothing is re-sent to it
+    // (primary 2026-09-28: 581 resends to a hidden tab); the window is cleared with a keyframe owed,
+    // and regaining a viewer forces it. Gate 2 budget: ≤24 lines / 4 ifs / 2 returns.
+    // WP-0 (D-4c, docs/remote-relay-ack-rate-limit-typing-delay-2026-10-28.html §5 D-4c, §9 S-9):
+    // every recovery is reported to `opts.onRecovered(id, {inFlightKind, inFlightAgeMs, stallMs,
+    // hidden})` — diagnostics only, read BEFORE the in-flight slot is cleared.
+    // WP-2 (D-5, §9 S-9): the stall is now PER DELIVERY (`stallMsFor`, sized from that delivery's
+    // own measured ack RTT); `opts.stallMs` is the ceiling and `opts.floorMs` the floor (default
+    // 250 ms when absent). The reported `stallMs` is the per-delivery value actually used.
+    // WP-2 fix-1 (RFC 6298 §5.5 timer backoff): a resend mints a NEW seq, so the late ack for the
+    // old seq misses the guard and samples nothing (Karn) — the estimate cannot grow on its own, and
+    // a large keyframe on a slow relay would otherwise be re-emitted on the floor's cadence forever.
+    // Back the timer off ×2 per consecutive unacked resend (`sweepResends`, incremented below and
+    // reset to 0 by onAck), capped at the ceiling. An unsampled delivery is already at the ceiling,
+    // so the backoff only binds once sampled.
     sweepStalledInFlight(nowTs, opts) {
       const t = Number(nowTs);
       const stallMs = Number(opts && opts.stallMs);
       if (!Number.isFinite(t) || !Number.isFinite(stallMs) || stallMs <= 0) return 0;
+      const rawFloor = Number(opts && opts.floorMs);
+      const floorMs = Number.isFinite(rawFloor) ? rawFloor : 250;
       let recovered = 0;
       for (const [id, session] of sessions) {
         if (session.clients.size === 0) continue;
         const hidden = !!(opts && opts.hasViewers) && !opts.hasViewers(id);
         for (const delivery of session.clients.values()) {
           const s = delivery.state;
-          if (!s.inFlightSeq || t - Number(s.inFlightAt || 0) <= stallMs) continue;
-          s.inFlightSeq = 0;
-          s.inFlightGrid = null;
+          const deliveryStallMs = Math.min(
+            stallMs,
+            stallMsFor(s, { floorMs, ceilingMs: stallMs }) * 2 ** Math.min(Number(s.sweepResends || 0), 6)
+          );
+          if (!s.inFlight.length || t - Number(s.inFlightAt || 0) <= deliveryStallMs) continue;
+          const inFlightKind = s.inFlightKind;
+          const inFlightAgeMs = t - Number(s.inFlightAt || 0);
+          s.inFlight = [];
+          s.inFlightBytes = 0;
           s.dirty = false;
           s.owedKeyframe = s.owedKeyframe || hidden;
-          if (!hidden && emit(id, delivery, { force: true })) {
+          syncOldest(s);
+          const reEmitted = !hidden && emit(id, delivery, {
+            force: true, echoedThroughSeq: Number(session.latestEchoedThroughSeq || 0),
+          });
+          if (reEmitted) {
             s.sweepResends = Number(s.sweepResends || 0) + 1;
             recovered += 1;
           }
+          if (hidden || reEmitted) _noteRecovered(opts, id, { inFlightKind, inFlightAgeMs, stallMs: deliveryStallMs, hidden });
         }
       }
       return recovered;
@@ -595,6 +785,7 @@ function createFrameEmitter(deps) {
               socketGeneration: Number(delivery.socketGeneration || 0),
               inFlightSeq: s.inFlightSeq,
               inFlightKind: s.inFlightKind,
+              inFlightCount: s.inFlight.length,
               ackedSeq: s.ackedSeq,
               lastAckAgeMs,
               lastAckClientId: s.lastAckClientId || '',
@@ -606,9 +797,28 @@ function createFrameEmitter(deps) {
       return out;
     },
 
-    // R-2 (0.9.33 shape): the fan-out reported this exact frame never left the wire (backpressure
-    // skip). Clear in flight; a dropped KEYFRAME owes one, a dropped delta just leaves the
-    // delivery dirty -- the next emit diffs losslessly against the unchanged ackedGrid.
+    // §6: read-only window telemetry for one delivery (null when unknown). oldestAgeMs is 0 for an
+    // empty window.
+    getWindowStats(id, clientId, socketGeneration) {
+      const session = sessions.get(id);
+      if (!session) return null;
+      const delivery = session.clients.get(deliveryKey(clientId, socketGeneration));
+      if (!delivery) return null;
+      const s = delivery.state;
+      return {
+        inFlightCount: s.inFlight.length,
+        inFlightBytes: Number(s.inFlightBytes || 0),
+        oldestAgeMs: s.inFlight.length ? Math.max(0, now() - Number(s.inFlightAt || now())) : 0,
+        windowFrames: windowFrames,
+        windowBytes: windowBytes,
+      };
+    },
+
+    // §5 D-5a: the fan-out reported this exact frame never left the wire (backpressure skip /
+    // restore hold). Drop every entry with seq ≥ the named one and keep the rest -- those still
+    // reach the client, in order -- then owe ONE keyframe whose scroll-out base is the newest kept
+    // grid (so rows the client already has are not re-donated). A seq not in the window touches
+    // nothing: the frame it names already left, or was itself cleared by a later event.
     noteUndeliverable(id, ctx) {
       ctx = ctx || {};
       const session = st(id);
@@ -616,16 +826,15 @@ function createFrameEmitter(deps) {
       const delivery = ctx.clientId ? session.clients.get(clientKey) : null;
       if (!delivery) return false;
       const s = delivery.state;
-      // A skip notice names the seq it is about. A notice for a seq that is no longer the
-      // in-flight one (already acked, already re-sent, or simply stale/reordered) is about an
-      // OLDER frame -- it must never clear or otherwise touch whatever is in flight NOW.
       const noticeSeq = Number(ctx.seq || 0);
-      if (noticeSeq && noticeSeq !== s.inFlightSeq) return false;
-      const wasKeyframe = !!ctx.wasKeyframe || s.inFlightKind === 'keyframe';
-      s.inFlightSeq = 0;
-      s.inFlightGrid = null;
+      if (!s.inFlight.some((e) => e.seq === noticeSeq)) return false;
+      const kept = s.inFlight.filter((e) => e.seq < noticeSeq);
+      s.inFlight = kept;
+      s.inFlightBytes = kept.reduce((sum, e) => sum + Number(e.bytes || 0), 0);
+      s.resetBaseGrid = kept.length ? kept[kept.length - 1].grid : (s.ackedGrid || EMPTY_GRID);
+      s.owedKeyframe = true;
       s.dirty = true;
-      if (wasKeyframe) s.owedKeyframe = true;
+      syncOldest(s);
       return true;
     },
 
@@ -705,6 +914,13 @@ function createFrameEmitter(deps) {
       state.ackedGrid = reservation.grid;
       state.ackedGridRevision = reservation.gridRevision;
       state.ackedSeq = reservation.baseSeq;
+      // WP-1 (D-1): the keyframe rule keys on sentSeq, not ackedSeq. A reservation IS a known
+      // receiver state (the client holds the bootstrap snapshot at this base), so the exit state
+      // must seed the SENT base too -- otherwise the first post-activation frame would be a
+      // spurious full keyframe instead of D-9's delta on the reservation base.
+      state.sentGrid = reservation.grid;
+      state.sentGridRevision = reservation.gridRevision;
+      state.sentSeq = reservation.baseSeq;
       state.surfaceEpoch = reservation.surfaceEpoch;
       state.surfaceIdentity = {
         rows: Number(reservation.grid.rows || 0), cols: Number(reservation.grid.cols || 0),
@@ -765,4 +981,7 @@ function createFrameEmitter(deps) {
   return emitter;
 }
 
-module.exports = { createFrameEmitter, EMPTY_GRID, gridsEqual, gridIsBlankAtHome };
+module.exports = {
+  createFrameEmitter, EMPTY_GRID, gridsEqual, gridIsBlankAtHome, noteAckRtt, stallMsFor,
+  STATE_SYNC_WINDOW_FRAMES, STATE_SYNC_WINDOW_BYTES,
+};