@agfpd/iapeer 0.2.63 → 0.2.65

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
+  })
+})

package/src/transport/index.ts

@@ -43,6 +43,23 @@ import type { ResolvedCaller } from '../identity/index.ts'
 // dependency: launch does NOT import transport, so no cycle.
 import { getAdapter } from '../launch/index.ts'
 import type { ControlCommand, DeliveryMarkers } from '../launch/types.ts'
+// Spawn-flip Ф0b-2: warm-deliver is HOST-AWARE. hostSessionAlive (runtime-state host detect, an
+// @xterm-free pid-file check) + deliverHosted (the pure-protocol socket leaf, Ф0a) come from
+// launch/ptyHost — already in transport's module graph via getAdapter above and @xterm-free by
+// construction (the daemon @xterm-probe covers it). No new cycle: ptyHost's subtree never imports
+// transport. Flag-off (no live supervisor session) → hostSessionAlive is a cheap miss → tmux path.
+import {
+  deliverHosted,
+  hasAttachedSupervisorClient,
+  hostRunDir,
+  hostSessionAlive,
+  hostSessionToken,
+  HOST_COLS,
+  HOST_ROWS,
+} from '../launch/ptyHost.ts'
+import { sendControlToHost, type DeliverResult } from '../supervisor/deliver.ts'
+import { keysToBytes } from '../supervisor/protocol.ts' // pure send-keys-vocab→pty-byte translation (boot-driver slice a), @xterm-free
+import { paneLogComposerOccupied } from '../launch/readyGateModel.ts' // spawn-flip Ф0b-3 slice 3c: hosted busy-composer detector (slice 2). @xterm dynamic-loaded inside it → warm path stays @xterm-free with the flip off
 
 export interface OnlinePeer {
   personality: string
@@ -408,6 +425,17 @@ function livenessGraceMs(): number {
   return Number.isFinite(n) && n >= 0 ? n : 3000
 }
 
+// Host (spawn-flip Ф0b-2) liveness grace — DECOUPLED from the tmux grace by design. The hosted path
+// has no input-clear fast confirm (no capture-pane), so a transcript advance is its SOLE landed-proof
+// and may need its own calibration. `IAP_HOST_LIVENESS_GRACE_MS` tunes ONLY the hosted path; when
+// unset it falls back to the shared `livenessGraceMs()` — so calibrating hosted NEVER loosens the
+// tmux/fleet grace (a global bump there would be a fleet regression).
+function hostLivenessGraceMs(): number {
+  const raw = process.env.IAP_HOST_LIVENESS_GRACE_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : livenessGraceMs()
+}
+
 /**
  * Deliver `envelope` into the target's tmux session and CONFIRM it landed in a LIVE
  * session (Ф-B delivery guarantee, contract Демон §Гарантия доставки). `cwd` (the
@@ -472,6 +500,78 @@ export function deliverViaTmux(target: DeliveryTarget, envelope: string, cwd?: s
   return ok(undefined)
 }
 
+// ─── Host-aware warm delivery (spawn-flip cutover Block 2, Ф0b-2) ────────────────────────────────
+
+/** Test seam for `deliverWarm`. Production defaults route on the real supervisor; tests inject a
+ *  fake host-detect + host-deliver + a temp transcript proxy, so the host branch is covered with no
+ *  live daemon. Omitting all fields = pure production behaviour. */
+export interface WarmDeliverSeam {
+  /** Runtime-state host detector (NOT the `.pty-host` marker). Default: the real `hostSessionAlive`. */
+  hostAlive?: (identity: string) => boolean
+  /** Deliver to the hosted session over its socket. Default: the real `deliverHosted` (Ф0a leaf). */
+  deliverHosted?: (identity: string, envelope: string) => Promise<DeliverResult>
+  /** Activity proxy for the landed-confirm. Default: the target runtime adapter's transcript mtime. */
+  newestActivityMtime?: (cwd: string) => number | null
+}
+
+/**
+ * Warm-deliver `envelope` to a LIVE local target, HOST-AWARE. A supervisor-HOSTED target (spawn-flip
+ * Ф0b: detected by live runtime state, NOT the `.pty-host` marker) is delivered over its socket; any
+ * other target takes the unchanged `deliverViaTmux` path. The host branch CONFIRMS landing by the
+ * SAME final arbiter as the tmux busy path — a transcript-mtime advance past the pre-deliver baseline,
+ * NOT the socket-ack (a flushed CR proves the bytes left us, NOT that the session accepted them;
+ * trusting the ack would re-open the silent-loss class the contract forbids). Flag-off (no live
+ * supervisor session) → `hostAlive` is a cheap false → `deliverViaTmux` verbatim (byte-identical).
+ */
+export async function deliverWarm(
+  target: DeliveryTarget,
+  envelope: string,
+  cwd?: string,
+  seam: WarmDeliverSeam = {},
+): Promise<Result<void>> {
+  const hostAlive = seam.hostAlive ?? hostSessionAlive
+  if (!hostAlive(target.address)) return deliverViaTmux(target, envelope, cwd)
+  return deliverViaHost(target, envelope, cwd, seam)
+}
+
+async function deliverViaHost(
+  target: DeliveryTarget,
+  envelope: string,
+  cwd: string | undefined,
+  seam: WarmDeliverSeam,
+): Promise<Result<void>> {
+  const adapter = getAdapter(target.runtime)
+  const mtimeOf = seam.newestActivityMtime ?? ((c: string) => adapter.newestActivityMtime(c))
+  // Baseline the activity proxy BEFORE delivery (a paste/CR does not move the transcript — only a
+  // model turn does), so an advance afterwards proves the session is alive and took our message.
+  const baseline = cwd ? mtimeOf(cwd) ?? 0 : 0
+  const send = seam.deliverHosted ?? deliverHosted
+  const sent = await send(target.address, envelope)
+  if (!sent.ok) {
+    return err(
+      `hosted peer "${target.personality}" (${target.runtime}) deliver failed: ${sent.error ?? 'unknown error'}; ` +
+        `message NOT delivered`,
+    )
+  }
+  // socket-ack ≠ landed. With no activity proxy (direct callers/tests without a cwd) we can only
+  // trust the flushed submit — confirmed-only, mirroring deliverViaTmux's legacy-caller path.
+  if (!cwd) return ok(undefined)
+  // Confirm landing by the SAME final arbiter as the tmux busy path: a transcript-mtime advance.
+  // Grace-poll the proxy (the model may take a beat to write its turn); a hosted session has no
+  // input-clear fast path (no capture-pane), so this is the SOLE confirm. Prefer a false-FAIL
+  // (sender retries) over a false-OK (silent loss, forbidden).
+  const graceMs = hostLivenessGraceMs()
+  const graceDeadline = monotonicMs() + graceMs
+  do {
+    if ((mtimeOf(cwd) ?? 0) > baseline) return ok(undefined)
+    sleepSync(LIVENESS_POLL_MS)
+  } while (monotonicMs() < graceDeadline)
+  return err(
+    `hosted peer "${target.personality}" (${target.runtime}) is listed live but did not accept the message ` +
+      `(no transcript advance within ${graceMs}ms) — treated as dead; message NOT delivered`,
+  )
+}
+
 
 // ─── Compact done gate (dialogue control must report FACT, not keystroke delivery) ──
 
@@ -705,11 +805,36 @@ export function waitForCompactDone(
  * when normal delivery would not land). An unsupported command (router runtimes,
  * unknown name) → explicit refusal, not a silent no-op.
  */
-export function executeControlOnTarget(target: DeliveryTarget, command: ControlCommand): Result<void> {
+/** Test seam for the hosted control branch (spawn-flip Ф0b-2 slice 3): inject host-detect + the
+ *  socket control-send so the host path is covered without a live supervisor. Omitting all = prod. */
+export interface ControlHostSeam {
+  hostAlive?: (identity: string) => boolean
+  sendControl?: (runDir: string, session: string, chunks: Buffer[], opts: { stepDelayMs?: number }) => Promise<DeliverResult>
+}
+
+export async function executeControlOnTarget(
+  target: DeliveryTarget,
+  command: ControlCommand,
+  seam: ControlHostSeam = {},
+): Promise<Result<void>> {
   const plan = getAdapter(target.runtime).executeControl(command)
   if (!plan) {
     return err(`runtime "${target.runtime}" does not support control command "${command.name}"`)
   }
+  // SPAWN-FLIP Ф0b-2 slice 3: a supervisor-HOSTED target has no tmux send-keys — translate each plan
+  // step to pty bytes with keysToBytes (REUSED from the boot-driver, NOT reimplemented) and send them
+  // over the supervisor socket. Same UNCONDITIONAL semantics (no ready-gate, no submit-confirm) — the
+  // point of interrupt is to break a stuck turn. Flag-off (no live host) → the unchanged tmux path.
+  const hostAlive = seam.hostAlive ?? hostSessionAlive
+  if (hostAlive(target.address)) {
+    const chunks = plan.sequence.map(keys => keysToBytes(keys))
+    const send = seam.sendControl ?? sendControlToHost
+    const sent = await send(hostRunDir(), target.address, chunks, { stepDelayMs: plan.stepDelayMs })
+    if (!sent.ok) {
+      return err(`hosted control "${command.name}" failed for "${target.personality}" (${target.runtime}): ${sent.error ?? 'unknown error'}`)
+    }
+    return ok(undefined)
+  }
   for (const keys of plan.sequence) {
     const r = tmux(target.socketPath, 'send-keys', '-t', target.address, ...keys)
     if (!r.ok) return err(`tmux send-keys failed for control "${command.name}": ${r.err.trim() || 'unknown error'}`)
@@ -732,14 +857,14 @@ export interface ControlResult {
  * "specify runtime"). The clean-slash control namespace (interrupt/compact/…) is the
  * caller's; /alias-* expansions are message, not control (docs/Control §namespace).
  */
-export function routeControl(personality: string, runtime: string | undefined, command: ControlCommand): Result<ControlResult> {
+export async function routeControl(personality: string, runtime: string | undefined, command: ControlCommand): Promise<Result<ControlResult>> {
   if (!isValidName(personality)) {
     return err(`invalid personality "${personality}" — must match /^[a-z][a-z0-9-]{0,31}$/`)
   }
   if (runtime && !isRuntime(runtime)) return err(`invalid runtime "${runtime}"`)
   const target = resolveDeliveryTarget({ personality, runtime })
   if (!target.ok) return err(`cannot control "${personality}": ${target.error.message}`)
-  const done = executeControlOnTarget(target.value, command)
+  const done = await executeControlOnTarget(target.value, command)
   if (!done.ok) return done
   return ok({
     ok: true,
@@ -893,19 +1018,25 @@ export interface ComposerDeliveryQueueOptions {
   env?: NodeJS.ProcessEnv
   pollMs?: number
   forceTimeoutMs?: number
-  /** Test seam / alternate detector. Production default is the full gate:
-   *  local TUI runtime + attached tmux client + non-dim composer text. */
-  shouldQueue?: (args: ComposerQueueTryEnqueueArgs) => boolean
-  /** Test seam for the drain phase. Production default re-reads the pane color
-   *  state (WITHOUT the attached-client prerequisite): once queued, abandoned
-   *  human text waits until cleared or until the 120s force ceiling. */
-  hasHumanInput?: (target: DeliveryTarget) => boolean
-  /** Test seam; production default compares tmux session/pane identity captured
-   *  at enqueue time, so `/new`/death/restart fails the old queued envelope rather
-   *  than delivering it into a fresh session with the same name. */
+  /** Daemon pane-log dir (spawn-flip Ф0b-3 slice 3c) — needed by the HOSTED occupancy default to read
+   *  `<logDir>/<identity>.log`. Absent → hosted targets never hold (safe: deliver rather than stall). */
+  logDir?: string
+  /** Test seam / alternate detector. Production default is the full gate — tmux: local TUI + attached
+   *  tmux client + non-dim composer text; HOSTED (spawn-flip): local TUI + attached SUPERVISOR client +
+   *  model-occupied composer. May be async (the hosted occupancy reads an @xterm model). */
+  shouldQueue?: (args: ComposerQueueTryEnqueueArgs) => boolean | Promise<boolean>
+  /** Test seam for the drain phase. Production default re-reads the composer occupancy (WITHOUT the
+   *  attached-client prerequisite): once queued, abandoned human text waits until cleared or the 120s
+   *  ceiling. tmux → capture-pane colour; HOSTED → pane-log model. May be async. */
+  hasHumanInput?: (target: DeliveryTarget) => boolean | Promise<boolean>
+  /** Test seam; production default compares the session-replacement token captured at enqueue time, so
+   *  `/new`/death/restart fails the old queued envelope rather than delivering it into a fresh same-named
+   *  session — tmux: session_id:pane_id; HOSTED: the supervisor daemon pid. */
   sessionToken?: (target: DeliveryTarget) => string | null
   sessionAlive?: (job: ComposerQueuedDelivery) => boolean
-  deliver?: (target: DeliveryTarget, envelope: string, cwd?: string) => Result<void>
+  /** Delivery sink. Production default is the HOST-AWARE deliverWarm (tmux target → deliverViaTmux
+   *  verbatim, hosted target → the supervisor socket). May be async. */
+  deliver?: (target: DeliveryTarget, envelope: string, cwd?: string) => Result<void> | Promise<Result<void>>
   notifyFailed: (job: ComposerQueuedDelivery, reason: string) => void | Promise<void>
   noteLiveTopic?: (identity: string, topic: string) => void
   onDelivered?: (caller: ResolvedCaller) => void
@@ -933,8 +1064,36 @@ function targetSessionToken(target: DeliveryTarget): string | null {
   return r.out.trim() || null
 }
 
+// ── Host-aware composer-queue predicates (spawn-flip Ф0b-3 slice 3c) ─────────────────────────────────
+// Each dispatches on hostSessionAlive(address): a HOSTED target uses the supervisor signals, any other
+// target falls through to the UNCHANGED tmux predicate (so the tmux fleet's observable queue behavior
+// is byte-identical — only the call becomes awaitable).
+
+/** Enqueue gate. HOSTED: hold ONLY when a HUMAN is attached (supervisor client) AND the composer model
+ *  is occupied — the slice-2 anti-bug: with no operator attached the composer text is the AI's own
+ *  output, never held. tmux: the unchanged shouldQueueForHumanComposer. */
+async function shouldQueueForComposer(target: DeliveryTarget, logDir: string | undefined): Promise<boolean> {
+  if (!hostSessionAlive(target.address)) return shouldQueueForHumanComposer(target)
+  if (!isSupportedLocalRuntime(target.runtime) || !hasAttachedSupervisorClient(target.address)) return false
+  if (!logDir) return false // no pane-log dir → cannot read occupancy → don't hold (deliver, never stall)
+  return paneLogComposerOccupied(`${logDir}/${target.address}.log`, HOST_COLS, HOST_ROWS, target.runtime)
+}
+
+/** Drain re-check (no attached-client prereq — once queued, abandoned input waits until cleared/ceiling).
+ *  HOSTED: pane-log model occupancy. tmux: the unchanged targetComposerBlocksDelivery. */
+async function composerStillBusy(target: DeliveryTarget, logDir: string | undefined): Promise<boolean> {
+  if (!hostSessionAlive(target.address)) return targetComposerBlocksDelivery(target)
+  if (!logDir) return false
+  return paneLogComposerOccupied(`${logDir}/${target.address}.log`, HOST_COLS, HOST_ROWS, target.runtime)
+}
+
+/** Session-replacement token. HOSTED: supervisor daemon pid; tmux: session_id:pane_id. */
+function composerSessionToken(target: DeliveryTarget): string | null {
+  return hostSessionAlive(target.address) ? hostSessionToken(target.address) : targetSessionToken(target)
+}
+
 function queuedTargetStillSameSession(job: ComposerQueuedDelivery): boolean {
-  return targetSessionToken(job.target) === job.sessionToken
+  return composerSessionToken(job.target) === job.sessionToken
 }
 
 let nextComposerQueueId = 1
@@ -957,11 +1116,12 @@ export function createComposerDeliveryQueue(opts: ComposerDeliveryQueueOptions):
   const env = opts.env ?? process.env
   const pollMs = opts.pollMs ?? composerQueuePollMs(env)
   const forceTimeoutMs = opts.forceTimeoutMs ?? composerQueueForceTimeoutMs(env)
-  const shouldQueue = opts.shouldQueue ?? ((args: ComposerQueueTryEnqueueArgs) => shouldQueueForHumanComposer(args.target))
-  const hasHumanInput = opts.hasHumanInput ?? targetComposerBlocksDelivery
-  const sessionToken = opts.sessionToken ?? targetSessionToken
+  const logDir = opts.logDir
+  const shouldQueue = opts.shouldQueue ?? ((args: ComposerQueueTryEnqueueArgs) => shouldQueueForComposer(args.target, logDir))
+  const hasHumanInput = opts.hasHumanInput ?? ((target: DeliveryTarget) => composerStillBusy(target, logDir))
+  const sessionToken = opts.sessionToken ?? composerSessionToken
   const sessionAliveFn = opts.sessionAlive ?? queuedTargetStillSameSession
-  const deliver = opts.deliver ?? deliverViaTmux
+  const deliver = opts.deliver ?? deliverWarm
   const queues = new Map<string, ComposerQueuedDelivery[]>()
   const draining = new Set<string>()
   let closed = false
@@ -997,12 +1157,12 @@ export function createComposerDeliveryQueue(opts: ComposerDeliveryQueueOptions):
 
       const ageMs = monotonicMs() - job.enqueuedAtMs
       const force = ageMs >= forceTimeoutMs
-      if (!force && hasHumanInput(job.target)) {
+      if (!force && (await hasHumanInput(job.target))) {
         await delay(pollMs)
         continue
       }
 
-      const delivered = deliver(job.target, job.envelope, job.peer.cwd)
+      const delivered = await deliver(job.target, job.envelope, job.peer.cwd)
       q.shift()
       if (!delivered.ok) {
         await notifyFailed(job, `queued delivery to ${job.target.personality} (${job.target.runtime}) failed: ${delivered.error.message}`)
@@ -1020,7 +1180,7 @@ export function createComposerDeliveryQueue(opts: ComposerDeliveryQueueOptions):
   return {
     tryEnqueue: async args => {
       if (closed) return err('composer delivery queue is closing; message NOT queued')
-      if (!shouldQueue(args)) return null
+      if (!(await shouldQueue(args))) return null
       const token = sessionToken(args.target)
       if (!token) {
         return err(
@@ -1202,7 +1362,9 @@ export async function routeSend(
     const queued = await deps.composerQueue?.tryEnqueue({ caller, peer, target: target.value, envelope, topic })
     if (queued) return queued
     // peer.cwd enables the Ф-B transcript-mtime liveness probe (busy-session case).
-    const delivered = deliverViaTmux(target.value, envelope, peer.cwd)
+    // deliverWarm is HOST-AWARE (spawn-flip Ф0b-2): a supervisor-hosted target delivers over its
+    // socket, any other target keeps the tmux path. Flag-off → byte-identical to deliverViaTmux.
+    const delivered = await deliverWarm(target.value, envelope, peer.cwd)
     if (!delivered.ok) return delivered
     noteTopic(deps, target.value.address, topic)
     return ok({
@@ -1243,7 +1405,7 @@ export async function routeSend(
   if (woke.taskDelivered === false) {
     const queued = await deps.composerQueue?.tryEnqueue({ caller, peer, target: live.value, envelope, topic })
     if (queued) return queued
-    const delivered = deliverViaTmux(live.value, envelope, peer.cwd)
+    const delivered = await deliverWarm(live.value, envelope, peer.cwd)
     if (!delivered.ok) return delivered
     noteTopic(deps, live.value.address, topic)
     return ok({