@agfpd/iapeer 0.4.31 → 0.4.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.31",
+  "version": "0.4.32",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -100,6 +100,9 @@ export interface PeerListing {
   default_runtime: Runtime
   /** Runtime with the freshest activity (what `attach` resumes); undefined if none. */
   last_active_runtime?: Runtime
+  /** Epoch-ms of that freshest activity (the dashboard's ACTIVE age column);
+   *  undefined when no runtime has an activity proxy. */
+  last_active_ms?: number
   intelligence: Intelligence
   description: string
   /** The peer's working directory (registry fact). Machine-readable so host-local
@@ -149,6 +152,7 @@ export function listPeers(opts: CliEnvOptions = {}): PeerListing[] {
       personality: peer.personality,
       default_runtime: peer.runtime,
       last_active_runtime: lastActive,
+      last_active_ms: bestMt >= 0 ? bestMt : undefined,
       intelligence: peer.intelligence,
       description: peer.description,
       cwd: peer.cwd,
@@ -1754,11 +1758,15 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return r.bootstrapped && (r.bootstrapped.state === 'failed' || r.bootstrapped.state === 'refused-foreign') ? 1 : 0
       }
       case 'list': {
-        // tty + no --json → the interactive control-panel (↑/↓ · Enter=attach · / · q);
-        // non-tty / --json → the scriptable table (machine-parsable).
+        // tty + no --json → the live Ink dashboard (Фаза 3: host header · live peer
+        // table · per-peer log panel · Enter=attach via suspend-and-spawn);
+        // non-tty / --json → the scriptable table (machine-parsable). The dashboard
+        // fails CLOSED to the table when no real TTY drives it (sentinel), the same
+        // belt as the onboard wizard.
         if (flags.json !== true && process.stdout.isTTY && process.stdin.isTTY) {
-          const { runListTui } = await import('./listTui.ts')
-          return await runListTui(env)
+          const { runDashboard, DASHBOARD_NOT_INTERACTIVE } = await import('../tui/dashboard/run.tsx')
+          const code = await runDashboard({ env })
+          if (code !== DASHBOARD_NOT_INTERACTIVE) return code
         }
         const rows = listPeers({ env })
         out(flags.json ? JSON.stringify(rows, null, 2) + '\n' : formatListTable(rows))

package/src/tui/dashboard/app.tsx

@@ -0,0 +1,256 @@
+// DashboardApp — the live management dashboard (Ink), the tty form of `iapeer list`
+// (Фаза 3 «TUI-редизайн management», эталон вкуса — Claude Code, владелец 02.07).
+//
+// Presents: a host header (daemon / memory / voice health), a live peer table
+// (per-runtime liveness ● ○ ✕, nature, last-activity age), an optional per-peer
+// event-log panel (delivery + lifecycle), and a hint footer. State is polled
+// in-process (решение B1) — peers every POLL_MS, host header every HOST_POLL_MS.
+//
+// The app itself never touches the terminal beyond Ink: attach is an ACTION handed
+// to run.tsx (suspend-and-spawn — Ink unmounts, `iapeer attach` child inherits the
+// real TTY, dashboard remounts on its exit). Quit likewise. That keeps ownership of
+// raw-mode/alt-screen in exactly one place (run.tsx).
+
+import React, { useEffect, useRef, useState } from 'react'
+import { Box, Text, useApp, useInput, useStdout } from 'ink'
+import type { PeerListing, RuntimeLiveness } from '../../cli/index.ts'
+import { clampCursor, ellipsize, filterRows, formatAge, scrollWindow } from './model.ts'
+import { takeHostHeader, takePeerLog, takePeersSnapshot, type HostHeader } from './data.ts'
+
+export type DashAction = { type: 'attach'; personality: string } | { type: 'quit' }
+
+const POLL_MS = 2000
+const HOST_POLL_MS = 10_000
+const LOG_LIMIT = 12
+
+const STATUS_GLYPH: Record<RuntimeLiveness, string> = { live: '●', asleep: '○', stopped: '✕' }
+const STATUS_COLOR: Record<RuntimeLiveness, string | undefined> = { live: 'green', asleep: undefined, stopped: 'red' }
+
+function RuntimeCells({ row }: { row: PeerListing }): React.ReactElement {
+  return (
+    <>
+      {row.runtimes.map((s, i) => (
+        <React.Fragment key={s.runtime}>
+          {i > 0 ? <Text> </Text> : null}
+          <Text color={STATUS_COLOR[s.status]} dimColor={s.status === 'asleep'}>
+            {STATUS_GLYPH[s.status]} {s.runtime}
+          </Text>
+        </React.Fragment>
+      ))}
+    </>
+  )
+}
+
+export function DashboardApp({
+  env,
+  onAction,
+}: {
+  env: NodeJS.ProcessEnv
+  onAction: (a: DashAction) => void
+}): React.ReactElement {
+  const { exit } = useApp()
+  const { stdout } = useStdout()
+  const [rows, setRows] = useState<PeerListing[]>(() => takePeersSnapshot(env))
+  const [host, setHost] = useState<HostHeader | null>(null)
+  const [now, setNow] = useState<number>(() => Date.now())
+  const [cursor, setCursor] = useState(0)
+  const [filter, setFilter] = useState('')
+  const [filterMode, setFilterMode] = useState(false)
+  const [logsOpen, setLogsOpen] = useState(false)
+  const [logLines, setLogLines] = useState<Array<{ text: string; tone: 'ok' | 'fail' | 'info' }>>([])
+  // NB: a pty can report 0×0 (ws unset) — `??` alone would keep the zero, so clamp
+  // through a positive-or-default helper everywhere a dimension is read.
+  const dim = (v: number | undefined, d: number): number => (v && v > 0 ? v : d)
+  const [size, setSize] = useState({ cols: dim(stdout?.columns, 80), rows: dim(stdout?.rows, 24) })
+  const doneRef = useRef(false)
+
+  const finish = (a: DashAction): void => {
+    if (doneRef.current) return
+    doneRef.current = true
+    onAction(a)
+    exit()
+  }
+
+  // peers + clock poll (fast), host header poll (slow), resize.
+  useEffect(() => {
+    const t = setInterval(() => {
+      setRows(takePeersSnapshot(env))
+      setNow(Date.now())
+    }, POLL_MS)
+    return () => clearInterval(t)
+  }, [env])
+  useEffect(() => {
+    let gone = false
+    const probe = (): void => {
+      void takeHostHeader(env).then(h => {
+        if (!gone) setHost(h)
+      })
+    }
+    probe()
+    const t = setInterval(probe, HOST_POLL_MS)
+    return () => {
+      gone = true
+      clearInterval(t)
+    }
+  }, [env])
+  useEffect(() => {
+    if (!stdout) return
+    const onResize = (): void => setSize({ cols: dim(stdout.columns, 80), rows: dim(stdout.rows, 24) })
+    stdout.on('resize', onResize)
+    return () => {
+      stdout.off('resize', onResize)
+    }
+  }, [stdout])
+
+  const visible = filterRows(rows, filter)
+  const cur = clampCursor(cursor, visible.length)
+  const selected = visible[cur]
+
+  // per-peer log panel poll — only while open, keyed to the selected peer.
+  useEffect(() => {
+    if (!logsOpen || !selected) return
+    const load = (): void => setLogLines(takePeerLog(env, selected.personality, LOG_LIMIT))
+    load()
+    const t = setInterval(load, POLL_MS)
+    return () => clearInterval(t)
+  }, [logsOpen, selected?.personality, env])
+
+  useInput((input, key) => {
+    if (filterMode) {
+      if (key.return || key.escape) setFilterMode(false)
+      else if (key.backspace || key.delete) setFilter(f => f.slice(0, -1))
+      else if (input && !key.ctrl && !key.meta) setFilter(f => f + input)
+      setCursor(0)
+      return
+    }
+    if (input === 'q' || (key.ctrl && input === 'c')) return finish({ type: 'quit' })
+    if (key.escape) {
+      if (logsOpen) setLogsOpen(false)
+      else if (filter) setFilter('')
+      return
+    }
+    if (input === '/') return setFilterMode(true)
+    if (input === 'l') return setLogsOpen(o => !o)
+    if (input === 'r') {
+      setRows(takePeersSnapshot(env))
+      setNow(Date.now())
+      return
+    }
+    if (key.upArrow || input === 'k') return setCursor(c => clampCursor(c - 1, visible.length))
+    if (key.downArrow || input === 'j') return setCursor(c => clampCursor(c + 1, visible.length))
+    if (key.return && selected) return finish({ type: 'attach', personality: selected.personality })
+  })
+
+  // ── layout ──────────────────────────────────────────────────────────────────
+  const liveCount = rows.filter(r => r.runtimes.some(s => s.status === 'live')).length
+  // fixed rows around the table: header(1) + header-margin(1) + column line(1) +
+  // "↓ N more"(1) + footer margin+line(2) + one spare against terminal rounding.
+  const overhead = 7 + (logsOpen ? LOG_LIMIT + 3 : 0) + (filterMode || filter ? 1 : 0)
+  const tableHeight = Math.max(3, size.rows - overhead)
+  const win = scrollWindow(cur, visible.length, tableHeight)
+  const nameW = Math.min(18, Math.max(6, ...visible.map(r => r.personality.length)))
+  const rtW = Math.max(10, ...visible.map(r => r.runtimes.map(s => `x ${s.runtime}`).join(' ').length))
+  const descW = Math.max(0, size.cols - (2 + nameW + 2 + rtW + 2 + 10 + 2 + 6 + 2) - 2)
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      {/* host header */}
+      <Box justifyContent="space-between">
+        <Box>
+          <Text color="cyan" bold>
+            ⏺ iapeer
+          </Text>
+          <Text bold> peers</Text>
+          <Text dimColor>
+            {'  '}
+            {rows.length} peers · {liveCount} live
+          </Text>
+        </Box>
+        <Box>
+          {host ? (
+            <>
+              <Text dimColor>v{host.version} · daemon </Text>
+              <Text color={host.daemonHealthy ? 'green' : 'red'}>{host.daemonHealthy ? '●' : '✕'}</Text>
+              <Text dimColor> · memory </Text>
+              <Text color={host.memory.present ? 'green' : undefined} dimColor={!host.memory.present}>
+                {host.memory.present ? '●' : '○'}
+              </Text>
+              <Text dimColor> · voice </Text>
+              <Text color={host.voice.present ? 'green' : undefined} dimColor={!host.voice.present}>
+                {host.voice.present ? '●' : '○'}
+              </Text>
+            </>
+          ) : (
+            <Text dimColor>probing host…</Text>
+          )}
+        </Box>
+      </Box>
+      <Box marginTop={1}>
+        <Text dimColor>
+          {'  '}
+          {'NAME'.padEnd(nameW)} {'RUNTIMES'.padEnd(rtW)} {'NATURE'.padEnd(10)} {'ACTIVE'.padEnd(6)} DESCRIPTION
+        </Text>
+      </Box>
+
+      {/* peer table (scroll window) */}
+      <Box flexDirection="column">
+        {visible.length === 0 ? (
+          <Text dimColor> (no peers{filter ? ' match' : ' registered'})</Text>
+        ) : (
+          visible.slice(win.start, win.end).map((r, i) => {
+            const idx = win.start + i
+            const sel = idx === cur
+            return (
+              <Box key={r.personality}>
+                <Text color={sel ? 'cyan' : undefined} bold={sel}>
+                  {sel ? '❯ ' : '  '}
+                  {ellipsize(r.personality, nameW).padEnd(nameW)}{' '}
+                </Text>
+                <Box width={rtW + 1}>
+                  <RuntimeCells row={r} />
+                </Box>
+                <Text dimColor> {r.intelligence.padEnd(10)}</Text>
+                <Text color={sel ? 'cyan' : undefined} dimColor={!sel}>
+                  {' '}
+                  {formatAge(r.last_active_ms, now).padEnd(6)}
+                </Text>
+                <Text dimColor> {ellipsize(r.description, descW)}</Text>
+              </Box>
+            )
+          })
+        )}
+        {visible.length > win.end ? <Text dimColor> ↓ {visible.length - win.end} more</Text> : null}
+      </Box>
+
+      {/* per-peer log panel */}
+      {logsOpen && selected ? (
+        <Box marginTop={1} flexDirection="column" borderStyle="round" borderDimColor paddingX={1}>
+          <Text dimColor>logs · {selected.personality} (delivery + lifecycle)</Text>
+          {logLines.length === 0 ? (
+            <Text dimColor>(no recent events)</Text>
+          ) : (
+            logLines.map((l, i) => (
+              <Text key={i} color={l.tone === 'fail' ? 'red' : l.tone === 'ok' ? undefined : undefined} dimColor={l.tone !== 'fail'}>
+                {ellipsize(l.text, Math.max(10, size.cols - 6))}
+              </Text>
+            ))
+          )}
+        </Box>
+      ) : null}
+
+      {/* filter + footer */}
+      {filterMode ? (
+        <Text>
+          <Text color="cyan">/</Text>
+          {filter}
+          <Text color="cyan">▌</Text>
+        </Text>
+      ) : filter ? (
+        <Text dimColor>filter: {filter} (esc to clear)</Text>
+      ) : null}
+      <Box marginTop={1}>
+        <Text dimColor>↑↓ move · ⏎ attach · l logs · / filter · r refresh · q quit</Text>
+      </Box>
+    </Box>
+  )
+}

package/src/tui/dashboard/data.ts

@@ -0,0 +1,79 @@
+// Dashboard DATA — the in-process state feed (решение B1: фундамент-примитивы, не
+// RPC): peer rows via listPeers (registry + per-runtime liveness + last-active), the
+// host header via hostStatus (daemon health probe + memory/voice slots), and the
+// per-peer event-log tails (delivery.log + lifecycle.log under cfg.eventLogDir).
+//
+// All paths resolve through the injected env → the same IAPEER_ROOT isolation as
+// every other side-effect (sandbox rule). Reads only — the dashboard mutates nothing.
+
+import { closeSync, openSync, readSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { listPeers, type PeerListing } from '../../cli/index.ts'
+import { loadLifecycleConfig } from '../../lifecycle/index.ts'
+import { deliveryLogPath } from '../../daemon/deliverylog.ts'
+import { lifecycleLogPath } from '../../lifecycle/eventlog.ts'
+import { assemblePeerLog } from './model.ts'
+
+/** One peers snapshot (the poll unit). listPeers is synchronous and cheap: registry
+ *  read + pidfile kill-0 liveness + transcript/pane-log statSync per peer. */
+export function takePeersSnapshot(env: NodeJS.ProcessEnv): PeerListing[] {
+  return listPeers({ env })
+}
+
+export interface HostHeader {
+  version: string
+  daemonHealthy: boolean
+  memory: { present: boolean; label: string }
+  voice: { present: boolean; label: string }
+}
+
+/** The host header line (slow poll — the daemon probe has its own short timeout).
+ *  Dynamic import keeps the update/status modules out of the fast peers-poll path. */
+export async function takeHostHeader(env: NodeJS.ProcessEnv): Promise<HostHeader> {
+  const { hostStatus } = await import('../../status/index.ts')
+  const s = await hostStatus({ env })
+  const slot = (p: { provider: string; version: string } | null, hbAge: number | null): { present: boolean; label: string } =>
+    p ? { present: true, label: `${p.version}${hbAge !== null ? ` · hb ${hbAge}s` : ''}` } : { present: false, label: 'none' }
+  return {
+    version: s.version,
+    daemonHealthy: s.daemon.healthy,
+    memory: slot(s.memory.provider, s.memory.heartbeatAgeSecs),
+    voice: slot(s.voice.provider, s.voice.heartbeatAgeSecs),
+  }
+}
+
+/** Read the last `bytes` of a file without loading the whole log (delivery.log can
+ *  be MBs before rotation). Missing/unreadable file → ''. */
+export function readTail(path: string, bytes = 64 * 1024): string {
+  try {
+    const size = statSync(path).size
+    const fd = openSync(path, 'r')
+    try {
+      const start = Math.max(0, size - bytes)
+      const buf = Buffer.alloc(size - start)
+      readSync(fd, buf, 0, buf.length, start)
+      // drop the leading partial line when we started mid-file
+      const s = buf.toString('utf8')
+      return start > 0 ? s.slice(s.indexOf('\n') + 1) : s
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return ''
+  }
+}
+
+/** The per-peer log panel content: newest `limit` events concerning the peer from
+ *  delivery.log + lifecycle.log (merged by timestamp). */
+export function takePeerLog(env: NodeJS.ProcessEnv, personality: string, limit: number): Array<{ text: string; tone: 'ok' | 'fail' | 'info' }> {
+  const cfg = loadLifecycleConfig(env)
+  const tails = [readTail(deliveryLogPath(cfg.eventLogDir)), readTail(lifecycleLogPath(cfg.eventLogDir))]
+  return assemblePeerLog(tails, personality, limit)
+}
+
+/** The pane-log path of a peer address — reserved for a future raw-view; unused by
+ *  the prototype (raw pty bytes are an attach concern, not a log panel one). */
+export function paneLogPath(env: NodeJS.ProcessEnv, address: string): string {
+  const cfg = loadLifecycleConfig(env)
+  return join(cfg.logDir, `${address}.log`)
+}

package/src/tui/dashboard/model.ts

@@ -0,0 +1,127 @@
+// Dashboard MODEL — the pure logic of the management dashboard (Фаза 3 «TUI-редизайн
+// management»): row filtering, activity-age formatting, event-log line parsing and
+// per-peer log assembly. NO Ink, NO I/O — unit-testable in isolation (the same
+// pure-core discipline as listTui.ts / the onboard wizard state machine).
+//
+// The VIEW (app.tsx) renders this; the DATA layer (data.ts) feeds it; run.tsx owns
+// the terminal. Keeping the model pure is what lets the dashboard stay testable
+// under `bun test` with zero terminal plumbing.
+
+import type { PeerListing } from '../../cli/index.ts'
+
+// ─── row filtering ───────────────────────────────────────────────────────────
+
+/** Rows matching the filter (case-insensitive substring over personality/description). */
+export function filterRows(rows: PeerListing[], filter: string): PeerListing[] {
+  const f = filter.trim().toLowerCase()
+  if (!f) return rows
+  return rows.filter(r => r.personality.toLowerCase().includes(f) || r.description.toLowerCase().includes(f))
+}
+
+/** Clamp the cursor into the filtered row set (rows shrink under a live filter). */
+export function clampCursor(cursor: number, visibleCount: number): number {
+  if (visibleCount <= 0) return 0
+  return Math.min(Math.max(0, cursor), visibleCount - 1)
+}
+
+/** The scroll window [start, end) of `height` rows keeping `cursor` visible. */
+export function scrollWindow(cursor: number, total: number, height: number): { start: number; end: number } {
+  if (total <= height) return { start: 0, end: total }
+  const start = Math.min(Math.max(0, cursor - Math.floor(height / 2)), total - height)
+  return { start, end: start + height }
+}
+
+// ─── activity age ────────────────────────────────────────────────────────────
+
+/** Compact k9s/CC-style age: 12s · 4m · 3h · 2d; '—' when unknown. */
+export function formatAge(mtimeMs: number | undefined, nowMs: number): string {
+  if (mtimeMs === undefined || mtimeMs <= 0) return '—'
+  const s = Math.max(0, Math.floor((nowMs - mtimeMs) / 1000))
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m`
+  const h = Math.floor(m / 60)
+  if (h < 48) return `${h}h`
+  return `${Math.floor(h / 24)}d`
+}
+
+// ─── event-log parsing (ts=… ev=… k=v lines from delivery.log / lifecycle.log) ──
+
+export interface LogEvent {
+  tsMs: number
+  /** HH:MM:SS local time for display. */
+  time: string
+  ev: string
+  fields: Record<string, string>
+}
+
+/** Parse one `ts=<iso> ev=<kind> k=v …` line; null for anything else (corrupt tail). */
+export function parseEventLine(line: string): LogEvent | null {
+  if (!line.startsWith('ts=')) return null
+  const fields: Record<string, string> = {}
+  // k=v tokens; values are token-atomic in our append format (no embedded spaces).
+  for (const tok of line.split(' ')) {
+    const i = tok.indexOf('=')
+    if (i > 0) fields[tok.slice(0, i)] = tok.slice(i + 1)
+  }
+  const ts = fields.ts
+  const ev = fields.ev
+  if (!ts || !ev) return null
+  const tsMs = Date.parse(ts)
+  if (!Number.isFinite(tsMs)) return null
+  const d = new Date(tsMs)
+  const pad = (n: number): string => String(n).padStart(2, '0')
+  return { tsMs, time: `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`, ev, fields }
+}
+
+/** Does this event concern the peer? Matches bare personality and any `<rt>-<personality>`
+ *  identity in the fields the two logs actually carry (to/caller/via/personality/identity). */
+export function eventConcernsPeer(e: LogEvent, personality: string): boolean {
+  const idSuffix = `-${personality}`
+  for (const key of ['to', 'caller', 'via', 'personality', 'identity', 'from', 'peer'] as const) {
+    const v = e.fields[key]
+    if (!v) continue
+    if (v === personality || v.endsWith(idSuffix)) return true
+  }
+  return false
+}
+
+/** One display line per event — compact, the interesting fields only. */
+export function formatEvent(e: LogEvent): { text: string; tone: 'ok' | 'fail' | 'info' } {
+  const f = e.fields
+  if (e.ev === 'delivery') {
+    const ok = f.ok === 'true'
+    return {
+      text: `${e.time} delivery ${f.caller ?? '?'} → ${f.to ?? '?'} ${ok ? 'ok' : 'FAIL'}${f.ms ? ` ${f.ms}ms` : ''}${f.woke === 'true' ? ' (woke)' : ''}`,
+      tone: ok ? 'ok' : 'fail',
+    }
+  }
+  const rest = Object.entries(f)
+    .filter(([k]) => k !== 'ts' && k !== 'ev')
+    .map(([k, v]) => `${k}=${v}`)
+    .join(' ')
+  return { text: `${e.time} ${e.ev} ${rest}`.trimEnd(), tone: e.ev.includes('error') || e.ev.includes('fail') ? 'fail' : 'info' }
+}
+
+/** Assemble the per-peer log panel: parse both raw tails, filter to the peer, merge
+ *  by timestamp, keep the newest `limit`. */
+export function assemblePeerLog(rawTails: string[], personality: string, limit: number): Array<{ text: string; tone: 'ok' | 'fail' | 'info' }> {
+  const events: LogEvent[] = []
+  for (const raw of rawTails) {
+    for (const line of raw.split('\n')) {
+      const e = parseEventLine(line)
+      if (e && eventConcernsPeer(e, personality)) events.push(e)
+    }
+  }
+  events.sort((a, b) => a.tsMs - b.tsMs)
+  return events.slice(-limit).map(formatEvent)
+}
+
+// ─── ellipsis ────────────────────────────────────────────────────────────────
+
+/** Truncate to `width` code points with a … tail (multi-byte-safe via the spread). */
+export function ellipsize(s: string, width: number): string {
+  if (width <= 0) return ''
+  const chars = [...s]
+  return chars.length <= width ? s : chars.slice(0, Math.max(0, width - 1)).join('') + '…'
+}

package/src/tui/dashboard/run.tsx

@@ -0,0 +1,96 @@
+// runDashboard — the Ink entry point + terminal owner of the management dashboard
+// (tty form of `iapeer list`). Owns EVERYTHING terminal-shaped so the app stays pure:
+//
+//  - alt-screen: the dashboard is a full-screen live surface; it renders on the
+//    alternate screen so quitting restores the operator's scrollback untouched
+//    (Apple Terminal keeps no E3, so repeated in-scrollback repaints would pile up —
+//    the alt-screen sidesteps that class entirely).
+//  - интерактив только в реальном TTY (контракт фазы): stdin+stdout must both be
+//    TTYs, else the caller falls back to the scriptable table (never render + hang;
+//    the same fail-closed belt as the onboard wizard).
+//  - TUI↔TUI handoff = suspend-and-spawn (решение фазы, Требование-1): on attach the
+//    dashboard fully unmounts + leaves the alt-screen + returns the terminal to
+//    cooked mode, then spawns `iapeer attach <peer>` as a CHILD with inherited stdio
+//    (the runtime TUI gets the REAL tty — the readline-class constraint), waits, and
+//    remounts. One full-screen TUI owns the terminal at any moment.
+//
+// Self-invocation uses the same `$bunfs` discriminator as supervisor's
+// resolveDaemonSelfArgv: compiled standalone → re-invoke the binary by verb; running
+// from src → `bun <cli/index.ts> attach …`.
+
+import React from 'react'
+import { render } from 'ink'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { DashboardApp, type DashAction } from './app.tsx'
+
+/** Sentinel: no real interactive TTY — the caller should print the scriptable table. */
+export const DASHBOARD_NOT_INTERACTIVE = -1
+
+const ALT_SCREEN_ON = '\x1b[?1049h\x1b[H'
+const ALT_SCREEN_OFF = '\x1b[?1049l'
+
+/** argv prefix that re-invokes THIS package's CLI (compiled binary by verb / src via
+ *  bun). Same discriminator as supervisor/index.ts resolveDaemonSelfArgv: `$bunfs` in
+ *  the module path marks the compiled standalone (existsSync is NO discriminator —
+ *  Bun intercepts bunfs reads). */
+export function resolveSelfCliArgv(execPath: string, selfPath: string): string[] {
+  return selfPath.includes('$bunfs') ? [execPath] : [execPath, selfPath]
+}
+
+function selfCliArgv(): string[] {
+  return resolveSelfCliArgv(process.execPath, fileURLToPath(new URL('../../cli/index.ts', import.meta.url)))
+}
+
+export interface DashboardOptions {
+  env?: NodeJS.ProcessEnv
+}
+
+/** Mount the dashboard once; resolve with the action that ended it. */
+async function mountOnce(env: NodeJS.ProcessEnv): Promise<DashAction> {
+  let action: DashAction = { type: 'quit' }
+  process.stdout.write(ALT_SCREEN_ON)
+  try {
+    const app = render(<DashboardApp env={env} onAction={a => (action = a)} />, {
+      // the dashboard repaints in place on the alt screen; Ctrl-C is handled by the
+      // app itself (quit action) so a half-torn frame never leaks to the main screen
+      exitOnCtrlC: false,
+    })
+    await app.waitUntilExit()
+  } finally {
+    process.stdout.write(ALT_SCREEN_OFF)
+  }
+  return action
+}
+
+/**
+ * Run the live management dashboard. Loops mount → (attach child) → remount until
+ * quit. Returns the process exit code, or DASHBOARD_NOT_INTERACTIVE when there is no
+ * real TTY to drive it (caller falls back to the scriptable table).
+ */
+export async function runDashboard(opts: DashboardOptions = {}): Promise<number> {
+  const env = opts.env ?? process.env
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) return DASHBOARD_NOT_INTERACTIVE
+  for (;;) {
+    let action: DashAction
+    try {
+      action = await mountOnce(env)
+    } catch {
+      // raw-mode unsupported / render failed → let the caller fall back, never hang
+      return DASHBOARD_NOT_INTERACTIVE
+    }
+    if (action.type === 'quit') return 0
+    // suspend-and-spawn: the child owns the real TTY until the operator detaches
+    // (Ctrl-]) or the session ends; then the dashboard remounts with fresh state.
+    const argv = selfCliArgv()
+    const r = spawnSync(argv[0]!, [...argv.slice(1), 'attach', action.personality], {
+      stdio: 'inherit',
+      env,
+    })
+    if (r.error) {
+      process.stdout.write(`attach failed: ${r.error.message}\npress Enter to continue…`)
+      // swallow one line so the operator sees the error before the alt-screen returns
+      spawnSync('sh', ['-c', 'read _'], { stdio: 'inherit' })
+    }
+  }
+}