@agfpd/iapeer 0.2.87 → 0.2.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.87",
+  "version": "0.2.89",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/shadow/render.ts

@@ -30,22 +30,19 @@ export function modelToPlainText(term: Terminal, cols: number, rows: number): st
 }
 
 /**
- * ATTACH SNAPSHOT (scrollback fix): the FULL model buffer — scrollback (`0..baseY`) + live viewport
- * (`baseY..baseY+rows`) — as PHYSICAL rows of plain text. This is the resolved-buffer reconstruction:
- * the @xterm model has already flattened claude's thousands of relative-cursor in-place redraws
- * (no DECSTBM, no alt-screen — see the daemon census) into final COMMITTED lines, so emitting these
- * rows as `line\r\n` into a fresh terminal reproduces native scrollback with NO duplication. Replaying
- * the child's RAW frame bytes can't do this (relative cursor-up can't reach scrolled-off lines on a
- * linear dump → overlap), and SerializeAddon re-emits escapes that the no-scroll-region redraws turn
- * into duplicate scrollback. Trailing blank rows are dropped so a fresh/short session emits no wall of
- * blanks. SGR colour is a deliberate follow-up — plain text first kills the mush without colour as a
- * second source of truth.
+ * ATTACH HISTORY rows — the model's SCROLLBACK ONLY (rows `0..baseY`, the committed history ABOVE the
+ * live viewport), as physical rows of plain text. The LIVE viewport (`baseY..`) is DELIBERATELY EXCLUDED:
+ * claude paints the current screen itself (its live render, forwarded right after attach), so including
+ * the viewport here would DOUBLE-PAINT it — the snapshot's copy collides with claude's live repaint →
+ * smeared overlap (the recurring bug). So on attach we ONLY prepend the history; claude shows the current
+ * screen. The @xterm model has already flattened claude's relative-cursor redraws into committed lines, so
+ * these rows render as native scrollback with no duplication. Trailing blank rows are dropped. SGR colour
+ * is a deliberate follow-up — plain text first.
  */
-export function modelAttachSnapshotRows(term: Terminal, cols: number, rows: number): string[] {
+export function modelAttachSnapshotRows(term: Terminal, cols: number): string[] {
   const b = term.buffer.active
   const out: string[] = []
-  const end = b.baseY + rows
-  for (let y = 0; y < end; y++) {
+  for (let y = 0; y < b.baseY; y++) {
     const l = b.getLine(y)
     out.push(l ? l.translateToString(true, 0, cols) : '')
   }

package/src/supervisor/daemon.ts

@@ -176,9 +176,11 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   // client leaves this set and live forwarding resumes — no gap, no duplication.
   const initializing = new WeakSet<object>()
   // MODEL-WRITE PARSE BARRIER: @xterm `write` is async (parsed on an internal queue). The attach snapshot
-  // must be built only AFTER in-flight writes have parsed, else it reflects a stale screen. We chain the
-  // latest write's parse-callback; repaint awaits it before reading the buffer.
+  // must be built only AFTER in-flight writes have parsed AND none arrived during the wait, else it reflects
+  // a stale screen / drops bytes that landed while the client was gated. `writeChain` tracks the latest
+  // write's parse-callback; `writeSeq` bumps on every write so the drain can detect new arrivals mid-await.
   let writeChain: Promise<void> = Promise.resolve()
+  let writeSeq = 0
   // ATTACHED-CLIENT MARKER (spawn-flip Ф0b-3 slice 3c): keep `<runDir>/<session>.attached` in sync with
   // clients.size — present iff ≥1 operator is attached. The warm-deliver path (a DIFFERENT process)
   // reads it to gate the hosted busy-composer hold: hold ONLY when a human is attached (their unfinished
@@ -232,6 +234,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
             /* best-effort */
           }
         const s = buf.toString('latin1')
+        writeSeq++ // a new write arrived (lets the attach drain detect bytes that land mid-await)
         writeChain = new Promise<void>(resolve => xterm.write(buf, () => resolve())) // authoritative model (+ parse barrier)
         for (const r of capabilityResponses(s)) child.terminal.write(r) // answer capability queries
         const fwd = Buffer.from(stripQueries(s), 'latin1') // forward to clients sans queries (daemon is authoritative)
@@ -285,25 +288,46 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
    *  (BackpressureWriter) — a large snapshot MUST NOT drop past the socket buffer (port-dep #2). Called
    *  EXACTLY ONCE per client (its first FRAME_RESIZE). NO clears (\x1b[2J/3J): a fresh window needs none,
    *  and Apple Terminal scrolls 2J into scrollback + ignores 3J. */
-  const repaint = async (s: { write(b: Buffer): number }): Promise<void> => {
-    try {
-      await writeChain // ensure in-flight model writes have parsed before snapshotting
-    } catch {
-      /* a write parse-callback should not reject; snapshot from whatever has parsed */
-    }
-    // Synchronous from here — NO await — so the live data() handler cannot interleave between building the
-    // snapshot and lifting the gate (single-threaded), guaranteeing no gap and no double-forward.
-    const rowsArr = modelAttachSnapshotRows(xterm, cols, rows)
-    if (rowsArr.length > 0) {
-      const cleaned = stripSpinnerScrollback(rowsArr.join('\r\n'), rows) // dechrome scrollback, viewport verbatim
-      const body = '\x1b[0m' + terminalModesPrefix(xterm) + cleaned + '\r\n'
-      sendClient(s, frame(FRAME_DATA, Buffer.from(body, 'utf8'))) // UTF-8: rows carry real glyphs (❯, box chars)
+  // Await until the model has parsed ALL writes AND none arrived during the wait (stable). Awaiting a single
+  // write promise is not enough: while the client is gated (initializing, live-forward skipped) new child
+  // bytes still land in the model and bump writeSeq — loop until the sequence holds steady so the snapshot
+  // reflects every byte received so far (no stale screen, no dropped tail).
+  const awaitModelParsedStable = async (): Promise<void> => {
+    for (;;) {
+      const seq = writeSeq
+      try {
+        await writeChain
+      } catch {
+        /* a write parse-callback should not reject */
+      }
+      if (seq === writeSeq) return
     }
-    initializing.delete(s as object) // snapshot sent → resume live forwarding for this client
+  }
+  // Build + send the one-time attach SNAPSHOT of the resolved model and LIFT the initializing gate —
+  // SYNCHRONOUS (no await), so the live data() handler cannot interleave between building the snapshot and
+  // resuming live-forward (single-threaded) → no gap, no double-forward. Called only from firstAttach, which
+  // owns the full order (drain → model-resize → THIS → child-resize). It is a SNAPSHOT of the resolved @xterm
+  // model (committed scrollback + viewport rows), NOT a raw-frame replay / SerializeAddon — both corrupt
+  // scrollback for claude's relative-cursor, no-scroll-region TUI. Scrollback rows are spinner-stripped, the
+  // viewport is verbatim. NO clears (\x1b[2J/3J): a fresh window needs none; Apple Terminal mishandles them.
+  const sendSnapshot = (s: { write(b: Buffer): number }): void => {
+    const historyRows = modelAttachSnapshotRows(xterm, cols) // SCROLLBACK only — claude paints the viewport live
+    const cleaned = stripSpinnerScrollback(historyRows.join('\r\n'), 0) // strip spinner remnants from ALL of history
+    // Prepend the committed HISTORY above the screen claude is about to repaint, after a modes-restore prefix.
+    // NO viewport rows — that is claude's job (forwarded live), which avoids the snapshot↔live double-paint
+    // overlap. Always send at least the modes prefix (restores bracketed-paste / app-cursor for a fresh session).
+    const body = '\x1b[0m' + terminalModesPrefix(xterm) + (cleaned ? cleaned + '\r\n' : '')
+    sendClient(s, frame(FRAME_DATA, Buffer.from(body, 'utf8'))) // UTF-8: rows carry real glyphs (❯, box chars)
+    initializing.delete(s as object) // history sent → resume live forwarding (claude's viewport repaint)
   }
 
-  // Resize the model + child pty to (c, r). Shared by client FRAME_RESIZE and the last-detach restore.
+  // Resize the model + child pty to (c, r). Shared by LATER client resizes and the last-detach restore.
+  // NO-OP when already at (c,r): a gratuitous resize SIGWINCHes the child → claude reflows its WHOLE
+  // transcript, and when that reflow is taller than the viewport the overflow scrolls into the model's
+  // scrollback as a DUPLICATE copy (the scrollback-pollution root). One real resize = one SIGWINCH; the
+  // old (r-1)→r "nudge" doubled every SIGWINCH and is removed for the same reason.
   const applyGeometry = (c: number, r: number): void => {
+    if (c === cols && r === rows) return // unchanged → no SIGWINCH → no reflow → no scrollback pollution
     cols = c
     rows = r
     try {
@@ -312,14 +336,37 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     } catch {
       /* transient */
     }
-    // Best-effort SIGWINCH nudge for a SIGWINCH-reactive child (forces a repaint at the new size); NOT
-    // load-bearing for an attached client (the complete snapshot repaint is), but for the unattached
-    // restore it is what makes the child redraw into the pane-log at the serve geometry.
+  }
+  // FIRST attach for a client. Order matters for a clean frame0 (codex review):
+  //   1. DRAIN to stability — pending child bytes were generated under the OLD pty geometry; parsing them
+  //      AFTER a model resize would rewrap them wrong, and the drain also captures bytes that land while the
+  //      client is gated, so they make the snapshot rather than being lost.
+  //   2. MODEL resize to the client geometry (so the snapshot wraps at the client's width).
+  //   3. SNAPSHOT — build + send + lift gate, SYNCHRONOUS (no await), so no live byte interleaves.
+  //   4. CHILD resize → SIGWINCH → claude's live reflow, forwarded AFTER the snapshot (post-gate).
+  // Resizing the child FIRST would SIGWINCH claude into a reflow whose bytes pollute frame0.
+  const firstAttach = async (s: { write(b: Buffer): number }, c: number, r: number): Promise<void> => {
+    await awaitModelParsedStable()
+    const changed = c !== cols || r !== rows
+    if (changed) {
+      try {
+        xterm.resize(c, r) // MODEL only — not the child yet
+      } catch {
+        /* transient */
+      }
+      cols = c
+      rows = r
+    }
+    sendSnapshot(s) // prepend the scrollback HISTORY (no viewport) + lift gate — synchronous, no interleave
+    // Force claude to repaint its CURRENT viewport BELOW the prepended history. A SIGWINCH triggers a full
+    // redraw; the (r-1)→r nudge guarantees it fires even on a SAME-size reattach (else an idle claude would
+    // leave the viewport blank until its next frame). Safe now: the snapshot carries NO viewport, so claude's
+    // repaint has nothing to collide with — the smeared-overlap class is gone at its source.
     try {
       child.terminal.resize(c, Math.max(1, r - 1))
       child.terminal.resize(c, r)
     } catch {
-      /* */
+      /* transient */
     }
   }
   // Restore the serve geometry when the last client detaches, so the unattached session never sticks at
@@ -334,14 +381,12 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       child.terminal.write(payload) // keystrokes → child
     } else if (type === FRAME_RESIZE) {
       const sz = parseSize(payload)
-      applyGeometry(sz.cols, sz.rows)
       if (!painted.has(s as object)) {
         painted.add(s as object)
-        void repaint(s) // FIRST resize for this client = the one-time catch-up (model snapshot at its real size)
+        void firstAttach(s, sz.cols, sz.rows) // split-resize: model → snapshot → gate-lift → child (clean frame0)
+      } else {
+        applyGeometry(sz.cols, sz.rows) // LATER resize: one real resize, no re-snapshot
       }
-      // LATER resizes: nothing from the supervisor. applyGeometry already SIGWINCH'd the child → it
-      // redraws its own viewport (forwarded live) and the terminal reflows its own scrollback, exactly
-      // like a directly-launched claude. Re-dumping here would stack history in a no-\x1b[3J terminal.
     }
   }