@agfpd/iapeer 0.2.86 → 0.2.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.86",
+  "version": "0.2.87",
   "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,16 @@ 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, else it reflects a stale screen. We chain the
+  // latest write's parse-callback; repaint awaits it before reading the buffer.
+  let writeChain: Promise<void> = Promise.resolve()
   // 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 +232,17 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
             /* best-effort */
           }
         const s = buf.toString('latin1')
-        xterm.write(buf) // authoritative model
+        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,22 +271,35 @@ 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. */
+  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)
+    }
+    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.
@@ -323,7 +337,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       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 repaint(s) // FIRST resize for this client = the one-time catch-up (model snapshot at its real size)
       }
       // 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
@@ -342,6 +356,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.