@agfpd/iapeer 0.2.73 → 0.2.75

package/README.md

@@ -2,10 +2,28 @@
 
 Ядро мультиагентной системы на одном хосте: реестр пиров, единый демон-роутер для обмена сообщениями между ними и команды управления — создание, запуск, усыпление, перезапуск, подключение к внешним каналам. Пиром может быть AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс; все адресуются одинаково через один протокол.
 
+## Ключевые возможности
+
+iapeer держит AI-агентов как **живые интерактивные сессии настоящего CLI** (Claude Code, Codex CLI) — со всем поведением реального CLI, а не headless-режим одноразовых вызовов (`claude -p`, `codex exec`). Поскольку это реальный интерактивный CLI, пиры работают в рамках обычной подписки на Claude Code (изменение тарификации headless-режима от 15 июня 2026 интерактивный CLI не затрагивает).
+
+Отдельные свойства ниже встречаются и в других инструментах; сильная сторона iapeer — их **комбинация целиком**:
+
+1. **Реальный интерактивный CLI в фоне.** Каждый AI-пир — полноценная сессия Claude Code или Codex CLI, поднятая в фоне и доступная по сообщению.
+
+2. **Постоянная сессия (persistent).** На входящее демон поднимает пира через возобновление (`--continue` / `--resume`) — диалог **продолжается**, а не начинается заново; контекст и история сохраняются между обращениями.
+
+3. **Событийный warm-on-demand жизненный цикл.** Сессия «тёплая» → быстро обрабатывает входящие; после ~часа простоя демон закрывает её (idle-reap); новое входящее → демон поднимает заново **автоматически**, с возобновлением контекста. Жизненным циклом правит поток сообщений, а не присутствие человека: это не привязанный к разработчику TUI и не одноразовый воркер на задачу. Ресурсы заняты, только пока пир работает.
+
+4. **Переносимость пиров между рантаймами.** Личность пира (`personality`) отделена от рантайма: один пир присутствует и в Claude, и в Codex, а основной рантайм переключается командой (`claude ↔ codex`) без потери идентичности и адресации.
+
+5. **Подключение человека к живой сессии.** `iapeer attach` открывает **живую** сессию пира прямо в вашем терминале через pty-супервизор — мышь, прокрутка и цвета работают нативно; отсоединение (`Ctrl-]`) сессию не закрывает.
+
+Целиком эту связку — событийный warm-on-demand жизненный цикл (не attached-разработчиком TUI и не воркер-на-задачу), переносимость пиров между рантаймами и единую ткань обмена (протокол IAP, память-vault с поиском, Telegram-мост) — даёт iapeer.
+
 ## Документация
 
 Документация проекта — в [`docs/`](docs/README.md): продуктовая часть (что это и как пользоваться) и механика изнутри ([`docs/internals/`](docs/internals/README.md)). Этот репозиторий — кодовая реализация.
 
 ## Статус
 
-Версия — **0.2.58**. Платформа — macOS/launchd.
+Версия — **0.2.73**. Платформа — macOS/launchd.

package/package.json

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

package/src/supervisor/daemon.ts

@@ -39,6 +39,29 @@ const TICK_CMD = ['sh', '-c', 'i=0; while true; do printf "STREAMTICK_%d\\r\\n"
 // answer off its model. 'tick' (and any unknown runtime) has no entry → no driver → the hermetic
 // spawn/attach tests and the bare conduit are untouched.
 const BOOT_ADAPTERS: Record<string, BootPredicates> = { codex: codexAdapter, claude: claudeAdapter }
+
+// SCROLLBACK SPINNER STRIP (serve-side, repaint snapshot only). claude's TUI redraws its bottom status
+// block WITHOUT a scroll-region (DECSTBM), so as the conversation scrolls, stale spinner frames
+// ("✶ Gerund… (Nm Ns · ↓ N tokens)" / "… (esc to interrupt)") get pushed into the @xterm scrollback ring
+// and ACCUMULATE — surfacing as repeated/broken lines when a reattaching operator scrolls history UP
+// (the live viewport is clean; only the served history is polluted). We drop those lines from the
+// SCROLLBACK part of the serialized repaint snapshot, keeping the last `viewportRows` segments (the LIVE
+// status block, incl. the current spinner) verbatim. Matched by STRUCTURE — a gerund + … + the
+// elapsed/token or esc-to-interrupt tail — NOT a word-list (claude rotates 100+ spinner gerunds). The
+// live byte stream, pane-log and transcript are untouched; only the human-attach repaint is filtered.
+const SPINNER_STATUS_LINE = /…[^\n]{0,48}\((?:esc to interrupt|\d+m? ?\d*s ?·)/
+const ANSI_SEQ = /\x1b\[[0-9;:?]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g
+export function stripSpinnerScrollback(serialized: string, viewportRows: number): string {
+  const segs = serialized.split('\r\n')
+  if (segs.length <= viewportRows) return serialized // no scrollback to clean
+  const scrollbackEnd = segs.length - viewportRows // keep the last viewportRows (live viewport) verbatim
+  const out: string[] = []
+  for (let i = 0; i < segs.length; i++) {
+    if (i < scrollbackEnd && SPINNER_STATUS_LINE.test(segs[i].replace(ANSI_SEQ, ''))) continue
+    out.push(segs[i])
+  }
+  return out.join('\r\n')
+}
 // Poll cadence mirrors the launch primitive's proven 2 s boot loop (index.ts:377). The supervisor
 // model is strictly FRESHER than capture-pane (bytes land in @xterm synchronously as they arrive),
 // so 2 s leaves ample repaint time — the claude resume-picker never over-Downs, since bootDialogKeys
@@ -220,7 +243,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   /** Repaint a (re)attaching client from the headless snapshot: clear+home, then the full grid.
    *  Backpressure-safe — a ~90 KB heavy snapshot MUST NOT drop past the socket buffer (port-dep #2). */
   const repaint = (s: { write(b: Buffer): number }): void => {
-    const snap = '\x1b[2J\x1b[3J\x1b[H' + ser.serialize()
+    const snap = '\x1b[2J\x1b[3J\x1b[H' + stripSpinnerScrollback(ser.serialize(), xterm.rows)
     sendClient(s, frame(FRAME_DATA, Buffer.from(snap, 'utf8')))
   }
 

package/src/supervisor/spinner-strip.test.ts

@@ -0,0 +1,52 @@
+// Scrollback spinner strip (serve-side repaint snapshot). claude's TUI redraws its status block without
+// a scroll-region, so stale spinner frames accumulate in the @xterm scrollback ring and pollute a
+// reattaching operator's scroll-up. stripSpinnerScrollback drops those frames from the SCROLLBACK part
+// of the serialized snapshot while keeping the live viewport (incl. the current spinner) verbatim,
+// matched by STRUCTURE (gerund + … + elapsed/token or esc-to-interrupt tail), not a word-list.
+import { describe, expect, test } from 'bun:test'
+import { stripSpinnerScrollback } from './daemon.ts'
+
+describe('stripSpinnerScrollback — drop stale spinner frames from served scrollback', () => {
+  test('strips scrollback spinner-status lines (elapsed + tokens), keeps real history + the live viewport', () => {
+    const lines = [
+      'real history line 1',
+      '\x1b[38;2;215;119;87m✶\x1b[39m Metamorphosing… (4m 24s · ↓ 18.4k tokens)', // scrollback spinner → drop
+      'real history line 2',
+      '· Quantumizing… (6m 57s · ↓ 30.0k tokens)', // scrollback spinner → drop
+      // last 3 = viewport (the LIVE status block, kept verbatim incl. the current spinner)
+      'real history line 3',
+      '────────────',
+      '✽ Brewing… (1m 59s · ↓ 6.5k tokens)',
+    ].join('\r\n')
+    const out = stripSpinnerScrollback(lines, 3).split('\r\n')
+    expect(out).toContain('real history line 1')
+    expect(out).toContain('real history line 2')
+    expect(out).toContain('real history line 3')
+    expect(out).toContain('✽ Brewing… (1m 59s · ↓ 6.5k tokens)') // viewport live spinner KEPT
+    expect(out.some(l => /Metamorphosing/.test(l))).toBe(false)
+    expect(out.some(l => /Quantumizing/.test(l))).toBe(false)
+  })
+
+  test('strips the (esc to interrupt) tail variant in scrollback', () => {
+    const lines = ['history', '· Running… (esc to interrupt · 1.2k tokens)', 'vp1', 'vp2', 'vp3'].join('\r\n')
+    const out = stripSpinnerScrollback(lines, 3)
+    expect(out.includes('Running…')).toBe(false)
+    expect(out.includes('history')).toBe(true)
+  })
+
+  test('does NOT over-strip — real content with … or (…) but no spinner tail is kept', () => {
+    const lines = [
+      'мы обсудили тайминг… он занял время', // … but no elapsed/token tail
+      'итого вышло (5 долларов)', //          (…) but no elapsed/esc tail
+      'vp1', 'vp2', 'vp3',
+    ].join('\r\n')
+    const out = stripSpinnerScrollback(lines, 3).split('\r\n')
+    expect(out).toContain('мы обсудили тайминг… он занял время')
+    expect(out).toContain('итого вышло (5 долларов)')
+  })
+
+  test('the LIVE spinner in the viewport is never stripped (no scrollback → unchanged)', () => {
+    const lines = ['✶ Vibing… (3s · ↓ 1 tokens)', 'vp2', 'vp3'].join('\r\n')
+    expect(stripSpinnerScrollback(lines, 3)).toBe(lines) // segs <= viewportRows → returned verbatim
+  })
+})

package/src/transport/compactDone.test.ts

@@ -2,7 +2,14 @@ import { describe, expect, test } from 'bun:test'
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync, appendFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
-import { compactDoneBaseline, compactTranscriptHasDone } from './index.ts'
+import { compactDoneBaseline, compactTranscriptHasDone, waitForCompactDone, type DeliveryTarget } from './index.ts'
+
+function claudeTarget(): DeliveryTarget {
+  return { runtime: 'claude', personality: 'tester', address: 'claude-tester', socketPath: '/tmp/iapeer-test-noop.sock' }
+}
+
+const CLAUDE_IDLE_PANE = '❯ \n bypass permissions on'
+const CLAUDE_BUSY_PANE = '· Compacting conversation… (esc to interrupt)\n  reloading context'
 
 function withHome(fn: (home: string, env: NodeJS.ProcessEnv) => void): void {
   const home = mkdtempSync(join(tmpdir(), 'iapeer-compact-gate-home-'))
@@ -58,3 +65,80 @@ describe('compact done transcript gate', () => {
     }
   }))
 })
+
+describe('waitForCompactDone — marker is authoritative, idle is a fast-path', () => {
+  function withClaudeMarker(
+    fn: (args: { cwd: string; env: NodeJS.ProcessEnv; writeMarker: () => void; baseline: ReturnType<typeof compactDoneBaseline> }) => void,
+  ): void {
+    withHome((home, env) => {
+      const cwd = mkdtempSync(join(tmpdir(), 'iapeer-compact-wait-cwd-'))
+      try {
+        const dir = join(home, '.claude', 'projects', claudeSlug(cwd))
+        mkdirSync(dir, { recursive: true })
+        const file = join(dir, 'session.jsonl')
+        writeFileSync(file, JSON.stringify({ type: 'user', message: { role: 'user', content: 'hi' } }) + '\n')
+        const baseline = compactDoneBaseline('claude', cwd, { env })
+        const writeMarker = () =>
+          appendFileSync(file, JSON.stringify({ type: 'system', subtype: 'compact_boundary', compactMetadata: { durationMs: 140708, preTokens: 535706, postTokens: 12524 } }) + '\n')
+        fn({ cwd, env, writeMarker, baseline })
+      } finally {
+        rmSync(cwd, { recursive: true, force: true })
+      }
+    })
+  }
+
+  // THE FIX: a large-context session that auto-continues into a working turn after compact
+  // keeps the composer busy (never idle). The marker proves completion → SUCCESS, not failure.
+  test('marker seen + composer never idle → success on the marker (signal: transcript)', () => withClaudeMarker(({ cwd, env, writeMarker, baseline }) => {
+    writeMarker()
+    const r = waitForCompactDone(claudeTarget(), cwd, baseline, {
+      env,
+      timeoutMs: 5000,
+      pollMs: 5,
+      graceMs: 20,
+      seam: { sessionAlive: () => true, capturePane: () => CLAUDE_BUSY_PANE },
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.value.signal).toBe('transcript')
+  }))
+
+  // Clean common case unchanged: marker + idle composer → the historical 'transcript+ready'.
+  test('marker seen + composer idle → fast-path success (signal: transcript+ready)', () => withClaudeMarker(({ cwd, env, writeMarker, baseline }) => {
+    writeMarker()
+    const r = waitForCompactDone(claudeTarget(), cwd, baseline, {
+      env,
+      timeoutMs: 5000,
+      pollMs: 5,
+      graceMs: 5000,
+      seam: { sessionAlive: () => true, capturePane: () => CLAUDE_IDLE_PANE },
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.value.signal).toBe('transcript+ready')
+  }))
+
+  // BOUNDARY preserved: no structured marker ever → honest failure (hung / never completed).
+  test('no marker → honest failure', () => withClaudeMarker(({ cwd, env, baseline }) => {
+    const r = waitForCompactDone(claudeTarget(), cwd, baseline, {
+      env,
+      timeoutMs: 40,
+      pollMs: 5,
+      graceMs: 20,
+      seam: { sessionAlive: () => true, capturePane: () => CLAUDE_BUSY_PANE },
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error.message).toContain('no transcript compact marker')
+  }))
+
+  // Session death during the wait still fails (liveness boundary).
+  test('session vanished → failure', () => withClaudeMarker(({ cwd, env, baseline }) => {
+    const r = waitForCompactDone(claudeTarget(), cwd, baseline, {
+      env,
+      timeoutMs: 5000,
+      pollMs: 5,
+      graceMs: 20,
+      seam: { sessionAlive: () => false, capturePane: () => CLAUDE_BUSY_PANE },
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error.message).toContain('session vanished')
+  }))
+})

package/src/transport/index.ts

@@ -603,7 +603,23 @@ export interface CompactDoneBaseline {
 export interface CompactDoneWaitResult {
   ok: true
   ms: number
-  signal: 'transcript+ready'
+  /** How completion was confirmed:
+   *   'transcript+ready' — marker seen AND the composer returned to idle (the clean,
+   *       common case: a small/medium compact that settles back to the prompt).
+   *   'transcript' — marker seen but the composer is still BUSY past the ready-grace
+   *       (a large-context session that auto-continues into a working turn right after
+   *       compact). The structured marker is the AUTHORITATIVE completion signal, so this
+   *       is SUCCESS, not a timeout. */
+  signal: 'transcript+ready' | 'transcript'
+}
+
+/** Test seam for waitForCompactDone — inject the tmux liveness + pane capture so the
+ *  marker/grace logic is covered hermetically (no live session). Omitting all = prod. */
+export interface CompactDoneWaitSeam {
+  /** Is the target session still alive? Default: the real tmux/host sessionAlive. */
+  sessionAlive?: (target: DeliveryTarget) => boolean
+  /** Capture the target pane; null = capture failed. Default: real tmux capture-pane. */
+  capturePane?: (target: DeliveryTarget) => string | null
 }
 
 function envHome(env: NodeJS.ProcessEnv | undefined): string {
@@ -763,41 +779,97 @@ function compactDonePollMs(env: NodeJS.ProcessEnv | undefined): number {
   return Number.isFinite(n) && n > 0 ? n : 1000
 }
 
+// Once the completion marker is seen, how long to keep PREFERRING the idle-composer
+// confirmation (the clean 'transcript+ready' signal) before reporting success on the
+// marker alone. A large-context session that auto-continues into a working turn never
+// goes idle — this bounds how long we wait for an idle that may never come, so the
+// busy case succeeds promptly instead of stalling to the overall deadline. Short by
+// design; the marker is already authoritative.
+function compactReadyGraceMs(env: NodeJS.ProcessEnv | undefined): number {
+  const raw = env?.IAPEER_COMPACT_READY_GRACE_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 5000
+}
+
 /**
  * Wait until a slash-/compact command has actually FINISHED, not merely until its
- * keystrokes were accepted. The primary signal is scroll-proof structured
- * transcript state written by the runtimes: Codex `context_compacted`, Claude
- * `compact_boundary`. The final input-ready check prevents a marker-only early
- * return while the TUI is still transitioning back to the composer/prompt.
+ * keystrokes were accepted. The AUTHORITATIVE signal is scroll-proof structured
+ * transcript state written by the runtimes at the END of the operation (with post-
+ * compact token metadata): Codex `context_compacted`, Claude `compact_boundary`.
+ * Once that marker is present the compact objectively completed.
+ *
+ * Idle-composer (`isInputReady`) is treated as a FAST-PATH confirmation, NOT a
+ * requirement. A healthy large-context session auto-continues into a working turn
+ * right after compact — its composer is legitimately busy (not idle) for a while, so
+ * requiring idle here false-failed a finished compact (live incident 15.06, boris:
+ * marker at 12:14:58, first post-compact idle only ~232s later, past the ~290s gate).
+ * Therefore: marker seen + composer idle → 'transcript+ready' (clean); marker seen +
+ * composer still busy past a short grace → 'transcript' (busy-but-done, still SUCCESS).
+ *
+ * BOUNDARY (preserved): a compact whose structured marker NEVER appears still fails
+ * honestly — that is the genuine "hung / never completed" case. Cross-runtime: the
+ * marker set + isInputReady are both per-adapter, so claude and codex share this path.
  */
 export function waitForCompactDone(
   target: DeliveryTarget,
   cwd: string,
   baseline: CompactDoneBaseline,
-  opts: { env?: NodeJS.ProcessEnv; timeoutMs?: number; pollMs?: number } = {},
+  opts: {
+    env?: NodeJS.ProcessEnv
+    timeoutMs?: number
+    pollMs?: number
+    graceMs?: number
+    seam?: CompactDoneWaitSeam
+  } = {},
 ): Result<CompactDoneWaitResult> {
   const env = opts.env ?? process.env
   const timeoutMs = opts.timeoutMs ?? compactDoneTimeoutMs(env)
   const pollMs = opts.pollMs ?? compactDonePollMs(env)
+  const graceMs = opts.graceMs ?? compactReadyGraceMs(env)
+  const aliveFn = opts.seam?.sessionAlive ?? ((t: DeliveryTarget) => sessionAlive(t.socketPath, t.address))
+  const captureFn =
+    opts.seam?.capturePane ??
+    ((t: DeliveryTarget) => {
+      const cap = tmux(t.socketPath, 'capture-pane', '-p', '-t', t.address)
+      return cap.ok ? cap.out : null
+    })
   const adapter = getAdapter(target.runtime)
   const started = monotonicMs()
   const deadline = started + timeoutMs
   let sawTranscriptDone = false
+  let markerSeenAtMs = -1
   let lastPane = ''
 
   do {
-    if (!sessionAlive(target.socketPath, target.address)) {
+    if (!aliveFn(target)) {
       return err(`compact did not complete: tmux session vanished`)
     }
-    sawTranscriptDone ||= compactTranscriptHasDone(baseline, { env })
-    const pane = tmux(target.socketPath, 'capture-pane', '-p', '-t', target.address)
-    if (pane.ok) lastPane = pane.out
-    if (sawTranscriptDone && pane.ok && adapter.isInputReady(pane.out)) {
-      return ok({ ok: true, ms: monotonicMs() - started, signal: 'transcript+ready' })
+    if (!sawTranscriptDone && compactTranscriptHasDone(baseline, { env })) {
+      sawTranscriptDone = true
+      markerSeenAtMs = monotonicMs()
+    }
+    const pane = captureFn(target)
+    if (pane !== null) lastPane = pane
+    if (sawTranscriptDone) {
+      // Fast clean path: the composer returned to idle (the historical signal).
+      if (pane !== null && adapter.isInputReady(pane)) {
+        return ok({ ok: true, ms: monotonicMs() - started, signal: 'transcript+ready' })
+      }
+      // Marker is authoritative: a busy composer after a held marker is a healthy
+      // auto-continue, not a failure. Succeed on the marker once the grace elapses.
+      if (monotonicMs() - markerSeenAtMs >= graceMs) {
+        return ok({ ok: true, ms: monotonicMs() - started, signal: 'transcript' })
+      }
     }
     sleepSync(pollMs)
   } while (monotonicMs() < deadline)
 
+  // Deadline hit. The marker is authoritative: if it was EVER seen, the compact did
+  // finish — a still-busy composer at the deadline is not a failure (succeed on the
+  // marker). Only a MISSING marker is an honest failure (hung / never-completed compact).
+  if (sawTranscriptDone) {
+    return ok({ ok: true, ms: monotonicMs() - started, signal: 'transcript' })
+  }
   const tail = lastPane
     .split(/\r?\n/)
     .map(line => line.trim())
@@ -807,8 +879,7 @@ export function waitForCompactDone(
     .replace(/"/g, "'")
     .slice(0, 240)
   return err(
-    `compact did not complete within ${timeoutMs}ms (` +
-      `${sawTranscriptDone ? 'transcript marker seen, input not ready' : 'no transcript compact marker'}` +
+    `compact did not complete within ${timeoutMs}ms (no transcript compact marker` +
       `${tail ? `; pane tail: ${tail}` : ''})`,
   )
 }