@agfpd/iapeer 0.2.87 → 0.2.88

package/package.json

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

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,14 +288,29 @@ 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 */
+  // 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
     }
-    // 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.
+  }
+  // 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 rowsArr = modelAttachSnapshotRows(xterm, cols, rows)
     if (rowsArr.length > 0) {
       const cleaned = stripSpinnerScrollback(rowsArr.join('\r\n'), rows) // dechrome scrollback, viewport verbatim
@@ -302,8 +320,13 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     initializing.delete(s as object) // snapshot sent → resume live forwarding for this client
   }
 
-  // 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 +335,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.
-    try {
-      child.terminal.resize(c, Math.max(1, r - 1))
-      child.terminal.resize(c, r)
-    } catch {
-      /* */
+  }
+  // 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) // synchronous: build + send + lift gate (no await before the child resize below)
+    // CHILD resize only when the size actually CHANGED. A reattach at the SAME geometry must NOT SIGWINCH the
+    // child — a gratuitous SIGWINCH makes claude re-render on-screen content, which (if taller than the
+    // viewport) scrolls a DUPLICATE copy into the model. Same-size reattach = pure snapshot, zero pollution.
+    if (changed) {
+      try {
+        child.terminal.resize(c, r) // SIGWINCH the child → live reflow (post-snapshot, forwarded live)
+      } catch {
+        /* transient */
+      }
     }
   }
   // Restore the serve geometry when the last client detaches, so the unattached session never sticks at
@@ -334,14 +380,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.
     }
   }