@agfpd/iapeer 0.2.51 → 0.2.53

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,
@@ -98,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)
@@ -309,6 +472,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 ──
 
 /**
@@ -384,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
 }
@@ -435,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:
@@ -465,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)
@@ -604,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
@@ -644,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)