@agfpd/iapeer 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.0",
+  "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

@@ -21,7 +21,7 @@ import {
 } from '../core/constants.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,
@@ -226,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
@@ -309,6 +354,7 @@ 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
@@ -459,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

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

@@ -101,6 +101,11 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
       // 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 */
+  }
+}

package/src/lifecycle/index.ts

@@ -40,6 +40,7 @@ import {
   type LaunchSpec,
 } from '../launch/index.ts'
 import { composeSystemPrompt, gatherPromptInput } from '../launch/composeSystemPrompt.ts'
+import { appendLifecycleEvent, superviseLogVerbose } from './eventlog.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Config
@@ -51,6 +52,11 @@ export interface LifecycleConfig {
   sockDir: string
   stateDir: string // ~/.iapeer/state/lifecycle
   logDir: string // ~/.iapeer/logs/lifecycle
+  /** Where the durable lifecycle DECISION log (lifecycle.log) is written
+   *  (~/.iapeer/logs/iapeer — next to daemon-stdout/stderr.log, where the first
+   *  investigator looks). Routed through cfg — NOT re-resolved from env — so it is
+   *  isolated by the same sandbox as stateDir (eventlog.ts). */
+  eventLogDir: string
   bootDeadlineSecs: number
   readyGateSecs: number
   idleSecs: number
@@ -74,6 +80,7 @@ export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): Lifec
     sockDir: resolveSockDir(env),
     stateDir: join(root, STATE_DIR, 'lifecycle'),
     logDir: join(root, LOGS_DIR, 'lifecycle'),
+    eventLogDir: join(root, LOGS_DIR, 'iapeer'),
     bootDeadlineSecs: num(env.IAPEER_BOOT_DEADLINE_SECS, 240),
     readyGateSecs: num(env.IAPEER_READY_GATE_SECS, 120),
     idleSecs: num(env.IAPEER_IDLE_SECS, 3600),
@@ -331,6 +338,10 @@ export interface WakeMode {
   /** Set ONLY for an EXPLICIT resume request that found nothing to resume — the
    *  caller must fail loud (never a silent fresh fallback). */
   failReason?: string
+  /** Which decision branch fired — the durable "why fresh / why resume" reason.
+   *  Logged by wakeOrSpawn: the .idle-reaped marker is CONSUMED inside this
+   *  function (branch 3b), so this cause is the only surviving record of it. */
+  cause?: string
 }
 
 /**
@@ -371,29 +382,33 @@ export function resolveWakeMode(
   incomingTopic?: string,
 ): WakeMode {
   // 1. folder-launch → always fresh.
-  if (argsResume === false) return { resume: false }
+  if (argsResume === false) return { resume: false, cause: 'folder-launch' }
   // 2. attach → always resume, fail-loud if nothing to resume.
   if (argsResume === true) {
     const r = resolveResume(cwd)
-    if (!r.ok) return { resume: false, failReason: r.reason ?? 'resume requested but nothing to resume' }
-    return { resume: true, resumeRef: r.ref }
+    if (!r.ok) return { resume: false, failReason: r.reason ?? 'resume requested but nothing to resume', cause: 'attach-nothing-to-resume' }
+    return { resume: true, resumeRef: r.ref, cause: 'attach' }
   }
   // 3. default (a message woke a dead/asleep peer): decide by the death cause.
   // 3a. NOT idle-reaped → it died on its own (crash / self-close) → clean FRESH.
-  if (!hasIdleReaped(cfg, identity)) return { resume: false }
+  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).
   clearIdleReaped(cfg, identity)
   // human-conversational dialogue never auto-freshes; only an explicit /new resets it.
   if (isHumanConversational(cwd)) {
     const r = resolveResume(cwd)
-    return r.ok ? { resume: true, resumeRef: r.ref } : { resume: false }
+    return r.ok
+      ? { resume: true, resumeRef: r.ref, cause: 'idle-reaped-human' }
+      : { resume: false, cause: 'idle-reaped-human-no-resume' }
   }
   // executor: a NEW topic (non-empty and differing from the stored one) means new
   // work → FRESH; same topic, or no incoming topic → continue the work → RESUME.
   const topic = incomingTopic?.trim() ?? ''
-  if (topic && topic !== readTopic(cfg, identity)) return { resume: false }
+  if (topic && topic !== readTopic(cfg, identity)) return { resume: false, cause: 'idle-reaped-new-topic' }
   const r = resolveResume(cwd)
-  return r.ok ? { resume: true, resumeRef: r.ref } : { resume: false }
+  return r.ok
+    ? { resume: true, resumeRef: r.ref, cause: 'idle-reaped-resume' }
+    : { resume: false, cause: 'idle-reaped-no-resume' }
 }
 
 export function readSessionStates(cfg: LifecycleConfig): SessionState[] {
@@ -636,6 +651,13 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
   const env = deps.env ?? process.env
   const cfg = deps.cfg ?? loadLifecycleConfig(env)
 
+  // Durable wake-decision trace (eventlog.ts): one line per bring-up decision —
+  // fresh / resume (with the resolveWakeMode cause) or a refusal (stopped / crash-
+  // loop / launchd). This is the direct answer to "why did peer X come up fresh",
+  // and the only surviving record of the .idle-reaped marker resolveWakeMode consumes.
+  const logWake = (fields: Record<string, string | number | undefined>): void =>
+    appendLifecycleEvent(cfg.eventLogDir, { ev: 'wake', personality: args.personality, ...fields }, { env })
+
   // Heal strays before launching — the sweep-at-spawn-start. This is the SAME
   // H4-guarded superviseTick the daemon timer runs, so both reap entry points
   // (timer + wake) go through one guarded path. Best-effort: never block a wake.
@@ -651,6 +673,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
 
   // H4 — never wake a launchd-managed peer (launchd KeepAlive owns it).
   if (isLaunchdManaged(args.personality, env)) {
+    logWake({ runtime: args.runtime, mode: 'refused', cause: 'launchd-managed' })
     return {
       status: 'FAILED',
       woke: false,
@@ -681,6 +704,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
   // halt: refuse with stopped:true so the sender gets an explicit "stopped" error,
   // not a generic "offline" — and no message is queued. `start` clears the flag.
   if (isStopped(cfg, identity)) {
+    logWake({ identity, runtime, mode: 'refused', cause: 'stopped' })
     return {
       status: 'FAILED',
       woke: false,
@@ -698,9 +722,11 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     // refusal). A stop racing DURING the spawn is a narrower window the wake-lock does not
     // cover (stop does not take this lock).
     if (isStopped(cfg, identity)) {
+      logWake({ identity, runtime, mode: 'refused', cause: 'stopped-mid-wake' })
       return { status: 'FAILED', woke: false, runtime, stopped: true, reason: `"${args.personality}" (${runtime}) is stopped and not accepting messages; start it to resume` }
     }
     if (isLaunchdManaged(args.personality, env)) {
+      logWake({ identity, runtime, mode: 'refused', cause: 'launchd-managed-mid-wake' })
       return { status: 'FAILED', woke: false, runtime, reason: `"${args.personality}" became launchd-managed mid-wake; the daemon does not wake it` }
     }
     // Idempotent fast path inside the lock: a live session wins (a concurrent
@@ -719,6 +745,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     // trims the ring, so the guard only fires on a genuine tight loop.
     const recentDeaths = countRecentDeaths(cfg, identity, cfg.crashLoopWindowSecs, Date.now())
     if (recentDeaths >= cfg.crashLoopMax) {
+      logWake({ identity, runtime, mode: 'refused', cause: 'crash-loop', reason: `${recentDeaths} deaths in ${cfg.crashLoopWindowSecs}s` })
       return {
         status: 'FAILED',
         woke: false,
@@ -732,6 +759,17 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     // that finds nothing to resume fails loud. incomingTopic (args.topic) is the
     // executor discriminator.
     const mode = resolveWakeMode(cfg, identity, cwd, args.resume, c => adapter.resolveResume(c), args.topic)
+    // The bring-up decision is the durable trace — log it BEFORE launch (the decision
+    // stands regardless of whether the subsequent launch succeeds). resolveWakeMode has
+    // already consumed any .idle-reaped marker, so `cause` is now its only record.
+    logWake({
+      identity,
+      runtime,
+      mode: mode.failReason ? 'fail' : mode.resume ? 'resume' : 'fresh',
+      cause: mode.cause,
+      ref: mode.resumeRef,
+      reason: mode.failReason,
+    })
     if (mode.failReason) return { status: 'FAILED', woke: false, runtime, reason: mode.failReason }
     const resume = mode.resume
     const resumeRef = mode.resumeRef
@@ -844,11 +882,19 @@ export interface SuperviseDeps {
 export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): SuperviseOutcome[] {
   const env = deps.env ?? process.env
   const nowMs = deps.nowMs ?? Date.now()
+  const verbose = superviseLogVerbose(env)
+  // Durable decision trace (eventlog.ts): every reap/death/eager-fresh gets a line
+  // so a postmortem can answer "when & how did peer X's prior session end" even
+  // after the .idle-reaped / .deaths markers are consumed. alive / skipped-launchd
+  // are steady-state non-decisions → logged only under IAPEER_SUPERVISE_LOG_VERBOSE.
+  const trace = (fields: Record<string, string | number | undefined>): void =>
+    appendLifecycleEvent(cfg.eventLogDir, { ev: 'supervise', ...fields }, { env, nowMs })
   const out: SuperviseOutcome[] = []
   for (const s of readSessionStates(cfg)) {
     // H4 — FIRST, before any reap. A launchd-managed peer is read-only.
     if (isLaunchdManaged(s.personality, env)) {
       out.push({ identity: s.identity, action: 'skipped-launchd' })
+      if (verbose) trace({ identity: s.identity, action: 'skipped-launchd', outcome: 'read-only-h4' })
       continue
     }
     const sock = buildSocketPath(s.runtime, s.personality, cfg.sockDir)
@@ -869,11 +915,13 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
           personality: s.personality,
           runtime: s.runtime,
         })
+        trace({ identity: s.identity, action: 'needs-eager-fresh', reason: '/new eager mark', outcome: 'eager-fresh' })
         continue
       }
       // Crash / self-close: NO marker written, NO eager relaunch — the peer stays
       // asleep and wakes FRESH lazily on the next message (resolveWakeMode branch 3a).
       out.push({ identity: s.identity, action: 'reaped-gone', reason: 'session no longer live' })
+      trace({ identity: s.identity, action: 'reaped-gone', reason: 'session no longer live', outcome: 'fresh-next-msg' })
       continue
     }
     // Idle accounting via the runtime adapter's activity proxy (claude transcript
@@ -896,8 +944,10 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       setIdleReaped(cfg, s.identity)
       removeSessionState(cfg, s.identity)
       out.push({ identity: s.identity, action: 'reaped-idle', reason: `idle ${ageSecs}s` })
+      trace({ identity: s.identity, action: 'reaped-idle', age: `${ageSecs}s`, outcome: 'resume-eligible' })
     } else {
       out.push({ identity: s.identity, action: 'alive' })
+      if (verbose) trace({ identity: s.identity, action: 'alive', age: `${ageSecs}s` })
     }
   }
   return out

package/src/lifecycle/lifecycle.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import {
@@ -176,6 +176,7 @@ describe('superviseTick H4 guard', () => {
       sockDir: '/tmp',
       stateDir,
       logDir: stateDir,
+      eventLogDir: stateDir, // isolate the decision log into the temp dir (no real-root leak)
       bootDeadlineSecs: 1,
       readyGateSecs: 1,
       idleSecs: 1,
@@ -204,11 +205,17 @@ describe('superviseTick H4 guard', () => {
   })
 
   test('a no-plist peer with a dead session → reaped-gone, state removed', () => {
+    const c = cfg()
     const id = writeState('iapeer-supgone') // no plist, no live tmux session
-    const out = superviseTick(cfg(), { env: env(), nowMs: Date.now() })
+    const out = superviseTick(c, { env: env(), nowMs: Date.now() })
     const o = out.find(x => x.identity === id)
     expect(o?.action).toBe('reaped-gone')
     expect(existsSync(join(stateDir, `${id}.session`))).toBe(false)
+    // the decision leaves a DURABLE trace line (the observability contract) — and it
+    // lands in the SANDBOXED eventLogDir, never the real ~/.iapeer.
+    const logged = readFileSync(join(c.eventLogDir, 'lifecycle.log'), 'utf8')
+    expect(logged).toContain(`ev=supervise identity=${id} action=reaped-gone`)
+    expect(logged).toContain('outcome=fresh-next-msg')
   })
 
   test('empty state dir → no outcomes', () => {
@@ -390,10 +397,10 @@ describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
 
   // ── branch 1/2: explicit fresh / explicit resume (unchanged) ────────────────
   test('argsResume=false (folder-launch) → FRESH', () => {
-    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), false, hasTranscript)).toEqual({ resume: false })
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), false, hasTranscript)).toEqual({ resume: false, cause: 'folder-launch' })
   })
   test('argsResume=true (attach) + transcript → RESUME', () => {
-    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), true, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1' })
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), true, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1', cause: 'attach' })
   })
   test('argsResume=true + nothing to resume → FAIL-LOUD (failReason, no silent fresh)', () => {
     const m = resolveWakeMode(cfg(), 'claude-p', cwd(), true, noTranscript)
@@ -405,7 +412,7 @@ describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
   test('DEFAULT + NOT idle-reaped (crash/self-close) → FRESH even when a transcript exists', () => {
     // INVERSION of the old polarity: absence of the daemon's idle-reaped marker = died
     // on its own = clean fresh, NOT a resume of a possibly-broken context.
-    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), undefined, hasTranscript)).toEqual({ resume: false })
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), undefined, hasTranscript)).toEqual({ resume: false, cause: 'crash-or-self-close' })
   })
 
   // ── branch 3b: default + idle-reaped → resume-eligible, CONSUME the marker ───
@@ -413,25 +420,25 @@ describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
     const c = cfg()
     setIdleReaped(c, 'claude-p')
     const human = cwd(true)
-    expect(resolveWakeMode(c, 'claude-p', human, undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1' })
+    expect(resolveWakeMode(c, 'claude-p', human, undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1', cause: 'idle-reaped-human' })
     expect(hasIdleReaped(c, 'claude-p')).toBe(false) // consumed
   })
   test('DEFAULT + idle-reaped + executor + NO incoming topic → RESUME (continue the work)', () => {
     const c = cfg()
     setIdleReaped(c, 'claude-p')
-    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1' })
+    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1', cause: 'idle-reaped-resume' })
   })
   test('DEFAULT + idle-reaped + executor + SAME topic → RESUME', () => {
     const c = cfg()
     setIdleReaped(c, 'claude-p')
     writeTopic(c, 'claude-p', 'deploy')
-    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript, 'deploy')).toEqual({ resume: true, resumeRef: 'uuid-1' })
+    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript, 'deploy')).toEqual({ resume: true, resumeRef: 'uuid-1', cause: 'idle-reaped-resume' })
   })
   test('DEFAULT + idle-reaped + executor + DIFFERENT topic → FRESH (new work), marker consumed', () => {
     const c = cfg()
     setIdleReaped(c, 'claude-p')
     writeTopic(c, 'claude-p', 'deploy')
-    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript, 'unrelated-bug')).toEqual({ resume: false })
+    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
   })
 })

package/src/registry/registry.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import {
+  clampDescription,
   findPeer,
   readPeersIndex,
   removePeer,
@@ -10,7 +11,7 @@ import {
   withPeersLock,
   type PeerRecord,
 } from './index.ts'
-import { defaultIntelligenceForRuntime, type Intelligence } from '../core/constants.ts'
+import { MAX_DESCRIPTION_LEN, defaultIntelligenceForRuntime, type Intelligence } from '../core/constants.ts'
 import { writeFileAtomic, resolvePeersPaths } from '../storage/index.ts'
 
 let root: string
@@ -398,3 +399,34 @@ describe('Companion fix — withPeersLock fail-closed sandbox isolation', () =>
     expect(out).toBe('ok')
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// clampDescription boundary — the limit was raised 250 → 450 so self-documenting
+// API-peer descriptions (notifier timer/watcher, ~408 chars) survive intact. The
+// boundary is exact: length == MAX passes untouched, length == MAX+1 truncates.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('clampDescription — MAX_DESCRIPTION_LEN boundary (450)', () => {
+  test('the limit is 450', () => {
+    expect(MAX_DESCRIPTION_LEN).toBe(450)
+  })
+  test('a 450-char description passes through untouched', () => {
+    const at = 'x'.repeat(450)
+    const r = clampDescription(at)
+    expect(r.truncated).toBe(false)
+    expect(r.description).toBe(at)
+    expect(r.description.length).toBe(450)
+  })
+  test('a 451-char description is truncated to 450', () => {
+    const over = 'y'.repeat(451)
+    const r = clampDescription(over)
+    expect(r.truncated).toBe(true)
+    expect(r.description.length).toBe(450)
+    expect(r.description).toBe('y'.repeat(450))
+  })
+  test('upsertPeer persists a full 450-char description (no clamp at the boundary)', async () => {
+    const desc = 'z'.repeat(450)
+    await upsertPeer({ personality: 'verbose', runtime: 'claude', cwd: '/tmp/verbose', description: desc }, opts())
+    expect(findPeer(readPeersIndex(opts()), 'verbose')!.description).toBe(desc)
+  })
+})