@agfpd/iapeer 0.2.88 → 0.2.90

package/package.json

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

package/src/launch/ptyHost.ts

@@ -12,7 +12,7 @@
 //   - readiness reuses paneLogViewport, whose @xterm import is dynamic and only loads flag-on.
 import { existsSync, readFileSync } from 'node:fs'
 import { deliverToHost, type DeliverResult } from '../supervisor/deliver.ts'
-import { attachedPath, defaultRunDir, pidPath } from '../supervisor/paths.ts'
+import { attachedPath, defaultRunDir, pidPath, readGeometry } from '../supervisor/paths.ts'
 import { sessionAlive as hostDaemonAlive } from '../supervisor/client.ts'
 import { killSession as killSupervisorSession, listSessions as listSupervisorSessions } from '../supervisor/index.ts'
 import { parseSessionName } from '../core/socket.ts'
@@ -72,6 +72,15 @@ export function hasAttachedSupervisorClient(identity: string): boolean {
   return existsSync(attachedPath(hostRunDir(), identity))
 }
 
+/** Current child pty geometry of a hosted session, from the supervisor's `<session>.geometry.json`
+ *  sidecar, or HOST defaults when absent/unreadable. Warm-deliver occupancy / ready-gate readers use THIS
+ *  rather than assuming the fixed HOST geometry, because a DETACHED session keeps its last client geometry
+ *  (the child is no longer reverted to serve on detach — that revert caused the reattach-duplicate bug).
+ *  Reading the actual geometry keeps the pane-log composer-occupancy model aligned with the real pty size. */
+export function hostGeometry(identity: string): { cols: number; rows: number } {
+  return readGeometry(hostRunDir(), identity) ?? { cols: HOST_COLS, rows: HOST_ROWS }
+}
+
 /**
  * A session-REPLACEMENT token for a hosted session (spawn-flip Ф0b-3 slice 3c): the supervisor
  * daemon's pid. A `/new` or restart spawns a NEW daemon (new pid), so a message queued against the old

package/src/shadow/render.ts

@@ -29,64 +29,11 @@ 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'
-}
+// NOTE: the attach catch-up SNAPSHOT is built in the supervisor daemon via SerializeAddon.serialize()
+// (scrollback + screen + cursor + SGR colour + private modes, all at once), NOT from this leaf. Earlier
+// plain-text attempts here (modelAttachSnapshotRows / terminalModesPrefix) were removed: translateToString
+// is text-only (→ monochrome) and a hand-rolled rows dump can't reproduce the grid+cursor the way the
+// emulate-then-rerender multiplexers (tmux/zellij) do. See the daemon's sendSnapshot.
 
 const promptGlyph = (rt: string): string => (rt === 'claude' ? '❯' : '›')
 

package/src/supervisor/daemon.ts

@@ -11,6 +11,7 @@
 // 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 { SerializeAddon } from '@xterm/addon-serialize'
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
 import { dirname } from 'node:path'
 import {
@@ -23,9 +24,9 @@ import {
   parseSize,
   stripQueries,
 } from './protocol.ts'
-import { attachedPath, pidPath, servePath, sockPath } from './paths.ts'
+import { attachedPath, geometryPath, pidPath, servePath, sockPath, writeGeometry } from './paths.ts'
 import { nextBootAction, type BootPredicates } from './boot.ts'
-import { modelAttachSnapshotRows, modelToPlainText, terminalModesPrefix } from '../shadow/render.ts'
+import { modelToPlainText } from '../shadow/render.ts'
 import { codexAdapter } from '../launch/adapters/codex.ts'
 import { claudeAdapter } from '../launch/adapters/claude.ts'
 
@@ -132,6 +133,12 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   const pid = pidPath(runDir, session)
 
   const xterm = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 5000 })
+  // SerializeAddon turns the resolved model (scrollback + screen + cursor + SGR colour + private modes)
+  // into a byte string that recreates it in a fresh terminal — the attach catch-up. This is how tmux /
+  // screen / zellij restore state on attach (emulate the VT, re-render on attach). Color comes free here
+  // (translateToString was text-only → the monochrome bug); serialize() carries SGR (xterm PR #2369).
+  const serializeAddon = new SerializeAddon()
+  xterm.loadAddon(serializeAddon)
 
   const bin = opts.bin ?? knownLauncher(runtime) ?? runtime
   // SERVING SEAM (slice b): opts.argv (launch-composed, carries the system-prompt swap + PEER_START_ARGS)
@@ -303,21 +310,20 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       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.
+  // Build + send the one-time attach SNAPSHOT (full resolved model: scrollback + screen + cursor + SGR colour
+  // + private modes) via SerializeAddon, and LIFT the initializing gate — SYNCHRONOUS (no await), so the live
+  // data() handler cannot interleave between serializing and resuming live-forward (single-threaded) → no gap,
+  // no double-forward. Called only from firstAttach, which owns the order (drain → model-resize-to-client →
+  // THIS → child-resize-if-changed). serialize() recreates the EXACT grid incl. cursor, so claude's live bytes
+  // continue seamlessly from the matching state — no separate viewport repaint, no double-paint overlap. The
+  // model is clean because the child is NEVER shrunk on detach (the resize-churn that polluted scrollback is
+  // gone), so serialize faithfully reports clean coloured history. Trailing \x1b[m guards the wrap bg-bleed
+  // artifact (xterm.js #3102). This is the tmux/zellij "re-render the emulated model on attach" architecture.
   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
+    const snap = serializeAddon.serialize({ scrollback: xterm.buffer.active.baseY }) // all scrollback + screen, with colour
+    const body = snap.length > 0 ? snap + '\x1b[m' : ''
+    if (body) sendClient(s, frame(FRAME_DATA, Buffer.from(body, 'utf8')))
+    initializing.delete(s as object) // snapshot sent → resume live forwarding
   }
 
   // Resize the model + child pty to (c, r). Shared by LATER client resizes and the last-detach restore.
@@ -335,44 +341,47 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     } catch {
       /* transient */
     }
+    writeGeometry(runDir, session, c, r) // record current child geometry → sidecar for warm-deliver / ready-gate readers
   }
-  // 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.
+  // FIRST attach for a client. Order (codex review) for a clean, coloured, correctly-sized snapshot:
+  //   1. DRAIN to stability — pending child bytes were generated under the OLD geometry; parse them BEFORE a
+  //      model resize (else they rewrap wrong), and capture bytes that land while the client is gated.
+  //   2. MODEL resize to the client geometry IF it differs — serialize() round-trips only at matching dims
+  //      (xterm.js #3093), so the model must be the client's size before we serialize.
+  //   3. SNAPSHOT — serialize + send + lift gate, SYNCHRONOUS (no await), so no live byte interleaves.
+  //   4. CHILD resize IF it differs — an honest one-SIGWINCH window-resize (like native). NOT a nudge, NOT a
+  //      forced repaint: serialize already recreated screen+cursor, so claude's live bytes continue from the
+  //      matching grid. A same-size reattach touches the child ZERO times → pure snapshot, no re-render.
   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
+        xterm.resize(c, r) // MODEL only (for the serialize round-trip) — child resized below, after the snapshot
       } 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.
+    sendSnapshot(s) // serialize the model → send → lift gate (synchronous, no interleave)
     if (changed) {
       try {
-        child.terminal.resize(c, r) // SIGWINCH the child → live reflow (post-snapshot, forwarded live)
+        child.terminal.resize(c, r) // honest one-SIGWINCH resize (post-snapshot, forwarded live), like native
       } catch {
         /* transient */
       }
+      writeGeometry(runDir, session, c, r) // record the new current child geometry for the warm-deliver readers
     }
   }
-  // Restore the serve geometry when the last client detaches, so the unattached session never sticks at
-  // a departed client's size (FINDING-2 — would mismatch the fixed-geometry warm-deliver/ready-gate
-  // viewport model). No-op when already at serve geometry or a client is still attached.
+  // DETACH = NO RESIZE (emulator invariant). A detached hosted TUI keeps its LAST client geometry — it is
+  // NEVER shrunk back to serve. The old FINDING-2 revert shrank the child into a tiny viewport, making claude
+  // reflow its live region and scroll DUPLICATE copies into scrollback — the root of the reattach-dup bug.
+  // tmux/screen likewise never collapse a detached session's size. Warm-deliver / ready-gate readers follow
+  // the actual geometry via the `<session>.geometry.json` sidecar instead of assuming serve. Kept as a no-op
+  // (callers in the close/drain/error handlers stay unchanged).
   const restoreServeGeometryIfIdle = (): void => {
-    if (clients.size === 0 && (cols !== serveCols || rows !== serveRows)) applyGeometry(serveCols, serveRows)
+    /* intentional no-op: detach must NOT resize the child — see comment above */
   }
 
   const onClientFrame = (s: { write(b: Buffer): number }, type: number, payload: Buffer): void => {
@@ -429,6 +438,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     },
   })
   writeFileSync(pid, String(process.pid))
+  writeGeometry(runDir, session, serveCols, serveRows) // initial geometry sidecar (= serve); updated on every real child resize
 
   let down = false
   function shutdown(): void {
@@ -450,7 +460,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     } catch {
       /* */
     }
-    for (const f of [sock, pid, servePath(runDir, session), attachedMarker]) {
+    for (const f of [sock, pid, servePath(runDir, session), attachedMarker, geometryPath(runDir, session)]) {
       try {
         unlinkSync(f)
       } catch {

package/src/supervisor/paths.ts

@@ -1,6 +1,8 @@
 // Supervisor session paths — under a configurable run dir (NOT hardcoded). Prod resolves it to
 // ~/.iapeer/state/supervisor via the storage layer; tests pass a temp dir, so the daemon's
 // socket/pid files never touch a real location.
+import { renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { pluginStateDir } from '../storage/index.ts'
 
@@ -21,3 +23,46 @@ export const servePath = (runDir: string, session: string): string => join(runDi
  *  reads it to gate the hosted busy-composer hold — never paste over a HUMAN's unfinished input, but
  *  never hold for the AI's own composer output when no operator is attached. */
 export const attachedPath = (runDir: string, session: string): string => join(runDir, `${session}.attached`)
+
+/** Geometry sidecar (emulator-model fix): the CURRENT child pty geometry of a hosted session. The
+ *  supervisor (the only process that resizes the child) writes it after every successful resize; the
+ *  warm-deliver / ready-gate readers in OTHER processes read it to build their pane-log viewport model at
+ *  the session's actual size instead of assuming the fixed HOST geometry. Critical because a detached
+ *  session is NO LONGER reverted to serve geometry (that revert caused claude to reflow into a tiny
+ *  viewport → duplicate scrollback) — so the child can sit at the last client's size, and readers must
+ *  follow it. Absent / unreadable → readers fall back to HOST geometry. */
+export const geometryPath = (runDir: string, session: string): string => join(runDir, `${session}.geometry.json`)
+
+/** Atomically (temp + rename) record the current child geometry — best-effort, never throws (a hint file). */
+export function writeGeometry(runDir: string, session: string, cols: number, rows: number): void {
+  const p = geometryPath(runDir, session)
+  try {
+    const tmp = `${p}.${process.pid}.tmp`
+    writeFileSync(tmp, JSON.stringify({ cols, rows }), { mode: 0o600 })
+    renameSync(tmp, p)
+  } catch {
+    /* best-effort: a geometry hint never blocks serving */
+  }
+}
+
+/** Read the current child geometry of a hosted session; null when absent / unreadable / invalid. */
+export function readGeometry(runDir: string, session: string): { cols: number; rows: number } | null {
+  try {
+    const o = JSON.parse(readFileSync(geometryPath(runDir, session), 'utf8')) as { cols?: unknown; rows?: unknown }
+    if (typeof o.cols === 'number' && typeof o.rows === 'number' && o.cols > 0 && o.rows > 0) {
+      return { cols: o.cols, rows: o.rows }
+    }
+  } catch {
+    /* absent / malformed → caller falls back to HOST */
+  }
+  return null
+}
+
+/** Remove the geometry sidecar (shutdown cleanup); best-effort. */
+export function clearGeometry(runDir: string, session: string): void {
+  try {
+    unlinkSync(geometryPath(runDir, session))
+  } catch {
+    /* */
+  }
+}

package/src/transport/index.ts

@@ -51,12 +51,11 @@ import type { ControlCommand, DeliveryMarkers } from '../launch/types.ts'
 import {
   deliverHosted,
   hasAttachedSupervisorClient,
+  hostGeometry,
   hostRunDir,
   hostSessionAlive,
   hostSessionToken,
   listHostedPeers,
-  HOST_COLS,
-  HOST_ROWS,
 } from '../launch/ptyHost.ts'
 import { sendControlToHost, type DeliverResult } from '../supervisor/deliver.ts'
 import { keysToBytes } from '../supervisor/protocol.ts' // pure send-keys-vocab→pty-byte translation (boot-driver slice a), @xterm-free
@@ -1158,7 +1157,7 @@ async function shouldQueueForComposer(target: DeliveryTarget, logDir: string | u
   if (!hostSessionAlive(target.address)) return shouldQueueForHumanComposer(target)
   if (!isSupportedLocalRuntime(target.runtime) || !hasAttachedSupervisorClient(target.address)) return false
   if (!logDir) return false // no pane-log dir → cannot read occupancy → don't hold (deliver, never stall)
-  return paneLogComposerOccupied(`${logDir}/${target.address}.log`, HOST_COLS, HOST_ROWS, target.runtime)
+  return paneLogComposerOccupied(`${logDir}/${target.address}.log`, hostGeometry(target.address).cols, hostGeometry(target.address).rows, target.runtime)
 }
 
 /** Drain re-check (no attached-client prereq — once queued, abandoned input waits until cleared/ceiling).
@@ -1166,7 +1165,7 @@ async function shouldQueueForComposer(target: DeliveryTarget, logDir: string | u
 async function composerStillBusy(target: DeliveryTarget, logDir: string | undefined): Promise<boolean> {
   if (!hostSessionAlive(target.address)) return targetComposerBlocksDelivery(target)
   if (!logDir) return false
-  return paneLogComposerOccupied(`${logDir}/${target.address}.log`, HOST_COLS, HOST_ROWS, target.runtime)
+  return paneLogComposerOccupied(`${logDir}/${target.address}.log`, hostGeometry(target.address).cols, hostGeometry(target.address).rows, target.runtime)
 }
 
 /** Session-replacement token. HOSTED: supervisor daemon pid; tmux: session_id:pane_id. */