@agfpd/iapeer 0.2.67 → 0.2.69

package/package.json

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

package/src/launch/ptyHost.ts

@@ -14,7 +14,9 @@ import { existsSync, readFileSync } from 'node:fs'
 import { deliverToHost, type DeliverResult } from '../supervisor/deliver.ts'
 import { attachedPath, defaultRunDir, pidPath } from '../supervisor/paths.ts'
 import { sessionAlive as hostDaemonAlive } from '../supervisor/client.ts'
-import { killSession as killSupervisorSession } from '../supervisor/index.ts'
+import { killSession as killSupervisorSession, listSessions as listSupervisorSessions } from '../supervisor/index.ts'
+import { parseSessionName } from '../core/socket.ts'
+import type { TmuxRuntime } from '../core/constants.ts'
 import { paneLogViewport } from './readyGateModel.ts'
 import type { LaunchInvocation } from './invocation.ts'
 import type { RuntimeAdapter } from './types.ts'
@@ -80,6 +82,22 @@ export function hostSessionToken(identity: string): string | null {
   }
 }
 
+/**
+ * Online supervisor-HOSTED peers (spawn-flip Ф0b-3): live sessions in the supervisor run-dir. A hosted
+ * peer has NO tmux socket, so the tmux-based listOnlinePeers scan can't see it — this lets the online
+ * scan (and the no-runtime delivery resolve) include hosted peers. Empty + cheap when flag-off (the
+ * run-dir is empty).
+ */
+export function listHostedPeers(): Array<{ runtime: TmuxRuntime; personality: string }> {
+  const out: Array<{ runtime: TmuxRuntime; personality: string }> = []
+  for (const s of listSupervisorSessions(hostRunDir())) {
+    if (!s.alive) continue
+    const p = parseSessionName(s.session)
+    if (p) out.push({ runtime: p.runtime, personality: p.personality })
+  }
+  return out
+}
+
 export interface HostStartResult {
   ok: boolean
   error?: string

package/src/lifecycle/index.ts

@@ -1255,9 +1255,16 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       // alive server means the previous canary VANISHED mid-watch (the death-#4
       // blind spot was exactly this churn being invisible); 'failed' means the
       // server is currently UNWATCHED. At most one line per loss, not per tick.
-      const canaryState = ensureServerCanary({ identity: s.identity, sock, exitLogDir: cfg.eventLogDir, env })
-      if (canaryState !== 'already') {
-        trace({ identity: s.identity, action: 'canary', state: canaryState, origin: 'retrofit' })
+      // SPAWN-FLIP Ф0b-3: the tmux server-death canary is meaningless for a supervisor-HOSTED session
+      // (no tmux server — the retrofit arms a watcher that immediately fires a spurious
+      // `server-vanished`). A hosted death is recorded by the supervisor's exits.log (host=supervisor,
+      // resilience-b), so skip the canary retrofit for hosted peers (mirror of the observer .pty-host
+      // skip — tmux-assuming infra must not run against a hosted session).
+      if (!hostSessionAlive(s.identity)) {
+        const canaryState = ensureServerCanary({ identity: s.identity, sock, exitLogDir: cfg.eventLogDir, env })
+        if (canaryState !== 'already') {
+          trace({ identity: s.identity, action: 'canary', state: canaryState, origin: 'retrofit' })
+        }
       }
       out.push({ identity: s.identity, action: 'alive' })
       if (verbose) trace({ identity: s.identity, action: 'alive', age: `${ageSecs}s` })

package/src/supervisor/client.attach.test.ts

@@ -0,0 +1,107 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { killSession, sessionAlive, startSupervisorDaemon } from './index.ts'
+
+// SURFACE-5 regression — the interactive attach-and-stay loop. The other supervisor tests attach a
+// RAW socket; none drives the real `runSupervisorClient` under a TTY, so the canary's first live
+// `iapeer attach` exposed a bug invisible to them: runSupervisorClient resolved its Promise the
+// instant Bun.connect returned (setup done), the CLI caller ran `await runSupervisorClient(); return
+// 0` → runCli's `.then(process.exit)`, and the just-attached client was torn down within
+// milliseconds (handshake-then-exit). The fix makes the client BLOCK (never-resolve) after setup so
+// process.exit from a terminal path owns termination — exactly the detached `daemon` case's guard.
+//
+// This is the headless verifier of that fix AND the missing surface-5 automation: allocate a REAL
+// Bun-native pty, run the actual client CLI in it, assert it STAYS attached + renders live frames +
+// Ctrl-] detaches cleanly while the session keeps running. Arthur's live attach is the final human
+// seal; this test makes every iteration of the fix verifiable WITHOUT pulling him in.
+// Gated on Bun-native PTY (≥1.3.5) so a runner without it skips rather than reds.
+const [maj, min, pat] = (Bun.version || '0.0.0').split('.').map(Number) as [number, number, number]
+const bunPty = maj > 1 || (maj === 1 && (min > 3 || (min === 3 && pat >= 5)))
+const d = bunPty ? describe : describe.skip
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+async function waitFor(pred: () => boolean, timeoutMs = 4000, step = 50): Promise<boolean> {
+  const end = Date.now() + timeoutMs
+  while (Date.now() < end) {
+    if (pred()) return true
+    await sleep(step)
+  }
+  return false
+}
+
+// Spawn the real attach client under a real pty (its stdin/stdout is a TTY → raw-mode path runs).
+interface PtyClient {
+  out(): string
+  exited(): boolean
+  sendKey(byte: number): void
+}
+function spawnAttachClient(runDir: string, session: string): PtyClient {
+  let buf = ''
+  let done = false
+  const proc = Bun.spawn(['bun', 'src/supervisor/index.ts', 'attach', session, '--run-dir', runDir], {
+    cwd: process.cwd(),
+    env: { ...process.env },
+    // a real Bun-native pty pair: the client sees a TTY on stdin (isTTY → setRawMode runs).
+    terminal: {
+      cols: 80,
+      rows: 24,
+      name: 'xterm-256color',
+      data(_t: unknown, data: Uint8Array | string) {
+        buf += Buffer.from(data as Uint8Array).toString('latin1')
+      },
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun pty spawn opts not yet in @types
+  } as any)
+  proc.exited.then(() => {
+    done = true
+  })
+  return {
+    out: () => buf,
+    exited: () => done,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- proc.terminal is the pty master writer
+    sendKey: (byte: number) => void (proc as any).terminal.write(Buffer.from([byte])),
+  }
+}
+
+d('runSupervisorClient interactive attach (surface-5, Bun-native pty)', () => {
+  let runDir: string
+  const session = 'ptsattach'
+
+  beforeAll(() => {
+    runDir = mkdtempSync(join(tmpdir(), 'iapeer-attach-'))
+    startSupervisorDaemon({ session, runtime: 'tick', runDir })
+  })
+  afterAll(() => {
+    try {
+      killSession(runDir, session)
+    } catch {
+      /* */
+    }
+    rmSync(runDir, { recursive: true, force: true })
+  })
+
+  test('the client STAYS attached after the handshake and keeps rendering live frames', async () => {
+    expect(sessionAlive(runDir, session)).toBe(true)
+    const c = spawnAttachClient(runDir, session)
+
+    // handshake: the attach line lands (connect + attach + terminal-setup succeeded).
+    expect(await waitFor(() => /\[supervisor\] attached to/.test(c.out()))).toBe(true)
+
+    // THE BUG was a handshake-then-exit within ~ms. Assert the client is STILL attached well past
+    // that window AND that live child output (STREAMTICK from the tick runtime) is reaching it —
+    // proving the attach-and-stay loop holds, not just that the process happens to linger.
+    await sleep(2000)
+    expect(c.exited()).toBe(false) // RED on the pre-fix early-resolve (exited ~ms after handshake)
+    expect(/STREAMTICK_\d+/.test(c.out())).toBe(true) // live frames flow through the held attach
+
+    // Ctrl-] (0x1d) detaches: the client exits cleanly, prints the DETACH message (not the
+    // misleading "session ended"), and the session keeps running.
+    c.sendKey(0x1d)
+    expect(await waitFor(() => c.exited())).toBe(true)
+    expect(/detached/.test(c.out())).toBe(true)
+    expect(/session ended/.test(c.out())).toBe(false) // detach must not claim the session ended
+    expect(sessionAlive(runDir, session)).toBe(true) // detach kept the daemon alive
+  })
+})

package/src/supervisor/client.ts

@@ -29,6 +29,10 @@ export async function runSupervisorClient(runDir: string, session: string): Prom
     process.exit(1)
   }
   let restored = false
+  // Set the instant a deliberate Ctrl-] detach begins. `sock.end()` can re-enter the socket close()
+  // handler synchronously, so close() must NOT claim "session ended" on an operator-initiated detach
+  // (the session keeps running) — it stays silent and lets the detach path own the message + exit.
+  let detaching = false
   // writeSync(1, …) works inside a signal handler (no event-loop dependency) — so a
   // SIGHUP/window-close client still resets the terminal before it dies (port-dep #1).
   const restore = (): void => {
@@ -70,6 +74,7 @@ export async function runSupervisorClient(runDir: string, session: string): Prom
       },
       close() {
         restore()
+        if (detaching) process.exit(0) // operator detached; the detach path already wrote its message
         process.stdout.write('\r\n[supervisor] session ended.\r\n')
         process.exit(0)
       },
@@ -82,13 +87,16 @@ export async function runSupervisorClient(runDir: string, session: string): Prom
 
   process.stdin.on('data', b => {
     if (b.includes(DETACH)) {
+      detaching = true
       restore()
+      // Write the detach message BEFORE sock.end() — sock.end() can re-enter close() synchronously,
+      // and close() now exits silently while `detaching`, so the message must already be out.
+      process.stdout.write(`\r\n[supervisor] detached — session still running. reattach: supervisor attach ${session}\r\n`)
       try {
         sock.end()
       } catch {
         /* */
       }
-      process.stdout.write(`\r\n[supervisor] detached — session still running. reattach: supervisor attach ${session}\r\n`)
       process.exit(0)
     }
     sock.write(frame(FRAME_DATA, b))
@@ -115,4 +123,11 @@ 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`)
+  // 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
+  // instant the handshake completed, and the CLI caller (`await runSupervisorClient(); return 0` →
+  // runCli's `.then(process.exit)`) would tear the just-attached client down in milliseconds — the
+  // surface-5 interactive-attach bug. The detached `daemon` case guards itself the same way.
+  await new Promise<never>(() => {})
 }

package/src/transport/hostLive.test.ts

@@ -0,0 +1,50 @@
+// Spawn-flip Ф0b-3 — transport liveness/resolution is HOST-AWARE. The canary exposed it: a genuinely
+// supervisor-HOSTED peer (live supervisor .pid, NO tmux) was seen as OFFLINE by resolveDeliveryTarget/
+// isPeerLive (transport had its OWN tmux-only sessionAlive, separate from the Ф0b-1 lifecycle fix), so
+// routeSend mis-routed a warm hit to a wake and the post-wake verify-before-act false-failed. This
+// binds the fix: a live supervisor .pid → live, even with no tmux.
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { hostRunDir } from '../launch/ptyHost.ts'
+import { isPeerLive, listOnlinePeers } from './index.ts'
+
+describe('isPeerLive — host-aware (spawn-flip Ф0b-3)', () => {
+  const savedRoot = process.env.IAPEER_ROOT
+  let root: string | null = null
+  afterEach(() => {
+    if (savedRoot === undefined) delete process.env.IAPEER_ROOT
+    else process.env.IAPEER_ROOT = savedRoot
+    if (root) rmSync(root, { recursive: true, force: true })
+    root = null
+  })
+
+  test('a LIVE supervisor .pid → live, with NO tmux session (the canary fix)', () => {
+    root = mkdtempSync(join(tmpdir(), 'iapeer-hostlive-'))
+    process.env.IAPEER_ROOT = root
+    const runDir = hostRunDir() // resolves under IAPEER_ROOT
+    mkdirSync(runDir, { recursive: true })
+    writeFileSync(join(runDir, 'codex-hostpeer.pid'), String(process.pid)) // a live pid = a live hosted daemon
+    expect(isPeerLive('codex', 'hostpeer')).toBe(true) // host-aware: no tmux, but the supervisor session is alive
+  })
+
+  test('no supervisor .pid and no tmux → offline', () => {
+    root = mkdtempSync(join(tmpdir(), 'iapeer-hostlive-'))
+    process.env.IAPEER_ROOT = root
+    mkdirSync(hostRunDir(), { recursive: true })
+    expect(isPeerLive('codex', 'ghostpeer')).toBe(false)
+  })
+
+  test('listOnlinePeers includes a live HOSTED peer (no tmux socket)', () => {
+    root = mkdtempSync(join(tmpdir(), 'iapeer-hostlive-'))
+    process.env.IAPEER_ROOT = root
+    const runDir = hostRunDir()
+    mkdirSync(runDir, { recursive: true })
+    // supervisor listSessions enumerates by `<identity>.sock`; alive = a live `<identity>.pid`.
+    writeFileSync(join(runDir, 'codex-hostpeer.sock'), '')
+    writeFileSync(join(runDir, 'codex-hostpeer.pid'), String(process.pid))
+    const online = listOnlinePeers()
+    expect(online.some(p => p.runtime === 'codex' && p.personality === 'hostpeer')).toBe(true)
+  })
+})

package/src/transport/index.ts

@@ -54,6 +54,7 @@ import {
   hostRunDir,
   hostSessionAlive,
   hostSessionToken,
+  listHostedPeers,
   HOST_COLS,
   HOST_ROWS,
 } from '../launch/ptyHost.ts'
@@ -113,7 +114,12 @@ function listSessions(sock: string): string[] {
 }
 
 function sessionAlive(sock: string, address: string): boolean {
-  return listSessions(sock).includes(address)
+  // SPAWN-FLIP Ф0b-3: a supervisor-HOSTED session has no tmux entry — its liveness is the supervisor
+  // daemon (runtime-state), checked FIRST (a cheap pid-file). Non-hosted → the tmux session list, as
+  // before (byte-identical). Without this, resolveDeliveryTarget/isPeerLive see a live hosted peer as
+  // OFFLINE → routeSend mis-routes a warm hit to a wake and the post-wake verify-before-act false-fails
+  // (the canary symptom: "woke but not live" though delivery actually landed). `address` IS the identity.
+  return hostSessionAlive(address) || listSessions(sock).includes(address)
 }
 
 // ─── Busy-composer detection (human input vs runtime ghost text) ─────────────
@@ -285,13 +291,13 @@ export function isPeerLive(runtime: string, personality: string, sockDir = resol
 }
 
 export function listOnlinePeers(sockDir = resolveSockDir()): OnlinePeer[] {
-  let entries: string[]
+  const out = new Map<string, OnlinePeer>()
+  let entries: string[] = []
   try {
     entries = readdirSync(sockDir)
   } catch {
-    return []
+    /* no tmux sock dir → only supervisor-hosted peers, merged below (never early-return past them) */
   }
-  const out = new Map<string, OnlinePeer>()
   for (const entry of entries) {
     const parsedSocket = parseSocketPath(join(sockDir, entry))
     if (!parsedSocket) continue
@@ -305,6 +311,11 @@ export function listOnlinePeers(sockDir = resolveSockDir()): OnlinePeer[] {
       })
     }
   }
+  // SPAWN-FLIP Ф0b-3: supervisor-HOSTED peers have no tmux socket, so the scan above misses them —
+  // merge in the live hosted sessions so the online scan + the no-runtime resolve see them too.
+  for (const h of listHostedPeers()) {
+    out.set(buildProcessAddress(h.runtime, h.personality), { personality: h.personality, runtime: h.runtime })
+  }
   return Array.from(out.values()).sort(
     (a, b) =>
       a.personality.localeCompare(b.personality) || a.runtime.localeCompare(b.runtime),