@agfpd/iapeer 0.1.2 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Foundation core for the IAPeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {
@@ -21,7 +21,14 @@
   },
   "scripts": {
     "test": "IAPEER_TEST_SANDBOX=1 bun test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "release": "npm version patch && npm publish && git push --follow-tags",
+    "release:minor": "npm version minor && npm publish && git push --follow-tags",
+    "release:major": "npm version major && npm publish && git push --follow-tags",
+    "prepublishOnly": "test -z \"$(git status --porcelain)\" || (echo 'release: working tree is dirty — commit or stash before release' >&2 && exit 1)"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",

package/src/cli/cli.test.ts

@@ -7,8 +7,8 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import { mkdtempSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
-import { formatListTable, listPeers, parseArgs, sendMessage, startPeer, stopPeer } from './index.ts'
-import { upsertPeer } from '../registry/index.ts'
+import { formatListTable, listPeers, parseArgs, removePeerCli, sendMessage, startPeer, stopPeer } from './index.ts'
+import { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
 import { isStopped, loadLifecycleConfig, setStopped } from '../lifecycle/index.ts'
 import { launchdPlistPath } from '../launch/launchd.ts'
 
@@ -90,6 +90,27 @@ describe('FLEET GUARD (H4) — foreign persistent-peer launchd plist is off-limi
   })
 })
 
+describe('remove (registry record via the locked writer)', () => {
+  test('removes a registered peer through registry.removePeer', async () => {
+    await register('zombie')
+    const e = env()
+    expect(findPeer(readPeersIndex({ env: e }), 'zombie')).not.toBeNull()
+    const o = await removePeerCli('zombie', { env: e })
+    expect(o.action).toBe('removed')
+    expect(findPeer(readPeersIndex({ env: e }), 'zombie')).toBeNull()
+  })
+  test('removing an absent peer is an idempotent no-op (not an error)', async () => {
+    const o = await removePeerCli('never-existed', { env: env() })
+    expect(o.action).toBe('absent')
+  })
+  test('a second remove of the same peer is also a no-op', async () => {
+    await register('twice')
+    const e = env()
+    expect((await removePeerCli('twice', { env: e })).action).toBe('removed')
+    expect((await removePeerCli('twice', { env: e })).action).toBe('absent')
+  })
+})
+
 describe('send validation', () => {
   test('invalid --from identity → throws', async () => {
     await register('alpha')

package/src/cli/index.ts

@@ -19,9 +19,9 @@ import {
   type Intelligence,
   type Runtime,
 } from '../core/constants.ts'
-import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
+import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { ensureGlobalIapScaffold } from '../storage/index.ts'
-import { findPeer, readPeersIndex, type PeerRecord } from '../registry/index.ts'
+import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../registry/index.ts'
 import { isPeerLive, routeControl, routeSend, type WakeFn } from '../transport/index.ts'
 import {
   attachPeer,
@@ -31,6 +31,7 @@ import {
   isStopped,
   killSession,
   loadLifecycleConfig,
+  setNewEager,
   setStopped,
   wakeOrSpawn,
 } from '../lifecycle/index.ts'
@@ -225,6 +226,51 @@ export function startPeer(personality: string, runtime: string | undefined, opts
   return out
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// remove — delete a peer's record from the registry through the LOCKED writer
+// (registry.removePeer). Direct edits of peers-profiles.json are refused at
+// storage.ts:304 (locked-writer invariant); this is the operator path that used
+// to require dropping into `bun -e removePeer(...)`. The use case is reaping the
+// ephemeral zombie records a retired spawn leaves behind.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RemoveOutcome {
+  personality: string
+  action: 'removed' | 'absent' | 'refused-live'
+  reason?: string
+}
+
+/**
+ * remove <peer> [--force]: drop the registry record via the locked writer.
+ * IDEMPOTENT — an absent peer is a no-op success (`absent`), never an error.
+ * SAFETY: refuses a peer that is currently LIVE on any runtime — deleting a
+ * running session's record would orphan it from routing (resolveCallerIdentity /
+ * findPeer would no longer resolve it while it still runs). --force overrides.
+ * A zombie record is dead by definition, so the guard never blocks the cleanup
+ * it exists for.
+ */
+export async function removePeerCli(
+  personality: string,
+  opts: CliEnvOptions & { force?: boolean } = {},
+): Promise<RemoveOutcome> {
+  const env = opts.env ?? process.env
+  const peer = findPeer(readPeersIndex({ env }), personality)
+  if (!peer) return { personality, action: 'absent' }
+  if (!opts.force) {
+    const cfg = loadLifecycleConfig(env)
+    const liveRt = peer.runtimes.find(rt => isPeerLive(rt, personality, cfg.sockDir))
+    if (liveRt) {
+      return {
+        personality,
+        action: 'refused-live',
+        reason: `"${personality}" is LIVE on ${liveRt} — removing its registry record would orphan the running session from routing; stop it first or pass --force`,
+      }
+    }
+  }
+  await removePeer(personality, { env })
+  return { personality, action: 'removed' }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // send — manual IAP send fallback (contract Примитивы §send). Goes through the
 // same router path as send_to_peer (resolve → deliver / wake), in-process so it
@@ -308,12 +354,14 @@ const USAGE = `usage: iapeer <verb> [args]
   list [--json]                                                  registered peers + per-runtime liveness
   stop <peer> [runtime] | --all                                  durable-stop a warm peer / bootout an always-on one
   start <peer> [runtime]                                         re-enable a stopped peer / bootstrap an always-on one
+  remove <peer> [--force]                                        delete a peer's registry record (locked writer); refuses a LIVE peer unless --force
   send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]   manual IAP send (fallback)
   <runtime>                                                      launch the cwd's peer (ALWAYS fresh)
   enable <plugin> [peer] [--no-setup]                            install + enable an agfpd capability for a peer
   attach <peer> [runtime]                                        ensure-live + resume, then tmux attach
   interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
   compact <peer> [runtime]                                       compact the peer's context (/compact)
+  self-fresh                                                     (agent self-call) mark /new eager-fresh + self-kill — the daemon relaunches fresh
 `
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
@@ -457,6 +505,17 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
         return outcomes.some(o => o.action === 'refused-foreign-launchd') ? 1 : 0
       }
+      case 'remove': {
+        // Reap a registry record through the locked writer (the operator path over
+        // registry.removePeer). Idempotent on an absent peer (exit 0). Refuses a LIVE
+        // peer unless --force (orphaning a running session from routing is the risk).
+        if (!positionals[0]) return usage(errOut)
+        const o = await removePeerCli(positionals[0], { force: flags.force === true, env })
+        if (o.action === 'removed') out(`removed "${o.personality}" from the registry\n`)
+        else if (o.action === 'absent') out(`"${o.personality}" not registered — no-op\n`)
+        else errOut(`remove: ${o.reason}\n`)
+        return o.action === 'refused-live' ? 1 : 0
+      }
       case 'send': {
         // Message body from EITHER --message <text> OR --message-file <f> (f='-' →
         // stdin). The runtime packages (telegram/notifier) + monitor deliver via
@@ -543,6 +602,35 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         if (!positionals[0] || !positionals[1]) return usage(errOut)
         return await runAlwaysOn(positionals[0], positionals[1], process.cwd())
       }
+      case 'self-fresh': {
+        // /new AGENT-FACING TRIGGER (TARGET redesign). Run BY the agent itself as the
+        // FINAL step of a /new graceful wind-down (the owner triggers it via a per-peer
+        // telegram alias: "write a handoff to durable memory, then run iapeer self-fresh"
+        // — the alias text is telegram-owned, NOT global doctrine). It: resolves the
+        // caller identity from PEER_IDENTITY (<runtime>-<personality>), writes the
+        // .new-eager mark, then self-kills the caller's OWN tmux session. The daemon's
+        // superviseTick then sees the dead session carrying .new-eager → eager fresh
+        // relaunch (with initial_prompt) so the agent reports it is back up.
+        const identity = env.PEER_IDENTITY?.trim()
+        if (!identity) {
+          errOut('self-fresh: PEER_IDENTITY is not set — this verb is an agent self-call from inside a session\n')
+          return 1
+        }
+        const addr = parseSessionName(identity)
+        if (!addr) {
+          errOut(`self-fresh: invalid PEER_IDENTITY "${identity}" — expected <runtime>-<personality>\n`)
+          return 1
+        }
+        const cfg = loadLifecycleConfig(env)
+        // Mark FIRST, kill SECOND: if the kill races ahead of the mark the daemon would
+        // see a dead session with no .new-eager → a plain reaped-gone (lazy fresh on the
+        // next message), not the eager relaunch — degrade gracefully, never lose the mark.
+        setNewEager(cfg, identity)
+        out(`self-fresh: marked ${identity} for eager fresh re-launch; self-killing session\n`)
+        const sock = buildSocketPath(addr.runtime, addr.personality, cfg.sockDir)
+        killSession(sock, identity)
+        return 0
+      }
       case 'interrupt':
       case 'compact': {
         // In-session control (Ф-E, clean-slash namespace): interrupt a stuck/raving

package/src/core/constants.ts

@@ -13,7 +13,13 @@ export const SUPPORTED_LOCAL_RUNTIMES = ['claude', 'codex'] as const
 export type SupportedLocalRuntime = (typeof SUPPORTED_LOCAL_RUNTIMES)[number]
 
 export const PEERS_SCHEMA_VERSION = 2
-export const MAX_DESCRIPTION_LEN = 250
+// 450 (was 250): self-documenting API-peer descriptions (notifier timer/watcher)
+// must fit "who the peer is + registration format + a live example" — dense full
+// texts run to ~408 chars; 250 cut them mid-word so the caller could not compose
+// the call. Bumped with Arthur's sanction (2026-06-08). NB: this is COMPILE-TIME
+// baked — the live daemon re-clamps descriptions on read (registry parsePeerRecord),
+// so the running router keeps the OLD limit until restarted onto the new binary.
+export const MAX_DESCRIPTION_LEN = 450
 
 // Contract vocabulary (docs/Идентичность, Артур 05.06): the nature of the
 // intelligence expressing itself through a runtime.

package/src/daemon/main.ts

@@ -99,8 +99,13 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     wake: makeWakeFn(cfg, env),
     supervise: {
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
-      // idle-reap / zombie-sweep, THEN C4b eager fresh re-launch for any peer whose
-      // session died carrying a /new graceful mark (async, best-effort).
+      // idle-reap / zombie-sweep, THEN the eager fresh re-launch for any peer whose
+      // session died carrying a .new-eager mark (owner /new; async, best-effort).
+      // The DURABLE decision trace (which peer, what outcome, when, why) is emitted
+      // INSIDE superviseTick (lifecycle/eventlog.ts → logs/iapeer/lifecycle.log), so
+      // every reap is recorded regardless of entry point (this timer AND the heal-at-
+      // wake superviseTick inside wakeOrSpawn). The outcomes array drives only the
+      // eager relaunch here; the trace does not depend on consuming it.
       tick: async () => {
         const outcomes = superviseTick(cfg, { env })
         await processEagerRelaunches(cfg, outcomes, { env })

package/src/lifecycle/eventlog.test.ts

@@ -0,0 +1,114 @@
+// eventlog — the daemon's durable, rotated lifecycle decision log. Tests the pure
+// logfmt formatter, the append path (into an explicit temp logDir — never the real
+// ~/.iapeer), and the size-rotation chain. No daemon, no tmux — pure FS.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  appendLifecycleEvent,
+  fmtValue,
+  formatEventLine,
+  lifecycleLogPath,
+} from './eventlog.ts'
+
+const TS = 1_749_470_400_000 // fixed epoch-ms → a stable ISO for golden lines
+const ISO = new Date(TS).toISOString()
+
+describe('fmtValue (logfmt escaping)', () => {
+  test('bare token stays bare', () => {
+    expect(fmtValue('reaped-idle')).toBe('reaped-idle')
+    expect(fmtValue('claude-boris')).toBe('claude-boris')
+    expect(fmtValue(42)).toBe('42')
+  })
+  test('empty string → ""', () => {
+    expect(fmtValue('')).toBe('""')
+  })
+  test('whitespace / = / " force quoting and escape', () => {
+    expect(fmtValue('session no longer live')).toBe('"session no longer live"')
+    expect(fmtValue('a=b')).toBe('"a=b"')
+    expect(fmtValue('say "hi"')).toBe('"say \\"hi\\""')
+    expect(fmtValue('back\\slash here')).toBe('"back\\\\slash here"')
+  })
+})
+
+describe('formatEventLine', () => {
+  test('ts is first; fields keep insertion order; undefined skipped', () => {
+    const line = formatEventLine(TS, {
+      ev: 'supervise',
+      identity: 'claude-boris',
+      action: 'reaped-gone',
+      reason: 'session no longer live',
+      ref: undefined, // dropped
+      outcome: 'fresh-next-msg',
+    })
+    expect(line).toBe(
+      `ts=${ISO} ev=supervise identity=claude-boris action=reaped-gone reason="session no longer live" outcome=fresh-next-msg`,
+    )
+  })
+  test('age field renders as a bare token', () => {
+    const line = formatEventLine(TS, { ev: 'supervise', identity: 'claude-x', action: 'reaped-idle', age: '4230s' })
+    expect(line).toBe(`ts=${ISO} ev=supervise identity=claude-x action=reaped-idle age=4230s`)
+  })
+})
+
+describe('appendLifecycleEvent', () => {
+  let dir: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'iapeer-eventlog-'))
+  })
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  test('falsy logDir → no-op (a partial cfg never writes / never resolves a real path)', () => {
+    expect(() => appendLifecycleEvent(undefined, { ev: 'supervise', identity: 'x' }, { nowMs: TS })).not.toThrow()
+    expect(() => appendLifecycleEvent('', { ev: 'supervise', identity: 'x' }, { nowMs: TS })).not.toThrow()
+  })
+
+  test('writes one logfmt line per call, appended in order', () => {
+    appendLifecycleEvent(dir, { ev: 'wake', personality: 'boris', mode: 'fresh', cause: 'crash-or-self-close' }, { nowMs: TS })
+    appendLifecycleEvent(dir, { ev: 'supervise', identity: 'claude-doc', action: 'reaped-gone' }, { nowMs: TS + 1000 })
+    const body = readFileSync(lifecycleLogPath(dir), 'utf8')
+    const lines = body.trimEnd().split('\n')
+    expect(lines).toHaveLength(2)
+    expect(lines[0]).toBe(`ts=${ISO} ev=wake personality=boris mode=fresh cause=crash-or-self-close`)
+    expect(lines[1]).toContain('ev=supervise identity=claude-doc action=reaped-gone')
+  })
+
+  test('creates the log dir if absent', () => {
+    const nested = join(dir, 'logs', 'iapeer')
+    appendLifecycleEvent(nested, { ev: 'supervise', identity: 'x' }, { nowMs: TS })
+    expect(existsSync(lifecycleLogPath(nested))).toBe(true)
+  })
+
+  test('size rotation: base → .1, oldest dropped past keep', () => {
+    const env = { IAPEER_LIFECYCLE_LOG_MAX_BYTES: '120', IAPEER_LIFECYCLE_LOG_KEEP: '2' }
+    const path = lifecycleLogPath(dir)
+    for (let i = 0; i < 6; i++) {
+      appendLifecycleEvent(dir, { ev: 'supervise', identity: `claude-peer${i}`, action: 'reaped-gone', n: i }, { env, nowMs: TS + i })
+    }
+    expect(existsSync(path)).toBe(true)
+    expect(existsSync(`${path}.1`)).toBe(true)
+    expect(existsSync(`${path}.2`)).toBe(true)
+    expect(existsSync(`${path}.3`)).toBe(false) // keep=2 → never a .3
+    expect(statSync(path).size).toBeLessThanOrEqual(200)
+    expect(readFileSync(path, 'utf8')).toContain('claude-peer5') // newest in the live base file
+  })
+
+  test('rotation preserves chronological order across files (.N oldest, base newest)', () => {
+    const env = { IAPEER_LIFECYCLE_LOG_MAX_BYTES: '90', IAPEER_LIFECYCLE_LOG_KEEP: '3' }
+    const path = lifecycleLogPath(dir)
+    for (let i = 0; i < 4; i++) {
+      appendLifecycleEvent(dir, { ev: 'supervise', identity: `claude-p${i}` }, { env, nowMs: TS + i })
+    }
+    const ordered = ['.3', '.2', '.1', '']
+      .map(suf => (existsSync(path + suf) ? readFileSync(path + suf, 'utf8') : ''))
+      .join('')
+    const seen = [...ordered.matchAll(/identity=claude-p(\d)/g)].map(m => Number(m[1]))
+    expect(seen).toEqual([...seen].sort((a, b) => a - b))
+    expect(seen[seen.length - 1]).toBe(3) // newest line is p3, in the base file
+  })
+})

package/src/lifecycle/eventlog.ts

@@ -0,0 +1,133 @@
+// Lifecycle event log — the daemon's DURABLE, ROTATED trace of every lifecycle
+// DECISION it makes. This is the observability gap the boris-fresh incident hit:
+// a peer woke fresh and there was NO record of when/how its prior session ended,
+// nor of the daemon's fresh-vs-resume reasoning, because superviseTick's outcomes
+// were dropped and the daemon never wrote a decision line anywhere.
+//
+// Design:
+//   • One line per decision, logfmt (`key=value`, values quoted iff they contain
+//     whitespace/quotes/`=`). Human-greppable AND machine-parseable. The state
+//     markers (.idle-reaped / .deaths) are CONSUMED on the next wake — this log is
+//     the part that survives, so a postmortem can reconstruct the death even after
+//     the marker is gone.
+//   • Append-only, app-managed SIZE rotation (NOT launchd's stdout/stderr, which
+//     are unbounded and truncated on restart). lifecycle.log → .1 … .N.
+//   • The target directory is passed IN (cfg.eventLogDir), NOT re-resolved from
+//     env — so it is isolated by the SAME cfg the rest of lifecycle routes through
+//     (a test that sandboxes cfg.stateDir also sandboxes this log; no leak to the
+//     real ~/.iapeer). A falsy dir → no-op (a partial test cfg never writes).
+//   • 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.
+
+import { appendFileSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
+import { join } from 'path'
+
+/** 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
+
+/** The durable lifecycle decision log inside `logDir` (cfg.eventLogDir). */
+export function lifecycleLogPath(logDir: string): string {
+  return join(logDir, 'lifecycle.log')
+}
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+/** Whether to also log the steady-state non-decisions (alive / skipped-launchd).
+ *  Off by default — they fire every tick per live/launchd peer and would bury the
+ *  actual decisions (reap / wake) under heartbeat noise. */
+export function superviseLogVerbose(env: NodeJS.ProcessEnv = process.env): boolean {
+  const v = env.IAPEER_SUPERVISE_LOG_VERBOSE?.trim().toLowerCase()
+  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
+  /** Stamp the line with this epoch-ms (superviseTick passes its own tick clock so
+   *  the log timestamp agrees with the death/idle accounting). Default Date.now(). */
+  nowMs?: number
+}
+
+/**
+ * Append one lifecycle decision line into `logDir`/lifecycle.log. A falsy `logDir`
+ * is a no-op (a partial test cfg without eventLogDir never writes — and never
+ * resolves a real path). Fully best-effort — never throws.
+ */
+export function appendLifecycleEvent(
+  logDir: string | undefined,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendEventOptions = {},
+): 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 */
+  }
+}