@agfpd/iapeer 0.2.10 → 0.2.12

package/src/lifecycle/index.ts

@@ -24,10 +24,16 @@ import {
   resolveSockDir,
   type Runtime,
 } from '../core/constants.ts'
-import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
+import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { err, ok, type Result } from '../core/errors.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import { readPeerProfile, resolveIdentity } from '../identity/index.ts'
+import {
+  ephemeralQueueDepth,
+  listQueuedIdentities,
+  peekEphemeralTask,
+  removeEphemeralTask,
+} from './queue.ts'
 import { findPeer, publicPeerSummary, readPeersIndex, type PeerRecord, type PublicPeerSummary } from '../registry/index.ts'
 // Ф3: launch = HOW to bring up ONE session (runtime-agnostic primitive + adapter).
 // lifecycle decides WHEN/HOW-MANY and delegates the bring-up to launch.
@@ -65,6 +71,13 @@ export interface LifecycleConfig {
   crashLoopMax: number
   /** Crash-loop guard: the sliding window (seconds) the death count is measured over. */
   crashLoopWindowSecs: number
+  /** wake_policy:ephemeral M2 — the quiet window (seconds of activity-proxy silence)
+   *  after which an ARMED ephemeral session (it has sent its outbound reply) is
+   *  reaped. Long enough for the post-reply housekeeping writes (operative notes)
+   *  to keep resetting it; far below idleSecs. ASSUMPTION (boris, by design): the
+   *  transcript mtime is a LIVENESS proxy — "no longer writing" — not a semantic
+   *  "done" signal. */
+  ephemeralQuietSecs: number
 }
 
 export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): LifecycleConfig {
@@ -87,6 +100,7 @@ export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): Lifec
     maxAgeSecs: num(env.IAPEER_MAX_AGE_SECS, 14400),
     crashLoopMax: num(env.IAPEER_CRASHLOOP_MAX, 3),
     crashLoopWindowSecs: num(env.IAPEER_CRASHLOOP_WINDOW_SECS, 300),
+    ephemeralQuietSecs: num(env.IAPEER_EPHEMERAL_QUIET_SECS, 20),
   }
 }
 
@@ -194,6 +208,14 @@ export function clearStopped(cfg: LifecycleConfig, identity: string): void {
 //   .deaths      : crash-loop guard — a small JSON ring of recent death epoch-ms.
 //   .topic       : the topic tag of the current/last session (executor fresh-vs-
 //     resume discriminator).
+//   .ephemeral-armed : wake_policy:ephemeral M2 — set by the DAEMON when it routes
+//     an OUTBOUND send from an ephemeral worker (its single final reply, ADR-006:
+//     workers send no intermediate messages, so outbound ⇒ the task is answered).
+//     An ARMED live session is reaped by superviseTick after a quiet window
+//     (die-after-reply). The marker belongs to the session that sent the outbound:
+//     it is cleared on the quiet-reap, on that session's own death, and on the
+//     next successful launch — it NEVER survives into a successor session (else a
+//     stray marker would quiet-reap the next task before its answer).
 //
 // Boolean markers carry an ISO timestamp line (audit-friendly); .deaths is a JSON
 // array; .topic is the raw topic string.
@@ -247,6 +269,32 @@ export function clearNewEager(cfg: LifecycleConfig, identity: string): void {
   }
 }
 
+function ephemeralArmedPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.ephemeral-armed`)
+}
+
+/** True iff the identity's live ephemeral session has sent its outbound reply
+ *  (→ quiet-reap candidate). */
+export function hasEphemeralArmed(cfg: LifecycleConfig, identity: string): boolean {
+  return existsSync(ephemeralArmedPath(cfg, identity))
+}
+
+/** Arm the die-after-reply reap — ONLY the daemon's outbound seam does this
+ *  (an ephemeral caller's send_to_peer was routed ok). */
+export function setEphemeralArmed(cfg: LifecycleConfig, identity: string): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  writeFileSync(ephemeralArmedPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
+}
+
+/** Clear the armed mark (quiet-reap done / the armed session died / a new launch). */
+export function clearEphemeralArmed(cfg: LifecycleConfig, identity: string): void {
+  try {
+    rmSync(ephemeralArmedPath(cfg, identity), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
 function deathsPath(cfg: LifecycleConfig, identity: string): string {
   return join(cfg.stateDir, `${identity}.deaths`)
 }
@@ -367,7 +415,7 @@ function isHumanConversational(cwd: string): boolean {
  * set, ephemeral WINS in resolveWakeMode (explicit policy beats the inferred human
  * type) — provision warns on that combination; it should not occur for real workers.
  */
-function isEphemeralPeer(cwd: string): boolean {
+export function isEphemeralPeer(cwd: string): boolean {
   try {
     return readPeerProfile(cwd)?.wake_policy === 'ephemeral'
   } catch {
@@ -855,6 +903,11 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
         `[iapeer] WARN session-state write failed for ${identity} — session is live + TTL-bounded but not idle-reap-supervised: ${e instanceof Error ? e.message : String(e)}\n`,
       )
     }
+    // A NEWLY launched session starts UNARMED by definition (no outbound yet) — clear
+    // any stray .ephemeral-armed so it can never quiet-reap this session before its
+    // reply. ONLY here on the actual launch path, NEVER on the live-session fast path
+    // above (a live session may be legitimately armed mid-quiet-window).
+    clearEphemeralArmed(cfg, identity)
     // Establish the session's topic (executor discriminator) and reset the crash-loop
     // ring — a successful wake means this is NOT a tight crash loop. Best-effort.
     writeTopic(cfg, identity, args.topic?.trim() ?? '')
@@ -894,10 +947,12 @@ export function killSession(sock: string, identity: string): void {
 
 export interface SuperviseOutcome {
   identity: string
-  action: 'reaped-idle' | 'reaped-gone' | 'skipped-launchd' | 'alive' | 'needs-eager-fresh'
+  action: 'reaped-idle' | 'reaped-gone' | 'reaped-ephemeral' | 'skipped-launchd' | 'alive' | 'needs-eager-fresh'
   reason?: string
   /** For 'needs-eager-fresh': the peer to EAGERLY re-launch fresh (its session died
-   *  carrying a .new-eager mark). The daemon timer drives the async relaunch. */
+   *  carrying a .new-eager mark). The daemon timer drives the async relaunch.
+   *  Also set on 'reaped-ephemeral' — the M3 queue-drain hook needs the peer to
+   *  wake fresh for the next queued task. */
   personality?: string
   runtime?: Runtime
 }
@@ -932,6 +987,10 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       // the idle-reap below) → it died on its own → do NOT write .idle-reaped here.
       recordDeath(cfg, s.identity, nowMs)
       removeSessionState(cfg, s.identity)
+      // The .ephemeral-armed mark belongs to THIS (now dead) session — it armed on its
+      // outbound reply. Clear it with the session, so a successor session can never be
+      // quiet-reaped on a stale mark before answering its own task. No-op otherwise.
+      clearEphemeralArmed(cfg, s.identity)
       // A session that died carrying a .new-eager mark is an owner /new: re-launch
       // EAGERLY as fresh (not lazily on the next message). The mark is LEFT for the
       // eager relaunch (processEagerRelaunches) to consume; the daemon timer drives it.
@@ -963,6 +1022,29 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       /* no adapter for this runtime yet → wokeAt fallback */
     }
     const ageSecs = Math.floor((nowMs - mt) / 1000)
+    // wake_policy:ephemeral M2 — die-after-reply: an ARMED ephemeral session (the
+    // daemon routed its outbound reply) is reaped after a QUIET window, checked
+    // BEFORE the idle branch (quiet ≪ idle). Quiet = the activity proxy stayed
+    // silent for ephemeralQuietSecs — post-reply housekeeping (operative-note
+    // writes) keeps resetting it, so the worker finishes its bookkeeping first.
+    // NOT armed (still mid-task, e.g. a long silent tool run) → the ordinary
+    // idle bound below is its only reaper. Deliberate, policy-driven death:
+    // NO .idle-reaped (an ephemeral peer never resumes) and NO recordDeath
+    // (the crash-loop ring counts faults, not policy reaps).
+    if (isEphemeralPeer(s.cwd) && hasEphemeralArmed(cfg, s.identity) && ageSecs > cfg.ephemeralQuietSecs) {
+      killSession(sock, s.identity)
+      clearEphemeralArmed(cfg, s.identity)
+      removeSessionState(cfg, s.identity)
+      out.push({
+        identity: s.identity,
+        action: 'reaped-ephemeral',
+        reason: `armed, quiet ${ageSecs}s`,
+        personality: s.personality,
+        runtime: s.runtime,
+      })
+      trace({ identity: s.identity, action: 'reaped-ephemeral', age: `${ageSecs}s`, outcome: 'ephemeral-done' })
+      continue
+    }
     if (ageSecs > cfg.idleSecs) {
       // THE ONLY place .idle-reaped is written: this is the one death the daemon
       // INITIATES. Its presence on the next wake = the session was parked cleanly =
@@ -1015,6 +1097,94 @@ export async function processEagerRelaunches(
   return results
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// wake_policy:"ephemeral" M3 — the serial-queue DRAIN. Deliveries to an ephemeral
+// target are always ENQUEUED (transport's injected ephemeral seam → queue.ts);
+// this is the consumer side: feed the worker ONE task per fresh session.
+// Re-export the queue API so consumers (daemon main, tests) reach it through the
+// module index.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  enqueueEphemeralTask,
+  ephemeralQueueDepth,
+  ephemeralQueueDir,
+  listQueuedIdentities,
+  peekEphemeralTask,
+  removeEphemeralTask,
+  type EphemeralQueueItem,
+  type PeekedQueueItem,
+} from './queue.ts'
+
+export interface DrainDeps {
+  env?: NodeJS.ProcessEnv
+  /** Injectable wake (tests); default wakeOrSpawn. */
+  wakeFn?: (args: WakeArgs, deps: WakeDeps) => Promise<WakeResult>
+}
+
+/**
+ * Feed ONE queued task to an ephemeral worker IFF it has no live session:
+ * peek → wake FRESH (the task is the boot first-message; resolveWakeMode takes
+ * the ephemeral-policy branch) → remove the item ONLY on READY. A FAILED wake
+ * LEAVES the item at the head — the next supervise-tick drain retries it (the
+ * crash-loop guard bounds a tight failure loop, its refusals land in
+ * lifecycle.log). Returns null when there is nothing to do (empty queue, or a
+ * session is still live — invariant: ≤1 live session = exactly one task).
+ * Serialization: concurrent drains converge on wakeOrSpawn's per-identity
+ * wake.lock — the loser takes the idempotent live-session fast path and the
+ * item is removed once, delivered once.
+ */
+export async function drainEphemeralQueue(
+  cfg: LifecycleConfig,
+  personality: string,
+  runtime: Runtime,
+  deps: DrainDeps = {},
+): Promise<WakeResult | null> {
+  const env = deps.env ?? process.env
+  const identity = buildProcessAddress(runtime, personality)
+  const sock = buildSocketPath(runtime, personality, cfg.sockDir)
+  if (sessionAlive(sock, identity)) return null // one task per session — wait for its reap
+  const item = peekEphemeralTask(cfg, identity)
+  if (!item) return null
+  // Durable drain trace (boris acceptance (a)): which item, how deep the queue.
+  appendLifecycleEvent(
+    cfg.eventLogDir,
+    { ev: 'ephemeral-drain', identity, seq: item.seq, depth: ephemeralQueueDepth(cfg, identity) },
+    { env },
+  )
+  const wake = deps.wakeFn ?? wakeOrSpawn
+  const result = await wake({ personality, runtime, topic: item.topic, task: item.task }, { cfg, env })
+  if (result.status === 'READY') removeEphemeralTask(cfg, identity, item.seq)
+  return result
+}
+
+/**
+ * Drain every identity with a non-empty queue and no live session — the daemon's
+ * supervise-tick hook. ONE mechanism is the whole M3 delivery loop: the inline
+ * kick after an enqueue covers the cold/empty case, and this periodic scan covers
+ * (a) the next task after a reaped-ephemeral (same tick that reaped it),
+ * (b) drain-on-start (the queue is durable across daemon restarts), and
+ * (c) the RETRY of a failed wake (the item was left at the head). H4-guarded:
+ * a launchd-managed peer is never woken by a drain (it should never have a
+ * queue, but the guard is structural, not situational).
+ */
+export async function drainAllEphemeralQueues(cfg: LifecycleConfig, deps: DrainDeps = {}): Promise<WakeResult[]> {
+  const env = deps.env ?? process.env
+  const results: WakeResult[] = []
+  for (const identity of listQueuedIdentities(cfg)) {
+    const parsed = parseSessionName(identity)
+    if (!parsed) continue
+    if (isLaunchdManaged(parsed.personality, env)) continue
+    try {
+      const r = await drainEphemeralQueue(cfg, parsed.personality, parsed.runtime, deps)
+      if (r) results.push(r)
+    } catch (e) {
+      results.push({ status: 'FAILED', woke: false, reason: e instanceof Error ? e.message : String(e) })
+    }
+  }
+  return results
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // folderLaunch / attachPeer — operator verbs (contract ЖЦ §Запуск из папки, §attach;
 // Примитивы §Карта verbs). Both reuse wakeOrSpawn (one bring-up path); the difference

package/src/lifecycle/lifecycle.test.ts

@@ -4,13 +4,16 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import {
   attachPeer,
+  clearEphemeralArmed,
   clearNewEager,
   clearStopped,
   composeFirstMessage,
   countRecentDeaths,
   folderLaunch,
+  hasEphemeralArmed,
   hasIdleReaped,
   hasNewEager,
+  isEphemeralPeer,
   isLaunchdManaged,
   isStopped,
   lastActiveRuntime,
@@ -20,6 +23,7 @@ import {
   recordDeath,
   resolveWakeMode,
   resolveWakeRuntime,
+  setEphemeralArmed,
   setIdleReaped,
   setNewEager,
   setStopped,
@@ -29,6 +33,7 @@ import {
   writeTopic,
   type LifecycleConfig,
 } from './index.ts'
+import { spawnSync } from 'child_process'
 import { upsertPeer, type PeerRecord } from '../registry/index.ts'
 
 function peer(over: Partial<PeerRecord>): PeerRecord {
@@ -557,6 +562,135 @@ describe('superviseTick death-cause accounting (TARGET)', () => {
       rmSync(laDir, { recursive: true, force: true })
     }
   })
+
+  test('a DEAD session clears a stale .ephemeral-armed (the mark dies with its session)', () => {
+    // The mark armed on the dead session's outbound; were it to survive, the NEXT
+    // session would be quiet-reap eligible BEFORE answering its own task.
+    const { env, cfg, root, laDir } = deadSessionEnv('q')
+    try {
+      setEphemeralArmed(cfg, 'claude-q')
+      const out = superviseTick(cfg, { env })
+      expect(out.find(x => x.identity === 'claude-q')?.action).toBe('reaped-gone')
+      expect(hasEphemeralArmed(cfg, 'claude-q')).toBe(false)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+      rmSync(laDir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wake_policy:ephemeral M2 — armed marker + quiet-reap (die-after-reply)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('ephemeral-armed marker + config', () => {
+  test('set/has/clear round-trip; clear is idempotent', () => {
+    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-eph-mark-'))
+    const cfg = { stateDir } as LifecycleConfig
+    try {
+      expect(hasEphemeralArmed(cfg, 'claude-e')).toBe(false)
+      setEphemeralArmed(cfg, 'claude-e')
+      expect(hasEphemeralArmed(cfg, 'claude-e')).toBe(true)
+      clearEphemeralArmed(cfg, 'claude-e')
+      clearEphemeralArmed(cfg, 'claude-e') // idempotent
+      expect(hasEphemeralArmed(cfg, 'claude-e')).toBe(false)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+
+  test('ephemeralQuietSecs: default 20, env-tunable', () => {
+    expect(loadLifecycleConfig({ HOME: '/tmp' } as NodeJS.ProcessEnv).ephemeralQuietSecs).toBe(20)
+    expect(
+      loadLifecycleConfig({ HOME: '/tmp', IAPEER_EPHEMERAL_QUIET_SECS: '45' } as NodeJS.ProcessEnv)
+        .ephemeralQuietSecs,
+    ).toBe(45)
+  })
+
+  test('isEphemeralPeer keys on the cwd profile; read hiccup → false (safe default)', () => {
+    const eph = profileCwd(false, true)
+    const plain = profileCwd(false, false)
+    try {
+      expect(isEphemeralPeer(eph)).toBe(true)
+      expect(isEphemeralPeer(plain)).toBe(false)
+      expect(isEphemeralPeer('/tmp/definitely-no-such-peer-cwd')).toBe(false)
+    } finally {
+      rmSync(eph, { recursive: true, force: true })
+      rmSync(plain, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('superviseTick quiet-reap (M2 die-after-reply, real tmux)', () => {
+  const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+
+  test.if(tmuxAvailable)(
+    'ARMED + quiet → reaped-ephemeral (killed, marks cleared, NO death/idle-reaped); unarmed/not-quiet → alive',
+    () => {
+      const root = mkdtempSync(join(tmpdir(), 'iapeer-eq-root-'))
+      const laDir = mkdtempSync(join(tmpdir(), 'iapeer-eq-la-')) // empty → not launchd-managed
+      const cwd = profileCwd(false, true) // ephemeral worker profile
+      const env = {
+        ...process.env,
+        IAPEER_ROOT: root,
+        IAPEER_LAUNCHAGENTS_DIR: laDir,
+        IAPEER_SOCK_DIR: join(root, 'socks'),
+      }
+      const cfg = loadLifecycleConfig(env) // ephemeralQuietSecs 20 ≪ idleSecs 3600
+      const identity = 'claude-eq'
+      const sock = join(root, 'socks', 'tmux-iap-claude-eq.sock')
+      const writeState = (wokeAt: number) => {
+        mkdirSync(cfg.stateDir, { recursive: true })
+        writeFileSync(
+          join(cfg.stateDir, `${identity}.session`),
+          JSON.stringify({ identity, runtime: 'claude', personality: 'eq', cwd, wokeAt }),
+        )
+      }
+      const alive = () => spawnSync('tmux', ['-S', sock, 'has-session', '-t', identity]).status === 0
+      try {
+        mkdirSync(join(root, 'socks'), { recursive: true })
+        spawnSync('tmux', ['-S', sock, 'new-session', '-d', '-s', identity, 'sleep', '300'])
+        expect(alive()).toBe(true)
+        // no transcript in the temp cwd → activity proxy = wokeAt fallback:
+        // quiet age is fully controlled by the .session wokeAt below.
+
+        // 1) NOT armed + quiet-aged → alive (a silent long tool-run is NOT reaped:
+        //    sleep-180 protection; only the ordinary idle bound applies).
+        writeState(Date.now() - 60_000) // age ~60s > quiet 20s, ≪ idle 3600s
+        expect(superviseTick(cfg, { env }).find(x => x.identity === identity)?.action).toBe('alive')
+        expect(alive()).toBe(true)
+
+        // 2) ARMED but NOT quiet → alive (post-reply housekeeping keeps it alive).
+        setEphemeralArmed(cfg, identity)
+        writeState(Date.now()) // age ~0 < quiet
+        expect(superviseTick(cfg, { env }).find(x => x.identity === identity)?.action).toBe('alive')
+        expect(alive()).toBe(true)
+
+        // 3) ARMED + quiet → reaped-ephemeral, with the M3 drain fields.
+        writeState(Date.now() - 60_000)
+        const o = superviseTick(cfg, { env }).find(x => x.identity === identity)
+        expect(o?.action).toBe('reaped-ephemeral')
+        expect(o?.personality).toBe('eq')
+        expect(o?.runtime).toBe('claude')
+        expect(alive()).toBe(false) // session killed
+        expect(hasEphemeralArmed(cfg, identity)).toBe(false) // mark consumed
+        expect(existsSync(join(cfg.stateDir, `${identity}.session`))).toBe(false)
+        // deliberate policy death: never resume-eligible, never a crash-loop count
+        expect(hasIdleReaped(cfg, identity)).toBe(false)
+        expect(readDeaths(cfg, identity).length).toBe(0)
+        // durable decision trace
+        const logged = readFileSync(join(cfg.eventLogDir, 'lifecycle.log'), 'utf8')
+        expect(logged).toContain(`action=reaped-ephemeral`)
+        expect(logged).toContain('outcome=ephemeral-done')
+      } finally {
+        spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+        rmSync(root, { recursive: true, force: true })
+        rmSync(laDir, { recursive: true, force: true })
+        rmSync(cwd, { recursive: true, force: true })
+      }
+    },
+    30000,
+  )
 })
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/lifecycle/queue.test.ts

@@ -0,0 +1,185 @@
+// Ephemeral serial queue (M3) — FIFO primitives + the drain consumer.
+// Retry semantics (boris acceptance (b)) are pinned here: a FAILED wake leaves
+// the item at the head and the NEXT drain call retries the SAME task; only a
+// READY wake consumes it. Strict FIFO order is asserted across drains.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import {
+  drainAllEphemeralQueues,
+  drainEphemeralQueue,
+  enqueueEphemeralTask,
+  ephemeralQueueDepth,
+  ephemeralQueueDir,
+  listQueuedIdentities,
+  peekEphemeralTask,
+  removeEphemeralTask,
+  type LifecycleConfig,
+  type WakeArgs,
+  type WakeResult,
+} from './index.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-equeue-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+function mkCfg(): LifecycleConfig {
+  const root = mkTmp()
+  return {
+    stateDir: join(root, 'state'),
+    sockDir: join(root, 'socks'),
+    eventLogDir: join(root, 'logs'),
+  } as LifecycleConfig
+}
+
+describe('ephemeral queue primitives (FIFO)', () => {
+  test('enqueue returns depth; peek is non-destructive; remove consumes; strict FIFO', () => {
+    const cfg = mkCfg()
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(0)
+    expect(peekEphemeralTask(cfg, 'claude-w')).toBeNull()
+
+    expect(enqueueEphemeralTask(cfg, 'claude-w', { task: 'first', topic: 't1' })).toBe(1)
+    expect(enqueueEphemeralTask(cfg, 'claude-w', { task: 'second' })).toBe(2)
+    expect(enqueueEphemeralTask(cfg, 'claude-w', { task: 'third', topic: 't3' })).toBe(3)
+
+    const head = peekEphemeralTask(cfg, 'claude-w')
+    expect(head?.task).toBe('first')
+    expect(head?.topic).toBe('t1')
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(3) // peek did not consume
+
+    removeEphemeralTask(cfg, 'claude-w', head!.seq)
+    removeEphemeralTask(cfg, 'claude-w', head!.seq) // idempotent
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(2)
+    expect(peekEphemeralTask(cfg, 'claude-w')?.task).toBe('second')
+    expect(peekEphemeralTask(cfg, 'claude-w')?.topic).toBeUndefined()
+  })
+
+  test('enqueue skips taken seq names (exclusive-create) — no overwrite of a pending task', () => {
+    const cfg = mkCfg()
+    enqueueEphemeralTask(cfg, 'claude-w', { task: 'one' })
+    // simulate a competitor that already claimed the next seq
+    writeFileSync(join(ephemeralQueueDir(cfg, 'claude-w'), '000002'), JSON.stringify({ task: 'competitor' }))
+    expect(enqueueEphemeralTask(cfg, 'claude-w', { task: 'three' })).toBe(3)
+    // all three distinct tasks live side-by-side
+    const dir = ephemeralQueueDir(cfg, 'claude-w')
+    expect(JSON.parse(readFileSync(join(dir, '000002'), 'utf8')).task).toBe('competitor')
+    expect(JSON.parse(readFileSync(join(dir, '000003'), 'utf8')).task).toBe('three')
+  })
+
+  test('a poison head (corrupt JSON) is dropped, not wedging the queue', () => {
+    const cfg = mkCfg()
+    mkdirSync(ephemeralQueueDir(cfg, 'claude-w'), { recursive: true })
+    writeFileSync(join(ephemeralQueueDir(cfg, 'claude-w'), '000001'), 'NOT JSON {{{')
+    enqueueEphemeralTask(cfg, 'claude-w', { task: 'good' })
+    const head = peekEphemeralTask(cfg, 'claude-w')
+    expect(head?.task).toBe('good')
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(1) // poison slot dropped
+  })
+
+  test('listQueuedIdentities: only non-empty queues, sorted', () => {
+    const cfg = mkCfg()
+    enqueueEphemeralTask(cfg, 'claude-b', { task: 'x' })
+    enqueueEphemeralTask(cfg, 'claude-a', { task: 'y' })
+    mkdirSync(ephemeralQueueDir(cfg, 'claude-empty'), { recursive: true }) // empty dir → excluded
+    expect(listQueuedIdentities(cfg)).toEqual(['claude-a', 'claude-b'])
+  })
+})
+
+describe('drainEphemeralQueue (peek → wake → rm-on-READY)', () => {
+  function fakeWake(
+    script: Array<'READY' | 'FAILED'>,
+    calls: WakeArgs[],
+  ): (args: WakeArgs) => Promise<WakeResult> {
+    return async args => {
+      calls.push(args)
+      const status = script[Math.min(calls.length - 1, script.length - 1)]!
+      return { status, woke: status === 'READY', runtime: 'claude' }
+    }
+  }
+
+  test('empty queue → null, wake NOT called', async () => {
+    const cfg = mkCfg()
+    const calls: WakeArgs[] = []
+    expect(await drainEphemeralQueue(cfg, 'w', 'claude', { wakeFn: fakeWake(['READY'], calls) })).toBeNull()
+    expect(calls).toEqual([])
+  })
+
+  test('READY consumes the head; successive drains feed tasks in STRICT FIFO order', async () => {
+    const cfg = mkCfg()
+    enqueueEphemeralTask(cfg, 'claude-w', { task: 'task-A', topic: 'ta' })
+    enqueueEphemeralTask(cfg, 'claude-w', { task: 'task-B' })
+    const calls: WakeArgs[] = []
+    const deps = { wakeFn: fakeWake(['READY'], calls) }
+
+    expect((await drainEphemeralQueue(cfg, 'w', 'claude', deps))?.status).toBe('READY')
+    expect(calls[0]).toMatchObject({ personality: 'w', runtime: 'claude', task: 'task-A', topic: 'ta' })
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(1) // A consumed
+
+    expect((await drainEphemeralQueue(cfg, 'w', 'claude', deps))?.status).toBe('READY')
+    expect(calls[1]).toMatchObject({ task: 'task-B' }) // FIFO: B strictly after A
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(0)
+    expect(await drainEphemeralQueue(cfg, 'w', 'claude', deps)).toBeNull() // drained dry
+
+    // durable drain trace (acceptance (a)): ev=ephemeral-drain with depth
+    const logged = readFileSync(join(cfg.eventLogDir, 'lifecycle.log'), 'utf8')
+    expect(logged).toContain('ev=ephemeral-drain')
+    expect(logged).toContain('identity=claude-w')
+    expect(logged).toContain('depth=2')
+  })
+
+  test('FAILED wake LEAVES the item at the head — the next drain RETRIES the same task (acceptance (b))', async () => {
+    const cfg = mkCfg()
+    enqueueEphemeralTask(cfg, 'claude-w', { task: 'flaky-task' })
+    const calls: WakeArgs[] = []
+    const deps = { wakeFn: fakeWake(['FAILED', 'READY'], calls) }
+
+    expect((await drainEphemeralQueue(cfg, 'w', 'claude', deps))?.status).toBe('FAILED')
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(1) // NOT consumed on failure
+
+    expect((await drainEphemeralQueue(cfg, 'w', 'claude', deps))?.status).toBe('READY')
+    expect(calls.length).toBe(2)
+    expect(calls[1]?.task).toBe('flaky-task') // the SAME task, retried
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(0)
+  })
+
+  const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+  test.if(tmuxAvailable)('a LIVE session blocks the drain (one task per session invariant)', async () => {
+    const cfg = mkCfg()
+    mkdirSync(cfg.sockDir, { recursive: true })
+    const sock = join(cfg.sockDir, 'tmux-iap-claude-w.sock')
+    enqueueEphemeralTask(cfg, 'claude-w', { task: 'queued-while-busy' })
+    const calls: WakeArgs[] = []
+    try {
+      spawnSync('tmux', ['-S', sock, 'new-session', '-d', '-s', 'claude-w', 'sleep', '60'])
+      expect(await drainEphemeralQueue(cfg, 'w', 'claude', { wakeFn: fakeWake(['READY'], calls) })).toBeNull()
+      expect(calls).toEqual([]) // no wake while the session lives
+      expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(1) // task waits for the reap
+    } finally {
+      spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+    }
+  })
+
+  test('drainAllEphemeralQueues: scans every queued identity, H4-skips launchd-managed', async () => {
+    const cfg = mkCfg()
+    const laDir = mkTmp()
+    const env = { ...process.env, IAPEER_LAUNCHAGENTS_DIR: laDir } as NodeJS.ProcessEnv
+    enqueueEphemeralTask(cfg, 'claude-free', { task: 'x' })
+    enqueueEphemeralTask(cfg, 'claude-held', { task: 'y' })
+    writeFileSync(join(laDir, 'com.iapeer.held.plist'), '') // 'held' is launchd-managed
+    const calls: WakeArgs[] = []
+    const results = await drainAllEphemeralQueues(cfg, { env, wakeFn: fakeWake(['READY'], calls) })
+    expect(results.length).toBe(1)
+    expect(calls.map(c => c.personality)).toEqual(['free']) // held NEVER woken (H4)
+    expect(ephemeralQueueDepth(cfg, 'claude-free')).toBe(0)
+    expect(ephemeralQueueDepth(cfg, 'claude-held')).toBe(1) // untouched
+  })
+})