@agfpd/iapeer 0.2.8 → 0.2.10

package/package.json

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

package/src/daemon/daemon.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
-import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import {
@@ -101,3 +101,40 @@ describe('callTool (no wake passed → Ф1 offline behaviour, never spawns)', ()
     expect((await callTool(caller, 'bogus', {})).isError).toBe(true)
   })
 })
+
+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: 'nobody', message: 'hello there', topic: 'probe topic' },
+      undefined,
+      logDir,
+    )
+    const lines = readFileSync(join(logDir, 'delivery.log'), 'utf8').trim().split('\n')
+    expect(lines.length).toBe(2)
+    // attempt 1: known-but-offline peer (no wake wired → Ф1 explicit offline)
+    expect(lines[0]).toContain('ev=delivery')
+    expect(lines[0]).toContain('caller=claude-boris')
+    expect(lines[0]).toContain('to=offlinepeer')
+    expect(lines[0]).toContain('ok=false')
+    expect(lines[0]).toMatch(/err=".*offline.*"/)
+    expect(lines[0]).toContain('len=2') // body length, NEVER the body itself
+    expect(lines[0]).not.toContain('hi"') // the message text must not leak
+    // attempt 2: unknown peer — validation failures are recorded too
+    expect(lines[1]).toContain('to=nobody')
+    expect(lines[1]).toContain('ok=false')
+    expect(lines[1]).toContain('topic="probe topic"')
+    expect(lines[1]).toContain('len=11')
+  })
+
+  test('without deliveryLogDir (default): nothing is written — library/test daemons stay hermetic', async () => {
+    const probeDir = join(root, 'logs', 'unwired')
+    const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
+    await callTool(caller, 'send_to_peer', { personality: 'offlinepeer', message: 'hi' })
+    expect(existsSync(join(probeDir, 'delivery.log'))).toBe(false)
+  })
+})

package/src/daemon/deliverylog.ts

@@ -0,0 +1,64 @@
+// Per-delivery outcome log — the daemon's DURABLE trace of EVERY send_to_peer it
+// routes (Ф-#8a transport hardening). This closes the observability gap the
+// 09.06 long-message investigation hit: a sender held an `ok:true` while the
+// recipient never saw the message, and there was NO daemon-side record of what
+// routeSend actually decided (hit/miss, woke, error) to reconstruct the path.
+// With this log, the NEXT suspected loss is answerable from disk: one logfmt
+// line per delivery attempt — who sent, to whom, how it resolved, how long it
+// took — delivery.log, sibling to lifecycle.log / exits.log (where the
+// investigator already looks).
+//
+// What is logged: routing METADATA only (caller, target, outcome, sizes, topic)
+// — never the message body (peer traffic stays out of the foundation's logs;
+// length is enough to correlate with the sender's account).
+//
+// Same class as lifecycle.log ("встроенная ротация", Фаза — Ротация логов
+// iapeer): written by OUR code → rotates itself in the writer, via the shared
+// storage/rotatelog primitive. The dir is passed IN by the composition point
+// (daemon/main.ts routes cfg.eventLogDir), NEVER re-resolved from env here — a
+// falsy dir → no-op, so library/test callers of startDaemon stay hermetic by
+// default (same opt-in pattern as the discovery file).
+
+import { join } from 'path'
+import {
+  DEFAULT_LOG_KEEP,
+  DEFAULT_LOG_MAX_BYTES,
+  appendRotatedEvent,
+} from '../storage/rotatelog.ts'
+
+/** The per-delivery outcome log inside `logDir` (sibling to lifecycle.log). */
+export function deliveryLogPath(logDir: string): string {
+  return join(logDir, 'delivery.log')
+}
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+export interface AppendDeliveryOptions {
+  /** Reads the rotation knobs IAPEER_DELIVERY_LOG_MAX_BYTES / _KEEP. */
+  env?: NodeJS.ProcessEnv
+  /** Stamp the line with this epoch-ms. Default Date.now(). */
+  nowMs?: number
+}
+
+/**
+ * Append one delivery outcome line into `logDir`/delivery.log. A falsy `logDir`
+ * is a no-op (the default for library/test daemons — production main passes the
+ * cfg-resolved dir). Fully best-effort — never throws; logging must never fail
+ * a delivery.
+ */
+export function appendDeliveryEvent(
+  logDir: string | undefined,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendDeliveryOptions = {},
+): void {
+  if (!logDir) return
+  const env = opts.env ?? process.env
+  appendRotatedEvent(deliveryLogPath(logDir), fields, {
+    nowMs: opts.nowMs,
+    maxBytes: envPosInt(env.IAPEER_DELIVERY_LOG_MAX_BYTES, DEFAULT_LOG_MAX_BYTES),
+    keep: envPosInt(env.IAPEER_DELIVERY_LOG_KEEP, DEFAULT_LOG_KEEP),
+  })
+}

package/src/daemon/index.ts

@@ -44,6 +44,7 @@ import { pluginStateDir, writeFileAtomic, type StorageOptions } from '../storage
 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 { appendDeliveryEvent } from './deliverylog.ts'
 
 export const CALLER_HEADER = 'x-iapeer-identity'
 const SERVER_INFO = { name: 'iapeer', version: '0.0.0' }
@@ -176,6 +177,7 @@ export async function callTool(
   name: string,
   args: Record<string, unknown>,
   wake?: WakeFn,
+  deliveryLogDir?: string,
 ): Promise<ToolResult> {
   if (name === 'send_to_peer') {
     const input: SendToPeerInput = {
@@ -185,7 +187,27 @@ export async function callTool(
       topic: typeof args.topic === 'string' ? args.topic : undefined,
       attachments: Array.isArray(args.attachments) ? (args.attachments as string[]) : undefined,
     }
+    const t0 = Date.now()
     const sent = await routeSend(caller, input, { wake })
+    // Ф-#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, {
+      ev: 'delivery',
+      caller: caller.address,
+      to: input.personality,
+      rt: input.runtime, // requested runtime override (skipped when absent)
+      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,
+      ms: Date.now() - t0,
+      len: input.message.length,
+      att: input.attachments?.length || undefined,
+      topic: input.topic,
+      err: sent.ok ? undefined : sent.error.message,
+    })
     return sent.ok ? jsonResult(sent.value) : errResult(sent.error.message)
   }
   return errResult(`unknown tool: ${name}`)
@@ -201,7 +223,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): Server {
+export function createMcpServer(wake?: WakeFn, deliveryLogDir?: string): Server {
   const server = new Server(SERVER_INFO, { capabilities: { tools: {} } })
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listTools(readPeersIndex()) }))
@@ -224,7 +246,7 @@ export function createMcpServer(wake?: WakeFn): 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)) as CallToolResult
+    return (await callTool(caller, req.params.name, args, wake, deliveryLogDir)) as CallToolResult
   })
 
   return server
@@ -292,6 +314,14 @@ export interface StartDaemonOptions extends StorageOptions {
    * broader than same-uid, so a token gates it without changing the on-wire MCP.
    */
   bearerToken?: string
+  /**
+   * Per-delivery outcome log dir (Ф-#8a) — when set, EVERY send_to_peer the daemon
+   * routes appends one logfmt outcome line to `<dir>/delivery.log` (rotated,
+   * metadata-only — see daemon/deliverylog.ts). OFF by default (library/test
+   * callers stay hermetic); the production main wires cfg.eventLogDir here, so
+   * delivery.log sits next to lifecycle.log under the SAME cfg-resolved root.
+   */
+  deliveryLogDir?: string
   /**
    * Write the discovery file (router.json) at <root>/state/iapeer/router.json with
    * the active addresses `{sock, tcp}` — atomically on listen, removed on close.
@@ -319,7 +349,7 @@ 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)
+    const server = createMcpServer(opts.wake, opts.deliveryLogDir)
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
     res.on('close', () => {
       transport.close()

package/src/daemon/main.ts

@@ -115,6 +115,10 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     port: opts.port ?? DEFAULT_DAEMON_PORT,
     host: opts.host ?? '127.0.0.1',
     socketPath: opts.socketPath ?? defaultDaemonSocketPath({ env, rootDir: opts.rootDir }),
+    // Ф-#8a per-delivery outcome log → delivery.log NEXT TO lifecycle.log, routed
+    // through the SAME lifecycle cfg (NOT re-resolved from env) so a sandboxed cfg
+    // sandboxes this log too.
+    deliveryLogDir: cfg.eventLogDir,
     discovery: opts.discovery ?? true,
     env,
     rootDir: opts.rootDir,

package/src/identity/identity.test.ts

@@ -121,6 +121,23 @@ describe('writePeerProfileAtomic H1 preserve', () => {
     const parsed = readPeerProfile(cwd)!
     expect(parsed.intelligence).toBe('artificial')
   })
+
+  test('wake_policy "ephemeral" parsed; unknown/absent → omitted (never throws)', () => {
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    // honored enum value
+    writeFileSync(peerProfilePath(cwd), JSON.stringify({
+      personality: 'p', runtime: 'claude', runtimes: ['claude'], wake_policy: 'ephemeral',
+    }))
+    expect(readPeerProfile(cwd)!.wake_policy).toBe('ephemeral')
+    // absent → undefined
+    writeFileSync(peerProfilePath(cwd), JSON.stringify({ personality: 'p', runtime: 'claude', runtimes: ['claude'] }))
+    expect(readPeerProfile(cwd)!.wake_policy).toBeUndefined()
+    // unknown value → omitted (forward-compatible, no throw)
+    writeFileSync(peerProfilePath(cwd), JSON.stringify({
+      personality: 'p', runtime: 'claude', runtimes: ['claude'], wake_policy: 'persistent-future',
+    }))
+    expect(readPeerProfile(cwd)!.wake_policy).toBeUndefined()
+  })
 })
 
 // ─────────────────────────────────────────────────────────────────────────────

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

@@ -359,6 +359,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.
+ */
+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 +406,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).

package/src/lifecycle/lifecycle.test.ts

@@ -366,8 +366,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 +379,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 +397,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 +451,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', () => {

package/src/storage/rotatelog.test.ts

@@ -0,0 +1,44 @@
+// rotatelog — the generic rotated-logfmt-append primitive (promoted from
+// lifecycle/eventlog.ts when the daemon's delivery.log became the second
+// producer). The logfmt formatting (fmtValue/formatEventLine) is pinned in
+// lifecycle/eventlog.test.ts (its historical home, re-exported); these tests
+// cover what is NEW at this layer: the path-parameterized append + rotation.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { appendRotatedEvent } from './rotatelog.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-rotatelog-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+describe('appendRotatedEvent', () => {
+  test('creates the parent dir and appends one ts-stamped logfmt line', () => {
+    const path = join(mkTmp(), 'deep', 'nested', 'some.log')
+    appendRotatedEvent(path, { ev: 'delivery', ok: 'true', note: 'two words' }, { nowMs: 1750000000000 })
+    const text = readFileSync(path, 'utf8')
+    expect(text).toBe('ts=2025-06-15T15:06:40.000Z ev=delivery ok=true note="two words"\n')
+  })
+
+  test('rotates base → .1 at maxBytes and drops beyond keep', () => {
+    const path = join(mkTmp(), 'r.log')
+    const line = { ev: 'x', pad: 'a'.repeat(50) } // ~65 bytes/line
+    // maxBytes 100 → every second append rotates; keep 1 → no .2 ever exists.
+    for (let i = 0; i < 6; i++) appendRotatedEvent(path, line, { maxBytes: 100, keep: 1 })
+    expect(existsSync(path)).toBe(true)
+    expect(existsSync(`${path}.1`)).toBe(true)
+    expect(existsSync(`${path}.2`)).toBe(false)
+  })
+
+  test('never throws on an unwritable path (best-effort observability)', () => {
+    expect(() => appendRotatedEvent('/dev/null/impossible/x.log', { ev: 'x' })).not.toThrow()
+  })
+})

package/src/storage/rotatelog.ts

@@ -0,0 +1,109 @@
+// Rotated logfmt append — the GENERIC durable-log primitive, promoted out of
+// lifecycle/eventlog.ts (its header anticipated exactly this: "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"). Producers today:
+//   • lifecycle.log  (lifecycle/eventlog.ts — daemon lifecycle decisions)
+//   • delivery.log   (daemon/deliverylog.ts — per-delivery outcomes, Ф-#8a)
+//
+// Design (carried verbatim from eventlog):
+//   • One line per event, logfmt (`key=value`, values quoted iff they contain
+//     whitespace/quotes/`=`). Human-greppable AND machine-parseable.
+//   • Append-only, app-managed SIZE rotation (base → .1 … .keep). This is the
+//     "встроенная ротация" class (Фаза — Ротация логов iapeer): a log OUR code
+//     writes rotates itself in the writer; external rotation is only for logs
+//     written by processes we don't control.
+//   • The target PATH is passed IN by the caller (who routes it through cfg),
+//     never re-resolved from env here — so a sandboxed caller cfg sandboxes the
+//     log too (no leak to the real ~/.iapeer).
+//   • Best-effort throughout: a write/rotate failure is swallowed. Observability
+//     must never take down the daemon or fail a wake/reap/delivery.
+
+import { appendFileSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
+import { dirname } from 'path'
+
+/** Default cap per log file before it rotates to <path>.1. */
+export const DEFAULT_LOG_MAX_BYTES = 5 * 1024 * 1024 // 5 MiB
+/** Default number of rotated backups kept (<path>.1 … .KEEP). */
+export const DEFAULT_LOG_KEEP = 5
+
+/** 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 AppendRotatedOptions {
+  /** Stamp the line with this epoch-ms (a caller may pass its own tick clock so the
+   *  log timestamp agrees with its accounting). Default Date.now(). */
+  nowMs?: number
+  /** Rotation cap per file (default DEFAULT_LOG_MAX_BYTES). */
+  maxBytes?: number
+  /** Rotated backups kept (default DEFAULT_LOG_KEEP). */
+  keep?: number
+}
+
+/**
+ * Append one logfmt event line to the rotated log at `path` (full file path,
+ * routed through the caller's cfg). Creates the parent dir (0700) and the file
+ * (0600) as needed. Fully best-effort — never throws.
+ */
+export function appendRotatedEvent(
+  path: string,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendRotatedOptions = {},
+): void {
+  const line = `${formatEventLine(opts.nowMs ?? Date.now(), fields)}\n`
+  const maxBytes = opts.maxBytes ?? DEFAULT_LOG_MAX_BYTES
+  const keep = opts.keep ?? DEFAULT_LOG_KEEP
+  try {
+    mkdirSync(dirname(path), { 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 the caller */
+  }
+}

package/src/update/index.ts

@@ -6,9 +6,10 @@
 // Flow:
 //   1. latest = `npm view @agfpd/iapeer version`           (the cloud's truth)
 //   2. installed == latest && !--force → "already latest"  (no needless rebuild/restart)
-//   3. `npx @agfpd/iapeer@<latest> install`                (fetch + rebuild ~/.local/bin/iapeer
-//      atomically; the COMPILED binary can't rebuild itself from source, so we shell to
-//      npx, which runs the freshly-fetched package's own install — same path consumers use)
+//   3. fetch the published tarball + build from its SOURCE (defaultRunInstall) — the
+//      COMPILED binary can't rebuild itself, so we pull the freshly-published package
+//      and run ITS own source installer. DELIBERATELY NOT `npx … install` (see
+//      defaultRunInstall for why npx is unsafe here).
 //   4. kickstart com.agfpd.iapeer IF loaded                (activate the new binary)
 //
 // Scope: the foundation ONLY (the @agfpd/iapeer binary + its daemon). It never
@@ -20,7 +21,10 @@
 // unit-testable with no network and no launchctl; the defaults are the real impls.
 
 import { spawnSync } from 'child_process'
+import { mkdtempSync, readdirSync, rmSync } from 'fs'
 import { connect } from 'net'
+import { tmpdir } from 'os'
+import { join } from 'path'
 import { IapError } from '../core/errors.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
 import { kickstartDaemon, type DaemonRestartResult } from '../launch/launchd.ts'
@@ -144,14 +148,51 @@ function defaultResolveVersion(spec: string, env: NodeJS.ProcessEnv): string | n
   return SEMVER_RE.test(v) ? v : null
 }
 
-/** Default installer: `npx -y @agfpd/iapeer@<version> install` (pull from cloud + rebuild). */
+/**
+ * Default installer — fetch the published tarball and build from its SOURCE,
+ * DELIBERATELY bypassing `npx`. Pull from the cloud + rebuild ~/.local/bin/iapeer.
+ *
+ * Why not `npx -y @agfpd/iapeer@<v> install`: the package's bin is named `iapeer`,
+ * and once `~/.local/bin/iapeer` is on PATH (true on every host AFTER the first
+ * install) npx resolves that bin NAME to the COMPILED binary already on PATH and
+ * runs ITS `install` — which cannot rebuild itself from source (`bun build --compile`
+ * gets a `/$bunfs/root` entrypoint → FileNotFound) — instead of fetching + running the
+ * freshly-published source. Verified reproducible (09.06, 0.2.8 deploy): with NO
+ * `iapeer` on PATH the same npx invocation prints `command not found` — it never
+ * installs the package — so this is a structural bin-name collision, NOT the
+ * publish-propagation transient (waiting/retry does not cure it).
+ *
+ * Deterministic path instead — no npx command-resolution in the loop:
+ *   1. `npm pack <pkg>@<v>` → the published tarball (rooted at `package/`).
+ *   2. `tar xzf` → extract.
+ *   3. `npm install --omit=dev` in the extracted dir — the tarball ships only
+ *      src/bin (no node_modules), and the source build imports prod deps
+ *      (@modelcontextprotocol/sdk, …).
+ *   4. run the package's OWN bin shim `bash <pkg>/bin/iapeer install` — that is
+ *      `bun src/cli/index.ts install` from the REAL fetched source → builds the prod
+ *      binary atomically (keeps `.prev`).
+ * Needs npm + tar + bash + bun on PATH (the toolchain the bootstrap already assumes).
+ */
 function defaultRunInstall(version: string, env: NodeJS.ProcessEnv): boolean {
   if (env.IAPEER_TEST_SANDBOX === '1') {
-    // A real npx install rebuilds the prod ~/.local/bin/iapeer — never under a test.
-    throw new IapError('refusing a real `npx install` under IAPEER_TEST_SANDBOX=1 — inject runInstall in tests')
+    // A real install rebuilds the prod ~/.local/bin/iapeer — never under a test.
+    throw new IapError('refusing a real install under IAPEER_TEST_SANDBOX=1 — inject runInstall in tests')
+  }
+  const tmp = mkdtempSync(join(tmpdir(), 'iapeer-deploy-'))
+  try {
+    const pack = spawnSync('npm', ['pack', '--silent', '--pack-destination', tmp, `${IAPEER_PACKAGE}@${version}`], { encoding: 'utf8', env })
+    if (pack.status !== 0) return false
+    const tgz = readdirSync(tmp).find(f => f.endsWith('.tgz'))
+    if (!tgz) return false
+    if (spawnSync('tar', ['xzf', join(tmp, tgz), '-C', tmp], { env }).status !== 0) return false
+    const pkg = join(tmp, 'package') // npm-pack tarballs always root at `package/`
+    const deps = spawnSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund', '--silent'], { cwd: pkg, stdio: 'inherit', env })
+    if (deps.status !== 0) return false
+    const build = spawnSync('bash', [join(pkg, 'bin', 'iapeer'), 'install'], { stdio: 'inherit', env })
+    return build.status === 0
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
   }
-  const r = spawnSync('npx', ['-y', `${IAPEER_PACKAGE}@${version}`, 'install'], { stdio: 'inherit', env })
-  return r.status === 0
 }
 
 /**

package/src/update/update.test.ts

@@ -137,9 +137,9 @@ describe('updateIapeer — failure paths', () => {
 })
 
 describe('updateIapeer — real-installer sandbox guard', () => {
-  test('default runInstall refuses a real npx install under IAPEER_TEST_SANDBOX', () => {
+  test('default runInstall refuses a real install under IAPEER_TEST_SANDBOX', () => {
     // fetchLatest injected (newer) so the gate proceeds to the DEFAULT installer,
-    // which must refuse rather than npx-install over the prod ~/.local/bin/iapeer.
+    // which must refuse rather than fetch+build over the prod ~/.local/bin/iapeer.
     expect(() =>
       updateIapeer({
         env: { IAPEER_TEST_SANDBOX: '1' },