@agfpd/iapeer 0.2.50 → 0.2.52

package/package.json

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

package/src/cli/cli.test.ts

@@ -11,7 +11,7 @@ import { addRuntime, compactPeer, defaultRuntime, formatListTable, listPeers, ne
 import { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
 import { hasIdleReaped, isStopped, loadLifecycleConfig, setIdleReaped, setStopped } from '../lifecycle/index.ts'
 import { launchdPlistPath } from '../launch/launchd.ts'
-import { ok } from '../core/errors.ts'
+import { err, ok } from '../core/errors.ts'
 
 let root: string
 let laDir: string
@@ -463,6 +463,7 @@ describe('compact (resume sleeping dialogue)', () => {
     setIdleReaped(cfg, 'codex-sleepy')
     const wakeCalls: unknown[] = []
     const controlCalls: unknown[] = []
+    const doneCalls: unknown[] = []
     const o = await compactPeer('sleepy', 'codex', {
       env: e,
       wakeFn: async args => {
@@ -473,13 +474,34 @@ describe('compact (resume sleeping dialogue)', () => {
         controlCalls.push({ personality, runtime, command })
         return ok({ ok: true, controlled: { personality, runtime: runtime! }, command: command.name, ts: 't' })
       },
+      compactDoneFn: (target, cwd, baseline) => {
+        doneCalls.push({ target, cwd, runtime: baseline.runtime })
+        return ok({ ok: true, ms: 42, signal: 'transcript+ready' })
+      },
     })
     expect(o).toMatchObject({ action: 'compacted', runtime: 'codex', woke: true })
     expect(wakeCalls).toEqual([{ personality: 'sleepy', runtime: 'codex', task: '', resume: true }])
     expect(controlCalls).toEqual([{ personality: 'sleepy', runtime: 'codex', command: { name: 'compact' } }])
+    expect(doneCalls).toHaveLength(1)
+    expect(doneCalls[0]).toMatchObject({ cwd: '/tmp/sleepy', runtime: 'codex', target: { runtime: 'codex', personality: 'sleepy' } })
     expect(hasIdleReaped(cfg, 'codex-sleepy')).toBe(false)
   })
 
+  test('compact done gate failure surfaces as failed (no false success)', async () => {
+    await register('slow', 'codex')
+    const e = env()
+    const cfg = loadLifecycleConfig(e)
+    setIdleReaped(cfg, 'codex-slow')
+    const o = await compactPeer('slow', 'codex', {
+      env: e,
+      wakeFn: async args => ({ status: 'READY', woke: true, runtime: args.runtime, process_address: `${args.runtime}-${args.personality}`, taskDelivered: true }),
+      controlFn: (personality, runtime, command) => ok({ ok: true, controlled: { personality, runtime: runtime! }, command: command.name, ts: 't' }),
+      compactDoneFn: () => err('compact did not complete within test'),
+    })
+    expect(o.action).toBe('failed')
+    expect(o.reason).toContain('did not complete')
+  })
+
   test('crashed / first-wake asleep peer (no clean idle marker) → nothing-to-compact, no fresh wake', async () => {
     await register('freshy', 'codex')
     let woke = false

package/src/cli/index.ts

@@ -24,7 +24,7 @@ import { recycleFoundationOwnedInfraJobs, updateIapeer, waitForDaemonHealthy } f
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { ensureGlobalIapScaffold } from '../storage/index.ts'
 import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../registry/index.ts'
-import { isPeerLive, routeControl, routeSend, type WakeFn } from '../transport/index.ts'
+import { compactDoneBaseline, isPeerLive, routeControl, routeSend, waitForCompactDone, type WakeFn } from '../transport/index.ts'
 import {
   attachPeer,
   clearIdleReaped,
@@ -515,9 +515,11 @@ export interface CompactPeerOutcome {
 
 /**
  * compact <peer> [runtime] — compact the DIALOGUE, not merely the currently-live
- * session. A live target receives the in-session `/compact` control as before. A
- * cleanly idle-reaped target is first resumed into the same dialogue, then compacted.
- * A crashed / never-run / non-resumable target returns an honest "nothing to compact"
+ * session. A live target receives the in-session `/compact` control; a cleanly
+ * idle-reaped target is first resumed into the same dialogue, then controlled.
+ * SUCCESS is gated on actual compaction completion (structured transcript marker
+ * after the command + input surface ready), not on keystrokes being accepted. A
+ * crashed / never-run / non-resumable target returns an honest "nothing to compact"
  * instead of starting a fresh empty session and compacting that.
  */
 export async function compactPeer(
@@ -526,6 +528,7 @@ export async function compactPeer(
   opts: CliEnvOptions & {
     wakeFn?: (args: { personality: string; runtime: Runtime; task: string; resume: true }) => Promise<WakeResult>
     controlFn?: typeof routeControl
+    compactDoneFn?: typeof waitForCompactDone
   } = {},
 ): Promise<CompactPeerOutcome> {
   const env = opts.env ?? process.env
@@ -551,10 +554,39 @@ export async function compactPeer(
   }
 
   const control = opts.controlFn ?? routeControl
+  const compactDone = opts.compactDoneFn ?? waitForCompactDone
+  const waitDone = (rt: Runtime, baseline: ReturnType<typeof compactDoneBaseline>, woke: boolean): CompactPeerOutcome | null => {
+    const done = compactDone(
+      {
+        personality,
+        runtime: rt,
+        address: buildProcessAddress(rt, personality),
+        socketPath: buildSocketPath(rt, personality, cfg.sockDir),
+      },
+      peer.cwd,
+      baseline,
+      { env },
+    )
+    if (!done.ok) return { personality, runtime: rt, action: 'failed', woke, reason: done.error.message }
+    return null
+  }
   const liveRuntimes = peer.runtimes.filter(rt => isPeerLive(rt, personality, cfg.sockDir))
   if (runtime ? liveRuntimes.includes(runtime as Runtime) : liveRuntimes.length > 0) {
-    const r = control(personality, runtime, { name: 'compact' })
-    if (!r.ok) return { personality, runtime: runtime ?? peer.runtime, action: 'failed', reason: r.error.message }
+    const rt = (runtime as Runtime | undefined)
+      ?? (liveRuntimes.includes(peer.runtime) ? peer.runtime : liveRuntimes.length === 1 ? liveRuntimes[0] : undefined)
+    if (!rt) {
+      return {
+        personality,
+        runtime: peer.runtime,
+        action: 'failed',
+        reason: `${personality} is online in multiple runtimes (${liveRuntimes.join(', ')}) — specify runtime`,
+      }
+    }
+    const baseline = compactDoneBaseline(rt, peer.cwd, { env })
+    const r = control(personality, rt, { name: 'compact' })
+    if (!r.ok) return { personality, runtime: rt, action: 'failed', reason: r.error.message }
+    const waited = waitDone(r.value.controlled.runtime as Runtime, baseline, false)
+    if (waited) return waited
     return { personality, runtime: r.value.controlled.runtime, action: 'compacted', woke: false }
   }
 
@@ -589,8 +621,11 @@ export async function compactPeer(
     return { personality, runtime: rt, action: 'failed', reason }
   }
   clearIdleReaped(cfg, identity)
+  const baseline = compactDoneBaseline(rt, peer.cwd, { env })
   const r = control(personality, rt, { name: 'compact' })
   if (!r.ok) return { personality, runtime: rt, action: 'failed', woke: true, reason: r.error.message }
+  const waited = waitDone(rt, baseline, true)
+  if (waited) return waited
   return { personality, runtime: rt, action: 'compacted', woke: true }
 }
 

package/src/launch/canary.test.ts

@@ -69,7 +69,8 @@ describe('canary script (pure)', () => {
     // proven live); the SERVER's liveness decides, after a dismissal grace sleep.
     expect(s).not.toContain(`[ "$rc" -eq 0 ] || [ "$rc" -ge 128 ]; then exit 0`) // the v1 hole
     expect(s).toContain('sleep 2') // dismissal grace window
-    expect(s).toContain(`has-session 2>/dev/null; then exit 0`) // server alive → nothing to record
+    expect(s).toContain(`kill -0 "$SPID" 2>/dev/null; then exit 0`) // original server alive → nothing to record
+    expect(s).toContain(`[ -z "$SPID" ]`) // fallback only when the original pid was unavailable
     expect(s).toContain('cause=server-vanished') // connection drop (SIGKILL/OOM class)
     expect(s).toContain('cause=signaled-server-gone') // rc=0: channel/client-TERM, server died
     expect(s).toContain('cause=client-killed-server-gone') // rc≥128: client took a hard kill
@@ -119,6 +120,7 @@ describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
     'notifier-canatear',
     'claude-canasweep',
     'claude-canaclient',
+    'claude-canareplaced',
   ]
 
   afterAll(() => {
@@ -285,4 +287,44 @@ describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
     },
     20000,
   )
+
+  test(
+    'dirty server death followed by immediate replacement on the same socket still records the ORIGINAL death',
+    async () => {
+      const identity = 'claude-canareplaced'
+      const { sock, logDir } = bringUp(identity)
+      const pid = serverPid(sock)
+      expect(pid).toBeGreaterThan(0)
+      expect(ensureServerCanary({ identity, sock, exitLogDir: logDir })).toBe('spawned')
+      expect(await waitFor(() => canaryRunning(identity), 3000)).toBe(true)
+      await sleep(500)
+
+      process.kill(pid, 'SIGKILL')
+      // Reuse the same socket before the canary's 2s dismissal-grace window
+      // expires. The old socket-level probe treated this successor as "server
+      // alive" and lost the predecessor's death; the canary must key on SPID.
+      let started = false
+      for (let i = 0; i < 20; i++) {
+        const r = spawnSync('tmux', ['-S', sock, 'new-session', '-d', '-s', identity, 'sleep', '120'], {
+          stdio: 'ignore',
+        })
+        if (r.status === 0) {
+          started = true
+          break
+        }
+        await sleep(50)
+      }
+      expect(started).toBe(true)
+
+      const log = exitLogPath(logDir)
+      expect(await waitFor(() => existsSync(log) && readFileSync(log, 'utf8').includes('ev=server-exit'), 8000)).toBe(
+        true,
+      )
+      const line = readFileSync(log, 'utf8')
+      expect(line).toContain(`ev=server-exit identity=${identity}`)
+      expect(line).toContain(`server_pid=${pid}`)
+      expect(readdirSync(serverDeathsDir(logDir)).length).toBe(1)
+    },
+    20000,
+  )
 })

package/src/launch/canary.ts

@@ -19,14 +19,18 @@
 //     sh recorder (`dismissCanary` → TERM → trap → silent exit). POSIX trap
 //     semantics make this race-free: the trap runs before any recording.
 //   • When wait-for returns — ANY code — the script sleeps 2 s (a concurrent
-//     dismissal TERM wins here), then probes SERVER LIVENESS: alive → exit
-//     silently (a lost canary is re-armed and logged by the supervise retrofit
-//     within a tick); dead with nobody having dismissed us → the death is real
-//     and unclaimed → ONE logfmt line `ev=server-exit` into exits.log (the
-//     per-peer death-cause home, next to pane-died's `ev=session-exit`) + a
-//     forensics snapshot (vm_stat / swap / top-RSS ps / fresh DiagnosticReports)
-//     captured within seconds — the evidence the 60 s supervise tick can never
-//     recover ("системных следов ноль" was the recurring investigation outcome).
+//     dismissal TERM wins here), then probes the ORIGINAL SERVER PID captured at
+//     arm time: still alive → exit silently (a lost canary is re-armed and logged
+//     by the supervise retrofit within a tick); gone with nobody having dismissed
+//     us → the death is real and unclaimed → ONE logfmt line `ev=server-exit`
+//     into exits.log (the per-peer death-cause home, next to pane-died's
+//     `ev=session-exit`) + a forensics snapshot (vm_stat / swap / top-RSS ps /
+//     fresh DiagnosticReports) captured within seconds — the evidence the 60 s
+//     supervise tick can never recover ("системных следов ноль" was the recurring
+//     investigation outcome). PID identity matters: a wake/attach can replace the
+//     tmux server on the same socket before the 2 s grace elapses; probing only
+//     the socket would mistake the successor for the dead original and lose the
+//     canary record (live canary-gap 11.06).
 //     The raw wait_rc still ATTRIBUTES the death (cause=server-vanished /
 //     signaled-server-gone / client-killed-server-gone).
 // Residual blind spot (structural): a killer that SIGKILLs the sh recorder
@@ -98,12 +102,16 @@ export function canaryScript(o: CanaryScriptOptions): string {
     // `rc=0 || rc>=128 → silent` was exactly that hole). v2 contract instead:
     //   • deliberate teardowns DISMISS this sh (TERM → trap above) — the sleep
     //     below gives a concurrently-delivered dismissal time to win;
-    //   • then the SERVER's liveness, not the exit code, decides: alive →
+    //   • then the ORIGINAL SERVER PID's liveness, not the exit code, decides: alive →
     //     nothing to record (a lost canary is re-armed and logged by the
-    //     supervise retrofit within a tick); dead and nobody dismissed us →
-    //     the death is real and unclaimed → record it.
+    //     supervise retrofit within a tick); original server dead and nobody
+    //     dismissed us → the death is real and unclaimed → record it. IMPORTANT:
+    //     check the ORIGINAL SPID, not merely "some server answers on the same
+    //     socket". A wake/attach can replace the server inside this 2 s window;
+    //     socket-liveness would then silently swallow the predecessor's death.
     `sleep 2`,
-    `if '${o.tmuxBin}' -S '${o.sock}' has-session 2>/dev/null; then exit 0; fi`,
+    `if [ -n "$SPID" ] && kill -0 "$SPID" 2>/dev/null; then exit 0; fi`,
+    `if [ -z "$SPID" ] && '${o.tmuxBin}' -S '${o.sock}' has-session 2>/dev/null; then exit 0; fi`,
     // The exit code still ATTRIBUTES the recorded death (raw wait_rc is kept):
     //   rc=0   → signaled-server-gone   (channel signal or client-TERM, server died)
     //   rc≥128 → client-killed-server-gone (client took a non-TERM kill)

package/src/transport/compactDone.test.ts

@@ -0,0 +1,60 @@
+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'
+
+function withHome(fn: (home: string, env: NodeJS.ProcessEnv) => void): void {
+  const home = mkdtempSync(join(tmpdir(), 'iapeer-compact-gate-home-'))
+  try {
+    fn(home, { ...process.env, HOME: home })
+  } finally {
+    rmSync(home, { recursive: true, force: true })
+  }
+}
+
+function claudeSlug(cwd: string): string {
+  return realpathSync(cwd).replace(/[^a-zA-Z0-9]/g, '-')
+}
+
+describe('compact done transcript gate', () => {
+  test('codex: ignores old markers and detects a new context_compacted event', () => withHome((home, env) => {
+    const cwd = mkdtempSync(join(tmpdir(), 'iapeer-compact-codex-cwd-'))
+    try {
+      const dir = join(home, '.codex', 'sessions', '2026', '06', '13')
+      mkdirSync(dir, { recursive: true })
+      const file = join(dir, 'rollout-test.jsonl')
+      writeFileSync(file,
+        JSON.stringify({ type: 'session_meta', payload: { cwd } }) + '\n' +
+        JSON.stringify({ type: 'event_msg', payload: { type: 'context_compacted' } }) + '\n',
+      )
+      const baseline = compactDoneBaseline('codex', cwd, { env })
+      expect(compactTranscriptHasDone(baseline, { env })).toBe(false)
+      appendFileSync(file, JSON.stringify({ type: 'event_msg', payload: { type: 'context_compacted' } }) + '\n')
+      expect(compactTranscriptHasDone(baseline, { env })).toBe(true)
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  }))
+
+  test('claude: detects a new compact_boundary and ignores raw text mentions', () => withHome((home, env) => {
+    const cwd = mkdtempSync(join(tmpdir(), 'iapeer-compact-claude-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: 'context_compacted is only text' } }) + '\n' +
+        JSON.stringify({ type: 'system', subtype: 'compact_boundary', content: 'Conversation compacted' }) + '\n',
+      )
+      const baseline = compactDoneBaseline('claude', cwd, { env })
+      expect(compactTranscriptHasDone(baseline, { env })).toBe(false)
+      appendFileSync(file, JSON.stringify({ type: 'user', message: { role: 'user', content: 'Conversation compacted text only' } }) + '\n')
+      expect(compactTranscriptHasDone(baseline, { env })).toBe(false)
+      appendFileSync(file, JSON.stringify({ type: 'system', subtype: 'compact_boundary', content: 'Conversation compacted', compactMetadata: { durationMs: 12 } }) + '\n')
+      expect(compactTranscriptHasDone(baseline, { env })).toBe(true)
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  }))
+})

package/src/transport/index.ts

@@ -13,8 +13,9 @@
 // runtime's adapter.deliveryMarkers. The poll/re-press logic is untouched; only the
 // marker SOURCE moved, so the timing behaviour is identical.
 
-import { readdirSync } from 'fs'
+import { readFileSync, readdirSync, realpathSync, statSync } from 'fs'
 import { join } from 'path'
+import { homedir } from 'os'
 import { spawnSync } from 'child_process'
 import {
   MAX_ATTACHMENTS,
@@ -309,6 +310,229 @@ export function deliverViaTmux(target: DeliveryTarget, envelope: string, cwd?: s
   return ok(undefined)
 }
 
+
+// ─── Compact done gate (dialogue control must report FACT, not keystroke delivery) ──
+
+export interface CompactDoneBaseline {
+  runtime: string
+  cwd: string
+  capturedAtMs: number
+  files: { path: string; size: number }[]
+}
+
+export interface CompactDoneWaitResult {
+  ok: true
+  ms: number
+  signal: 'transcript+ready'
+}
+
+function envHome(env: NodeJS.ProcessEnv | undefined): string {
+  return env?.HOME?.trim() || homedir()
+}
+
+function canonicalPath(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+function claudeTranscriptDirForCwd(cwd: string, env?: NodeJS.ProcessEnv): string {
+  const slug = canonicalPath(cwd).replace(/[^a-zA-Z0-9]/g, '-')
+  return join(envHome(env), '.claude', 'projects', slug)
+}
+
+function codexSessionCwd(file: string): string | null {
+  try {
+    const firstLine = readFileSync(file, 'utf8').split(/\r?\n/, 1)[0]
+    if (!firstLine) return null
+    const entry = JSON.parse(firstLine) as { type?: unknown; payload?: { cwd?: unknown } }
+    return entry.type === 'session_meta' && typeof entry.payload?.cwd === 'string' ? entry.payload.cwd : null
+  } catch {
+    return null
+  }
+}
+
+function compactCandidateFiles(runtime: string, cwd: string, env?: NodeJS.ProcessEnv): string[] {
+  const target = canonicalPath(cwd)
+  const out: string[] = []
+  if (runtime === 'claude') {
+    const dir = claudeTranscriptDirForCwd(cwd, env)
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return []
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.jsonl')) out.push(join(dir, entry.name))
+    }
+  } else if (runtime === 'codex') {
+    const root = join(envHome(env), '.codex', 'sessions')
+    function visit(dir: string): void {
+      let entries
+      try {
+        entries = readdirSync(dir, { withFileTypes: true })
+      } catch {
+        return
+      }
+      for (const entry of entries) {
+        const path = join(dir, entry.name)
+        if (entry.isDirectory()) {
+          visit(path)
+          continue
+        }
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue
+        if (canonicalPath(codexSessionCwd(path) ?? '') === target) out.push(path)
+      }
+    }
+    visit(root)
+  }
+  return out.sort()
+}
+
+function compactDoneFileSize(path: string): number {
+  try {
+    return statSync(path).size
+  } catch {
+    return 0
+  }
+}
+
+export function compactDoneBaseline(runtime: string, cwd: string, opts: { env?: NodeJS.ProcessEnv } = {}): CompactDoneBaseline {
+  return {
+    runtime,
+    cwd,
+    capturedAtMs: monotonicMs(),
+    files: compactCandidateFiles(runtime, cwd, opts.env).map(path => ({ path, size: compactDoneFileSize(path) })),
+  }
+}
+
+function isStructuredCompactDone(runtime: string, obj: unknown): boolean {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false
+  const rec = obj as Record<string, unknown>
+  const payload = rec.payload && typeof rec.payload === 'object' && !Array.isArray(rec.payload)
+    ? rec.payload as Record<string, unknown>
+    : undefined
+
+  // Codex writes an explicit structured completion event after slash-/compact.
+  // The adjacent top-level `compacted` record is accepted too: older/newer Codex
+  // builds can emit it immediately before/without the event_msg wrapper.
+  if (runtime === 'codex') {
+    if (rec.type === 'event_msg' && payload?.type === 'context_compacted') return true
+    if (rec.type === 'compacted') return true
+  }
+
+  // Claude Code records the finished compaction as a system compact boundary with
+  // compactMetadata (duration/pre/post tokens). Raw text mentions are ignored.
+  if (runtime === 'claude') {
+    if (rec.type === 'system' && rec.subtype === 'compact_boundary') return true
+    if (rec.type === 'system' && rec.compactMetadata && typeof rec.compactMetadata === 'object') return true
+  }
+
+  return false
+}
+
+export function compactTranscriptHasDone(
+  baseline: CompactDoneBaseline,
+  opts: { env?: NodeJS.ProcessEnv } = {},
+): boolean {
+  const offsets = new Map(baseline.files.map(f => [f.path, f.size]))
+  // Include a transcript/session file that appears after the baseline (rare, but a
+  // resume/rotate race should not make the done gate blind). Existing files are
+  // read only from their baseline byte offset, so old compact markers cannot pass.
+  for (const path of compactCandidateFiles(baseline.runtime, baseline.cwd, opts.env)) {
+    if (!offsets.has(path)) offsets.set(path, 0)
+  }
+
+  for (const [path, offset] of offsets) {
+    let buf: Buffer
+    try {
+      buf = readFileSync(path)
+    } catch {
+      continue
+    }
+    const start = Math.min(Math.max(0, offset), buf.length)
+    const tail = buf.subarray(start).toString('utf8')
+    for (const line of tail.split(/\r?\n/)) {
+      if (!line.trim()) continue
+      let obj: unknown
+      try {
+        obj = JSON.parse(line)
+      } catch {
+        continue
+      }
+      if (isStructuredCompactDone(baseline.runtime, obj)) return true
+    }
+  }
+  return false
+}
+
+function compactDoneTimeoutMs(env: NodeJS.ProcessEnv | undefined): number {
+  const raw = env?.IAPEER_COMPACT_DONE_TIMEOUT_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  // Keep default below telegram-runtime's 300 s command timeout so iapeer returns
+  // the truthful failure itself instead of letting the channel kill the process.
+  return Number.isFinite(n) && n >= 0 ? n : 290_000
+}
+
+function compactDonePollMs(env: NodeJS.ProcessEnv | undefined): number {
+  const raw = env?.IAPEER_COMPACT_DONE_POLL_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n > 0 ? n : 1000
+}
+
+/**
+ * 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.
+ */
+export function waitForCompactDone(
+  target: DeliveryTarget,
+  cwd: string,
+  baseline: CompactDoneBaseline,
+  opts: { env?: NodeJS.ProcessEnv; timeoutMs?: number; pollMs?: number } = {},
+): Result<CompactDoneWaitResult> {
+  const env = opts.env ?? process.env
+  const timeoutMs = opts.timeoutMs ?? compactDoneTimeoutMs(env)
+  const pollMs = opts.pollMs ?? compactDonePollMs(env)
+  const adapter = getAdapter(target.runtime)
+  const started = monotonicMs()
+  const deadline = started + timeoutMs
+  let sawTranscriptDone = false
+  let lastPane = ''
+
+  do {
+    if (!sessionAlive(target.socketPath, target.address)) {
+      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' })
+    }
+    sleepSync(pollMs)
+  } while (monotonicMs() < deadline)
+
+  const tail = lastPane
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(-2)
+    .join(' ⏎ ')
+    .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'}` +
+      `${tail ? `; pane tail: ${tail}` : ''})`,
+  )
+}
+
 // ─── Control channel (Ф-E) — in-session control via the adapter, UNCONDITIONAL ──
 
 /**