@agfpd/iapeer 0.2.9 → 0.2.11

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 {
@@ -366,8 +371,9 @@ describe('C2 initial_prompt (composeFirstMessage)', () => {
 // = .idle-reaped marker, plus peer-type/topic; NO agent-dropped fresh mark).
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** A temp cwd with a peer-profile; interfaces.telegram present → human-conversational. */
-function profileCwd(human: boolean): string {
+/** A temp cwd with a peer-profile; interfaces.telegram present → human-conversational;
+ *  ephemeral → wake_policy "ephemeral". */
+function profileCwd(human: boolean, ephemeral = false): string {
   const cwd = mkdtempSync(join(tmpdir(), 'iapeer-wm-cwd-'))
   mkdirSync(join(cwd, '.iapeer'), { recursive: true })
   writeFileSync(
@@ -378,6 +384,7 @@ function profileCwd(human: boolean): string {
       runtimes: ['claude'],
       intelligence: human ? 'natural' : 'artificial',
       ...(human ? { interfaces: { telegram: { user_id: 1 } } } : {}),
+      ...(ephemeral ? { wake_policy: 'ephemeral' } : {}),
     }),
   )
   return cwd
@@ -395,8 +402,8 @@ describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
     for (const c of cwds) rmSync(c, { recursive: true, force: true })
   })
   const cfg = () => ({ stateDir } as LifecycleConfig)
-  const cwd = (human = false) => {
-    const c = profileCwd(human)
+  const cwd = (human = false, ephemeral = false) => {
+    const c = profileCwd(human, ephemeral)
     cwds.push(c)
     return c
   }
@@ -449,6 +456,26 @@ describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
     expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript, 'unrelated-bug')).toEqual({ resume: false, cause: 'idle-reaped-new-topic' })
     expect(hasIdleReaped(c, 'claude-p')).toBe(false) // consumed even on the fresh executor branch
   })
+
+  // ── M1: wake_policy "ephemeral" → ALWAYS fresh on delivery, overrides resume ──
+  test('DEFAULT + ephemeral → FRESH (ephemeral-policy), even with a resumable transcript', () => {
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(false, true), undefined, hasTranscript)).toEqual({ resume: false, cause: 'ephemeral-policy' })
+  })
+  test('DEFAULT + ephemeral + idle-reaped → FRESH (overrides idle-reaped-resume), marker consumed', () => {
+    const c = cfg()
+    setIdleReaped(c, 'claude-p')
+    expect(resolveWakeMode(c, 'claude-p', cwd(false, true), undefined, hasTranscript)).toEqual({ resume: false, cause: 'ephemeral-policy' })
+    expect(hasIdleReaped(c, 'claude-p')).toBe(false) // stray marker consumed
+  })
+  test('DEFAULT + ephemeral + telegram (human) → FRESH (ephemeral WINS over human type)', () => {
+    const c = cfg()
+    setIdleReaped(c, 'claude-p')
+    expect(resolveWakeMode(c, 'claude-p', cwd(true, true), undefined, hasTranscript)).toEqual({ resume: false, cause: 'ephemeral-policy' })
+  })
+  test('ephemeral does NOT hijack explicit attach (argsResume=true still resumes)', () => {
+    // attach is an operator action; ephemeral only governs the delivery path.
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(false, true), true, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1', cause: 'attach' })
+  })
 })
 
 describe('idle-reaped marker round-trip', () => {
@@ -535,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
+  })
+})

package/src/lifecycle/queue.ts

@@ -0,0 +1,159 @@
+// Ephemeral serial queue (wake_policy:"ephemeral" M3) — per-peer disk FIFO of
+// pending tasks for a stateless worker. Deliveries to an ephemeral target are
+// NEVER injected into a live session (one task = one clean context window =
+// the whole point of the policy); they are ALWAYS enqueued here, and the drain
+// (drainEphemeralQueue in index.ts) feeds the worker one task per fresh session.
+//
+// Layout: `<stateDir>/<identity>.queue/<seq>` — one JSON file per task
+// ({ task, topic? }), zero-padded numeric names so lexicographic order IS the
+// FIFO order. Durable by construction: the queue survives a daemon restart and
+// is drained by the supervise tick (the same scan that retries a failed wake).
+//
+// Concurrency: the daemon is the main writer, but a direct CLI `iap send`
+// (daemon down) can race it from another process. Enqueue is therefore
+// EXCLUSIVE-CREATE: write a temp file, then linkSync it to the next seq —
+// linkSync fails with EEXIST on a taken name (atomic on POSIX), so two
+// concurrent enqueues can never share a seq; the loser just advances. Content
+// is complete before the link lands (no partial reads).
+//
+// Retry semantics (boris acceptance (b)): the consumer PEEKS (reads without
+// removing), wakes the worker, and removes the item ONLY on READY — a failed
+// wake leaves the task at the head for the next supervise-tick drain. See
+// drainEphemeralQueue.
+
+import { linkSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import type { LifecycleConfig } from './index.ts'
+
+/** One queued task for an ephemeral worker. */
+export interface EphemeralQueueItem {
+  /** The routed envelope — becomes the boot first-message of the fresh session. */
+  task: string
+  /** Optional topic (threading; recorded by the wake as the session topic). */
+  topic?: string
+}
+
+/** A peeked item: the queue position (for the later remove) plus the payload. */
+export interface PeekedQueueItem extends EphemeralQueueItem {
+  seq: string
+}
+
+export function ephemeralQueueDir(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.queue`)
+}
+
+const SEQ_PAD = 6
+
+function listSeqs(dir: string): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return [] // no dir yet → empty queue
+  }
+  // Only the numbered items — temp files (.tmp-*) and strays are not queue entries.
+  return entries.filter(name => /^\d+$/.test(name)).sort()
+}
+
+/** Queue depth (pending tasks). 0 for a missing dir. */
+export function ephemeralQueueDepth(cfg: LifecycleConfig, identity: string): number {
+  return listSeqs(ephemeralQueueDir(cfg, identity)).length
+}
+
+/**
+ * Append a task to the identity's FIFO. Returns the depth AFTER the append
+ * (≥1 — usable as the "qd" observability field). Exclusive-create: safe against
+ * a concurrent enqueue from another process. Throws only on a real FS failure
+ * (the caller surfaces it as a delivery error — an un-enqueued task must NOT be
+ * reported queued).
+ */
+export function enqueueEphemeralTask(
+  cfg: LifecycleConfig,
+  identity: string,
+  item: EphemeralQueueItem,
+): number {
+  const dir = ephemeralQueueDir(cfg, identity)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const tmp = join(dir, `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  writeFileSync(tmp, JSON.stringify({ task: item.task, ...(item.topic ? { topic: item.topic } : {}) }), {
+    mode: 0o600,
+  })
+  try {
+    // Next seq = max existing + 1; on an EEXIST race, advance and retry.
+    let seq = (() => {
+      const seqs = listSeqs(dir)
+      return seqs.length ? parseInt(seqs[seqs.length - 1]!, 10) + 1 : 1
+    })()
+    // Bounded retry: a competitor can win a name at most once per its own enqueue.
+    for (let attempt = 0; attempt < 1000; attempt++, seq++) {
+      const target = join(dir, String(seq).padStart(SEQ_PAD, '0'))
+      try {
+        linkSync(tmp, target) // atomic exclusive-create (EEXIST when taken)
+        return listSeqs(dir).length
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+      }
+    }
+    throw new Error(`ephemeral queue enqueue: could not claim a seq for ${identity} after 1000 attempts`)
+  } finally {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/**
+ * Read the HEAD of the FIFO without removing it (retry semantics: the item is
+ * removed only after the wake went READY — removeEphemeralTask). null on empty.
+ * A corrupt head (unparseable JSON) is dropped with its slot — a poison task
+ * must not wedge the whole queue — and the next item (if any) is returned.
+ */
+export function peekEphemeralTask(cfg: LifecycleConfig, identity: string): PeekedQueueItem | null {
+  const dir = ephemeralQueueDir(cfg, identity)
+  for (const seq of listSeqs(dir)) {
+    const path = join(dir, seq)
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+      if (typeof raw.task === 'string' && raw.task.length > 0) {
+        return { seq, task: raw.task, topic: typeof raw.topic === 'string' ? raw.topic : undefined }
+      }
+    } catch {
+      /* unreadable/corrupt → drop the slot below */
+    }
+    try {
+      rmSync(path, { force: true }) // poison/corrupt item: drop, do not wedge the queue
+    } catch {
+      return null // cannot even drop it — give up this round, retry next tick
+    }
+  }
+  return null
+}
+
+/** Remove a consumed item (after its wake went READY). Idempotent. */
+export function removeEphemeralTask(cfg: LifecycleConfig, identity: string, seq: string): void {
+  try {
+    rmSync(join(ephemeralQueueDir(cfg, identity), seq), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
+/** Identities with a non-empty queue (the supervise-tick drain scan; also the
+ *  drain-on-start surface — the queue is durable across daemon restarts). */
+export function listQueuedIdentities(cfg: LifecycleConfig): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(cfg.stateDir)
+  } catch {
+    return []
+  }
+  const out: string[] = []
+  for (const name of entries) {
+    if (!name.endsWith('.queue')) continue
+    const identity = name.slice(0, -'.queue'.length)
+    if (listSeqs(join(cfg.stateDir, name)).length > 0) out.push(identity)
+  }
+  return out.sort()
+}

package/src/provision/index.ts

@@ -91,6 +91,27 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
     runtimeBin,
     warn: opts.warn,
   })
+  // wake_policy:"ephemeral" sanity (M2 edge cases — warn, don't refuse: the policy
+  // lives in the hand-editable local profile, provision just surfaces the mismatch):
+  //   • + interfaces.telegram: ephemeral WINS in resolveWakeMode (explicit policy
+  //     beats the inferred human type), so a human dialogue channel would die-after-
+  //     reply and never resume — almost certainly a config mistake.
+  //   • + infra (always-on) runtime: launchd KeepAlive owns the session (H4 read-only)
+  //     — the daemon never wakes/reaps it, so the ephemeral policy is INERT.
+  if (profile.wake_policy === 'ephemeral') {
+    if (profile.interfaces?.telegram != null) {
+      opts.warn?.(
+        `peer "${profile.personality}" declares BOTH wake_policy:"ephemeral" AND interfaces.telegram — ` +
+          `ephemeral wins (always-fresh, die-after-reply); a human telegram dialogue should not be ephemeral`,
+      )
+    }
+    if (isInfraRuntime(opts.runtime)) {
+      opts.warn?.(
+        `peer "${profile.personality}" declares wake_policy:"ephemeral" on always-on infra runtime ` +
+          `"${opts.runtime}" — launchd owns the session (H4), the daemon never wakes/reaps it, the policy is inert`,
+      )
+    }
+  }
   // 2) registry entry — without it the daemon does not see the peer (tool-list,
   //    caller resolution, wake-on-miss findPeer all read peers-profiles.json).
   await upsertPeer(

package/src/provision/provision.test.ts

@@ -3,7 +3,7 @@
 // IAPEER_LAUNCHAGENTS_DIR temp dirs so the suite never touches the live fleet.
 
 import { afterEach, describe, expect, test } from 'bun:test'
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { provisionPeer } from './index.ts'
@@ -102,3 +102,59 @@ describe('provisionPeer', () => {
     expect(findPeer(readPeersIndex({ env }), 'timer')?.cwd).toBe(cwd)
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wake_policy:"ephemeral" provision warnings (M2 edge cases — warn, not refuse)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('provisionPeer ephemeral warnings', () => {
+  test('ephemeral + interfaces.telegram → WARN (ephemeral wins; human dialogue should not die-after-reply)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'wtg')
+    // pre-existing profile (provision returns it unchanged) carrying the bad combo
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({
+        personality: 'wtg',
+        runtime: 'claude',
+        intelligence: 'natural',
+        interfaces: { telegram: { user_id: 1 } },
+        wake_policy: 'ephemeral',
+      }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(warns.some(w => /ephemeral/.test(w) && /telegram/.test(w))).toBe(true)
+  })
+
+  test('plain ephemeral worker (claude, no telegram) → NO ephemeral warn', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'weph')
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({ personality: 'weph', runtime: 'claude', wake_policy: 'ephemeral' }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(warns.filter(w => /ephemeral/.test(w))).toEqual([])
+  })
+
+  test('ephemeral + always-on infra runtime → WARN (H4: launchd owns it, the policy is inert)', async () => {
+    const root = mkTmp()
+    const { dir: bindir } = fakeBinDir()
+    const env = envFor(root, bindir)
+    const cwd = join(root, 'winf')
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({ personality: 'winf', runtime: 'notifier', wake_policy: 'ephemeral' }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'notifier', env, warn: m => warns.push(m) })
+    expect(warns.some(w => /ephemeral/.test(w) && /inert|launchd/i.test(w))).toBe(true)
+  })
+})