@agfpd/iapeer 0.2.10 → 0.2.11

package/package.json

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

package/src/daemon/daemon.test.ts

@@ -106,13 +106,12 @@ describe('per-delivery outcome log (Ф-#8a — delivery.log)', () => {
   test('with deliveryLogDir wired: ONE logfmt outcome line per attempt, metadata only', async () => {
     const logDir = join(root, 'logs', 'iapeer')
     const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
-    await callTool(caller, 'send_to_peer', { personality: 'offlinepeer', message: 'hi' }, undefined, logDir)
+    await callTool(caller, 'send_to_peer', { personality: 'offlinepeer', message: 'hi' }, { deliveryLogDir: logDir })
     await callTool(
       caller,
       'send_to_peer',
       { personality: 'nobody', message: 'hello there', topic: 'probe topic' },
-      undefined,
-      logDir,
+      { deliveryLogDir: logDir },
     )
     const lines = readFileSync(join(logDir, 'delivery.log'), 'utf8').trim().split('\n')
     expect(lines.length).toBe(2)
@@ -138,3 +137,117 @@ describe('per-delivery outcome log (Ф-#8a — delivery.log)', () => {
     expect(existsSync(join(probeDir, 'delivery.log'))).toBe(false)
   })
 })
+
+describe('onDelivered hook (M2 arm-on-outbound seam)', () => {
+  test('NOT fired on a FAILED delivery — a worker whose reply did not land must not be armed', async () => {
+    const fired: string[] = []
+    const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
+    // offline target, no wake → routeSend fails → hook must stay silent
+    const r = await callTool(
+      caller,
+      'send_to_peer',
+      { personality: 'offlinepeer', message: 'hi' },
+      { onDelivered: c => fired.push(c.address) },
+    )
+    expect(r.isError).toBe(true)
+    expect(fired).toEqual([])
+  })
+
+  test('a throwing hook never fails the tool call (fail-safe)', async () => {
+    const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
+    // even on the error path nothing throws; the ok-path guard is the same try/catch
+    const r = await callTool(
+      caller,
+      'send_to_peer',
+      { personality: 'offlinepeer', message: 'hi' },
+      {
+        onDelivered: () => {
+          throw new Error('hook boom')
+        },
+      },
+    )
+    expect(r.isError).toBe(true) // the routeSend offline error, NOT the hook's
+    expect(r.content[0].text).toMatch(/offline/)
+  })
+})
+
+describe('ephemeral serial-queue seam (M3)', () => {
+  test('ephemeral TARGET → deliver() handles it (no live/miss routing); queued result + delivery.log queued/qd', async () => {
+    const logDir = join(root, 'logs', 'm3')
+    const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
+    const delivered: string[] = []
+    const r = await callTool(
+      caller,
+      'send_to_peer',
+      { personality: 'offlinepeer', message: 'job for the worker', topic: 'job-1' },
+      {
+        deliveryLogDir: logDir,
+        ephemeral: {
+          isEphemeral: cwd => {
+            delivered.push(`checked:${cwd}`)
+            return true // offlinepeer plays an ephemeral worker
+          },
+          deliver: async ({ peer, envelope, topic }) => {
+            delivered.push(`deliver:${peer.personality}:${topic}`)
+            expect(envelope).toContain('job for the worker') // the routed envelope, not the raw body
+            return {
+              ok: true,
+              value: {
+                ok: true as const,
+                delivered_to: { personality: peer.personality, runtime: 'claude' },
+                woke: false,
+                queued: true,
+                queueDepth: 2,
+                ts: 'now',
+              },
+            }
+          },
+        },
+      },
+    )
+    expect(r.isError).toBeUndefined()
+    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('qd=2')
+    expect(line).toContain('ok=true')
+  })
+
+  test('ephemeral self-send is refused up front (a worker enqueueing itself would deadlock its reap)', async () => {
+    const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
+    const r = await callTool(
+      caller,
+      'send_to_peer',
+      { personality: 'boris', message: 'to myself' },
+      {
+        ephemeral: {
+          isEphemeral: () => true,
+          deliver: async () => {
+            throw new Error('must not be reached')
+          },
+        },
+      },
+    )
+    expect(r.isError).toBe(true)
+    expect(r.content[0].text).toMatch(/cannot send to self/)
+  })
+
+  test('non-ephemeral target ignores the seam (normal offline path)', async () => {
+    const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
+    const r = await callTool(
+      caller,
+      'send_to_peer',
+      { personality: 'offlinepeer', message: 'hi' },
+      {
+        ephemeral: {
+          isEphemeral: () => false,
+          deliver: async () => {
+            throw new Error('must not be reached')
+          },
+        },
+      },
+    )
+    expect(r.isError).toBe(true)
+    expect(r.content[0].text).toMatch(/offline/) // took the ordinary miss path
+  })
+})

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 SendToPeerInput, type WakeFn } from '../transport/index.ts'
+import { routeSend, type EphemeralRouteDeps, type SendToPeerInput, type WakeFn } from '../transport/index.ts'
 import { appendDeliveryEvent } from './deliverylog.ts'
 
 export const CALLER_HEADER = 'x-iapeer-identity'
@@ -172,12 +172,29 @@ function errResult(text: string): ToolResult {
   return { isError: true, content: [{ type: 'text', text }] }
 }
 
+/** Injected seams for callTool — all OPTIONAL, all wired by the composition point
+ *  (daemon/main.ts); library/test callers omit them and stay hermetic. */
+export interface CallToolDeps {
+  /** Wake-on-miss primitive (Ф2) — see StartDaemonOptions.wake. */
+  wake?: WakeFn
+  /** Per-delivery outcome log dir (Ф-#8a) — see StartDaemonOptions.deliveryLogDir. */
+  deliveryLogDir?: string
+  /** Fired AFTER a delivery resolved ok, with the request-resolved CALLER (the
+   *  sender). The wake_policy:ephemeral M2 arm-on-outbound seam: the composition
+   *  point marks an ephemeral caller as armed (its single reply is out → quiet-reap
+   *  eligible). Kept as an injected hook so the daemon never imports lifecycle
+   *  (layering: main.ts is the only place transport meets lifecycle). Failures are
+   *  swallowed — a hook must never fail a delivery that already succeeded. */
+  onDelivered?: (caller: ResolvedCaller) => void
+  /** Ephemeral-target serial-queue delivery (M3) — see transport.EphemeralRouteDeps. */
+  ephemeral?: EphemeralRouteDeps
+}
+
 export async function callTool(
   caller: ResolvedCaller,
   name: string,
   args: Record<string, unknown>,
-  wake?: WakeFn,
-  deliveryLogDir?: string,
+  deps: CallToolDeps = {},
 ): Promise<ToolResult> {
   if (name === 'send_to_peer') {
     const input: SendToPeerInput = {
@@ -188,13 +205,13 @@ 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 })
+    const sent = await routeSend(caller, input, { wake: deps.wake, ephemeral: deps.ephemeral })
     // Ф-#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
     // disk (the gap the 09.06 investigation hit). No-op when no dir is wired
     // (library/test daemons); appendDeliveryEvent itself never throws.
-    appendDeliveryEvent(deliveryLogDir, {
+    appendDeliveryEvent(deps.deliveryLogDir, {
       ev: 'delivery',
       caller: caller.address,
       to: input.personality,
@@ -202,12 +219,27 @@ export async function callTool(
       ok: String(sent.ok),
       via: sent.ok ? `${sent.value.delivered_to.runtime}-${sent.value.delivered_to.personality}` : undefined,
       woke: sent.ok ? String(sent.value.woke) : undefined,
+      // 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,
+      qd: sent.ok ? sent.value.queueDepth : undefined,
       ms: Date.now() - t0,
       len: input.message.length,
       att: input.attachments?.length || undefined,
       topic: input.topic,
       err: sent.ok ? undefined : sent.error.message,
     })
+    // M2 arm-on-outbound: ONLY on an ok outcome — a failed send means the caller's
+    // 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) {
+      try {
+        deps.onDelivered?.(caller)
+      } catch {
+        /* a post-delivery hook must never fail the delivery */
+      }
+    }
     return sent.ok ? jsonResult(sent.value) : errResult(sent.error.message)
   }
   return errResult(`unknown tool: ${name}`)
@@ -223,7 +255,7 @@ function headerFromRequestInfo(extra: { requestInfo?: { headers?: Record<string,
   return Array.isArray(value) ? (value[0] as string) : (value as string | undefined)
 }
 
-export function createMcpServer(wake?: WakeFn, deliveryLogDir?: string): Server {
+export function createMcpServer(deps: CallToolDeps = {}): Server {
   const server = new Server(SERVER_INFO, { capabilities: { tools: {} } })
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listTools(readPeersIndex()) }))
@@ -246,7 +278,7 @@ export function createMcpServer(wake?: WakeFn, deliveryLogDir?: string): Server
       process.stderr.write(`[iapeer-daemon] tools/call tool=${req.params.name} caller=${caller.address}\n`)
     }
     const args = (req.params.arguments ?? {}) as Record<string, unknown>
-    return (await callTool(caller, req.params.name, args, wake, deliveryLogDir)) as CallToolResult
+    return (await callTool(caller, req.params.name, args, deps)) as CallToolResult
   })
 
   return server
@@ -322,6 +354,19 @@ export interface StartDaemonOptions extends StorageOptions {
    * delivery.log sits next to lifecycle.log under the SAME cfg-resolved root.
    */
   deliveryLogDir?: string
+  /**
+   * Post-delivery hook (wake_policy:ephemeral M2 arm-on-outbound seam) — fired with
+   * the request-resolved CALLER after each delivery that resolved ok. See
+   * CallToolDeps.onDelivered. OFF by default; the production main wires the
+   * lifecycle arm (an ephemeral caller's ok outbound ⇒ armed for quiet-reap).
+   */
+  onDelivered?: (caller: ResolvedCaller) => void
+  /**
+   * Ephemeral-target serial-queue delivery (wake_policy:"ephemeral" M3) — see
+   * transport.EphemeralRouteDeps. OFF by default; the production main wires the
+   * lifecycle queue + drain (makeEphemeralRouteDeps).
+   */
+  ephemeral?: EphemeralRouteDeps
   /**
    * Write the discovery file (router.json) at <root>/state/iapeer/router.json with
    * the active addresses `{sock, tcp}` — atomically on listen, removed on close.
@@ -349,7 +394,12 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
       res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32001, message: 'unauthorized' } }))
       return
     }
-    const server = createMcpServer(opts.wake, opts.deliveryLogDir)
+    const server = createMcpServer({
+      wake: opts.wake,
+      deliveryLogDir: opts.deliveryLogDir,
+      onDelivered: opts.onDelivered,
+      ephemeral: opts.ephemeral,
+    })
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
     res.on('close', () => {
       transport.close()

package/src/daemon/main.test.ts

@@ -13,10 +13,19 @@ import {
   buildDaemonPlistSpec,
   daemonPlistPath,
   installDaemonPlist,
+  makeArmEphemeralOnDelivered,
+  makeEphemeralRouteDeps,
   startConfiguredDaemon,
   DEFAULT_DAEMON_PORT,
 } from './main.ts'
 import { daemonDiscoveryPath, defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
+import {
+  ephemeralQueueDepth,
+  hasEphemeralArmed,
+  peekEphemeralTask,
+  type LifecycleConfig,
+} from '../lifecycle/index.ts'
+import type { ResolvedCaller } from '../identity/index.ts'
 import { isFoundationOwnedPlist } from '../launch/index.ts'
 import { DAEMON_PLIST_LABEL } from '../core/constants.ts'
 
@@ -192,3 +201,106 @@ describe('dual-listen + router.json discovery', () => {
     }
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wake_policy:ephemeral M2 — makeArmEphemeralOnDelivered (the arm-on-outbound
+// composition: ephemeral caller's ok send ⇒ .ephemeral-armed for its identity)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('makeArmEphemeralOnDelivered (M2 arm-on-outbound)', () => {
+  function caller(cwd: string): ResolvedCaller {
+    return {
+      personality: 'w',
+      runtime: 'claude',
+      address: 'claude-w',
+      description: '',
+      intelligence: 'artificial',
+      cwd,
+      record: { personality: 'w', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'artificial', cwd },
+    } as ResolvedCaller
+  }
+
+  test('EPHEMERAL caller → armed for the CALLER identity; plain caller → no-op', () => {
+    const stateDir = join(mkTmp(), 'lifecycle')
+    const cfg = { stateDir } as LifecycleConfig
+    const arm = makeArmEphemeralOnDelivered(cfg)
+    // ephemeral worker cwd
+    const eph = mkTmp()
+    mkdirSync(join(eph, '.iapeer'), { recursive: true })
+    writeFileSync(
+      join(eph, '.iapeer', 'peer-profile.json'),
+      JSON.stringify({ personality: 'w', runtime: 'claude', wake_policy: 'ephemeral' }),
+    )
+    arm(caller(eph))
+    expect(hasEphemeralArmed(cfg, 'claude-w')).toBe(true)
+    // plain peer cwd (no wake_policy) → never armed
+    const plainCfg = { stateDir: join(mkTmp(), 'lifecycle') } as LifecycleConfig
+    const plain = mkTmp()
+    mkdirSync(join(plain, '.iapeer'), { recursive: true })
+    writeFileSync(
+      join(plain, '.iapeer', 'peer-profile.json'),
+      JSON.stringify({ personality: 'w', runtime: 'claude' }),
+    )
+    makeArmEphemeralOnDelivered(plainCfg)(caller(plain))
+    expect(hasEphemeralArmed(plainCfg, 'claude-w')).toBe(false)
+  })
+
+  test('missing profile / unreadable cwd → no-op, never throws (best-effort)', () => {
+    const cfg = { stateDir: join(mkTmp(), 'lifecycle') } as LifecycleConfig
+    const arm = makeArmEphemeralOnDelivered(cfg)
+    expect(() => arm(caller('/tmp/no-such-peer-cwd-anywhere'))).not.toThrow()
+    expect(hasEphemeralArmed(cfg, 'claude-w')).toBe(false)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wake_policy:"ephemeral" M3 — makeEphemeralRouteDeps (enqueue + async drain kick)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('makeEphemeralRouteDeps (M3 serial-queue composition)', () => {
+  const workerPeer = {
+    personality: 'w',
+    runtime: 'claude' as const,
+    runtimes: ['claude' as const],
+    description: '',
+    intelligence: 'artificial' as const,
+    cwd: '/tmp/w',
+  }
+
+  test('deliver = enqueue to disk + fast {queued, qd} ack + drain kick (NOT awaited wake)', async () => {
+    const stateDir = join(mkTmp(), 'lifecycle')
+    const cfg = { stateDir } as LifecycleConfig
+    const kicks: string[] = []
+    const deps = makeEphemeralRouteDeps(cfg, {} as NodeJS.ProcessEnv, (p, rt) => kicks.push(`${rt}-${p}`))
+
+    const r1 = await deps.deliver({ peer: workerPeer, envelope: '<iap>task one</iap>', topic: 't1' })
+    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.queueDepth).toBe(1)
+    expect(r1.ok && r1.value.woke).toBe(false)
+    expect(r2.ok && r2.value.queueDepth).toBe(2)
+    expect(kicks).toEqual(['claude-w', 'claude-w']) // drain kicked per enqueue
+    // durable FIFO on disk, head intact
+    expect(ephemeralQueueDepth(cfg, 'claude-w')).toBe(2)
+    expect(peekEphemeralTask(cfg, 'claude-w')).toMatchObject({ task: '<iap>task one</iap>', topic: 't1' })
+  })
+
+  test('enqueue failure → fail-loud delivery error (never a false queued ack)', async () => {
+    const root = mkTmp()
+    const blocker = join(root, 'state-is-a-file')
+    writeFileSync(blocker, 'not a dir')
+    const cfg = { stateDir: join(blocker, 'lifecycle') } as LifecycleConfig // mkdir must fail
+    const deps = makeEphemeralRouteDeps(cfg, {} as NodeJS.ProcessEnv, () => {})
+    const r = await deps.deliver({ peer: workerPeer, envelope: 'x' })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error.message).toMatch(/enqueue failed/)
+  })
+
+  test('runtime override resolves through the registry gate (undeclared → fail-loud)', async () => {
+    const cfg = { stateDir: join(mkTmp(), 'lifecycle') } as LifecycleConfig
+    const deps = makeEphemeralRouteDeps(cfg, {} as NodeJS.ProcessEnv, () => {})
+    const r = await deps.deliver({ peer: workerPeer, envelope: 'x', runtime: 'codex' })
+    expect(r.ok).toBe(false) // 'codex' is not declared for this worker
+  })
+})

package/src/daemon/main.ts

@@ -29,13 +29,22 @@ import {
 } from '../launch/launchd.ts'
 import type { LaunchdPlistSpec } from '../launch/launchd.ts'
 import {
+  drainAllEphemeralQueues,
+  drainEphemeralQueue,
+  enqueueEphemeralTask,
+  isEphemeralPeer,
   loadLifecycleConfig,
   processEagerRelaunches,
+  resolveWakeRuntime,
+  setEphemeralArmed,
   superviseTick,
   wakeOrSpawn,
   type LifecycleConfig,
 } from '../lifecycle/index.ts'
-import type { WakeFn, WakeOutcome, WakeRequest } from '../transport/index.ts'
+import { buildProcessAddress } from '../core/socket.ts'
+import { err, ok } from '../core/errors.ts'
+import type { ResolvedCaller } from '../identity/index.ts'
+import type { EphemeralRouteDeps, WakeFn, WakeOutcome, WakeRequest } from '../transport/index.ts'
 import { iapeerBinPath } from '../install/index.ts'
 import { defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
 
@@ -68,6 +77,72 @@ export function makeWakeFn(cfg: LifecycleConfig, env: NodeJS.ProcessEnv): WakeFn
     )
 }
 
+/**
+ * wake_policy:ephemeral M2 — the arm-on-outbound composition (the ONE place the
+ * daemon's onDelivered seam meets lifecycle, like makeWakeFn for wake). An
+ * ephemeral worker sends exactly ONE outbound — its final reply (ADR-006: no
+ * intermediate send_to_peer) — so "this caller's send was delivered ok" ⇒ the
+ * task is answered ⇒ arm the quiet-reap marker for the caller's identity.
+ * Non-ephemeral callers (the profile read keys on the caller's registry cwd) are
+ * a no-op, so the hook is safe to run on EVERY delivery. Best-effort: an arm
+ * failure must never fail the already-succeeded delivery (superviseTick's idle
+ * bound still reaps an unarmed worker eventually).
+ */
+export function makeArmEphemeralOnDelivered(cfg: LifecycleConfig): (caller: ResolvedCaller) => void {
+  return caller => {
+    try {
+      if (caller.cwd && isEphemeralPeer(caller.cwd)) setEphemeralArmed(cfg, caller.address)
+    } catch {
+      /* arming is best-effort */
+    }
+  }
+}
+
+/**
+ * wake_policy:"ephemeral" M3 — the serial-queue delivery composition (the third
+ * lifecycle⇆transport seam after makeWakeFn / makeArmEphemeralOnDelivered).
+ * deliver = enqueue (exclusive-create FIFO) → fast `{queued:true, qd}` ack →
+ * ASYNC drain kick (deliberately not awaited: the wake takes ~30-60s and the
+ * sender's substantive answer is the worker's own reply — FaaS, ADR-006). A
+ * failed kick is not a lost task: the supervise-tick drain scan retries every
+ * non-empty queue without a live session. An enqueue FAILURE is a delivery
+ * error (fail-loud) — a task that did not reach disk must never be acked queued.
+ * `kick` is injectable for tests; default drains the real queue.
+ */
+export function makeEphemeralRouteDeps(
+  cfg: LifecycleConfig,
+  env: NodeJS.ProcessEnv,
+  kick: (personality: string, runtime: Parameters<typeof drainEphemeralQueue>[2]) => void = (p, rt) => {
+    void drainEphemeralQueue(cfg, p, rt, { env }).catch(() => {})
+  },
+): EphemeralRouteDeps {
+  return {
+    isEphemeral: cwd => isEphemeralPeer(cwd),
+    deliver: async ({ peer, envelope, topic, runtime }) => {
+      const rt = resolveWakeRuntime(runtime, peer)
+      if (!rt.ok) return rt
+      const identity = buildProcessAddress(rt.value, peer.personality)
+      let depth: number
+      try {
+        depth = enqueueEphemeralTask(cfg, identity, { task: envelope, topic })
+      } catch (e) {
+        return err(
+          `ephemeral enqueue failed for "${peer.personality}": ${e instanceof Error ? e.message : String(e)}; message NOT queued`,
+        )
+      }
+      kick(peer.personality, rt.value)
+      return ok({
+        ok: true as const,
+        delivered_to: { personality: peer.personality, runtime: rt.value },
+        woke: false,
+        queued: true,
+        queueDepth: depth,
+        ts: new Date().toISOString(),
+      })
+    },
+  }
+}
+
 export interface ConfiguredDaemonOptions {
   /** TCP loopback port (default DEFAULT_DAEMON_PORT). */
   port?: number
@@ -97,6 +172,12 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
   const bearerToken = opts.bearerToken ?? (env.IAPEER_BEARER_TOKEN?.trim() || undefined)
   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),
+    // M3 serial queue (see makeEphemeralRouteDeps): ephemeral TARGET ⇒ enqueue +
+    // async drain. No-op for every other target.
+    ephemeral: makeEphemeralRouteDeps(cfg, env),
     supervise: {
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
       // idle-reap / zombie-sweep, THEN the eager fresh re-launch for any peer whose
@@ -109,6 +190,11 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
       tick: async () => {
         const outcomes = superviseTick(cfg, { env })
         await processEagerRelaunches(cfg, outcomes, { env })
+        // M3 drain scan — ONE mechanism for the whole serial-queue loop: feeds the
+        // next task right after a reaped-ephemeral (same tick), drains on daemon
+        // start (durable queue), and RETRIES a failed wake (the item stayed at the
+        // head). Identities without a queue or with a live session are no-ops.
+        await drainAllEphemeralQueues(cfg, { env })
       },
     },
     bearerToken,