@agfpd/iapeer 0.2.9 → 0.2.11

package/src/identity/index.ts

@@ -48,6 +48,14 @@ import {
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** Per-peer wake policy. `ephemeral` = stateless worker: every delivery is handled in
+ *  a FRESH session, the peer dies after its turn, and a delivery to a still-live session
+ *  is QUEUED (serial) rather than injected — so each task gets a clean context window.
+ *  Lifecycle-owned (resolveWakeMode forces fresh; superviseTick reaps post-turn; the
+ *  daemon drains the queue on death). Absent = normal warm-on-demand (resume-eligible).
+ *  Enum (not bool) to leave room for future policies. */
+export type WakePolicy = 'ephemeral'
+
 export interface PeerProfile {
   personality: string
   runtime: Runtime
@@ -59,6 +67,8 @@ export interface PeerProfile {
    *  warm). Carries an opening directive and/or a "I'm up" report. */
   initial_prompt?: string
   interfaces?: PeerInterfaces
+  /** Per-peer wake policy (lifecycle-owned). Absent = normal warm-on-demand. */
+  wake_policy?: WakePolicy
 }
 
 // Write shape: intelligence/description optional so a caller can write a profile
@@ -211,6 +221,9 @@ export function readPeerProfile(cwd: string = process.cwd()): PeerProfile | null
       ? { initial_prompt: obj.initial_prompt }
       : {}),
     ...(interfaces ? { interfaces } : {}),
+    // Wake policy — only the known enum value is honored; anything else → omitted
+    // (treated as normal warm-on-demand, never throws on an unknown future value).
+    ...(obj.wake_policy === 'ephemeral' ? { wake_policy: 'ephemeral' as const } : {}),
   }
 }
 

package/src/launch/bootdeliver.test.ts

@@ -0,0 +1,106 @@
+// Ф-#8b: cold-wake boot first-message delivery via load-buffer + bracketed
+// paste-buffer — the SAME byte-path as warm delivery (transport.deliverViaTmux),
+// replacing the old `send-keys -l` retype. Proven hermetically against a REAL
+// tmux (gated like sockdir.test.ts) with a fake tui adapter whose "runtime" is
+// `cat >> <file>`: whatever the boot path injects into the pane lands verbatim in
+// the file, and the ready-gate keys on that file's mtime (the activity proxy).
+//
+// pty note: `cat` reads the pane pty in CANONICAL mode (line-buffered, ~1 KiB
+// line cap on macOS) — real TUIs run raw and have no such cap. The fixture
+// message therefore uses many sub-1-KiB LINES to total multi-KiB; what this test
+// pins is the INJECTION path (one bracketed paste, no option-parsing traps, no
+// key-by-key retype), not the tty discipline.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, readFileSync, rmSync, statSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import { launch } from './index.ts'
+import type { LaunchConfig, LaunchSpec, RuntimeAdapter } from './types.ts'
+
+const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-bootdeliver-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+/** Fake tui adapter: the "runtime" appends its pty input to `recvPath`; the
+ *  activity proxy is that file's mtime (absent → null, exactly like a missing
+ *  transcript), so the boot baseline is 0 and the ready-gate flips on receipt. */
+function catAdapter(recvPath: string): RuntimeAdapter {
+  return {
+    runtime: 'claude', // any tui Runtime — the adapter object itself is what launch consumes
+    kind: 'tui',
+    usesDoctrine: false,
+    deliveryMarkers: { promptGlyphs: [] },
+    buildArgv: () => ['/bin/sh', '-c', `cat >> ${recvPath}`],
+    bootDialogKeys: () => null,
+    isInputReady: () => true,
+    newestActivityMtime: () => {
+      try {
+        return statSync(recvPath).mtimeMs
+      } catch {
+        return null
+      }
+    },
+    permissionDialogActive: () => false,
+    permissionDialogKeys: () => [],
+    resolveResume: () => ({ ok: true }),
+    executeControl: () => null,
+  }
+}
+
+describe('boot first-message delivery (load-buffer + bracketed paste)', () => {
+  test.if(tmuxAvailable)(
+    'a multi-line, dash-leading, multi-KiB first message lands INTACT and launch goes READY',
+    async () => {
+      const root = mkTmp()
+      const recv = join(root, 'received.txt')
+      const sock = join(root, 'tmux-iap-claude-bootd.sock')
+      // The fixture stresses every historical boot-inject trap at once:
+      //   • leading '-'  — the send-keys option-parsing trap (audit #6);
+      //   • quotes/$()/; — shell-metachar corruption if anything re-quoted the body;
+      //   • multi-KiB    — a size send-keys -l replayed key-by-key (8 × ~700 B lines).
+      const firstMessage = [
+        '- dash-leading first line (the send-keys option-parsing trap)',
+        `quotes "double" 'single' and $dollar \`backtick\` ; semicolon`,
+        ...Array.from({ length: 8 }, (_, i) => `${i}:${'x'.repeat(700)}`),
+      ].join('\n')
+      const spec: LaunchSpec = {
+        personality: 'bootd',
+        runtime: 'claude',
+        cwd: root,
+        identity: 'claude-bootd',
+        socketPath: sock,
+        intelligence: 'artificial',
+      }
+      const cfg: LaunchConfig = {
+        claudeBin: 'unused',
+        codexBin: 'unused',
+        sockDir: root,
+        bootDeadlineSecs: 10,
+        readyGateSecs: 8,
+        maxAgeSecs: 120,
+        logDir: join(root, 'logs'),
+      }
+      try {
+        const r = await launch(spec, catAdapter(recv), firstMessage, cfg)
+        expect(r.status).toBe('READY')
+        const got = readFileSync(recv, 'utf8')
+        expect(got).toContain('- dash-leading first line (the send-keys option-parsing trap)')
+        expect(got).toContain(`quotes "double" 'single' and $dollar \`backtick\` ; semicolon`)
+        for (let i = 0; i < 8; i++) expect(got).toContain(`${i}:${'x'.repeat(700)}`)
+      } finally {
+        spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+      }
+    },
+    60000,
+  )
+})

package/src/launch/index.ts

@@ -273,7 +273,8 @@ export const launch: LaunchFn = async (
   }
 
   // (6) BOOT phase (tui) — baseline the activity proxy, answer startup dialogs,
-  //     wait for the input surface, then deliver firstMessage (send-keys -l + Enter).
+  //     wait for the input surface, then deliver firstMessage (load-buffer +
+  //     bracketed paste-buffer + Enter — the SAME byte-path as warm delivery).
   //     An EMPTY firstMessage is a BARE bring-up (folder-launch with no seed, or an
   //     attach-resume that carries no message): reach the input surface and return
   //     READY — there is no message to deliver and nothing to ready-gate on (the
@@ -297,12 +298,31 @@ export const launch: LaunchFn = async (
     }
     if (adapter.isInputReady(pane)) {
       if (!hasMessage) return ready(identity) // bare bring-up — session up, no message
-      // `--` terminates tmux option parsing (audit #6): without it a firstMessage that
-      // starts with '-' (e.g. a task opening with a markdown bullet) is mis-parsed as a
-      // send-keys flag, losing the boot message and failing the wake with a wrong reason.
-      tmux(sock, 'send-keys', '-t', identity, '-l', '--', firstMessage)
+      // Boot delivery = load-buffer → paste-buffer -p → Enter (Ф-#8b hardening):
+      // the SAME mechanism warm delivery uses (transport.deliverViaTmux), replacing
+      // the old `send-keys -l`. send-keys retypes the message as literal keystrokes —
+      // a multi-KB envelope replays key-by-key through the pty input buffer, and the
+      // two paths could diverge (a message that survives warm delivery could be
+      // mangled at cold-wake). load-buffer hands the TUI the whole envelope as ONE
+      // bracketed paste, byte-identical to the warm path. A load/paste hiccup →
+      // retry on the next boot iteration (previously the send-keys result was
+      // ignored and a failed inject was declared delivered, failing the wake later
+      // with the wrong reason at the ready-gate).
+      const bufferName = `iapeer-boot-${process.pid}-${Date.now()}`
+      const load = spawnSync(
+        'tmux',
+        ['-S', sock, 'load-buffer', '-b', bufferName, '-'],
+        { input: firstMessage, encoding: 'utf8' },
+      )
+      if (load.status !== 0) continue
+      const paste = tmux(sock, 'paste-buffer', '-p', '-b', bufferName, '-t', identity)
+      if (!paste.ok) {
+        tmux(sock, 'delete-buffer', '-b', bufferName)
+        continue
+      }
       await sleep(300)
       tmux(sock, 'send-keys', '-t', identity, 'Enter')
+      tmux(sock, 'delete-buffer', '-b', bufferName)
       delivered = true
     }
   }

package/src/launch/types.ts

@@ -312,7 +312,8 @@ export interface LaunchResult {
  * Bring up ONE session: pre-clean stale tmux server → tmux new-session -d with
  * adapter.buildArgv → pipe-pane → session self-TTL → boot (answer dialogs via
  * adapter, wait for adapter.isInputReady, deliver the first message via
- * send-keys -l) → ready-gate (adapter.newestActivityMtime strictly advances).
+ * load-buffer + bracketed paste — the same byte-path as warm delivery) →
+ * ready-gate (adapter.newestActivityMtime strictly advances).
  * Runtime-agnostic; all specifics come from the adapter. Returns READY/FAILED.
  * `firstMessage` (the task / routed envelope) is delivered as the boot message;
  * a router runtime skips the TUI boot/ready phases.

package/src/lifecycle/eventlog.ts

@@ -19,17 +19,22 @@
 //   • Best-effort throughout: a write/rotate failure is swallowed. Observability
 //     must never take down the daemon or fail a wake/reap.
 //
-// Lifted-out-able: the rotate-append primitive is path-parameterized, so the
-// adjacent "log rotation" phase can promote it to storage/ and point other log
-// producers at it without touching this module's call sites.
+// The rotate-append primitive was PROMOTED to storage/rotatelog.ts (as this header
+// anticipated) when the daemon's per-delivery log became the second producer
+// (Ф-#8a). This module keeps its public API (appendLifecycleEvent + the logfmt
+// helpers, re-exported) so its call sites and tests are untouched; only the
+// implementation now lives in storage.
 
-import { appendFileSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
 import { join } from 'path'
+import {
+  DEFAULT_LOG_KEEP,
+  DEFAULT_LOG_MAX_BYTES,
+  appendRotatedEvent,
+} from '../storage/rotatelog.ts'
 
-/** Default cap per lifecycle.log file before it rotates to lifecycle.log.1. */
-const DEFAULT_MAX_BYTES = 5 * 1024 * 1024 // 5 MiB
-/** Default number of rotated backups kept (lifecycle.log.1 … .KEEP). */
-const DEFAULT_KEEP = 5
+// Re-export the logfmt helpers — historical home of these (consumers import them
+// from eventlog; the implementation moved to storage/rotatelog.ts).
+export { fmtValue, formatEventLine } from '../storage/rotatelog.ts'
 
 /** The durable lifecycle decision log inside `logDir` (cfg.eventLogDir). */
 export function lifecycleLogPath(logDir: string): string {
@@ -49,56 +54,6 @@ export function superviseLogVerbose(env: NodeJS.ProcessEnv = process.env): boole
   return v === '1' || v === 'true' || v === 'yes'
 }
 
-/** logfmt value: bare token, or double-quoted with `"`/`\` escaped, when it
- *  contains whitespace, `=` or `"`. Empty string → `""`. */
-export function fmtValue(v: string | number): string {
-  const s = String(v)
-  if (s === '') return '""'
-  if (/[\s"=]/.test(s)) return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
-  return s
-}
-
-/** Render one logfmt line (ts first, then fields in insertion order; undefined
- *  fields are skipped). No trailing newline. Pure — unit-testable. */
-export function formatEventLine(nowMs: number, fields: Record<string, string | number | undefined>): string {
-  const parts = [`ts=${new Date(nowMs).toISOString()}`]
-  for (const [k, v] of Object.entries(fields)) {
-    if (v === undefined) continue
-    parts.push(`${k}=${fmtValue(v)}`)
-  }
-  return parts.join(' ')
-}
-
-/** Size-rotate `path` (and its .1 … .keep backups) when the next line would push
- *  it over `maxBytes`. Drops the oldest, shifts each backup up by one, base→.1.
- *  Best-effort: any fs hiccup leaves the chain as-is (we then just append). */
-function rotateIfNeeded(path: string, lineLen: number, maxBytes: number, keep: number): void {
-  let size: number
-  try {
-    size = statSync(path).size
-  } catch {
-    return // no file yet → nothing to rotate
-  }
-  if (size + lineLen <= maxBytes) return
-  try {
-    rmSync(`${path}.${keep}`, { force: true })
-  } catch {
-    /* best-effort */
-  }
-  for (let i = keep - 1; i >= 1; i--) {
-    try {
-      renameSync(`${path}.${i}`, `${path}.${i + 1}`)
-    } catch {
-      /* that backup may not exist yet */
-    }
-  }
-  try {
-    renameSync(path, `${path}.1`)
-  } catch {
-    /* best-effort */
-  }
-}
-
 export interface AppendEventOptions {
   /** Reads the rotation knobs IAPEER_LIFECYCLE_LOG_MAX_BYTES / _KEEP. */
   env?: NodeJS.ProcessEnv
@@ -119,15 +74,9 @@ export function appendLifecycleEvent(
 ): void {
   if (!logDir) return
   const env = opts.env ?? process.env
-  const path = lifecycleLogPath(logDir)
-  const line = `${formatEventLine(opts.nowMs ?? Date.now(), fields)}\n`
-  const maxBytes = envPosInt(env.IAPEER_LIFECYCLE_LOG_MAX_BYTES, DEFAULT_MAX_BYTES)
-  const keep = envPosInt(env.IAPEER_LIFECYCLE_LOG_KEEP, DEFAULT_KEEP)
-  try {
-    mkdirSync(logDir, { recursive: true, mode: 0o700 })
-    rotateIfNeeded(path, line.length, maxBytes, keep)
-    appendFileSync(path, line, { mode: 0o600 })
-  } catch {
-    /* observability is best-effort — a log failure must never break a wake/reap */
-  }
+  appendRotatedEvent(lifecycleLogPath(logDir), fields, {
+    nowMs: opts.nowMs,
+    maxBytes: envPosInt(env.IAPEER_LIFECYCLE_LOG_MAX_BYTES, DEFAULT_LOG_MAX_BYTES),
+    keep: envPosInt(env.IAPEER_LIFECYCLE_LOG_KEEP, DEFAULT_LOG_KEEP),
+  })
 }

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`)
 }
@@ -359,6 +407,22 @@ function isHumanConversational(cwd: string): boolean {
   }
 }
 
+/**
+ * True iff the peer of `cwd` declares `wake_policy: "ephemeral"` — a stateless worker
+ * that ALWAYS wakes fresh on delivery (never resume), dies after its turn, and whose
+ * warm-session deliveries are queued (M3). A profile read hiccup → not-ephemeral (safe
+ * default: normal warm-on-demand). When BOTH ephemeral and a telegram interface are
+ * set, ephemeral WINS in resolveWakeMode (explicit policy beats the inferred human
+ * type) — provision warns on that combination; it should not occur for real workers.
+ */
+export function isEphemeralPeer(cwd: string): boolean {
+  try {
+    return readPeerProfile(cwd)?.wake_policy === 'ephemeral'
+  } catch {
+    return false
+  }
+}
+
 /**
  * Decide resume vs fresh on a wake (TARGET redesign). Branch order:
  *   1. argsResume === false (folder-launch `iapeer <runtime>`) → FRESH.
@@ -390,6 +454,14 @@ export function resolveWakeMode(
     return { resume: true, resumeRef: r.ref, cause: 'attach' }
   }
   // 3. default (a message woke a dead/asleep peer): decide by the death cause.
+  // 3-ephemeral (M1): a stateless worker ALWAYS wakes fresh on delivery — never resume,
+  // regardless of death cause or topic. Its clean-window-per-task is the whole point.
+  // Consume a stray .idle-reaped marker so it does not accumulate (it has no effect for
+  // an ephemeral peer, which never resumes, but keep state tidy).
+  if (isEphemeralPeer(cwd)) {
+    clearIdleReaped(cfg, identity)
+    return { resume: false, cause: 'ephemeral-policy' }
+  }
   // 3a. NOT idle-reaped → it died on its own (crash / self-close) → clean FRESH.
   if (!hasIdleReaped(cfg, identity)) return { resume: false, cause: 'crash-or-self-close' }
   // 3b. idle-reaped → resume-eligible. Consume the marker now (it has done its job).
@@ -831,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() ?? '')
@@ -870,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
 }
@@ -908,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.
@@ -939,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 =
@@ -991,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