@agfpd/iapeer 0.2.52 → 0.2.53

package/package.json

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

package/src/cli/index.ts

@@ -838,6 +838,7 @@ export async function sendMessage(
     via: result.ok ? `${result.value.delivered_to.runtime}-${result.value.delivered_to.personality}` : undefined,
     woke: result.ok ? String(result.value.woke) : undefined,
     queued: result.ok && result.value.queued ? 'true' : undefined,
+    qkind: result.ok ? result.value.queuedBy : undefined,
     qd: result.ok ? result.value.queueDepth : undefined,
     ms: Date.now() - t0,
     len: opts.message.length,

package/src/daemon/daemon.test.ts

@@ -197,6 +197,7 @@ describe('ephemeral serial-queue seam (M3)', () => {
                 delivered_to: { personality: peer.personality, runtime: 'claude' },
                 woke: false,
                 queued: true,
+                queuedBy: 'ephemeral',
                 queueDepth: 2,
                 ts: 'now',
               },
@@ -209,6 +210,7 @@ describe('ephemeral serial-queue seam (M3)', () => {
     expect(delivered).toEqual(['checked:/tmp/offlinepeer', 'deliver:offlinepeer:job-1'])
     const line = readFileSync(join(logDir, 'delivery.log'), 'utf8').trim()
     expect(line).toContain('queued=true')
+    expect(line).toContain('qkind=ephemeral')
     expect(line).toContain('qd=2')
     expect(line).toContain('ok=true')
   })

package/src/daemon/index.ts

@@ -43,7 +43,7 @@ import { IapError } from '../core/errors.ts'
 import { pluginStateDir, writeFileAtomic, type StorageOptions } from '../storage/index.ts'
 import { publicPeerSummary, readPeersIndex, type PeersIndex } from '../registry/index.ts'
 import { resolveCallerIdentity, type CallerIdentity, type ResolvedCaller } from '../identity/index.ts'
-import { routeSend, type EphemeralRouteDeps, type SendToPeerInput, type WakeFn } from '../transport/index.ts'
+import { routeSend, type ComposerQueueRouteDeps, type EphemeralRouteDeps, type SendToPeerInput, type WakeFn } from '../transport/index.ts'
 import { appendDeliveryEvent } from './deliverylog.ts'
 
 export const CALLER_HEADER = 'x-iapeer-identity'
@@ -192,6 +192,8 @@ export interface CallToolDeps {
    *  see transport.RouteDeps.noteLiveTopic. Injected so the daemon never imports
    *  lifecycle; the production main wires makeNoteLiveTopic. */
   noteLiveTopic?: (identity: string, topic: string) => void
+  /** Busy-human-composer queue — see transport.createComposerDeliveryQueue. */
+  composerQueue?: ComposerQueueRouteDeps
 }
 
 export async function callTool(
@@ -209,7 +211,12 @@ export async function callTool(
       attachments: Array.isArray(args.attachments) ? (args.attachments as string[]) : undefined,
     }
     const t0 = Date.now()
-    const sent = await routeSend(caller, input, { wake: deps.wake, ephemeral: deps.ephemeral, noteLiveTopic: deps.noteLiveTopic })
+    const sent = await routeSend(caller, input, {
+      wake: deps.wake,
+      ephemeral: deps.ephemeral,
+      noteLiveTopic: deps.noteLiveTopic,
+      composerQueue: deps.composerQueue,
+    })
     // Ф-#8a: ONE durable outcome line per delivery attempt (delivery.log, sibling
     // to lifecycle.log) — metadata only, never the body. Both branches of the
     // routeSend result are recorded, so a suspected loss is reconstructable from
@@ -226,6 +233,7 @@ export async function callTool(
       // M3 queue observability (boris acceptance (a)): a queued accept is marked
       // and carries the queue depth at accept time — a stuck queue is visible.
       queued: sent.ok && sent.value.queued ? 'true' : undefined,
+      qkind: sent.ok ? sent.value.queuedBy : undefined,
       qd: sent.ok ? sent.value.queueDepth : undefined,
       ms: Date.now() - t0,
       len: input.message.length,
@@ -237,7 +245,7 @@ export async function callTool(
     // reply is NOT out, and arming then could quiet-reap a worker mid-retry (the
     // ordinary idle bound covers that case instead). Fail-safe: hook errors are
     // swallowed, the delivery result stands.
-    if (sent.ok) {
+    if (sent.ok && sent.value.queuedBy !== 'composer') {
       try {
         deps.onDelivered?.(caller)
       } catch {
@@ -377,6 +385,13 @@ export interface StartDaemonOptions extends StorageOptions {
    * main wires the lifecycle marker write (makeNoteLiveTopic).
    */
   noteLiveTopic?: (identity: string, topic: string) => void
+  /**
+   * Busy-human-composer queue — async acceptance for live local TUI delivery when
+   * an attached operator has non-dim text in the target composer. OFF by default
+   * for library/tests; production main wires an in-memory queue that fail-notifies
+   * senders on shutdown/restart.
+   */
+  composerQueue?: ComposerQueueRouteDeps
   /**
    * Write the discovery file (router.json) at <root>/state/iapeer/router.json with
    * the active addresses `{sock, tcp}` — atomically on listen, removed on close.
@@ -410,6 +425,7 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
       onDelivered: opts.onDelivered,
       ephemeral: opts.ephemeral,
       noteLiveTopic: opts.noteLiveTopic,
+      composerQueue: opts.composerQueue,
     })
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
     res.on('close', () => {
@@ -507,8 +523,9 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
     host: tcpEnabled ? host : undefined,
     port,
     url,
-    close: () =>
-      new Promise<void>(resolve => {
+    close: async () => {
+      await opts.composerQueue?.failAll?.('daemon shutting down/restarting before queued delivery completed')
+      await new Promise<void>(resolve => {
         if (supervisor) clearInterval(supervisor)
         for (const s of servers) s.closeAllConnections?.() // drop lingering keep-alive/SSE conns
         let pending = servers.length
@@ -525,6 +542,7 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
             }
           })
         }
-      }),
+      })
+    },
   }
 }

package/src/daemon/main.test.ts

@@ -232,6 +232,24 @@ describe('dual-listen + router.json discovery', () => {
   })
 })
 
+describe('startDaemon composerQueue shutdown seam', () => {
+  test('close() fails pending busy-composer queue before tearing listeners down', async () => {
+    const reasons: string[] = []
+    const h = await startDaemon({
+      port: 0,
+      host: '127.0.0.1',
+      composerQueue: {
+        tryEnqueue: async () => null,
+        failAll: async reason => {
+          reasons.push(reason)
+        },
+      },
+    })
+    await h.close()
+    expect(reasons).toEqual(['daemon shutting down/restarting before queued delivery completed'])
+  })
+})
+
 // ─────────────────────────────────────────────────────────────────────────────
 // wake_policy:ephemeral M2 — makeArmEphemeralOnDelivered (the arm-on-outbound
 // composition: ephemeral caller's ok send ⇒ .ephemeral-armed for its identity)
@@ -307,6 +325,7 @@ describe('makeEphemeralRouteDeps (M3 serial-queue composition)', () => {
     const r2 = await deps.deliver({ peer: workerPeer, envelope: '<iap>task two</iap>' })
 
     expect(r1.ok && r1.value.queued).toBe(true)
+    expect(r1.ok && r1.value.queuedBy).toBe('ephemeral')
     expect(r1.ok && r1.value.queueDepth).toBe(1)
     expect(r1.ok && r1.value.woke).toBe(false)
     expect(r2.ok && r2.value.queueDepth).toBe(2)

package/src/daemon/main.ts

@@ -46,9 +46,21 @@ import {
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { buildProcessAddress } from '../core/socket.ts'
 import { err, ok } from '../core/errors.ts'
+import { resolveCallerIdentity } from '../identity/index.ts'
 import type { ResolvedCaller } from '../identity/index.ts'
-import type { EphemeralRouteDeps, WakeFn, WakeOutcome, WakeRequest } from '../transport/index.ts'
+import { findPeer, readPeersIndex } from '../registry/index.ts'
+import {
+  createComposerDeliveryQueue,
+  routeSend,
+  type ComposerQueueRouteDeps,
+  type ComposerQueuedDelivery,
+  type EphemeralRouteDeps,
+  type WakeFn,
+  type WakeOutcome,
+  type WakeRequest,
+} from '../transport/index.ts'
 import { iapeerBinPath } from '../install/index.ts'
+import { appendDeliveryEvent } from './deliverylog.ts'
 import { defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
 
 /** Default TCP loopback port for the always-on router. Real http MCP clients
@@ -168,6 +180,7 @@ export function makeEphemeralRouteDeps(
         delivered_to: { personality: peer.personality, runtime: rt.value },
         woke: false,
         queued: true,
+        queuedBy: 'ephemeral',
         queueDepth: depth,
         ts: new Date().toISOString(),
       })
@@ -175,6 +188,80 @@ export function makeEphemeralRouteDeps(
   }
 }
 
+function queuedFailureMessage(job: ComposerQueuedDelivery, reason: string): string {
+  const topic = job.topic ? ` topic="${job.topic}"` : ''
+  return (
+    `delivery failed: queued message to ${job.target.personality} (${job.target.runtime})${topic} was not delivered.\n` +
+    `reason: ${reason}\n` +
+    'The original send was accepted as queued because a human operator was typing in the target composer; retry if still needed.'
+  )
+}
+
+/**
+ * Busy-human-composer queue composition. This is deliberately daemon-owned and
+ * in-memory: it exists only to bridge a short operator-editing window. Because a
+ * queued ack is not a delivery fact, the queue has two extra responsibilities:
+ *   1) after actual drain success, run the same post-delivery hooks as the
+ *      synchronous path (topic marker + ephemeral caller arm);
+ *   2) before daemon shutdown/restart, fail every pending queued envelope back
+ *      to its sender, so `queued` never becomes silent loss.
+ */
+export function makeComposerQueueRouteDeps(cfg: LifecycleConfig, env: NodeJS.ProcessEnv): ComposerQueueRouteDeps {
+  const noteLiveTopic = makeNoteLiveTopic(cfg, env)
+  const onDelivered = makeArmEphemeralOnDelivered(cfg)
+  const wake = makeWakeFn(cfg, env)
+  const ephemeral = makeEphemeralRouteDeps(cfg, env)
+
+  return createComposerDeliveryQueue({
+    env,
+    noteLiveTopic,
+    onDelivered,
+    notifyFailed: async (job, reason) => {
+      const index = readPeersIndex({ env })
+      const self = findPeer(index, 'iapeer')
+      if (!self) {
+        appendDeliveryEvent(cfg.eventLogDir, {
+          ev: 'composer-queue-failed-notify',
+          caller: 'iapeer',
+          to: job.caller.personality,
+          rt: job.caller.runtime,
+          ok: 'false',
+          err: 'foundation peer "iapeer" is not registered; cannot notify queued sender',
+        })
+        return
+      }
+      const sender = resolveCallerIdentity({ personality: 'iapeer', runtime: self.runtime }, index)
+      const result = await routeSend(
+        sender,
+        {
+          personality: job.caller.personality,
+          runtime: job.caller.runtime,
+          message: queuedFailureMessage(job, reason),
+          topic: job.topic ?? 'delivery-failed',
+        },
+        // Do not pass composerQueue here: this path is the queue's failure outlet
+        // (including SIGTERM/update). Recursively queueing a failure notification
+        // could turn shutdown re-fail into another queued item.
+        { wake, ephemeral, noteLiveTopic },
+      )
+      appendDeliveryEvent(cfg.eventLogDir, {
+        ev: 'composer-queue-failed-notify',
+        caller: sender.address,
+        to: job.caller.personality,
+        rt: job.caller.runtime,
+        ok: String(result.ok),
+        via: result.ok ? `${result.value.delivered_to.runtime}-${result.value.delivered_to.personality}` : undefined,
+        woke: result.ok ? String(result.value.woke) : undefined,
+        queued: result.ok && result.value.queued ? 'true' : undefined,
+        qkind: result.ok ? result.value.queuedBy : undefined,
+        qd: result.ok ? result.value.queueDepth : undefined,
+        topic: job.topic ?? 'delivery-failed',
+        err: result.ok ? undefined : result.error.message,
+      })
+    },
+  })
+}
+
 export interface ConfiguredDaemonOptions {
   /** TCP loopback port (default DEFAULT_DAEMON_PORT). */
   port?: number
@@ -202,18 +289,25 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
   const env = opts.env ?? process.env
   const cfg = loadLifecycleConfig(env)
   const bearerToken = opts.bearerToken ?? (env.IAPEER_BEARER_TOKEN?.trim() || undefined)
+  const noteLiveTopic = makeNoteLiveTopic(cfg, env)
+  const armEphemeralOnDelivered = makeArmEphemeralOnDelivered(cfg)
+  const ephemeral = makeEphemeralRouteDeps(cfg, env)
+  const composerQueue = makeComposerQueueRouteDeps(cfg, env)
   return startDaemon({
     wake: makeWakeFn(cfg, env),
     // M2 arm-on-outbound (see makeArmEphemeralOnDelivered): ephemeral caller's ok
     // send ⇒ armed for the supervise quiet-reap. No-op for every other caller.
-    onDelivered: makeArmEphemeralOnDelivered(cfg),
+    onDelivered: armEphemeralOnDelivered,
     // M3 serial queue (see makeEphemeralRouteDeps): ephemeral TARGET ⇒ enqueue +
     // async drain. No-op for every other target.
-    ephemeral: makeEphemeralRouteDeps(cfg, env),
+    ephemeral,
     // Live-delivered topic → the target's .topic marker (see makeNoteLiveTopic):
     // the wake resolver's executor discriminator then compares against the topic
     // the session last WORKED ON, not the one it woke with (defect 11.06).
-    noteLiveTopic: makeNoteLiveTopic(cfg, env),
+    noteLiveTopic,
+    // Busy-human-composer queue: fast queued ack, async drain, fail all pending
+    // on daemon close/update so a queued envelope is never silently lost.
+    composerQueue,
     supervise: {
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
       // idle-reap / zombie-sweep, THEN the eager fresh re-launch for any peer whose

package/src/launch/adapters/claude.ts

@@ -103,6 +103,7 @@ export const claudeAdapter: RuntimeAdapter = {
   deliveryMarkers: {
     promptGlyphs: ['❯'],
     pastePatterns: [/\[Pasted text/, /\[Image #/],
+    ghostTextSgr: ['2', '38;5;246'],
   },
 
   /**

package/src/launch/adapters/codex.ts

@@ -167,6 +167,7 @@ export const codexAdapter: RuntimeAdapter = {
   deliveryMarkers: {
     promptGlyphs: ['›'],
     pastePatterns: [/\[Pasted text/, /\[Image #/],
+    ghostTextSgr: ['2', '38;5;246'],
   },
 
   /**

package/src/launch/launch.test.ts

@@ -304,10 +304,12 @@ describe('deliveryMarkers (adapter-owned, was transport PROMPT_GLYPHS)', () => {
   test('claude: ❯ glyph + paste patterns', () => {
     expect(claudeAdapter.deliveryMarkers.promptGlyphs).toEqual(['❯'])
     expect(claudeAdapter.deliveryMarkers.pastePatterns?.some(re => re.test('[Pasted text +5 lines]'))).toBe(true)
+    expect(claudeAdapter.deliveryMarkers.ghostTextSgr).toEqual(['2', '38;5;246'])
   })
   test('codex: › glyph (not ❯) — per-runtime, no false cross-match', () => {
     expect(codexAdapter.deliveryMarkers.promptGlyphs).toEqual(['›'])
     expect(codexAdapter.deliveryMarkers.promptGlyphs).not.toContain('❯')
+    expect(codexAdapter.deliveryMarkers.ghostTextSgr).toEqual(['2', '38;5;246'])
   })
   test('routers have no submit surface → empty glyphs', () => {
     expect(telegramAdapter.deliveryMarkers.promptGlyphs).toEqual([])

package/src/launch/types.ts

@@ -180,6 +180,14 @@ export interface DeliveryMarkers {
    *  (claude '[Pasted text' / '[Image #'). Optional — when absent the tail-marker is
    *  the sole landed-signal. */
   pastePatterns?: RegExp[]
+  /** SGR parameter sequences that the runtime uses for composer ghost/placeholder
+   *  text (non-human input). The busy-composer delivery queue captures the pane
+   *  with ANSI escapes and treats visible text after the prompt glyph as HUMAN only
+   *  when at least one non-whitespace character is NOT under these dim/grey SGR
+   *  attributes. Runtime-owned for the same reason as promptGlyphs: color is TUI
+   *  surface, not transport policy. Examples observed on live panes:
+   *  `2` (faint/dim) and `38;5;246` (xterm 256-color grey). */
+  ghostTextSgr?: string[]
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/transport/composerQueue.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from 'bun:test'
+import { ok } from '../core/errors.ts'
+import { getAdapter } from '../launch/index.ts'
+import type { PeerRecord } from '../registry/index.ts'
+import type { ResolvedCaller } from '../identity/index.ts'
+import {
+  composerCaptureHasHumanInput,
+  createComposerDeliveryQueue,
+  type ComposerQueueTryEnqueueArgs,
+  type DeliveryTarget,
+} from './index.ts'
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+describe('composerCaptureHasHumanInput (SGR color gate)', () => {
+  test('codex: default-fg text after › is human input; faint/grey ghost text is not', () => {
+    const markers = getAdapter('codex').deliveryMarkers
+    expect(composerCaptureHasHumanInput('\x1b[32m›\x1b[0m hello', markers)).toBe(true)
+    expect(composerCaptureHasHumanInput('\x1b[32m›\x1b[0m \x1b[2mghost suggestion\x1b[0m', markers)).toBe(false)
+    expect(composerCaptureHasHumanInput('\x1b[32m›\x1b[0m \x1b[38;5;246mplaceholder\x1b[0m', markers)).toBe(false)
+    // A suggestion accepted into the composer is no longer grey/faint; it must be held.
+    expect(composerCaptureHasHumanInput('\x1b[32m›\x1b[0m accepted suggestion', markers)).toBe(true)
+  })
+
+  test('claude: same color rule is runtime-owned behind the ❯ prompt glyph', () => {
+    const markers = getAdapter('claude').deliveryMarkers
+    expect(composerCaptureHasHumanInput('\x1b[35m❯\x1b[0m human', markers)).toBe(true)
+    expect(composerCaptureHasHumanInput('\x1b[35m❯\x1b[0m \x1b[2mghost\x1b[0m', markers)).toBe(false)
+    expect(composerCaptureHasHumanInput('\x1b[35m❯\x1b[0m \x1b[38;5;246mplaceholder\x1b[0m', markers)).toBe(false)
+  })
+})
+
+const callerRecord = {
+  personality: 'sender',
+  runtime: 'codex',
+  runtimes: ['codex'],
+  description: '',
+  intelligence: 'artificial',
+  cwd: '/tmp/sender',
+} as unknown as PeerRecord
+const caller: ResolvedCaller = {
+  personality: 'sender',
+  runtime: 'codex',
+  address: 'codex-sender',
+  description: '',
+  intelligence: 'artificial',
+  cwd: '/tmp/sender',
+  record: callerRecord,
+}
+const peer = {
+  personality: 'target',
+  runtime: 'codex',
+  runtimes: ['codex'],
+  description: '',
+  intelligence: 'artificial',
+  cwd: '/tmp/target',
+} as unknown as PeerRecord
+const target: DeliveryTarget = {
+  personality: 'target',
+  runtime: 'codex',
+  address: 'codex-target',
+  socketPath: '/tmp/no-such-sock',
+}
+function args(envelope = '<iap>hello</iap>'): ComposerQueueTryEnqueueArgs {
+  return { caller, peer, target, envelope, topic: 'q-test' }
+}
+
+describe('createComposerDeliveryQueue', () => {
+  test('queued ack is immediate; drain waits until composer clears, then delivers silently', async () => {
+    let held = true
+    const delivered: string[] = []
+    const failed: string[] = []
+    const q = createComposerDeliveryQueue({
+      pollMs: 5,
+      forceTimeoutMs: 1000,
+      shouldQueue: () => true,
+      hasHumanInput: () => held,
+      sessionToken: () => 'session-1:pane-1',
+      sessionAlive: () => true,
+      deliver: (_target, envelope) => {
+        delivered.push(envelope)
+        return ok(undefined)
+      },
+      notifyFailed: (_job, reason) => { failed.push(reason) },
+    })
+
+    const accepted = await q.tryEnqueue(args('first'))
+    expect(accepted?.ok).toBe(true)
+    if (!accepted?.ok) return
+    expect(accepted.value).toMatchObject({ queued: true, queuedBy: 'composer', queueDepth: 1 })
+    await sleep(20)
+    expect(delivered).toEqual([])
+    held = false
+    await sleep(30)
+    expect(delivered).toEqual(['first'])
+    expect(failed).toEqual([])
+  })
+
+  test('120s ceiling (env-tunable in tests) force-delivers instead of waiting forever', async () => {
+    const delivered: string[] = []
+    const failed: string[] = []
+    const q = createComposerDeliveryQueue({
+      pollMs: 5,
+      forceTimeoutMs: 20,
+      shouldQueue: () => true,
+      hasHumanInput: () => true,
+      sessionToken: () => 'session-1:pane-1',
+      sessionAlive: () => true,
+      deliver: (_target, envelope) => {
+        delivered.push(envelope)
+        return ok(undefined)
+      },
+      notifyFailed: (_job, reason) => { failed.push(reason) },
+    })
+
+    await q.tryEnqueue(args('force-me'))
+    await sleep(70)
+    expect(delivered).toEqual(['force-me'])
+    expect(failed).toEqual([])
+  })
+
+  test('target death/session replacement fails the queued sender instead of delivering to a corpse/new session', async () => {
+    let alive = true
+    const delivered: string[] = []
+    const failed: string[] = []
+    const q = createComposerDeliveryQueue({
+      pollMs: 5,
+      forceTimeoutMs: 1000,
+      shouldQueue: () => true,
+      hasHumanInput: () => true,
+      sessionToken: () => 'session-1:pane-1',
+      sessionAlive: () => alive,
+      deliver: (_target, envelope) => {
+        delivered.push(envelope)
+        return ok(undefined)
+      },
+      notifyFailed: (_job, reason) => { failed.push(reason) },
+    })
+
+    await q.tryEnqueue(args('must-fail'))
+    alive = false
+    await sleep(30)
+    expect(delivered).toEqual([])
+    expect(failed.join('\n')).toMatch(/vanished|replaced/)
+  })
+
+  test('daemon close/restart failAll re-fails every queued-but-undelivered envelope', async () => {
+    const delivered: string[] = []
+    const failed: string[] = []
+    const q = createComposerDeliveryQueue({
+      pollMs: 50,
+      forceTimeoutMs: 1000,
+      shouldQueue: () => true,
+      hasHumanInput: () => true,
+      sessionToken: () => 'session-1:pane-1',
+      sessionAlive: () => true,
+      deliver: (_target, envelope) => {
+        delivered.push(envelope)
+        return ok(undefined)
+      },
+      notifyFailed: (_job, reason) => { failed.push(reason) },
+    })
+
+    await q.tryEnqueue(args('queued-a'))
+    await q.tryEnqueue(args('queued-b'))
+    await q.failAll?.('daemon shutting down/restarting before queued delivery completed')
+    await sleep(10)
+    expect(delivered).toEqual([])
+    expect(failed).toEqual([
+      'daemon shutting down/restarting before queued delivery completed',
+      'daemon shutting down/restarting before queued delivery completed',
+    ])
+  })
+})

package/src/transport/index.ts

@@ -99,6 +99,168 @@ function sessionAlive(sock: string, address: string): boolean {
   return listSessions(sock).includes(address)
 }
 
+// ─── Busy-composer detection (human input vs runtime ghost text) ─────────────
+
+interface SgrState {
+  faint: boolean
+  fg256: number | null
+  fgBasic: number | null
+}
+
+interface GhostSgrConfig {
+  faint: boolean
+  fg256: Set<number>
+  fgBasic: Set<number>
+}
+
+interface PaneToken {
+  ch: string
+  ghost: boolean
+}
+
+function parseSgrCodeList(raw: string): number[] | null {
+  if (raw.trim() === '') return [0]
+  const out = raw.split(';').map(part => (part === '' ? 0 : Number(part)))
+  return out.every(Number.isFinite) ? out : null
+}
+
+function ghostSgrConfig(markers: DeliveryMarkers): GhostSgrConfig {
+  const cfg: GhostSgrConfig = { faint: false, fg256: new Set(), fgBasic: new Set() }
+  for (const raw of markers.ghostTextSgr ?? []) {
+    const codes = parseSgrCodeList(raw)
+    if (!codes) continue
+    if (codes.length === 1 && codes[0] === 2) {
+      cfg.faint = true
+      continue
+    }
+    if (codes.length === 1 && ((codes[0] >= 30 && codes[0] <= 37) || (codes[0] >= 90 && codes[0] <= 97))) {
+      cfg.fgBasic.add(codes[0])
+      continue
+    }
+    if (codes.length === 3 && codes[0] === 38 && codes[1] === 5) cfg.fg256.add(codes[2])
+  }
+  return cfg
+}
+
+function applySgr(state: SgrState, codes: number[]): void {
+  let i = 0
+  while (i < codes.length) {
+    const code = codes[i]
+    if (code === 0) {
+      state.faint = false
+      state.fg256 = null
+      state.fgBasic = null
+    } else if (code === 2) {
+      state.faint = true
+    } else if (code === 22) {
+      state.faint = false
+    } else if (code === 39) {
+      state.fg256 = null
+      state.fgBasic = null
+    } else if ((code >= 30 && code <= 37) || (code >= 90 && code <= 97)) {
+      state.fgBasic = code
+      state.fg256 = null
+    } else if (code === 38 && codes[i + 1] === 5 && Number.isFinite(codes[i + 2])) {
+      state.fg256 = codes[i + 2]
+      state.fgBasic = null
+      i += 2
+    } else if (code === 38 && codes[i + 1] === 2) {
+      // Truecolor foreground: not one of the calibrated grey-256 markers. Track
+      // it as "not ghost" by clearing the 256/basic foreground slots.
+      state.fg256 = null
+      state.fgBasic = null
+      i += 4
+    }
+    i += 1
+  }
+}
+
+function stateIsGhost(state: SgrState, cfg: GhostSgrConfig): boolean {
+  if (cfg.faint && state.faint) return true
+  if (state.fg256 !== null && cfg.fg256.has(state.fg256)) return true
+  if (state.fgBasic !== null && cfg.fgBasic.has(state.fgBasic)) return true
+  return false
+}
+
+function parseAnsiLine(line: string, cfg: GhostSgrConfig): PaneToken[] {
+  const tokens: PaneToken[] = []
+  const state: SgrState = { faint: false, fg256: null, fgBasic: null }
+  let i = 0
+  while (i < line.length) {
+    if (line.charCodeAt(i) === 0x1b && line[i + 1] === '[') {
+      let end = i + 2
+      while (end < line.length && !/[A-Za-z]/.test(line[end])) end += 1
+      if (end < line.length) {
+        if (line[end] === 'm') {
+          const codes = parseSgrCodeList(line.slice(i + 2, end))
+          if (codes) applySgr(state, codes)
+        }
+        i = end + 1
+        continue
+      }
+    }
+    const ch = Array.from(line.slice(i))[0] ?? ''
+    if (!ch) break
+    tokens.push({ ch, ghost: stateIsGhost(state, cfg) })
+    i += ch.length
+  }
+  return tokens
+}
+
+/** True iff a captured TUI pane shows non-dim human text in the composer row.
+ *  Grey/faint ghost suggestions and placeholders are intentionally NOT human
+ *  input: holding IAP delivery behind them would be a false busy state. */
+export function composerCaptureHasHumanInput(pane: string, markers: DeliveryMarkers): boolean {
+  if (markers.promptGlyphs.length === 0) return false
+  const cfg = ghostSgrConfig(markers)
+  let promptTokens: PaneToken[] | null = null
+  let promptIndex = -1
+
+  for (const line of pane.split(/\r?\n/)) {
+    const tokens = parseAnsiLine(line, cfg)
+    const firstVisible = tokens.findIndex(tok => tok.ch.trim() !== '')
+    if (firstVisible < 0) continue
+    if (!markers.promptGlyphs.includes(tokens[firstVisible].ch)) continue
+    promptTokens = tokens
+    promptIndex = firstVisible
+  }
+
+  if (!promptTokens || promptIndex < 0) return false
+  for (const tok of promptTokens.slice(promptIndex + 1)) {
+    if (tok.ch.trim() === '') continue
+    if (!tok.ghost) return true
+  }
+  return false
+}
+
+export function hasAttachedTmuxClient(target: DeliveryTarget): boolean {
+  const r = tmux(target.socketPath, 'list-clients', '-F', '#{client_session}')
+  if (!r.ok) return false
+  return r.out.split(/\r?\n/).map(line => line.trim()).includes(target.address)
+}
+
+export function targetComposerHasHumanInput(target: DeliveryTarget): boolean {
+  if (!isSupportedLocalRuntime(target.runtime)) return false
+  const cap = tmux(target.socketPath, 'capture-pane', '-e', '-p', '-t', target.address)
+  if (!cap.ok) return false
+  return composerCaptureHasHumanInput(cap.out, getAdapter(target.runtime).deliveryMarkers)
+}
+
+function targetComposerBlocksDelivery(target: DeliveryTarget): boolean {
+  if (!isSupportedLocalRuntime(target.runtime)) return false
+  const cap = tmux(target.socketPath, 'capture-pane', '-e', '-p', '-t', target.address)
+  // With a live resolved target, a capture failure is an uncertainty in the
+  // dangerous direction: prefer a bounded false-busy queue/force over a false-free
+  // paste into a human composer. If the session is actually gone, the queue's
+  // session-token/identity check fails loudly.
+  if (!cap.ok) return true
+  return composerCaptureHasHumanInput(cap.out, getAdapter(target.runtime).deliveryMarkers)
+}
+
+export function shouldQueueForHumanComposer(target: DeliveryTarget): boolean {
+  return isSupportedLocalRuntime(target.runtime) && hasAttachedTmuxClient(target) && targetComposerBlocksDelivery(target)
+}
+
 /** Is the (runtime,personality) endpoint live right now? Public liveness predicate. */
 export function isPeerLive(runtime: string, personality: string, sockDir = resolveSockDir()): boolean {
   const socketPath = buildSocketPath(runtime, personality, sockDir)
@@ -608,6 +770,11 @@ export interface RouteResult {
    *  substantive result arrives as the worker's own reply (FaaS semantics);
    *  `delivered_to` names the ACCEPTING queue identity, not a live session. */
   queued?: boolean
+  /** Which async queue accepted the delivery. `ephemeral` is the durable worker
+   *  task queue; `composer` is the daemon's in-memory busy-human-composer queue.
+   *  Both surface as `queued:true`, but only `composer` means "not yet delivered
+   *  and may still fail with an explicit sender notification". */
+  queuedBy?: 'ephemeral' | 'composer'
   /** Queue depth right after the enqueue (observability; only with queued). */
   queueDepth?: number
 }
@@ -659,11 +826,44 @@ export interface EphemeralRouteDeps {
   }) => Promise<Result<RouteResult>>
 }
 
+export interface ComposerQueuedDelivery {
+  id: number
+  caller: ResolvedCaller
+  peer: PeerRecord
+  target: DeliveryTarget
+  envelope: string
+  topic?: string
+  enqueuedAtMs: number
+  sessionToken: string
+}
+
+export interface ComposerQueueTryEnqueueArgs {
+  caller: ResolvedCaller
+  peer: PeerRecord
+  target: DeliveryTarget
+  envelope: string
+  topic?: string
+}
+
+export interface ComposerQueueRouteDeps {
+  /** Return null when the live delivery should proceed synchronously; return a
+   *  RouteResult when the envelope was accepted by the composer queue. */
+  tryEnqueue: (args: ComposerQueueTryEnqueueArgs) => Promise<Result<RouteResult> | null>
+  /** Fail every queued-but-not-yet-delivered envelope, used by daemon shutdown /
+   *  restart so `queued` never degrades into silent loss. */
+  failAll?: (reason: string) => Promise<void>
+}
+
 export interface RouteDeps {
   /** On a miss, wake the dead peer instead of returning offline (Ф2). */
   wake?: WakeFn
   /** Ephemeral-target serial-queue delivery (M3); absent → normal routing. */
   ephemeral?: EphemeralRouteDeps
+  /** Busy-human-composer queue. When a LIVE local TUI target has an attached
+   *  operator and non-dim text in its composer, routeSend returns a fast
+   *  `{queued:true, queuedBy:"composer"}` ack and the daemon drains the message
+   *  later instead of blindly paste+Enter-ing into the human's unfinished input. */
+  composerQueue?: ComposerQueueRouteDeps
   /** Fired after a successful LIVE delivery whose envelope carried a non-empty
    *  topic — the hit path AND the post-wake fast-path redelivery, NOT the boot
    *  first-message (the wake itself records its topic). The fresh-vs-resume seam:
@@ -689,6 +889,177 @@ function noteTopic(deps: RouteDeps, identity: string, topic: string | undefined)
   }
 }
 
+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. */
+  sessionToken?: (target: DeliveryTarget) => string | null
+  sessionAlive?: (job: ComposerQueuedDelivery) => boolean
+  deliver?: (target: DeliveryTarget, envelope: string, cwd?: string) => Result<void>
+  notifyFailed: (job: ComposerQueuedDelivery, reason: string) => void | Promise<void>
+  noteLiveTopic?: (identity: string, topic: string) => void
+  onDelivered?: (caller: ResolvedCaller) => void
+}
+
+function composerQueuePollMs(env: NodeJS.ProcessEnv | undefined): number {
+  const raw = env?.IAPEER_COMPOSER_QUEUE_POLL_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n > 0 ? n : 500
+}
+
+function composerQueueForceTimeoutMs(env: NodeJS.ProcessEnv | undefined): number {
+  const raw = env?.IAPEER_COMPOSER_QUEUE_TIMEOUT_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 120_000
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function targetSessionToken(target: DeliveryTarget): string | null {
+  const r = tmux(target.socketPath, 'display-message', '-p', '-t', target.address, '#{session_id}:#{pane_id}')
+  if (!r.ok) return null
+  return r.out.trim() || null
+}
+
+function queuedTargetStillSameSession(job: ComposerQueuedDelivery): boolean {
+  return targetSessionToken(job.target) === job.sessionToken
+}
+
+let nextComposerQueueId = 1
+
+/**
+ * In-memory async delivery queue for the narrow "operator is typing in the target
+ * TUI composer" case. It prevents the daemon's paste+Enter from concatenating an
+ * IAP envelope with human text already present in the shared composer stdin.
+ *
+ * Contract:
+ *   - enqueue only on live local TUI + attached tmux client + non-dim composer text;
+ *   - sender gets fast `{queued:true, queuedBy:"composer"}`;
+ *   - FIFO drain delivers with the same deliverViaTmux Ф-B confirmation once the
+ *     composer clears;
+ *   - after 120s (env-tunable) force-deliver rather than hold forever;
+ *   - target death/session replacement or daemon shutdown emits `failed` to sender
+ *     via the injected notifier.
+ */
+export function createComposerDeliveryQueue(opts: ComposerDeliveryQueueOptions): ComposerQueueRouteDeps {
+  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 sessionAliveFn = opts.sessionAlive ?? queuedTargetStillSameSession
+  const deliver = opts.deliver ?? deliverViaTmux
+  const queues = new Map<string, ComposerQueuedDelivery[]>()
+  const draining = new Set<string>()
+  let closed = false
+
+  async function notifyFailed(job: ComposerQueuedDelivery, reason: string): Promise<void> {
+    try {
+      await opts.notifyFailed(job, reason)
+    } catch {
+      /* best-effort notification; delivery.log still has the queued accept */
+    }
+  }
+
+  function kick(identity: string): void {
+    if (draining.has(identity)) return
+    draining.add(identity)
+    void drain(identity).finally(() => draining.delete(identity))
+  }
+
+  async function drain(identity: string): Promise<void> {
+    for (;;) {
+      const q = queues.get(identity)
+      const job = q?.[0]
+      if (!q || !job) {
+        queues.delete(identity)
+        return
+      }
+
+      if (!sessionAliveFn(job)) {
+        q.shift()
+        await notifyFailed(job, `queued delivery to ${job.target.personality} (${job.target.runtime}) failed: target session vanished or was replaced before delivery`)
+        continue
+      }
+
+      const ageMs = monotonicMs() - job.enqueuedAtMs
+      const force = ageMs >= forceTimeoutMs
+      if (!force && hasHumanInput(job.target)) {
+        await delay(pollMs)
+        continue
+      }
+
+      const delivered = 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}`)
+      } else {
+        noteTopic({ noteLiveTopic: opts.noteLiveTopic }, job.target.address, job.topic)
+        try {
+          opts.onDelivered?.(job.caller)
+        } catch {
+          /* a post-delivery hook must never fail a delivery that already landed */
+        }
+      }
+    }
+  }
+
+  return {
+    tryEnqueue: async args => {
+      if (closed) return err('composer delivery queue is closing; message NOT queued')
+      if (!shouldQueue(args)) return null
+      const token = sessionToken(args.target)
+      if (!token) {
+        return err(
+          `composer queue could not identify the live tmux session for "${args.target.personality}" (${args.target.runtime}); message NOT queued`,
+        )
+      }
+      const job: ComposerQueuedDelivery = {
+        id: nextComposerQueueId++,
+        caller: args.caller,
+        peer: args.peer,
+        target: args.target,
+        envelope: args.envelope,
+        topic: args.topic,
+        enqueuedAtMs: monotonicMs(),
+        sessionToken: token,
+      }
+      const q = queues.get(args.target.address) ?? []
+      q.push(job)
+      queues.set(args.target.address, q)
+      kick(args.target.address)
+      return ok({
+        ok: true as const,
+        delivered_to: { personality: args.target.personality, runtime: args.target.runtime },
+        woke: false,
+        queued: true,
+        queuedBy: 'composer',
+        queueDepth: q.length,
+        ts: new Date().toISOString(),
+      })
+    },
+    failAll: async reason => {
+      closed = true
+      const jobs = Array.from(queues.values()).flat()
+      queues.clear()
+      await Promise.all(jobs.map(job => notifyFailed(job, reason)))
+    },
+  }
+}
+
 function truncateTopic(raw: string | undefined): string | undefined {
   if (!raw) return undefined
   return raw.slice(0, MAX_TOPIC_LEN)
@@ -828,6 +1199,8 @@ export async function routeSend(
     // land on telegram without an override and without telegram being the default).
     const liveGuard = telegramSenderGuard(caller, target.value.runtime, personality)
     if (!liveGuard.ok) return liveGuard
+    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)
     if (!delivered.ok) return delivered
@@ -868,6 +1241,8 @@ export async function routeSend(
   // a false ok:true — the class the contract forbids. A delivery failure here is
   // surfaced loudly (false-FAIL over false-OK).
   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)
     if (!delivered.ok) return delivered
     noteTopic(deps, live.value.address, topic)

package/src/transport/routesend-wake.test.ts

@@ -40,6 +40,9 @@ const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status ===
 const TARGET = 'fpw'
 const SESSION = `telegram-${TARGET}`
 const sockPath = () => join(sockDir, `tmux-iap-telegram-${TARGET}.sock`)
+const TUI_TARGET = 'tq'
+const TUI_SESSION = `codex-${TUI_TARGET}`
+const tuiSockPath = () => join(sockDir, `tmux-iap-codex-${TUI_TARGET}.sock`)
 
 const callerRecord = {
   personality: 'boris',
@@ -79,6 +82,17 @@ function capturePane(): string {
   return r.stdout ?? ''
 }
 
+function startTuiSession(): void {
+  const r = spawnSync('tmux', ['-S', tuiSockPath(), 'new-session', '-d', '-x', '200', '-y', '50', '-s', TUI_SESSION, 'cat'], {
+    encoding: 'utf8',
+  })
+  if (r.status !== 0) throw new Error(`tmux new-session failed: ${r.stderr}`)
+}
+
+function killTuiSession(): void {
+  spawnSync('tmux', ['-S', tuiSockPath(), 'kill-server'], { encoding: 'utf8' })
+}
+
 beforeAll(() => {
   root = mkdtempSync(join(tmpdir(), 'fpw-'))
   sockDir = join(root, 'socks')
@@ -90,6 +104,7 @@ beforeAll(() => {
       peers: [
         { personality: 'boris', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'artificial', cwd: '/tmp/boris' },
         { personality: TARGET, runtime: 'telegram', runtimes: ['telegram'], description: '', intelligence: 'artificial', cwd: root },
+        { personality: TUI_TARGET, runtime: 'codex', runtimes: ['codex'], description: '', intelligence: 'artificial', cwd: root },
       ],
     }),
   )
@@ -97,6 +112,7 @@ beforeAll(() => {
 })
 afterAll(() => {
   killTargetSession()
+  killTuiSession()
   if (prevRoot === undefined) delete process.env.IAPEER_ROOT
   else process.env.IAPEER_ROOT = prevRoot
   rmSync(root, { recursive: true, force: true })
@@ -218,6 +234,42 @@ describe.if(tmuxAvailable)('routeSend noteLiveTopic seam (live-delivered topic)'
   })
 })
 
+describe.if(tmuxAvailable)('routeSend busy-composer queue seam', () => {
+  test('live local TUI hit can return fast queued ack instead of delivering synchronously', async () => {
+    startTuiSession()
+    const seen: string[] = []
+    const r = await routeSend(
+      caller,
+      { personality: TUI_TARGET, message: 'hold until operator submits', topic: 'composer-q' },
+      {
+        composerQueue: {
+          tryEnqueue: async ({ target, envelope, topic }) => {
+            seen.push(`${target.runtime}-${target.personality}:${topic}:${envelope.includes('hold until operator submits')}`)
+            return {
+              ok: true,
+              value: {
+                ok: true as const,
+                delivered_to: { personality: target.personality, runtime: target.runtime },
+                woke: false,
+                queued: true,
+                queuedBy: 'composer',
+                queueDepth: 1,
+                ts: 'now',
+              },
+            }
+          },
+        },
+      },
+    )
+    expect(r.ok).toBe(true)
+    if (!r.ok) return
+    expect(r.value.queued).toBe(true)
+    expect(r.value.queuedBy).toBe('composer')
+    expect(seen).toEqual([`codex-${TUI_TARGET}:composer-q:true`])
+    killTuiSession()
+  })
+})
+
 // ─── Telegram sender policy (defect track 11.06) ─────────────────────────────
 // A sender with NO declared telegram presence (interfaces.telegram.bot|user_id)
 // must get a SYNCHRONOUS refusal when the delivery channel is telegram — the