@agfpd/iapeer 0.2.86 → 0.2.88

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.86",
+  "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/shadow/render.ts

@@ -29,6 +29,65 @@ export function modelToPlainText(term: Terminal, cols: number, rows: number): st
   return lines.join('\n')
 }
 
+/**
+ * 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.
+ */
+export function modelAttachSnapshotRows(term: Terminal, cols: number, rows: number): string[] {
+  const b = term.buffer.active
+  const out: string[] = []
+  const end = b.baseY + rows
+  for (let y = 0; y < end; y++) {
+    const l = b.getLine(y)
+    out.push(l ? l.translateToString(true, 0, cols) : '')
+  }
+  while (out.length > 0 && out[out.length - 1].trim() === '') out.pop()
+  return out
+}
+
+interface XtermModeData {
+  applicationCursorKeysMode?: boolean
+  applicationKeypadMode?: boolean
+  bracketedPasteMode?: boolean
+  sendFocusMode?: boolean
+  mouseTrackingMode?: string
+}
+
+/**
+ * Terminal MODES restore prefix for the attach snapshot. A plain-text snapshot loses the private
+ * modes the child set (bracketed paste `?2004h`, application cursor keys `?1h`, focus `?1004h`,
+ * keypad, mouse) — the RAW-byte replay restored them only INCIDENTALLY because those set-sequences
+ * sat inline in the bytes. Without them, after attach paste / arrow keys can behave unlike a native
+ * run. We re-assert them explicitly from the model's tracked mode state (proposed API; guarded).
+ * Ends by showing the cursor.
+ */
+export function terminalModesPrefix(term: Terminal): string {
+  let out = ''
+  try {
+    const m = (term as unknown as { modes?: XtermModeData }).modes
+    if (m) {
+      if (m.applicationCursorKeysMode) out += '\x1b[?1h'
+      if (m.applicationKeypadMode) out += '\x1b='
+      if (m.bracketedPasteMode) out += '\x1b[?2004h'
+      if (m.sendFocusMode) out += '\x1b[?1004h'
+      const mouse: Record<string, string> = { x10: '?9h', vt200: '?1000h', drag: '?1002h', any: '?1003h' }
+      const seq = m.mouseTrackingMode ? mouse[m.mouseTrackingMode] : undefined
+      if (seq) out += '\x1b[' + seq
+    }
+  } catch {
+    /* modes is proposed API — absent → no restore, snapshot still renders */
+  }
+  return out + '\x1b[?25h'
+}
+
 const promptGlyph = (rt: string): string => (rt === 'claude' ? '❯' : '›')
 
 /**

package/src/supervisor/client.ts

@@ -122,7 +122,9 @@ export async function runSupervisorClient(runDir: string, session: string): Prom
     })
   }
   process.on('exit', () => restore()) // last-resort sync net
-  process.stdout.write(`\x1b[2m[supervisor] attached to "${session}". detach: Ctrl-]  (session keeps running)\x1b[0m\r\n`)
+  // NO pre-repaint attach banner: any stdout (even stderr — same tty device) printed before the daemon's
+  // snapshot lands pollutes the fresh terminal's scrollback, defeating native-history reconstruction. The
+  // detach key (Ctrl-]) is documented in CLI help / the attach verb, not emitted as a scrollback line.
   // STAY ATTACHED. The client lives on its handles (raw stdin + the socket); EVERY terminal path
   // (detach Ctrl-], session-end close(), SIGHUP/SIGTERM, socket error) calls process.exit ITSELF.
   // This promise INTENTIONALLY never resolves: returning here would resolve runSupervisorClient the

package/src/supervisor/daemon.ts

@@ -6,9 +6,10 @@
 // @xterm never loads in the central router's delivery path nor in the launch/lifecycle process.
 //
 // Loads @xterm/headless as the authoritative model (boot-driver reads it; capability queries answered
-// off it). The attach catch-up is NOT a model serialize — it REPLAYS the child's recent raw output ring
-// (claude's own bytes → native scrollback, no duplication; see repaint). @xterm/headless bundles under
-// `bun build --compile` (pure JS; the Bun-native pty has no native addon).
+// off it). The attach catch-up sends a SNAPSHOT of that resolved model (scrollback + viewport as
+// committed text rows; see repaint) — NOT a replay of the child's raw frames and NOT a SerializeAddon
+// dump, both of which corrupt scrollback for a relative-cursor, no-scroll-region TUI like claude.
+// @xterm/headless bundles under `bun build --compile` (pure JS; the Bun-native pty has no native addon).
 import { Terminal } from '@xterm/headless'
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
 import { dirname } from 'node:path'
@@ -24,7 +25,7 @@ import {
 } from './protocol.ts'
 import { attachedPath, pidPath, servePath, sockPath } from './paths.ts'
 import { nextBootAction, type BootPredicates } from './boot.ts'
-import { modelToPlainText } from '../shadow/render.ts'
+import { modelAttachSnapshotRows, modelToPlainText, terminalModesPrefix } from '../shadow/render.ts'
 import { codexAdapter } from '../launch/adapters/codex.ts'
 import { claudeAdapter } from '../launch/adapters/claude.ts'
 
@@ -168,21 +169,18 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   // NOTHING on resize — the child redraws its viewport (SIGWINCH) and the terminal reflows its own
   // scrollback, like a directly-launched claude.
   const painted = new WeakSet<object>()
-  // RAW REPLAY RING (Bug B catch-up): the last ~RAW_RING_MAX bytes of the child's RAW output, exactly as
-  // forwarded to live clients. The attach catch-up REPLAYS this verbatim so the client renders claude's
-  // OWN bytes — native scrollback, NO duplication. (The previous catch-up dumped the @xterm model via
-  // SerializeAddon, which captures claude's no-scroll-region status/tool-list redraws as DUPLICATE
-  // scrollback frames; a directly-launched claude has no such duplication — the dup was the model's, not
-  // claude's.) No clears in the replay: Apple Terminal scrolls \x1b[2J into scrollback and ignores
-  // \x1b[3J, so claude's own print+\n stream is the only clean primitive.
-  const RAW_RING_MAX = 1024 * 1024
-  const rawRing: Buffer[] = []
-  let rawRingBytes = 0
-  const ringAppend = (b: Buffer): void => {
-    rawRing.push(b)
-    rawRingBytes += b.length
-    while (rawRingBytes > RAW_RING_MAX && rawRing.length > 1) rawRingBytes -= rawRing.shift()!.length
-  }
+  // INITIALIZING GATE (scrollback fix): a client is held OUT of live output-forwarding from connect until
+  // its one-time attach snapshot has been sent. Without this, live frames (claude's relative-cursor
+  // redraws) race ahead of the snapshot and corrupt the fresh terminal. The model still ingests those
+  // bytes, so the snapshot (built FROM the model) already contains them; once the snapshot is sent the
+  // 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 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
@@ -236,12 +234,18 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
             /* best-effort */
           }
         const s = buf.toString('latin1')
-        xterm.write(buf) // authoritative model
+        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)
         if (fwd.length) {
-          ringAppend(fwd) // keep recent raw output for the attach catch-up (raw replay = native, no dup)
-          for (const c of [...clients]) sendClient(c as { write(b: Buffer): number }, frame(FRAME_DATA, fwd))
+          // Forward live output to every ATTACHED client — but NOT to one still INITIALIZING (its
+          // snapshot hasn't been sent; these bytes are already in the model and will be in that snapshot,
+          // so forwarding now would duplicate / race ahead of the snapshot).
+          for (const c of [...clients]) {
+            if (initializing.has(c as object)) continue
+            sendClient(c as { write(b: Buffer): number }, frame(FRAME_DATA, fwd))
+          }
         }
       },
       exit(_t?: unknown, exitCode?: number | null, signalCode?: number | null) {
@@ -270,26 +274,59 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   } as unknown as Parameters<typeof Bun.spawn>[1]) as unknown as PtyChild
   xterm.onData(resp => child.terminal.write(resp)) // @xterm auto-answers DA1/DSR → back to child
 
-  /** Catch up a (re)attaching client to the current screen + history ONCE by REPLAYING the child's recent
-   *  RAW output (its own bytes from the ring) — so the client renders exactly what a directly-launched
-   *  claude would, with native scrollback and NO duplication. Backpressure-safe — a ~1 MB replay MUST NOT
-   *  drop past the socket buffer (port-dep #2). Called EXACTLY ONCE per client (its first FRAME_RESIZE):
-   *  re-replaying on a later resize would stack a second history copy in a terminal that ignores \x1b[3J
-   *  (Apple Terminal has no E3) → smeared scroll-up history (Bug B). After the catch-up the supervisor
-   *  stops intervening: a resize just re-sizes the child (applyGeometry → SIGWINCH), and the child redraws
-   *  its own viewport while the terminal reflows its own scrollback — exactly like a direct claude launch.
-   *  NO clears (\x1b[2J/3J): Apple Terminal scrolls 2J into scrollback and ignores 3J — claude's own
-   *  print+\n stream is the only clean primitive. A leading \x1b[0m resets any inherited SGR before the
-   *  replay; the child's SIGWINCH redraw (from applyGeometry) then settles the current screen at the
-   *  client's width. Empty ring (fresh session, no output yet) → nothing to replay; the SIGWINCH redraw
-   *  paints the first screen. */
-  const repaint = (s: { write(b: Buffer): number }): void => {
-    if (rawRingBytes === 0) return
-    sendClient(s, frame(FRAME_DATA, Buffer.concat([Buffer.from('\x1b[0m', 'latin1'), ...rawRing])))
+  /** Catch up a (re)attaching client to the current screen + history ONCE by sending a SNAPSHOT of the
+   *  resolved @xterm MODEL — scrollback + viewport as committed plain-text rows — NOT a replay of the
+   *  child's raw frames. The model has already flattened claude's relative-cursor in-place redraws into
+   *  final lines (no DECSTBM / alt-screen — see the census), so the rows render as native scrollback with
+   *  NO duplication. Raw-frame replay can't (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 — the two prior dead-ends. Awaits the model parse barrier first (write is async),
+   *  then builds + sends the snapshot SYNCHRONOUSLY and lifts the INITIALIZING gate; with no await between
+   *  build and lift, a live data() event cannot interleave (single-threaded) → no gap, no double-forward.
+   *  Scrollback rows are spinner-stripped; the viewport stays verbatim. The child's SIGWINCH redraw (from
+   *  applyGeometry) then settles the live viewport at the client's width. Backpressure-safe
+   *  (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. */
+  // 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
+    }
+  }
+  // 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
+      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)
+    }
+    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 {
@@ -298,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
@@ -320,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)
-        repaint(s) // FIRST resize for this client = the one-time catch-up (full 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.
     }
   }
 
@@ -342,6 +400,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       open(s: { write(b: Buffer): number }) {
         framers.set(s as object, makeFramer((t, p) => onClientFrame(s, t, p)))
         clients.add(s)
+        initializing.add(s as object) // hold live-forward until this client's snapshot is sent (race guard)
         syncAttached() // ≥1 client now attached → marker present
         // NO repaint here. A viewer's runClient sends its real terminal size as the FIRST FRAME_RESIZE on
         // connect (client.ts open → "repaint at our size"); we paint THEN, ONCE, at the correct geometry.