@agfpd/iapeer 0.2.64 → 0.2.65

package/src/supervisor/panelog.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Terminal } from '@xterm/headless'
+import { modelToPlainText } from '../shadow/render.ts'
+import { killSession, startSupervisorDaemon } from './index.ts'
+
+// Slice c — the supervisor pane-log must be a drop-in for tmux pipe-pane: the SAME raw child bytes to
+// <identity>.log (so observer/shadow/readyGateViewport read a served session identically), AND a model
+// built from it must render what tmux's capture-pane shows. Live tmux + Bun-native pty → guarded.
+const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+const [maj, min, pat] = (Bun.version || '0.0.0').split('.').map(Number) as [number, number, number]
+const bunPty = maj > 1 || (maj === 1 && (min > 3 || (min === 3 && pat >= 5)))
+const d = tmuxAvailable && bunPty ? describe : describe.skip
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+const readBuf = (p: string): Buffer => (existsSync(p) ? readFileSync(p) : Buffer.alloc(0))
+const modelOf = (bytes: Buffer, cols: number, rows: number): Promise<string> => {
+  const t = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 1000 })
+  return new Promise<string>(res => t.write(bytes, () => res(modelToPlainText(t, cols, rows))))
+}
+
+d('supervisor pane-log ≡ tmux pipe-pane', () => {
+  test('RAW-BYTE-IDENTITY: the same child yields byte-identical logs (LF/CRLF + multibyte + ANSI)', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'panelog-bp-'))
+    const tmuxSock = join(dir, 't.sock')
+    const logTmux = join(dir, 'tmux.log')
+    const logSup = join(dir, 'sup.log')
+    const runDir = join(dir, 'run')
+    // bare \n, \r\n, multibyte ❯ › … é (the latin1 grabli), ANSI SGR — the byte classes that diverge
+    const child = ['sh', '-c', `sleep 0.5; printf 'L1\\nL2\\r\\ng:❯›…é\\n\\033[31mRED\\033[0m\\nTAB\\tEND\\n'; sleep 1`]
+    try {
+      spawnSync('tmux', ['-S', tmuxSock, 'new-session', '-d', '-s', 'p', '-x', '80', '-y', '24', ...child], { stdio: 'ignore' })
+      spawnSync('tmux', ['-S', tmuxSock, 'pipe-pane', '-o', '-t', 'p', `cat >> '${logTmux}'`], { stdio: 'ignore' })
+      startSupervisorDaemon({ session: 'bp', runtime: 'tick', runDir, serve: { argv: child, env: { PATH: process.env.PATH ?? '' }, cwd: dir, paneLogPath: logSup } })
+      await sleep(2300) // both children: sleep .5 + emit + sleep 1 ≈ exit ~1.5s; tmux's cat EOF-flushes
+      const a = readBuf(logTmux)
+      const b = readBuf(logSup)
+      expect(b.length).toBeGreaterThan(0)
+      expect(b.equals(a)).toBe(true) // byte-for-byte — raw Buffer passthrough, shared onlcr default
+      expect(b.includes(Buffer.from('❯›…é', 'utf8'))).toBe(true) // multibyte survived (no latin1 re-encode)
+    } finally {
+      spawnSync('tmux', ['-S', tmuxSock, 'kill-server'], { stdio: 'ignore' })
+      try {
+        killSession(runDir, 'bp')
+      } catch {
+        /* */
+      }
+      await sleep(300)
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('BINDING: a model from the supervisor pane-log renders what tmux capture-pane shows', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'panelog-bind-'))
+    const tmuxSock = join(dir, 't.sock')
+    const logSup = join(dir, 'sup.log')
+    const runDir = join(dir, 'run')
+    const COLS = 80,
+      ROWS = 24
+    // a static frame (clear+home, three lines incl. the ❯ ready glyph), then idle so capture-pane sees it
+    const child = ['sh', '-c', `printf '\\033[2J\\033[HLine one\\r\\n  ❯ ready prompt\\r\\nthird line ok\\r\\n'; sleep 30`]
+    try {
+      spawnSync('tmux', ['-S', tmuxSock, 'new-session', '-d', '-s', 'b', '-x', String(COLS), '-y', String(ROWS), ...child], { stdio: 'ignore' })
+      startSupervisorDaemon({ session: 'bind', runtime: 'tick', runDir, serve: { argv: child, env: { PATH: process.env.PATH ?? '' }, cwd: dir, paneLogPath: logSup } })
+      // let the frame render in both
+      let cap = ''
+      for (let i = 0; i < 30 && !/❯ ready prompt/.test(cap); i++) {
+        await sleep(200)
+        cap = spawnSync('tmux', ['-S', tmuxSock, 'capture-pane', '-p', '-t', 'b'], { encoding: 'utf8' }).stdout || ''
+      }
+      const modelSup = await modelOf(readBuf(logSup), COLS, ROWS)
+      // tmux capture-pane render (its own emulator) == @xterm model of the SUPERVISOR's pane-log
+      const norm = (s: string): string =>
+        s
+          .split('\n')
+          .map(l => l.replace(/\s+$/, ''))
+          .join('\n')
+          .replace(/\n+$/, '')
+      expect(norm(modelSup)).toBe(norm(cap))
+      expect(modelSup).toContain('❯ ready prompt') // the ready glyph survived into the model
+    } finally {
+      spawnSync('tmux', ['-S', tmuxSock, 'kill-server'], { stdio: 'ignore' })
+      try {
+        killSession(runDir, 'bind')
+      } catch {
+        /* */
+      }
+      await sleep(300)
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/supervisor/paths.ts

@@ -12,3 +12,12 @@ export function defaultRunDir(env: NodeJS.ProcessEnv = process.env): string {
 export const sockPath = (runDir: string, session: string): string => join(runDir, `${session}.sock`)
 export const pidPath = (runDir: string, session: string): string => join(runDir, `${session}.pid`)
 export const logPath = (runDir: string, session: string): string => join(runDir, `${session}.log`)
+/** Serving spec (cutover Block 2 slice b): the composed {argv, env, cwd} a detached daemon serves.
+ *  Written 0600 by startSupervisorDaemon BEFORE spawn (env can carry launch.env secrets), read by
+ *  the daemon CLI entry, removed on shutdown. Absent → a bare throwaway/tick session. */
+export const servePath = (runDir: string, session: string): string => join(runDir, `${session}.serve.json`)
+/** Attached-client marker (spawn-flip Ф0b-3 slice 3c): present iff ≥1 supervisor client is attached.
+ *  The daemon maintains it on every client add/delete; the warm-deliver path (a DIFFERENT process)
+ *  reads it to gate the hosted busy-composer hold — never paste over a HUMAN's unfinished input, but
+ *  never hold for the AI's own composer output when no operator is attached. */
+export const attachedPath = (runDir: string, session: string): string => join(runDir, `${session}.attached`)

package/src/supervisor/protocol.test.ts

@@ -1,4 +1,8 @@
 import { describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import {
   BackpressureWriter,
   FRAME_DATA,
@@ -6,12 +10,15 @@ import {
   TERM_RESET,
   capabilityResponses,
   frame,
+  keysToBytes,
   makeFramer,
   parseSize,
   sizePayload,
   stripQueries,
 } from './protocol.ts'
 
+const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+
 describe('frame protocol', () => {
   test('frame() lays out [type][len:u32be][payload]', () => {
     const f = frame(FRAME_DATA, 'hi')
@@ -129,3 +136,87 @@ describe('BackpressureWriter (port-dep #2: the ~90 KB-over-8 KB truncation that
     expect(w.isDead).toBe(true)
   })
 })
+
+describe('keysToBytes (tmux send-keys vocabulary → pty bytes, the boot key-set)', () => {
+  test('Enter → CR (the trust/proceed dialogs)', () => {
+    expect(keysToBytes(['Enter'])).toEqual(Buffer.from('\r'))
+  })
+  test('codex update-decline [2,Enter] → "2" + CR', () => {
+    expect(keysToBytes(['2', 'Enter'])).toEqual(Buffer.from('2\r'))
+  })
+  test('codex hooks-review [Down,Enter] in NORMAL cursor mode → CSI-B + CR', () => {
+    expect(keysToBytes(['Down', 'Enter'])).toEqual(Buffer.from('\x1b[B\r'))
+  })
+  test('[Down,Enter] under DECCKM application-cursor mode → SS3-B + CR (the mode-sensitivity boris flagged)', () => {
+    expect(keysToBytes(['Down', 'Enter'], { appCursorKeys: true })).toEqual(Buffer.from('\x1bOB\r'))
+  })
+  test('claude resume-picker [Down] → cursor-down only', () => {
+    expect(keysToBytes(['Down'])).toEqual(Buffer.from('\x1b[B'))
+  })
+  test('literal mode -l sends the rest verbatim (executeControl /compact)', () => {
+    expect(keysToBytes(['-l', '/compact'])).toEqual(Buffer.from('/compact'))
+  })
+  test('Escape (interrupt) → ESC', () => {
+    expect(keysToBytes(['Escape'])).toEqual(Buffer.from('\x1b'))
+  })
+  test('an unknown token falls through to literal text', () => {
+    expect(keysToBytes(['hello'])).toEqual(Buffer.from('hello'))
+  })
+})
+
+// boris's acceptance bar: the translator must be BYTE-IDENTICAL to real `tmux send-keys` for the
+// key-set the adapters actually return — not a "looks right" table. We capture exactly what tmux
+// delivers to a pane (raw mode bypasses the line discipline so no CR↔NL cooking) and compare.
+// Guarded by tmuxAvailable (a clean CI runner has no tmux → these skip, per the live-tmux lesson).
+function tmuxSendKeysBytes(keys: string[], appCursor: boolean, n: number): Buffer {
+  const dir = mkdtempSync(join(tmpdir(), 'pts-keys-'))
+  const sock = join(dir, 's.sock')
+  const out = join(dir, 'out.bin')
+  // The pane program: optionally emit DECCKM (CSI ? 1 h) as its OWN output so tmux tracks
+  // application-cursor mode; then raw mode (capture send-keys bytes verbatim); then read exactly n
+  // bytes and exit (head flushes on exit — a buffered cat would lose the tail on kill).
+  const pre = appCursor ? `printf '\\033[?1h'; ` : ''
+  const paneCmd = `${pre}stty raw -echo; head -c ${n} > '${out}'`
+  try {
+    const create = spawnSync(
+      'tmux',
+      ['-S', sock, 'new-session', '-d', '-s', 'k', '-x', '80', '-y', '24', 'sh', '-c', paneCmd],
+      { stdio: 'ignore' },
+    )
+    if (create.status !== 0) throw new Error('tmux new-session failed')
+    Bun.sleepSync(400) // let the pane reach raw mode + tmux process the DECCKM output
+    spawnSync('tmux', ['-S', sock, 'send-keys', '-t', 'k', ...keys], { stdio: 'ignore' })
+    const deadline = Date.now() + 3000
+    while (Date.now() < deadline) {
+      if (existsSync(out) && statSync(out).size >= n) break
+      Bun.sleepSync(50)
+    }
+    return existsSync(out) ? readFileSync(out) : Buffer.alloc(0)
+  } finally {
+    spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+    try {
+      rmSync(dir, { recursive: true, force: true })
+    } catch {
+      /* */
+    }
+  }
+}
+
+describe.if(tmuxAvailable)('keysToBytes byte-identity vs real tmux send-keys (live)', () => {
+  test('NORMAL cursor mode: [Down,Enter]', () => {
+    const ours = keysToBytes(['Down', 'Enter'])
+    expect(tmuxSendKeysBytes(['Down', 'Enter'], false, ours.length)).toEqual(ours)
+  })
+  test('DECCKM application-cursor mode: [Down,Enter] → SS3', () => {
+    const ours = keysToBytes(['Down', 'Enter'], { appCursorKeys: true })
+    expect(tmuxSendKeysBytes(['Down', 'Enter'], true, ours.length)).toEqual(ours)
+  })
+  test('literal digit + Enter: [2,Enter]', () => {
+    const ours = keysToBytes(['2', 'Enter'])
+    expect(tmuxSendKeysBytes(['2', 'Enter'], false, ours.length)).toEqual(ours)
+  })
+  test('bare Enter', () => {
+    const ours = keysToBytes(['Enter'])
+    expect(tmuxSendKeysBytes(['Enter'], false, ours.length)).toEqual(ours)
+  })
+})

package/src/supervisor/protocol.ts

@@ -70,6 +70,55 @@ export function stripQueries(s: string): string {
   return s.replace(QUERY_RE, '')
 }
 
+// ── key-name → pty bytes (boot-driver, serving slice a) ─────────────────────────
+// Translate a tmux send-keys-style key list into the raw bytes a pty expects, so the supervisor
+// boot-driver can answer startup dialogs (codex trust/update/hooks, claude trust/resume-picker) off
+// the MODEL exactly as the launch primitive answers them via `tmux send-keys`. PURE — the byte
+// output is unit-comparable to real `tmux send-keys` (the acceptance bar: byte-identity, not a
+// "looks right" table).
+//
+// tmux semantics mirrored for the vocabulary our RuntimeAdapters actually emit (bootDialogKeys /
+// permissionDialogKeys / executeControl): a leading `-l` switches to LITERAL mode (every following
+// token sent verbatim, no key-name lookup); otherwise each token is a KEY NAME when known, else
+// literal text. Cursor keys depend on DECCKM application-cursor-keys mode — `\x1b[B` (normal) vs
+// `\x1bOB` (application) — which tmux keys off the terminal mode and the caller reads from the
+// @xterm model (term.modes.applicationCursorKeysMode), passing it in `enc`. Both codex hooks-review
+// (`['Down','Enter']`) and the claude resume-picker (`['Down']`) put a cursor key in the boot set,
+// so the mode is load-bearing — a hardcoded `\x1b[B` would corrupt the key under DECCKM.
+
+export interface KeyEncoding {
+  /** DECCKM application-cursor-keys mode (CSI ? 1 h). When set, arrow keys use SS3 (ESC O x)
+   *  instead of CSI (ESC [ x), matching what tmux send-keys emits in that mode. */
+  appCursorKeys?: boolean
+}
+
+const NAMED_KEYS: Record<string, string> = {
+  Enter: '\r',
+  Escape: '\x1b',
+  Tab: '\t',
+  Space: ' ',
+  BSpace: '\x7f',
+}
+
+/** Translate `keys` (tmux send-keys vocabulary) to the pty byte stream. See section header. */
+export function keysToBytes(keys: string[], enc: KeyEncoding = {}): Buffer {
+  const cur: Record<string, string> = enc.appCursorKeys
+    ? { Up: '\x1bOA', Down: '\x1bOB', Right: '\x1bOC', Left: '\x1bOD' }
+    : { Up: '\x1b[A', Down: '\x1b[B', Right: '\x1b[C', Left: '\x1b[D' }
+  let literal = false
+  let out = ''
+  for (const k of keys) {
+    if (!literal && k === '-l') {
+      literal = true
+      continue
+    }
+    if (!literal && k in NAMED_KEYS) out += NAMED_KEYS[k]
+    else if (!literal && k in cur) out += cur[k]
+    else out += k
+  }
+  return Buffer.from(out, 'utf8')
+}
+
 // ── port-dep #1: terminal reset on every client exit path ───────────────────────
 // The child sets a STACK of app-modes on the live terminal (alt-screen, bracketed-paste,
 // focus-events, theme-update, ALL mouse tracking, kitty-keyboard, scroll-region, hidden cursor).

package/src/transport/composerQueue.test.ts

@@ -144,6 +144,36 @@ describe('createComposerDeliveryQueue', () => {
     expect(failed.join('\n')).toMatch(/vanished|replaced/)
   })
 
+  test('async-correctness: concurrent enqueue with ASYNC predicates → each delivered exactly once, no dup/loss (Ф0b-3 3c-2)', async () => {
+    // The host-aware refactor makes shouldQueue/hasHumanInput/deliver awaitable. Inject ASYNC seams
+    // (a real yield window) and fire concurrent enqueues — the FIFO + per-identity drain guard must
+    // still deliver each envelope EXACTLY once (no race-doubled, no race-lost).
+    let held = true
+    const delivered: string[] = []
+    const q = createComposerDeliveryQueue({
+      pollMs: 5,
+      forceTimeoutMs: 2000,
+      shouldQueue: async () => { await sleep(4); return true },
+      hasHumanInput: async () => { await sleep(2); return held },
+      sessionToken: () => 'session-1:pane-1',
+      sessionAlive: () => true,
+      deliver: async (_target, envelope) => { await sleep(1); delivered.push(envelope); return ok(undefined) },
+      notifyFailed: () => { /* */ },
+    })
+
+    const acks = await Promise.all([
+      q.tryEnqueue(args('msg-A')),
+      q.tryEnqueue(args('msg-B')),
+      q.tryEnqueue(args('msg-C')),
+    ])
+    expect(acks.every(a => a?.ok)).toBe(true)
+    await sleep(40)
+    expect(delivered).toEqual([]) // all three held while busy
+    held = false
+    await sleep(80)
+    expect(delivered.slice().sort()).toEqual(['msg-A', 'msg-B', 'msg-C']) // each ONCE — no dup, no loss
+  })
+
   test('daemon close/restart failAll re-fails every queued-but-undelivered envelope', async () => {
     const delivered: string[] = []
     const failed: string[] = []

package/src/transport/hostControl.test.ts

@@ -0,0 +1,87 @@
+// Spawn-flip cutover Block 2, Ф0b-2 slice 3 — host-aware in-session control (interrupt / compact).
+//
+// executeControlOnTarget becomes host-aware: a supervisor-HOSTED target has no `tmux send-keys`, so
+// each control plan step is translated to pty bytes by keysToBytes (REUSED from the boot-driver) and
+// sent over the supervisor socket. These suites cover the host branch hermetically (a seam injects the
+// host-detect + the socket control-send) — asserting the BYTE TRANSLATION + dispatch. The live
+// "interrupt really interrupts a hosted turn" effect is proven separately against a real hosted codex.
+import { describe, expect, test } from 'bun:test'
+import { executeControlOnTarget, type ControlHostSeam, type DeliveryTarget } from './index.ts'
+
+const hostedCodex: DeliveryTarget = {
+  runtime: 'codex',
+  personality: 'ptyx',
+  address: 'codex-ptyx',
+  socketPath: '/tmp/nonexistent-iap-test.sock',
+}
+
+interface Captured {
+  session: string
+  chunks: Buffer[]
+  stepDelayMs?: number
+}
+
+function capturingSeam(captured: Captured[]): ControlHostSeam {
+  return {
+    hostAlive: () => true,
+    sendControl: async (_runDir, session, chunks, opts) => {
+      captured.push({ session, chunks, stepDelayMs: opts.stepDelayMs })
+      return { ok: true }
+    },
+  }
+}
+
+describe('executeControlOnTarget — hosted control over the socket (slice 3)', () => {
+  test('interrupt → a single bare ESC byte (\\x1b), no step delay', async () => {
+    const cap: Captured[] = []
+    const r = await executeControlOnTarget(hostedCodex, { name: 'interrupt' }, capturingSeam(cap))
+    expect(r.ok).toBe(true)
+    expect(cap).toHaveLength(1)
+    expect(cap[0].session).toBe('codex-ptyx')
+    expect(cap[0].chunks.map(b => b.toString('latin1'))).toEqual(['\x1b'])
+    expect(cap[0].stepDelayMs).toBeUndefined()
+  })
+
+  test('compact → "/compact" literal then Enter (CR), with the 300ms step delay', async () => {
+    const cap: Captured[] = []
+    const r = await executeControlOnTarget(hostedCodex, { name: 'compact' }, capturingSeam(cap))
+    expect(r.ok).toBe(true)
+    expect(cap[0].chunks.map(b => b.toString('latin1'))).toEqual(['/compact', '\r'])
+    expect(cap[0].stepDelayMs).toBe(300)
+  })
+
+  test('flag-off (hostAlive=false) → the socket control-send is NEVER touched (tmux path)', async () => {
+    let sendCalls = 0
+    const seam: ControlHostSeam = {
+      hostAlive: () => false,
+      sendControl: async () => {
+        sendCalls++
+        return { ok: true }
+      },
+    }
+    // tmux send-keys will fail against the bogus socket — incidental; the contract is that flag-off
+    // never reaches the host branch.
+    await executeControlOnTarget(hostedCodex, { name: 'interrupt' }, seam)
+    expect(sendCalls).toBe(0)
+  })
+
+  test('socket control-send fails → loud error, no false ok', async () => {
+    const seam: ControlHostSeam = {
+      hostAlive: () => true,
+      sendControl: async () => ({ ok: false, error: 'socket dead during control send' }),
+    }
+    const r = await executeControlOnTarget(hostedCodex, { name: 'interrupt' }, seam)
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.error.message).toContain('hosted control "interrupt" failed')
+      expect(r.error.message).toContain('socket dead')
+    }
+  })
+
+  test('unsupported command for the runtime → explicit refusal (router runtime, no control plan)', async () => {
+    const router: DeliveryTarget = { runtime: 'telegram', personality: 'tg', address: 'telegram-tg', socketPath: '/tmp/x.sock' }
+    const r = await executeControlOnTarget(router, { name: 'interrupt' }, capturingSeam([]))
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error.message).toContain('does not support control command')
+  })
+})

package/src/transport/hostDeliver.test.ts

@@ -0,0 +1,102 @@
+// Spawn-flip cutover Block 2, Ф0b-2 — host-aware warm delivery (`deliverWarm`).
+//
+// The warm-deliver path becomes host-aware: a supervisor-HOSTED target is delivered over its socket
+// (Ф0a leaf) and CONFIRMED by the SAME final arbiter as the tmux busy path — a transcript-mtime
+// advance, NOT the socket-ack. These suites cover the host branch hermetically (injected seams: a
+// fake host-detect + host-deliver + a transcript-mtime proxy) so no live supervisor daemon is needed.
+// The flag-off (tmux) routing is asserted by the host seam staying UNTOUCHED — the byte-identical
+// guarantee that lets this ship dark.
+import { afterEach, describe, expect, test } from 'bun:test'
+import { deliverWarm, type DeliveryTarget, type WarmDeliverSeam } from './index.ts'
+
+const hostedTarget: DeliveryTarget = {
+  runtime: 'codex',
+  personality: 'ptyx',
+  address: 'codex-ptyx',
+  socketPath: '/tmp/nonexistent-iap-test.sock',
+}
+
+const savedGrace = process.env.IAP_HOST_LIVENESS_GRACE_MS
+afterEach(() => {
+  if (savedGrace === undefined) delete process.env.IAP_HOST_LIVENESS_GRACE_MS
+  else process.env.IAP_HOST_LIVENESS_GRACE_MS = savedGrace
+})
+
+describe('deliverWarm — flag-off (no live supervisor session) keeps the tmux path', () => {
+  test('hostAlive=false → the host-deliver seam is NEVER touched (routes to deliverViaTmux)', async () => {
+    let hostedCalls = 0
+    const seam: WarmDeliverSeam = {
+      hostAlive: () => false,
+      deliverHosted: async () => {
+        hostedCalls++
+        return { ok: true }
+      },
+    }
+    // The tmux path will fail against a bogus socket — but that is incidental; the contract under
+    // test is that flag-off NEVER reaches the host branch. We assert the host seam stayed cold.
+    await deliverWarm(hostedTarget, 'hi', '/tmp', seam)
+    expect(hostedCalls).toBe(0)
+  })
+})
+
+describe('deliverWarm — hosted target delivers over the socket + confirms by transcript advance', () => {
+  test('socket deliver ok AND transcript advances → ok', async () => {
+    let mtime = 100
+    const seam: WarmDeliverSeam = {
+      hostAlive: () => true,
+      deliverHosted: async () => {
+        mtime = 200 // the session took our message and started a model turn → transcript moved
+        return { ok: true }
+      },
+      newestActivityMtime: () => mtime,
+    }
+    const r = await deliverWarm(hostedTarget, 'task', '/peer/cwd', seam)
+    expect(r.ok).toBe(true)
+  })
+
+  test('socket-ack is NOT landed: deliver ok but NO transcript advance → loud fail (treated as dead)', async () => {
+    process.env.IAP_HOST_LIVENESS_GRACE_MS = '0' // expire the HOST grace immediately — deterministic fail
+    let hostedCalls = 0
+    const seam: WarmDeliverSeam = {
+      hostAlive: () => true,
+      deliverHosted: async () => {
+        hostedCalls++
+        return { ok: true } // CR flushed to the socket — but the session never advanced
+      },
+      newestActivityMtime: () => 100, // constant → never advances past baseline
+    }
+    const r = await deliverWarm(hostedTarget, 'task', '/peer/cwd', seam)
+    expect(hostedCalls).toBe(1)
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error.message).toContain('no transcript advance')
+  })
+
+  test('socket deliver fails (socket dead/stalled) → loud fail, no false ok', async () => {
+    const seam: WarmDeliverSeam = {
+      hostAlive: () => true,
+      deliverHosted: async () => ({ ok: false, error: 'socket dead during submit' }),
+      newestActivityMtime: () => 100,
+    }
+    const r = await deliverWarm(hostedTarget, 'task', '/peer/cwd', seam)
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.error.message).toContain('deliver failed')
+      expect(r.error.message).toContain('socket dead')
+    }
+  })
+
+  test('no cwd (direct caller, no activity proxy) → confirmed-only (socket-ack), no mtime probe', async () => {
+    let mtimeProbes = 0
+    const seam: WarmDeliverSeam = {
+      hostAlive: () => true,
+      deliverHosted: async () => ({ ok: true }),
+      newestActivityMtime: () => {
+        mtimeProbes++
+        return 100
+      },
+    }
+    const r = await deliverWarm(hostedTarget, 'task', undefined, seam)
+    expect(r.ok).toBe(true)
+    expect(mtimeProbes).toBe(0) // no cwd → the transcript proxy is never consulted
+  })
+})