@agfpd/iapeer 0.2.63 → 0.2.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.63",
+  "version": "0.2.64",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/launch/index.ts

@@ -21,6 +21,7 @@ import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER, type Runtime } from '../core/
 import { readLaunchEnv } from '../storage/index.ts'
 import { canaryChannel, dismissCanary, ensureServerCanary, exitLogPath, signalCanaryClean } from './canary.ts'
 import { hardenCmdLogDir, prepareCmdLogDir } from './cmdlog.ts'
+import { logReadyGateCrossCheck, readyGatePtyFlipEnabled, readyGateViewport } from './readyGateModel.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { claudeAdapter } from './adapters/claude.ts'
 import { codexAdapter } from './adapters/codex.ts'
@@ -385,7 +386,29 @@ export const launch: LaunchFn = async (
       tmux(sock, 'send-keys', '-t', identity, ...dialogKeys)
       continue
     }
-    if (adapter.isInputReady(pane)) {
+    // Ф1 READY-GATE SOURCE FLIP (per-peer flag, DARK by default). When the peer's flip flag is set,
+    // run the SAME isInputReady predicate on the pty-MODEL viewport (validated 0-divergence vs
+    // capture-pane by the burn-in gate, incl. the codex resume-with-history splash-off-screen center)
+    // instead of the capture-pane scrape, with an UNCONDITIONAL capture-pane fallback. This is the
+    // ONLY changed input — dialog detection (above) and delivery + delivery-confirm (below + transport)
+    // are untouched. Flag OFF → readyView === pane (byte-identical to today).
+    let readyView = pane
+    if (readyGatePtyFlipEnabled(cfg.logDir, identity)) {
+      const geo = tmux(sock, 'display', '-p', '-t', identity, '#{pane_width}x#{pane_height}')
+      const [c, r] = geo.ok ? geo.out.trim().split('x').map(Number) : [0, 0]
+      readyView = await readyGateViewport({ logDir: cfg.logDir, identity, fallback: pane, cols: c ?? 0, rows: r ?? 0 })
+      // SERVING-path cross-check (post-flip soak gate): the model verdict is AUTHORITATIVE (readyView);
+      // record what capture-pane WOULD have said, to prove 0 model-vs-capture divergence live in the
+      // serving path. Observability only — never affects the ready decision.
+      logReadyGateCrossCheck(cfg.exitLogDir, {
+        identity,
+        modelReady: adapter.isInputReady(readyView),
+        captureReady: adapter.isInputReady(pane),
+        geom: `${c ?? 0}x${r ?? 0}`,
+        nowISO: new Date().toISOString(),
+      })
+    }
+    if (adapter.isInputReady(readyView)) {
       if (!hasMessage) return ready(identity) // bare bring-up — session up, no message
       // Boot delivery = load-buffer → paste-buffer -p → Enter (Ф-#8b hardening):
       // the SAME mechanism warm delivery uses (transport.deliverViaTmux), replacing

package/src/launch/readyGateModel.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { logReadyGateCrossCheck, readyGatePtyFlipEnabled, readyGateViewport } from './readyGateModel.ts'
+
+// The Ф1 ready-gate source swap is DARK by default and falls back to capture-pane UNCONDITIONALLY,
+// so the flip can never make readiness worse than tmux today. These prove exactly that contract.
+const tmps: string[] = []
+const mkLogDir = (): string => {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-rgm-'))
+  tmps.push(d)
+  return d
+}
+afterEach(() => {
+  while (tmps.length) rmSync(tmps.pop()!, { recursive: true, force: true })
+})
+const FALLBACK = '<<capture-pane-fallback>>'
+
+describe('readyGatePtyFlipEnabled (per-peer flip flag, canary-first)', () => {
+  test('absent marker → off; present marker → on', () => {
+    const d = mkLogDir()
+    expect(readyGatePtyFlipEnabled(d, 'codex-x')).toBe(false)
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    expect(readyGatePtyFlipEnabled(d, 'codex-x')).toBe(true)
+  })
+})
+
+describe('readyGateViewport (Ф1 viewport-source swap, tmux-fallback)', () => {
+  test('flag OFF → the capture-pane fallback VERBATIM (byte-identical to today, no model built)', async () => {
+    const d = mkLogDir()
+    expect(await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 80, rows: 24 })).toBe(FALLBACK)
+  })
+
+  test('flag ON + a pane-log → the MODEL viewport (source swapped), not the fallback', async () => {
+    const d = mkLogDir()
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    writeFileSync(join(d, 'codex-x.log'), '\x1b[24;1H› ready prompt here') // render a codex '›' prompt row
+    const v = await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 80, rows: 24 })
+    expect(v).not.toBe(FALLBACK) // the source was swapped to the model
+    expect(v).toContain('› ready prompt here') // the model rendered the prompt the predicate keys on
+  })
+
+  test('flag ON but the pane-log is MISSING → fallback (never worse than tmux)', async () => {
+    const d = mkLogDir()
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    expect(await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 80, rows: 24 })).toBe(FALLBACK)
+  })
+
+  test('flag ON but geometry is unknown (0x0) → fallback', async () => {
+    const d = mkLogDir()
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    writeFileSync(join(d, 'codex-x.log'), '\x1b[24;1H› ready')
+    expect(await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 0, rows: 0 })).toBe(FALLBACK)
+  })
+})
+
+describe('logReadyGateCrossCheck (serving-path soak observability)', () => {
+  test('appends a record with diverged computed; agreement → false, mismatch → true', () => {
+    const d = mkLogDir()
+    logReadyGateCrossCheck(d, { identity: 'codex-x', modelReady: true, captureReady: false, geom: '220x50', nowISO: '2026-06-14T00:00:00Z' })
+    logReadyGateCrossCheck(d, { identity: 'codex-x', modelReady: true, captureReady: true, geom: '220x50', nowISO: '2026-06-14T00:00:05Z' })
+    const lines = readFileSync(join(d, 'readygate-flip.jsonl'), 'utf8').trim().split('\n').map(l => JSON.parse(l))
+    expect(lines[0].diverged).toBe(true) // model ahead of capture
+    expect(lines[0].modelReady).toBe(true)
+    expect(lines[0].captureReady).toBe(false)
+    expect(lines[1].diverged).toBe(false) // agreement
+  })
+  test('no event-log dir → no-op (never blocks the ready-gate)', () => {
+    expect(() => logReadyGateCrossCheck(undefined, { identity: 'x', modelReady: true, captureReady: true, geom: '1x1', nowISO: 't' })).not.toThrow()
+  })
+})

package/src/launch/readyGateModel.ts

@@ -0,0 +1,99 @@
+// Ф1 READY-GATE viewport-source FLIP (cutover Block 3) — DARK / flag-gated, canary-first.
+//
+// The cold-wake ready-gate (launch index.ts step 6) decides "is the input surface ready?" by
+// running adapter.isInputReady on a VIEWPORT. Today that viewport is a `tmux capture-pane` scrape.
+// This is the FIRST migration mutation: swap the viewport SOURCE to the pty-MODEL (an @xterm/headless
+// emulation of the daemon's pane-log — the SAME raw child bytes tmux renders), keeping the SAME
+// production predicate (adapter.isInputReady) and an UNCONDITIONAL capture-pane fallback.
+//
+// Why this is low-radius (boris's frame): it is a viewport-SOURCE swap, NOT a predicate change.
+// The model verdict was validated 0-divergence vs capture-pane on the readiness predicate by the
+// burn-in gate (incl. the codex resume-with-history splash-off-screen center cell) before any peer
+// is flipped. It touches ONLY the isInputReady INPUT — dialog detection upstream and the delivery +
+// delivery-confirm downstream (submitIntoTui's submit-landed + deliverViaTmux's transcript-mtime
+// advance, the "real model advancement" final-arbiter) are untouched, so the canonical
+// harmless-false-glyph property is preserved by construction.
+//
+// FLAG: a per-peer marker `<logDir>/<identity>.pty-readygate`. Absent → capture-pane (byte-identical
+// to today). Present → the model viewport. Per-peer so the first flip is a single canary with the
+// whole fleet still on tmux; dynamic (touch/rm, no daemon restart). @xterm is dynamic-imported ONLY
+// when the flag is set, so the launch hot path stays @xterm-free with the flip off.
+
+import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SEED_BYTES = 4 * 1024 * 1024
+
+/**
+ * SERVING-path cross-check log (the post-flip soak gate). When a peer is flipped, the MODEL verdict
+ * is AUTHORITATIVE in the cold-wake ready-gate; this records, per evaluation, what capture-pane WOULD
+ * have said — so a soak can prove 0 model-vs-capture divergence IN THE SERVING PATH (the read-only
+ * burn-in measures continuously but never drove the actual ready decision). Append-only jsonl under
+ * the event-log dir. Best-effort: a log hiccup never affects the ready decision. No-op without a dir.
+ */
+export function logReadyGateCrossCheck(
+  eventLogDir: string | undefined,
+  rec: { identity: string; modelReady: boolean; captureReady: boolean; geom: string; nowISO: string },
+): void {
+  if (!eventLogDir) return
+  try {
+    appendFileSync(
+      join(eventLogDir, 'readygate-flip.jsonl'),
+      JSON.stringify({
+        ts: rec.nowISO,
+        identity: rec.identity,
+        modelReady: rec.modelReady,
+        captureReady: rec.captureReady,
+        diverged: rec.modelReady !== rec.captureReady,
+        geom: rec.geom,
+      }) + '\n',
+    )
+  } catch {
+    /* observability only — never block the ready-gate */
+  }
+}
+
+/** Per-peer ready-gate flip flag: the marker `<logDir>/<identity>.pty-readygate`. */
+export function readyGatePtyFlipEnabled(logDir: string, identity: string): boolean {
+  return existsSync(`${logDir}/${identity}.pty-readygate`)
+}
+
+export interface ReadyGateViewportOpts {
+  logDir: string
+  identity: string
+  /** The capture-pane scrape — returned verbatim when the flag is off OR any model build fails. */
+  fallback: string
+  cols: number
+  rows: number
+}
+
+/**
+ * Resolve the ready-gate viewport. Flag OFF → `fallback` (capture-pane) verbatim — zero work, the
+ * caller never even reaches here unless it pre-checked the flag, but this stays safe regardless.
+ * Flag ON → the pty-model viewport as plain text. ANY failure (unreadable/short log, @xterm hiccup)
+ * → `fallback`: the flip can never make readiness WORSE than capture-pane today (tmux is the floor).
+ */
+export async function readyGateViewport(opts: ReadyGateViewportOpts): Promise<string> {
+  if (!readyGatePtyFlipEnabled(opts.logDir, opts.identity)) return opts.fallback
+  if (!(opts.cols > 0 && opts.rows > 0)) return opts.fallback
+  const log = `${opts.logDir}/${opts.identity}.log`
+  if (!existsSync(log)) return opts.fallback
+  try {
+    const { Terminal } = await import('@xterm/headless')
+    const { modelToPlainText } = await import('../shadow/index.ts')
+    const fd = openSync(log, 'r')
+    try {
+      const sz = fstatSync(fd).size
+      const off = Math.max(0, sz - SEED_BYTES)
+      const buf = Buffer.alloc(sz - off)
+      readSync(fd, buf, 0, buf.length, off)
+      const term = new Terminal({ cols: opts.cols, rows: opts.rows, allowProposedApi: true, scrollback: 3000 })
+      await new Promise<void>(res => term.write(buf, () => res()))
+      return modelToPlainText(term, opts.cols, opts.rows)
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return opts.fallback // tmux-fallback is unconditional — never worse than today
+  }
+}