@agfpd/iapeer 0.2.57 → 0.2.59

package/README.md

@@ -0,0 +1,11 @@
+# iapeer
+
+Ядро мультиагентной системы на одном хосте: реестр пиров, единый демон-роутер для обмена сообщениями между ними и команды управления — создание, запуск, усыпление, перезапуск, подключение к внешним каналам. Пиром может быть AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс; все адресуются одинаково через один протокол.
+
+## Документация
+
+Документация проекта — в [`docs/`](docs/README.md): продуктовая часть (что это и как пользоваться) и механика изнутри ([`docs/internals/`](docs/internals/README.md)). Этот репозиторий — кодовая реализация.
+
+## Статус
+
+Версия — **0.2.58**. Платформа — macOS/launchd.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.57",
+  "version": "0.2.59",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
+    "@xterm/headless": "6.0.0",
     "proper-lockfile": "^4.1.2",
     "transliteration": "^2.6.1"
   },

package/src/cli/index.ts

@@ -936,6 +936,9 @@ const USAGE = `usage: iapeer <verb> [args]
   self-done                                                      (agent self-call, ephemeral) silent finish: arm own quiet-reap, wake no one
   native-memory <off|on> (--peer <p> | --all)                    gate/restore runtimes' native memory (canonized lever; контракт «Слот памяти»)
   trust-hooks <hooks.json> [--check]                             pre-seed codex hooks trust for a file-form hooks.json (no modal); --check = drift report
+  shadow [--once | --minutes <m>] [--interval <ms>]              READ-ONLY tmux→pty fidelity observer (migration burn-in): compares pty-model verdicts vs live tmux on the warm fleet → ~/.iapeer/logs/iapeer/shadow-fidelity.json. Never delivers/mutates.
+  shadow-install                                                 install + load the always-on shadow burn-in launchd job (com.iapeer.shadow-fidelity); idempotent, re-cycled by update/rollback
+  shadow-uninstall                                               bootout + remove the shadow burn-in launchd job (the correct way to stop it; STOP file is respawned past by KeepAlive)
 `
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
@@ -1750,6 +1753,54 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach-end', identity: r.identity, rc: a.status ?? -1 }, { env })
         return a.status ?? 0
       }
+      case 'shadow': {
+        // Read-only fidelity OBSERVER for the tmux→pty migration burn-in (track «b»). Compares
+        // the pty-model verdicts (occupancy/ready-gate/liveness) vs live tmux verdicts on the
+        // warm fleet, logs to <eventLogDir>/shadow-fidelity.{jsonl,json}. STRICTLY read-only —
+        // nothing in delivery/lifecycle imports the shadow module; the dynamic import keeps
+        // @xterm OUT of the hot path (the daemon never loads it). --once | --minutes <m> |
+        // --interval <ms>; stop a long run with `touch <eventLogDir>/shadow-fidelity.STOP`.
+        const cfg = loadLifecycleConfig(env)
+        const { runShadowFidelity } = await import('../shadow/index.ts')
+        await runShadowFidelity({
+          logDir: cfg.logDir,
+          eventLogDir: cfg.eventLogDir,
+          sockDir: cfg.sockDir,
+          intervalMs: flags.interval ? Number(flags.interval) : 5000,
+          maxMinutes: flags.minutes ? Number(flags.minutes) : 0,
+          once: flags.once === true,
+          log: errOut,
+        })
+        out(`shadow-fidelity → ${cfg.eventLogDir}/shadow-fidelity.json\n`)
+        return 0
+      }
+      case 'shadow-install': {
+        // Code-managed install of the always-on shadow burn-in launchd job
+        // (com.iapeer.shadow-fidelity) — reproducible, ownership-sentinel-guarded, and
+        // re-cycled automatically by `iapeer update` / `rollback`. Replaces a hand-written
+        // plist. Idempotent (no-op on an unchanged, loaded job). install.ts carries NO @xterm
+        // — dynamic-imported anyway to keep the CLI's common path light.
+        const { installShadowJob } = await import('../shadow/install.ts')
+        const r = installShadowJob(env)
+        if (r.action === 'failed' || r.action === 'refused-foreign') {
+          errOut(`shadow-install: ${r.action}${r.detail ? ` — ${r.detail}` : ''}\n  plist: ${r.path}\n`)
+          return 1
+        }
+        out(`shadow burn-in job ${r.action} (plist ${r.changed ? 'written' : 'unchanged'}): ${r.path}\n`)
+        return 0
+      }
+      case 'shadow-uninstall': {
+        // Stop + remove the burn-in job (bootout + rm) — the CORRECT halt (KeepAlive would
+        // respawn past the STOP sentinel). Refuses a non-foundation plist (ownership guard).
+        const { uninstallShadowJob } = await import('../shadow/install.ts')
+        const r = uninstallShadowJob(env)
+        if (r.action === 'failed' || r.action === 'refused-foreign') {
+          errOut(`shadow-uninstall: ${r.action}${r.detail ? ` — ${r.detail}` : ''}\n  plist: ${r.path}\n`)
+          return 1
+        }
+        out(`shadow burn-in job ${r.action}: ${r.path}\n`)
+        return 0
+      }
       default: {
         // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh.
         if (verb && isRuntime(verb)) {

package/src/shadow/index.ts

@@ -0,0 +1,170 @@
+// Read-only fidelity OBSERVER for the tmux→pty migration (prod burn-in track «b»).
+//
+// For each warm claude/codex peer it builds an @xterm/headless model from the daemon's
+// EXISTING pipe-pane log (`<identity>.log` under cfg.logDir) — the same raw child bytes
+// tmux's emulator gets — and compares the PTY-model verdicts (composer-occupancy / ready-gate
+// / liveness) to the live AUTHORITATIVE tmux verdicts, logging divergences + rolling fidelity
+// to `<eventLogDir>/shadow-fidelity.{jsonl,json}`.
+//
+// STRICTLY READ-ONLY: it tails log FILES and runs read-only tmux (`capture-pane`/`display`/
+// `has-session`). It NEVER delivers, sends keys, spawns, or touches delivery/lifecycle/
+// registry/launch. Nothing in the delivery/lifecycle hot paths imports this module — it runs
+// ONLY via the `iapeer shadow` CLI verb (dynamic-imported, so @xterm is never loaded in the
+// daemon). With it off, the daemon's behavior is byte-identical. This is the prod burn-in:
+// the supervisor's model proven alongside tmux on real traffic BEFORE any delivery cutover.
+import { Terminal } from '@xterm/headless'
+import { openSync, closeSync, fstatSync, readSync, existsSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmux, composerCaptureHasHumanInput, listOnlinePeers } from '../transport/index.ts'
+import { getAdapter } from '../launch/index.ts'
+import { buildSocketPath, buildProcessAddress } from '../core/socket.ts'
+import type { Runtime } from '../core/constants.ts'
+
+const SEED_BYTES = 4 * 1024 * 1024
+const promptGlyph = (rt: string): string => (rt === 'claude' ? '❯' : '›')
+const pidAlive = (pid: number): boolean => {
+  try { process.kill(pid, 0); return true } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM' }
+}
+
+/** PTY composer-occupancy verdict: getCell on the model's viewport composer row (the row whose
+ *  first visible cell is the prompt glyph); human input = a non-ghost (non-dim, non-grey246)
+ *  visible cell after it. Mirrors composerCaptureHasHumanInput — validated 0-divergence vs it. */
+export function composerOccupancyFromModel(term: Terminal, cols: number, rows: number, runtime: string): boolean {
+  const b = term.buffer.active, top = b.baseY, bot = b.baseY + rows, g = promptGlyph(runtime)
+  let py = -1, px = -1
+  for (let y = top; y < bot; y++) {
+    const l = b.getLine(y); if (!l) continue
+    let fx = -1
+    for (let x = 0; x < cols; x++) { if ((l.getCell(x)?.getChars() || ' ').trim() !== '') { fx = x; break } }
+    if (fx < 0) continue
+    if (l.getCell(fx)!.getChars() === g) { py = y; px = fx }
+  }
+  if (py < 0) return false
+  const l = b.getLine(py)!
+  for (let x = px + 1; x < cols; x++) {
+    const c = l.getCell(x); if ((c?.getChars() || ' ').trim() === '') continue
+    if (!(c!.isDim() || (c!.isFgPalette() && c!.getFgColor() === 246))) return true
+  }
+  return false
+}
+
+/** The model's viewport as PLAIN text (mimics `capture-pane -p`, the input isInputReady takes). */
+export function modelToPlainText(term: Terminal, cols: number, rows: number): string {
+  const b = term.buffer.active, lines: string[] = []
+  for (let y = b.baseY; y < b.baseY + rows; y++) {
+    const l = b.getLine(y); if (!l) { lines.push(''); continue }
+    let s = ''
+    for (let x = 0; x < cols; x++) s += l.getCell(x)?.getChars() || ' '
+    lines.push(s.replace(/\s+$/, ''))
+  }
+  return lines.join('\n')
+}
+
+interface Obs { addr: string; sock: string; runtime: Runtime; cols: number; rows: number; term: Terminal; fd: number; offset: number }
+
+export interface ShadowOptions {
+  logDir: string        // daemon pane-logs live here (<identity>.log)
+  eventLogDir: string   // shadow-fidelity.{jsonl,json} written here
+  sockDir: string
+  intervalMs?: number
+  maxMinutes?: number   // 0/undefined + once=false → run until <eventLogDir>/shadow-fidelity.STOP
+  once?: boolean
+  log?: (s: string) => void
+}
+
+function feed(o: Obs): Promise<void> {
+  const sz = fstatSync(o.fd).size
+  if (sz <= o.offset) return Promise.resolve()
+  const buf = Buffer.alloc(sz - o.offset)
+  readSync(o.fd, buf, 0, buf.length, o.offset)
+  o.offset = sz
+  return new Promise(res => o.term.write(buf, () => res()))
+}
+
+function enumerate(models: Map<string, Obs>, opts: ShadowOptions): void {
+  let peers: { runtime: Runtime; personality: string }[] = []
+  try { peers = listOnlinePeers(opts.sockDir).filter(p => p.runtime === 'claude' || p.runtime === 'codex') } catch { return }
+  const live = new Set<string>()
+  for (const p of peers) {
+    const addr = buildProcessAddress(p.runtime, p.personality); live.add(addr)
+    if (models.has(addr)) continue
+    try {
+      const sock = buildSocketPath(p.runtime, p.personality, opts.sockDir)
+      const log = join(opts.logDir, `${addr}.log`); if (!existsSync(log)) continue
+      const geo = tmux(sock, 'display', '-p', '-t', addr, '#{pane_width}x#{pane_height}'); if (!geo.ok) continue
+      const [cols, rows] = geo.out.trim().split('x').map(Number); if (!cols || !rows) continue
+      const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 3000 })
+      const fd = openSync(log, 'r'); const offset = Math.max(0, fstatSync(fd).size - SEED_BYTES)
+      models.set(addr, { addr, sock, runtime: p.runtime, cols, rows, term, fd, offset })
+    } catch { /* a peer racing spawn/teardown — skip this round */ }
+  }
+  for (const [addr, o] of models) if (!live.has(addr)) { try { closeSync(o.fd) } catch { /* */ }; models.delete(addr) }
+}
+
+/** Run the read-only fidelity observer. Resolves when once/maxMinutes/STOP completes. */
+export async function runShadowFidelity(opts: ShadowOptions): Promise<void> {
+  mkdirSync(opts.eventLogDir, { recursive: true })
+  const jsonl = join(opts.eventLogDir, 'shadow-fidelity.jsonl')
+  const statsFile = join(opts.eventLogDir, 'shadow-fidelity.json')
+  const stopFile = join(opts.eventLogDir, 'shadow-fidelity.STOP')
+  const interval = opts.intervalMs ?? 5000
+  const log = opts.log ?? (() => { /* */ })
+  const models = new Map<string, Obs>()
+  const tot = { samples: 0, occDiv: 0, occNt: 0, rgDiv: 0, livDiv: 0 }
+  const startedISO = new Date().toISOString(), t0 = Date.now()
+  enumerate(models, opts)
+  for (const o of models.values()) await feed(o)  // seed each model
+  log(`shadow-fidelity: ${models.size} warm peers, interval ${interval}ms\n`)
+  let i = 0
+  for (;;) {
+    if (opts.maxMinutes && Date.now() - t0 >= opts.maxMinutes * 60000) break
+    if (existsSync(stopFile)) break
+    if (i > 0 && i % 15 === 0) enumerate(models, opts)
+    for (const o of models.values()) {
+      try {
+        await feed(o)
+        const adapter = getAdapter(o.runtime)
+        const capE = tmux(o.sock, 'capture-pane', '-e', '-p', '-t', o.addr); if (!capE.ok) continue
+        const occTmux = composerCaptureHasHumanInput(capE.out, adapter.deliveryMarkers)
+        const occPty = composerOccupancyFromModel(o.term, o.cols, o.rows, o.runtime)
+        const capP = tmux(o.sock, 'capture-pane', '-p', '-t', o.addr)
+        const rgTmux = capP.ok ? adapter.isInputReady(capP.out) : null
+        const rgPty = adapter.isInputReady(modelToPlainText(o.term, o.cols, o.rows))
+        const livTmux = tmux(o.sock, 'has-session', '-t', o.addr).ok
+        const ppid = tmux(o.sock, 'display', '-p', '-t', o.addr, '#{pane_pid}')
+        const pid = ppid.ok ? Number(ppid.out.trim()) : NaN
+        const livPty = Number.isFinite(pid) ? pidAlive(pid) : false
+
+        tot.samples++
+        const occDiv = occPty !== occTmux, rgDiv = rgTmux !== null && rgPty !== rgTmux, livDiv = livPty !== livTmux
+        const occNt = occPty || occTmux
+        if (occNt) tot.occNt++
+        if (occDiv) tot.occDiv++
+        if (rgDiv) tot.rgDiv++
+        if (livDiv) tot.livDiv++
+        if (occDiv || rgDiv || livDiv) {
+          appendFileSync(jsonl, JSON.stringify({
+            ts: new Date().toISOString(), peer: o.addr, geom: `${o.cols}x${o.rows}`,
+            occupancy: { pty: occPty, tmux: occTmux, diverged: occDiv, nontrivial: occNt },
+            readyGate: { pty: rgPty, tmux: rgTmux, diverged: rgDiv },
+            liveness: { pty: livPty, tmux: livTmux, diverged: livDiv },
+            ...(occDiv ? { capE: capE.out.slice(-2500), model: modelToPlainText(o.term, o.cols, o.rows).slice(-2500) } : {}),
+          }) + '\n')
+          log(`DIVERGE ${o.addr} occ=${occDiv} rg=${rgDiv} liv=${livDiv}${occNt && occDiv ? ' *** NON-TRIVIAL occ ***' : ''}\n`)
+        }
+      } catch { /* an observer error must NEVER escape — it is a passive sidecar */ }
+    }
+    i++
+    writeFileSync(statsFile, JSON.stringify({
+      startedISO, lastISO: new Date().toISOString(), elapsedMin: +((Date.now() - t0) / 60000).toFixed(1),
+      peers: models.size, samples: tot.samples,
+      occupancy: { divergences: tot.occDiv, nonTrivialSamples: tot.occNt },
+      readyGate: { divergences: tot.rgDiv },
+      liveness: { divergences: tot.livDiv },
+      fidelity: tot.samples ? +(1 - (tot.occDiv + tot.rgDiv + tot.livDiv) / (tot.samples * 3)).toFixed(6) : 1,
+    }, null, 2))
+    if (opts.once) break
+    await new Promise(r => setTimeout(r, interval))
+  }
+  for (const o of models.values()) { try { closeSync(o.fd) } catch { /* */ } }
+}

package/src/shadow/install.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { isFoundationOwnedPlist } from '../launch/launchd.ts'
+import {
+  SHADOW_PERSONALITY,
+  SHADOW_PLIST_LABEL,
+  buildShadowPlistSpec,
+  cycleShadowJob,
+  installShadowJob,
+  installShadowPlist,
+  shadowPlistPath,
+  uninstallShadowJob,
+} from './install.ts'
+
+// Hermetic: every plist write lands under IAPEER_LAUNCHAGENTS_DIR / IAPEER_ROOT overrides, and
+// the suite runs with IAPEER_TEST_SANDBOX=1 (process.env) so the launchctl-touching paths
+// (installShadowJob / cycleShadowJob / uninstallShadowJob) fail-CLOSED to skipped-sandbox — they
+// NEVER load/unload a real launchd job. No tmux, no @xterm (install.ts is pure plumbing).
+
+const tmpDirs: string[] = []
+function mkEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
+  const root = mkdtempSync(join(tmpdir(), 'iapeer-shadow-install-'))
+  tmpDirs.push(root)
+  return {
+    IAPEER_LAUNCHAGENTS_DIR: join(root, 'LaunchAgents'),
+    IAPEER_ROOT: join(root, 'iapeer'),
+    HOME: root,
+    PATH: '/usr/bin:/bin',
+    ...extra,
+  } as NodeJS.ProcessEnv
+}
+afterEach(() => {
+  while (tmpDirs.length) rmSync(tmpDirs.pop()!, { recursive: true, force: true })
+})
+const plutilLint = (path: string): boolean => spawnSync('plutil', ['-lint', path], { encoding: 'utf8' }).status === 0
+
+describe('buildShadowPlistSpec', () => {
+  test('label is com.iapeer.shadow-fidelity and runs the INSTALLED `iapeer shadow`', () => {
+    const spec = buildShadowPlistSpec({ HOME: '/Users/x' } as NodeJS.ProcessEnv)
+    expect(spec.label).toBe(SHADOW_PLIST_LABEL)
+    expect(SHADOW_PLIST_LABEL).toBe('com.iapeer.shadow-fidelity')
+    expect(spec.programArguments).toEqual(['/Users/x/.local/bin/iapeer', 'shadow'])
+  })
+  test('launchd-minimal PATH includes /opt/homebrew/bin (tmux lives there — the observer shells read-only tmux)', () => {
+    expect(buildShadowPlistSpec({ HOME: '/Users/x' } as NodeJS.ProcessEnv).environment.PATH).toContain('/opt/homebrew/bin')
+  })
+  test('stdout/stderr land under ~/.iapeer/logs/iapeer', () => {
+    const spec = buildShadowPlistSpec(mkEnv())
+    expect(spec.stdoutPath).toContain(join('logs', 'iapeer', 'shadow-fidelity.launchd-stdout.log'))
+    expect(spec.stderrPath).toContain(join('logs', 'iapeer', 'shadow-fidelity.launchd-stderr.log'))
+  })
+})
+
+describe('installShadowPlist', () => {
+  test('writes a valid, foundation-owned (sentinel) always-on plist under the override dir', () => {
+    const env = mkEnv()
+    const r = installShadowPlist(env)
+    expect(r.path).toBe(shadowPlistPath(env))
+    expect(r.changed).toBe(true)
+    expect(existsSync(r.path)).toBe(true)
+    expect(isFoundationOwnedPlist(r.path)).toBe(true) // carries the ownership sentinel
+    expect(plutilLint(r.path)).toBe(true)
+    const xml = readFileSync(r.path, 'utf8')
+    expect(xml).toContain(`<string>${SHADOW_PLIST_LABEL}</string>`)
+    expect(xml).toContain('<string>shadow</string>')
+    expect(xml).toContain('<key>RunAtLoad</key>')
+    expect(xml).toContain('<key>KeepAlive</key>')
+  })
+
+  test('idempotent by content: an unchanged re-install does NOT rewrite (changed:false, mtime stable); a changed PATH DOES', () => {
+    const env = mkEnv()
+    const first = installShadowPlist(env)
+    expect(first.changed).toBe(true)
+    const mtime1 = statSync(first.path).mtimeMs
+    const second = installShadowPlist(env)
+    expect(second.changed).toBe(false)
+    expect(statSync(second.path).mtimeMs).toBe(mtime1) // file untouched (no BTM spam)
+    // a different rendered plist (PATH override) rewrites
+    const third = installShadowPlist(mkEnv({ IAPEER_SHADOW_PATH: '/opt/homebrew/bin:/usr/bin:/bin', IAPEER_LAUNCHAGENTS_DIR: env.IAPEER_LAUNCHAGENTS_DIR!, IAPEER_ROOT: env.IAPEER_ROOT!, HOME: env.HOME! }))
+    expect(third.changed).toBe(true)
+  })
+
+  test('collision guard: REFUSES to overwrite a foreign (no-sentinel) plist at the label', () => {
+    const env = mkEnv()
+    const laDir = env.IAPEER_LAUNCHAGENTS_DIR!
+    mkdirSync(laDir, { recursive: true })
+    const path = shadowPlistPath(env)
+    const foreign = '<?xml version="1.0"?>\n<plist><dict><key>Label</key><string>com.iapeer.shadow-fidelity</string></dict></plist>\n'
+    writeFileSync(path, foreign)
+    expect(() => installShadowPlist(env)).toThrow(/foundation-managed|refus/i)
+    expect(readFileSync(path, 'utf8')).toBe(foreign) // untouched — guard fires before any write
+  })
+})
+
+describe('installShadowJob (sandbox fail-closed)', () => {
+  test('writes the plist FILE but NEVER touches launchctl under IAPEER_TEST_SANDBOX → skipped-sandbox', () => {
+    const env = mkEnv()
+    const r = installShadowJob(env)
+    expect(r.action).toBe('skipped-sandbox')
+    expect(r.path).toBe(shadowPlistPath(env))
+    expect(r.changed).toBe(true)
+    expect(existsSync(r.path)).toBe(true) // file written to the override dir
+    expect(isFoundationOwnedPlist(r.path)).toBe(true)
+  })
+})
+
+describe('cycleShadowJob (deploy re-cycle hook)', () => {
+  test('returns null when no plist exists (nothing to recycle)', () => {
+    expect(cycleShadowJob(mkEnv())).toBeNull()
+  })
+  test('a written foundation plist recycles to skipped-sandbox under the test flag (never a real launchctl cycle)', () => {
+    const env = mkEnv()
+    installShadowPlist(env)
+    expect(cycleShadowJob(env)?.state).toBe('skipped-sandbox')
+  })
+  test('a foreign plist at the label is NOT recycled (ownership guard) → null', () => {
+    const env = mkEnv()
+    mkdirSync(env.IAPEER_LAUNCHAGENTS_DIR!, { recursive: true })
+    writeFileSync(shadowPlistPath(env), '<?xml version="1.0"?>\n<plist><dict/></plist>\n')
+    expect(cycleShadowJob(env)).toBeNull()
+  })
+})
+
+describe('uninstallShadowJob', () => {
+  test('absent plist → absent (no-op)', () => {
+    expect(uninstallShadowJob(mkEnv()).action).toBe('absent')
+  })
+  test('foundation plist under sandbox → skipped-sandbox, plist left in place (no real bootout)', () => {
+    const env = mkEnv()
+    installShadowPlist(env)
+    const r = uninstallShadowJob(env)
+    expect(r.action).toBe('skipped-sandbox')
+    expect(existsSync(shadowPlistPath(env))).toBe(true)
+  })
+  test('foreign plist → refused-foreign, untouched', () => {
+    const env = mkEnv()
+    mkdirSync(env.IAPEER_LAUNCHAGENTS_DIR!, { recursive: true })
+    const path = shadowPlistPath(env)
+    writeFileSync(path, '<?xml version="1.0"?>\n<plist><dict/></plist>\n')
+    expect(uninstallShadowJob(env).action).toBe('refused-foreign')
+    expect(existsSync(path)).toBe(true)
+  })
+})
+
+describe('exports wire to the running job', () => {
+  test('SHADOW_PERSONALITY/LABEL match the live burn-in job naming', () => {
+    expect(SHADOW_PERSONALITY).toBe('shadow-fidelity')
+    expect(SHADOW_PLIST_LABEL).toBe('com.iapeer.shadow-fidelity')
+  })
+})

package/src/shadow/install.ts

@@ -0,0 +1,256 @@
+// Code-managed install / teardown / update-recycle for the read-only tmux→pty fidelity
+// BURN-IN job (`iapeer shadow`). The OBSERVER itself is src/shadow/index.ts (it loads
+// @xterm/headless); THIS module is PURE launchd plumbing — it imports NO @xterm — so the
+// deploy path (update/rollback) and the CLI can install/recycle the job without pulling the
+// terminal emulator into their import graph (the daemon hot path stays @xterm-free).
+//
+// The job is a foundation-OWNED, always-on launchd LaunchAgent (com.iapeer.shadow-fidelity)
+// running the INSTALLED binary `iapeer shadow`. It is NOT a registry peer — it receives no
+// IAP and has no peer profile — so recycleFoundationOwnedInfraJobs' registry SCAN cannot see
+// it; cycleShadowJob recycles it by LABEL instead. It carries the same ownership sentinel as
+// every foundation plist, so the collision guard (install) and the recycle guard both
+// recognize it as ours. KeepAlive owns its lifecycle; stop it with `iapeer shadow-uninstall`
+// (bootout + rm), NEVER the STOP sentinel file (KeepAlive would just respawn straight past it).
+
+import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { IAPEER_DIR } from '../core/constants.ts'
+import { IapError } from '../core/errors.ts'
+import { iapeerBinPath } from '../install/index.ts'
+import { pluginLogsDir } from '../storage/index.ts'
+import {
+  cycleLaunchdJob,
+  isFoundationOwnedPlist,
+  launchAgentsDir,
+  launchctlBootstrap,
+  launchdLabel,
+  renderLaunchdPlist,
+  type LaunchdJobCycleResult,
+  type LaunchdPlistSpec,
+} from '../launch/launchd.ts'
+
+/** The burn-in job's personality stem → label com.iapeer.shadow-fidelity (the running job). */
+export const SHADOW_PERSONALITY = 'shadow-fidelity'
+/** com.iapeer.shadow-fidelity — keyed through launchdLabel so the scheme has ONE source. */
+export const SHADOW_PLIST_LABEL = launchdLabel(SHADOW_PERSONALITY)
+
+export function shadowPlistPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(launchAgentsDir(env), `${SHADOW_PLIST_LABEL}.plist`)
+}
+
+/** The STOP sentinel the observer polls (under <eventLogDir>=~/.iapeer/logs/iapeer). Under
+ *  KeepAlive a STALE one would respawn the observer straight into an immediate exit → a
+ *  throttle-storm, so installShadowJob clears it before (re)loading. */
+function shadowStopFile(env: NodeJS.ProcessEnv = process.env): string {
+  return join(pluginLogsDir('iapeer', { env }), 'shadow-fidelity.STOP')
+}
+
+function inSandbox(env: NodeJS.ProcessEnv): boolean {
+  return env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1'
+}
+
+/** Resolve the gui-domain uid, or null when `id -u` is non-numeric (never assume 0). */
+function uidOrNull(): string | null {
+  const u = (spawnSync('id', ['-u'], { encoding: 'utf8' }).stdout ?? '').trim()
+  return /^\d+$/.test(u) ? u : null
+}
+
+/** Is com.iapeer.shadow-fidelity currently loaded in the gui domain? */
+function isShadowLoaded(): boolean {
+  const uid = uidOrNull()
+  if (!uid) return false
+  return spawnSync('launchctl', ['print', `gui/${uid}/${SHADOW_PLIST_LABEL}`], { stdio: 'ignore' }).status === 0
+}
+
+/**
+ * Build the burn-in job's launchd plist spec (PURE — render/lint-testable). Runs the
+ * INSTALLED `iapeer shadow` (prod decoupled from the src tree). The launchd-minimal PATH
+ * MUST include /opt/homebrew/bin: the observer shells READ-ONLY tmux (capture-pane /
+ * has-session / display), and tmux lives there — a bare PATH would make every tmux probe
+ * fail (no peers enumerated). Deterministic (curated PATH, not env.PATH) so the rendered
+ * plist is byte-stable across deploys → installShadowPlist's write-if-changed stays a no-op
+ * when nothing actually changed (no Background Task Management notification spam).
+ */
+export function buildShadowPlistSpec(env: NodeJS.ProcessEnv = process.env): LaunchdPlistSpec {
+  const home = env.HOME?.trim() || homedir()
+  const defaultPath = `${home}/.local/bin:${home}/.bun/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`
+  const logDir = pluginLogsDir('iapeer', { env })
+  const environment: Record<string, string> = { PATH: env.IAPEER_SHADOW_PATH?.trim() || defaultPath }
+  // Sandbox/test parity (mirror of installDaemonPlist / installAlwaysOnPlist): bake the
+  // non-default root overrides so a SANDBOXED install resolves the SAME isolated tree the
+  // observer reads. In production these are unset → nothing baked, real ~/.iapeer + /tmp used.
+  for (const key of ['IAPEER_ROOT', 'IAPEER_SOCK_DIR', 'IAPEER_LAUNCHAGENTS_DIR'] as const) {
+    if (env[key]?.trim()) environment[key] = env[key]!.trim()
+  }
+  return {
+    label: SHADOW_PLIST_LABEL,
+    programArguments: [iapeerBinPath(env), 'shadow'],
+    workingDirectory: home, // cwd-agnostic (the observer resolves paths from IAPEER_ROOT/cfg)
+    environment,
+    stdoutPath: join(logDir, 'shadow-fidelity.launchd-stdout.log'),
+    stderrPath: join(logDir, 'shadow-fidelity.launchd-stderr.log'),
+  }
+}
+
+export interface InstallShadowPlistResult {
+  path: string
+  /** false when the on-disk plist already matched byte-for-byte → NO write (no BTM spam). */
+  changed: boolean
+}
+
+/**
+ * Write the burn-in plist (file only — does NOT load it). IDEMPOTENT BY CONTENT
+ * (write-if-changed, mirror of installDaemonPlist: a byte-identical rewrite trips the owner's
+ * Background Task Management notification for zero benefit). Collision guard: refuses to
+ * overwrite a com.iapeer.shadow-fidelity.plist that lacks the ownership sentinel (a foreign
+ * manager owns it) — the guard fires FIRST, before any mkdir/write, so a refusal leaves the
+ * filesystem untouched.
+ */
+export function installShadowPlist(env: NodeJS.ProcessEnv = process.env): InstallShadowPlistResult {
+  const path = shadowPlistPath(env)
+  if (existsSync(path) && !isFoundationOwnedPlist(path)) {
+    throw new IapError(
+      `refusing to overwrite ${path}: ${SHADOW_PLIST_LABEL} exists but is not foundation-managed ` +
+        `(no ownership sentinel) — another manager owns it`,
+    )
+  }
+  const rendered = renderLaunchdPlist(buildShadowPlistSpec(env))
+  mkdirSync(launchAgentsDir(env), { recursive: true })
+  // Never mkdir the REAL ~/.iapeer log dir under a sandbox that forgot IAPEER_ROOT (mirror
+  // installAlwaysOnPlist's guard); a real run (no sandbox flag) always makes it.
+  const logDir = pluginLogsDir('iapeer', { env })
+  const realRoot = join(homedir(), IAPEER_DIR)
+  if (!(inSandbox(env) && logDir.startsWith(`${realRoot}/`))) {
+    mkdirSync(logDir, { recursive: true, mode: 0o700 })
+  }
+  let existing: string | null = null
+  try {
+    existing = readFileSync(path, 'utf8')
+  } catch {
+    existing = null
+  }
+  if (existing === rendered) return { path, changed: false }
+  writeFileSync(path, rendered, { mode: 0o644 })
+  return { path, changed: true }
+}
+
+export type ShadowJobAction =
+  | 'loaded' // bootstrapped now (was not loaded)
+  | 'reloaded' // plist changed on an already-loaded job → bootout+bootstrap applied the new one
+  | 'already-loaded' // loaded and the plist did not change → left running untouched
+  | 'refused-foreign' // a non-foundation plist sits at the label → never loaded
+  | 'failed' // launchctl bootstrap/cycle failed (detail carries the rescue recipe)
+  | 'skipped-sandbox' // IAPEER_TEST_SANDBOX=1 → never touch real launchd
+
+export interface InstallShadowJobResult extends InstallShadowPlistResult {
+  action: ShadowJobAction
+  detail?: string
+}
+
+/**
+ * Install the burn-in plist AND ensure the job is live: write-if-changed, clear a stale STOP
+ * sentinel, then load it (or RELOAD via bootout+bootstrap when the plist content changed on
+ * an already-loaded job — bootstrap alone is idempotent and would NOT pick up a changed
+ * plist). Idempotent: a repeat call on an unchanged, loaded job is a no-op ('already-loaded').
+ * Sandbox-safe: under IAPEER_TEST_SANDBOX it writes the (overridden-dir) plist FILE but never
+ * calls launchctl ('skipped-sandbox'). This is the code-managed replacement for a hand-written
+ * burn-in plist — reproducible, ownership-sentinel-guarded, fleet-deployable.
+ */
+export function installShadowJob(env: NodeJS.ProcessEnv = process.env): InstallShadowJobResult {
+  const { path, changed } = installShadowPlist(env)
+  if (inSandbox(env)) return { path, changed, action: 'skipped-sandbox' }
+  // Clear a STALE STOP sentinel BEFORE (re)loading — else KeepAlive respawns the observer
+  // into an instant exit (it polls the STOP file) → 10s-throttled respawn storm.
+  try {
+    unlinkSync(shadowStopFile(env))
+  } catch {
+    /* none present */
+  }
+  if (isShadowLoaded()) {
+    if (!changed) return { path, changed, action: 'already-loaded' }
+    const c = cycleLaunchdJob(SHADOW_PLIST_LABEL, path, env)
+    return c.state === 'restarted'
+      ? { path, changed, action: 'reloaded' }
+      : { path, changed, action: 'failed', detail: c.detail }
+  }
+  const b = launchctlBootstrap(SHADOW_PERSONALITY, path, env)
+  const action: ShadowJobAction =
+    b.state === 'loaded'
+      ? 'loaded'
+      : b.state === 'already-loaded'
+        ? 'already-loaded'
+        : b.state === 'refused-foreign'
+          ? 'refused-foreign'
+          : b.state === 'skipped-sandbox'
+            ? 'skipped-sandbox'
+            : 'failed'
+  return { path, changed, action, detail: b.detail }
+}
+
+/**
+ * Recycle the burn-in job by LABEL after a binary swap (deploy path). The plist runs the
+ * just-replaced `iapeer shadow` off the same binary, so the SAME LWCR managed-launch-constraint
+ * bomb that bit the daemon (EX_CONFIG(78) on a KeepAlive respawn into the stale constraint)
+ * applies here too — only a full bootout→bootstrap clears it. It is NOT a registry peer, so
+ * recycleFoundationOwnedInfraJobs' registry scan misses it; this cycles it directly. Only
+ * touches a LOADED, foundation-owned job: absent / foreign / not-loaded → null (no-op).
+ * Sandbox-safe (cycleLaunchdJob returns skipped-sandbox under the test flag).
+ */
+export function cycleShadowJob(env: NodeJS.ProcessEnv = process.env): LaunchdJobCycleResult | null {
+  const path = shadowPlistPath(env)
+  if (!existsSync(path) || !isFoundationOwnedPlist(path)) return null
+  return cycleLaunchdJob(SHADOW_PLIST_LABEL, path, env)
+}
+
+export type ShadowUninstallAction =
+  | 'booted-out' // job was loaded → booted out, plist removed
+  | 'removed-not-loaded' // plist removed, job was not loaded
+  | 'absent' // nothing to do (no plist)
+  | 'refused-foreign' // the plist is not foundation-owned → left untouched
+  | 'skipped-sandbox'
+  | 'failed'
+
+export interface UninstallShadowJobResult {
+  path: string
+  action: ShadowUninstallAction
+  detail?: string
+}
+
+/**
+ * Stop and remove the burn-in job — the CORRECT way to halt it (the STOP sentinel would be
+ * respawned past by KeepAlive): bootout the loaded job, then delete the plist. Refuses a
+ * non-foundation plist (ownership guard). Sandbox-safe. Reversibility for the install verb.
+ */
+export function uninstallShadowJob(env: NodeJS.ProcessEnv = process.env): UninstallShadowJobResult {
+  const path = shadowPlistPath(env)
+  if (!existsSync(path)) return { path, action: 'absent' }
+  if (!isFoundationOwnedPlist(path)) {
+    return { path, action: 'refused-foreign', detail: `${path} is not foundation-owned — not booting it out` }
+  }
+  if (inSandbox(env)) return { path, action: 'skipped-sandbox' }
+  let action: ShadowUninstallAction = 'removed-not-loaded'
+  if (isShadowLoaded()) {
+    const uid = uidOrNull()
+    const r = uid
+      ? spawnSync('launchctl', ['bootout', `gui/${uid}/${SHADOW_PLIST_LABEL}`], { encoding: 'utf8' })
+      : { status: 1, stderr: 'cannot resolve uid' }
+    if (r.status !== 0 && isShadowLoaded()) {
+      return { path, action: 'failed', detail: `launchctl bootout failed: ${(r.stderr ?? '').trim() || `exit ${r.status}`}` }
+    }
+    action = 'booted-out'
+  }
+  // Also clear any STOP sentinel so a later reinstall starts clean.
+  try {
+    unlinkSync(shadowStopFile(env))
+  } catch {
+    /* none */
+  }
+  try {
+    rmSync(path)
+  } catch {
+    /* best-effort */
+  }
+  return { path, action }
+}

package/src/shadow/shadow.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'bun:test'
+import { Terminal } from '@xterm/headless'
+import { composerOccupancyFromModel, modelToPlainText } from './index.ts'
+
+// The observer's pty-side verdicts are pure functions of the @xterm model — hermetic, no tmux.
+// These mirror the verdicts validated 0-divergence vs the prod tmux verdicts in the migration
+// fidelity shadows (occupancy: getCell dim/ghost; ready-gate: isInputReady on plain text).
+const build = (frame: string, cols = 80, rows = 24): Promise<Terminal> =>
+  new Promise(res => { const t = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 200 }); t.write(frame, () => res(t)) })
+
+describe('composerOccupancyFromModel (pty occupancy verdict)', () => {
+  test('human non-dim text after the prompt glyph → TRUE', async () => {
+    const t = await build(`\x1b[24;1H❯ the quick brown fox`)
+    expect(composerOccupancyFromModel(t, 80, 24, 'claude')).toBe(true)
+  })
+  test('dim/ghost placeholder after the glyph → FALSE (the critical discriminator)', async () => {
+    const t = await build(`\x1b[24;1H❯ \x1b[2m\x1b[38;5;246mTry "fix typecheck errors"\x1b[0m`)
+    expect(composerOccupancyFromModel(t, 80, 24, 'claude')).toBe(false)
+  })
+  test('empty composer (glyph alone) → FALSE', async () => {
+    const t = await build(`\x1b[24;1H❯ `)
+    expect(composerOccupancyFromModel(t, 80, 24, 'claude')).toBe(false)
+  })
+  test('codex glyph › with human text → TRUE', async () => {
+    const t = await build(`\x1b[24;1H› reviewer note`)
+    expect(composerOccupancyFromModel(t, 80, 24, 'codex')).toBe(true)
+  })
+  test('no prompt glyph at all → FALSE', async () => {
+    const t = await build(`\x1b[24;1Hjust some output line`)
+    expect(composerOccupancyFromModel(t, 80, 24, 'claude')).toBe(false)
+  })
+})
+
+describe('modelToPlainText (feeds isInputReady)', () => {
+  test('renders the viewport as plain text (no SGR), trailing-trimmed', async () => {
+    const t = await build(`\x1b[1;1Hhello\x1b[2;1H\x1b[1mbold\x1b[0m world`)
+    const plain = modelToPlainText(t, 80, 24)
+    expect(plain.split('\n')[0]).toBe('hello')
+    expect(plain).toContain('bold world')
+    expect(plain).not.toContain('\x1b')
+  })
+})

package/src/update/index.ts

@@ -41,6 +41,7 @@ import {
   type DaemonRestartResult,
   type LaunchdJobCycleResult,
 } from '../launch/launchd.ts'
+import { cycleShadowJob, SHADOW_PERSONALITY, SHADOW_PLIST_LABEL } from '../shadow/install.ts'
 import { defaultDaemonSocketPath } from '../daemon/index.ts'
 
 /** The npm package the foundation publishes / updates from. */
@@ -242,6 +243,14 @@ export function recycleFoundationOwnedInfraJobs(env: NodeJS.ProcessEnv = process
     const r = cycleLaunchdJob(label, plist, env)
     out.push({ personality: peer.personality, runtime, label, state: r.state, detail: r.detail })
   }
+  // The tmux→pty fidelity BURN-IN job (com.iapeer.shadow-fidelity) is foundation-owned and
+  // runs the just-replaced `iapeer shadow` off the same binary, so it carries the same LWCR
+  // constraint — but it is NOT a registry peer, so the scan above cannot reach it. Cycle it
+  // by label too (no-op when absent / not-loaded / foreign).
+  const shadow = cycleShadowJob(env)
+  if (shadow) {
+    out.push({ personality: SHADOW_PERSONALITY, runtime: 'foundation', label: SHADOW_PLIST_LABEL, state: shadow.state, detail: shadow.detail })
+  }
   return out
 }