@agfpd/iapeer 0.1.2 → 0.2.1

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,10 +52,19 @@ 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
   maxAgeSecs: number
+  /** Crash-loop guard: refuse to (re)launch after this many deaths within the window. */
+  crashLoopMax: number
+  /** Crash-loop guard: the sliding window (seconds) the death count is measured over. */
+  crashLoopWindowSecs: number
 }
 
 export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): LifecycleConfig {
@@ -70,10 +80,13 @@ 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),
     maxAgeSecs: num(env.IAPEER_MAX_AGE_SECS, 14400),
+    crashLoopMax: num(env.IAPEER_CRASHLOOP_MAX, 3),
+    crashLoopWindowSecs: num(env.IAPEER_CRASHLOOP_WINDOW_SECS, 300),
   }
 }
 
@@ -168,42 +181,155 @@ export function clearStopped(cfg: LifecycleConfig, identity: string): void {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// C4 — /new graceful mark (contract ЖЦ §/new). The AGENT, on an owner /new,
-// writes a handoff to durable memory, drops THIS mark, and self-kills. The daemon
-// detects the mark and re-launches EAGERLY as FRESH + initial_prompt (contrast:
-// idle-reap is markless → lazy resume on the next message). The mark is consumed on
-// that fresh re-launch. The mark TEXT/agent-side (doctrine /new instruction) is a
-// separate deploy artifact; THIS is only the daemon side (detect → fresh + seed).
+// Lifecycle markers — the DAEMON decides fresh-vs-resume by the DEATH CAUSE it
+// tracks itself (TARGET redesign). Plain files in state/lifecycle/<identity>.* :
+//
+//   .idle-reaped : written ONLY when the daemon idle-reaps the session (the only
+//     death the daemon initiates). Presence on the next wake = session was parked
+//     cleanly = RESUME-eligible. ABSENT on a dead session = it died on its own
+//     (crash / self-close) = FRESH. (resolver branch 3.)
+//   .new-eager   : set when /new is invoked (owner reset, via `iapeer self-fresh`).
+//     Presence on a dead session = the daemon EAGERLY relaunches FRESH (does NOT
+//     wait for a message) and injects initial_prompt. Consumed on the relaunch.
+//   .deaths      : crash-loop guard — a small JSON ring of recent death epoch-ms.
+//   .topic       : the topic tag of the current/last session (executor fresh-vs-
+//     resume discriminator).
+//
+// Boolean markers carry an ISO timestamp line (audit-friendly); .deaths is a JSON
+// array; .topic is the raw topic string.
 // ─────────────────────────────────────────────────────────────────────────────
 
-function newMarkPath(cfg: LifecycleConfig, identity: string): string {
-  return join(cfg.stateDir, `${identity}.new`)
+function idleReapedPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.idle-reaped`)
+}
+
+/** True iff the identity was idle-reaped by the daemon (→ RESUME-eligible). */
+export function hasIdleReaped(cfg: LifecycleConfig, identity: string): boolean {
+  return existsSync(idleReapedPath(cfg, identity))
+}
+
+/** Write the idle-reaped marker — ONLY the idle-reap path in superviseTick does this. */
+export function setIdleReaped(cfg: LifecycleConfig, identity: string): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  writeFileSync(idleReapedPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
+}
+
+/** Consume the idle-reaped marker (the resolver does this on the resume decision). */
+export function clearIdleReaped(cfg: LifecycleConfig, identity: string): void {
+  try {
+    rmSync(idleReapedPath(cfg, identity), { force: true })
+  } catch {
+    /* already gone */
+  }
 }
 
-/** True iff the identity carries a /new graceful mark (→ eager fresh + seed). */
-export function hasNewMark(cfg: LifecycleConfig, identity: string): boolean {
-  return existsSync(newMarkPath(cfg, identity))
+function newEagerPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.new-eager`)
 }
 
-/** Drop the /new mark (the agent's self-kill ritual does this before exiting). */
-export function setNewMark(cfg: LifecycleConfig, identity: string): void {
+/** True iff the identity carries a /new eager-fresh mark (→ eager fresh + seed). */
+export function hasNewEager(cfg: LifecycleConfig, identity: string): boolean {
+  return existsSync(newEagerPath(cfg, identity))
+}
+
+/** Set the /new eager-fresh mark (the `self-fresh` verb does this before self-kill). */
+export function setNewEager(cfg: LifecycleConfig, identity: string): void {
   mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
-  writeFileSync(newMarkPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
+  writeFileSync(newEagerPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
 }
 
-/** Consume the /new mark (the daemon does this on the eager fresh re-launch). */
-export function clearNewMark(cfg: LifecycleConfig, identity: string): void {
+/** Consume the /new eager-fresh mark (the daemon does this on the eager relaunch). */
+export function clearNewEager(cfg: LifecycleConfig, identity: string): void {
   try {
-    rmSync(newMarkPath(cfg, identity), { force: true })
+    rmSync(newEagerPath(cfg, identity), { force: true })
   } catch {
     /* already gone */
   }
 }
 
+function deathsPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.deaths`)
+}
+
+/** Read the crash-loop death ring (epoch-ms timestamps). Garbage → empty. */
+export function readDeaths(cfg: LifecycleConfig, identity: string): number[] {
+  try {
+    const arr = JSON.parse(readFileSync(deathsPath(cfg, identity), 'utf8'))
+    return Array.isArray(arr) ? arr.filter((n): n is number => typeof n === 'number' && Number.isFinite(n)) : []
+  } catch {
+    return []
+  }
+}
+
+/** Append a death epoch-ms to the crash-loop ring (best-effort, bounded). */
+export function recordDeath(cfg: LifecycleConfig, identity: string, nowMs: number = Date.now()): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  // Keep the ring small — only the most recent matter for the window check.
+  const next = [...readDeaths(cfg, identity), nowMs].slice(-16)
+  try {
+    writeFileSync(deathsPath(cfg, identity), JSON.stringify(next), { mode: 0o600 })
+  } catch {
+    /* best-effort accounting; never block a reap */
+  }
+}
+
+/** Count deaths within `windowSecs` of `nowMs` (crash-loop guard input). */
+export function countRecentDeaths(
+  cfg: LifecycleConfig,
+  identity: string,
+  windowSecs: number,
+  nowMs: number = Date.now(),
+): number {
+  const cutoff = nowMs - windowSecs * 1000
+  return readDeaths(cfg, identity).filter(t => t >= cutoff).length
+}
+
+/** Trim the death ring to the window (called on a successful wake to reset the loop). */
+export function trimDeaths(
+  cfg: LifecycleConfig,
+  identity: string,
+  windowSecs: number,
+  nowMs: number = Date.now(),
+): void {
+  const cutoff = nowMs - windowSecs * 1000
+  const kept = readDeaths(cfg, identity).filter(t => t >= cutoff)
+  try {
+    if (kept.length === 0) rmSync(deathsPath(cfg, identity), { force: true })
+    else writeFileSync(deathsPath(cfg, identity), JSON.stringify(kept), { mode: 0o600 })
+  } catch {
+    /* best-effort */
+  }
+}
+
+function topicPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.topic`)
+}
+
+/** Read the stored topic of the current/last session (executor discriminator). '' if none. */
+export function readTopic(cfg: LifecycleConfig, identity: string): string {
+  try {
+    return readFileSync(topicPath(cfg, identity), 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
+/** Store the incoming topic for the established session (raw string, best-effort). */
+export function writeTopic(cfg: LifecycleConfig, identity: string, topic: string): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  try {
+    writeFileSync(topicPath(cfg, identity), topic, { mode: 0o600 })
+  } catch {
+    /* best-effort — topic is a discriminator hint, never blocks a wake */
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
-// resolveWakeMode (C3a + C4a) — the resume-vs-fresh decision, contract ЖЦ
-// §resume/fresh. Pure but for the /new-mark consume (a wake side-effect); takes the
-// adapter's resolveResume as a parameter so it is unit-testable without a runtime.
+// resolveWakeMode — the resume-vs-fresh decision (TARGET redesign). The DAEMON
+// decides by the DEATH CAUSE it tracks (.idle-reaped marker), plus peer-type /
+// topic — NOT an agent-dropped fresh mark. Takes the adapter's resolveResume as a
+// parameter so it is unit-testable without a runtime. The .idle-reaped marker is
+// CONSUMED when the default branch acts on it (a wake side-effect).
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface WakeMode {
@@ -212,17 +338,40 @@ 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
 }
 
 /**
- * Decide resume vs fresh on a wake. Priority (contract ЖЦ §resume/fresh, /new):
- *   1. /new-mark present → eager graceful re-launch: FRESH; consume the mark.
- *   2. explicit fresh (argsResume === false) → FRESH.
- *   3. explicit resume (argsResume === true, e.g. attach) → RESUME, FAIL-LOUD if the
- *      preflight finds nothing (failReason set; never a silent fresh fallback).
- *   4. default (argsResume undefined) → warm-asleep RESUME when a transcript exists,
- *      else FRESH (a first-ever launch has nothing to resume — NOT an error here).
- * Fixes the prior divergence (code: always fresh; contract: warm-asleep → resume).
+ * True iff the peer of `cwd` is a human-conversational peer — i.e. its local
+ * profile declares an `interfaces.telegram` binding (a telegram-fronted dialogue).
+ * Such a peer NEVER auto-freshes a resume-eligible wake; only an explicit /new
+ * (eager) resets it. A profile read hiccup → not-human (safe default: an executor).
+ */
+function isHumanConversational(cwd: string): boolean {
+  try {
+    const ifaces = readPeerProfile(cwd)?.interfaces
+    return !!(ifaces && ifaces.telegram != null)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Decide resume vs fresh on a wake (TARGET redesign). Branch order:
+ *   1. argsResume === false (folder-launch `iapeer <runtime>`) → FRESH.
+ *   2. argsResume === true (attach) → RESUME; FAIL-LOUD via resolveResume if there
+ *      is nothing to resume (failReason set; never a silent fresh fallback).
+ *   3. default (argsResume undefined — a message woke a dead/asleep peer):
+ *      a. NOT hasIdleReaped → FRESH. (It died on its own: crash / self-close. A
+ *         crash needs a CLEAN fresh, not a re-crashing resume of a broken context;
+ *         durable handoff carries continuity.)
+ *      b. hasIdleReaped (CONSUME the marker now) → resume-eligible, then by type:
+ *         - human-conversational (interfaces.telegram present) → RESUME.
+ *         - executor: incomingTopic non-empty AND differs from stored .topic →
+ *           FRESH (new work); else (same topic, or no incoming topic) → RESUME.
  */
 export function resolveWakeMode(
   cfg: LifecycleConfig,
@@ -230,19 +379,36 @@ export function resolveWakeMode(
   cwd: string,
   argsResume: boolean | undefined,
   resolveResume: (cwd: string) => { ok: boolean; ref?: string; reason?: string },
+  incomingTopic?: string,
 ): WakeMode {
-  if (hasNewMark(cfg, identity)) {
-    clearNewMark(cfg, identity) // consume the graceful mark on the fresh re-launch
-    return { resume: false }
-  }
-  if (argsResume === false) return { resume: false }
+  // 1. folder-launch → always fresh.
+  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, 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, 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, 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[] {
@@ -485,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.
@@ -500,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,
@@ -530,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,
@@ -547,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
@@ -562,9 +739,37 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
       return { status: 'FAILED', woke: false, runtime, reason: `peer cwd does not exist: ${cwd}` }
     }
 
-    // C3a + C4a — resolve resume vs fresh (extracted resolveWakeMode, contract ЖЦ
-    // §resume/fresh). An EXPLICIT resume that finds nothing to resume fails loud.
-    const mode = resolveWakeMode(cfg, identity, cwd, args.resume, c => adapter.resolveResume(c))
+    // Crash-loop guard — BEFORE launching: if the peer has died crashLoopMax times
+    // within crashLoopWindowSecs, refuse to (re)launch and leave it asleep (a clear
+    // FAILED reason, not a silent fresh that re-crashes). A successful wake below
+    // 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,
+        runtime,
+        reason: `crash-loop guard: ${recentDeaths} deaths in ${cfg.crashLoopWindowSecs}s, leaving asleep`,
+      }
+    }
+
+    // Resolve resume vs fresh (TARGET redesign resolveWakeMode): the daemon decides
+    // by the death cause (.idle-reaped marker) + peer-type/topic. An EXPLICIT resume
+    // 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
@@ -622,6 +827,10 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
         `[iapeer] WARN session-state write failed for ${identity} — session is live + TTL-bounded but not idle-reap-supervised: ${e instanceof Error ? e.message : String(e)}\n`,
       )
     }
+    // Establish the session's topic (executor discriminator) and reset the crash-loop
+    // ring — a successful wake means this is NOT a tight crash loop. Best-effort.
+    writeTopic(cfg, identity, args.topic?.trim() ?? '')
+    trimDeaths(cfg, identity, cfg.crashLoopWindowSecs, Date.now())
     return { status: 'READY', woke: true, runtime, process_address: identity }
   })
 }
@@ -659,8 +868,8 @@ export interface SuperviseOutcome {
   identity: string
   action: 'reaped-idle' | 'reaped-gone' | 'skipped-launchd' | 'alive' | 'needs-eager-fresh'
   reason?: string
-  /** For 'needs-eager-fresh' (C4b): the peer to EAGERLY re-launch fresh (its session
-   *  died carrying a /new-mark). The daemon timer drives the async relaunch. */
+  /** For 'needs-eager-fresh': the peer to EAGERLY re-launch fresh (its session died
+   *  carrying a .new-eager mark). The daemon timer drives the async relaunch. */
   personality?: string
   runtime?: Runtime
 }
@@ -673,31 +882,46 @@ 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)
     if (!sessionAlive(sock, s.identity)) {
+      // A dead session: record a death for crash-loop accounting, then branch on the
+      // .new-eager mark. This death was NOT daemon-initiated (the daemon only initiates
+      // the idle-reap below) → it died on its own → do NOT write .idle-reaped here.
+      recordDeath(cfg, s.identity, nowMs)
       removeSessionState(cfg, s.identity)
-      // C4b — a session that died carrying a /new-mark is a GRACEFUL завершение by the
-      // owner: re-launch EAGERLY as fresh (not lazily on the next message, the way a
-      // markless idle-reap death resumes). The mark is LEFT for the relaunch's
-      // resolveWakeMode to consume; the daemon timer drives the async wakeOrSpawn.
-      if (hasNewMark(cfg, s.identity)) {
+      // A session that died carrying a .new-eager mark is an owner /new: re-launch
+      // EAGERLY as fresh (not lazily on the next message). The mark is LEFT for the
+      // eager relaunch (processEagerRelaunches) to consume; the daemon timer drives it.
+      if (hasNewEager(cfg, s.identity)) {
         out.push({
           identity: s.identity,
           action: 'needs-eager-fresh',
-          reason: '/new graceful mark — eager fresh re-launch',
+          reason: '/new eager mark — eager fresh re-launch',
           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
@@ -712,25 +936,33 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
     }
     const ageSecs = Math.floor((nowMs - mt) / 1000)
     if (ageSecs > cfg.idleSecs) {
+      // THE ONLY place .idle-reaped is written: this is the one death the daemon
+      // INITIATES. Its presence on the next wake = the session was parked cleanly =
+      // RESUME-eligible (resolveWakeMode branch 3b). A crash/self-close (the dead
+      // branch above) never writes it → that wakes FRESH (branch 3a).
       killSession(sock, s.identity)
+      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
 }
 
 /**
- * C4b — drive the EAGER fresh re-launch for peers superviseTick flagged
- * 'needs-eager-fresh' (their session died carrying a /new graceful mark). Async +
- * best-effort: task='' so the seed (initial_prompt) is self-sufficient (a /new has no
- * incoming message — the agent auto-reports "I'm up" from the seed). resolveWakeMode
- * consumes the /new-mark on the relaunch (→ fresh). A relaunch failure leaves the
- * mark, so the peer still fresh-wakes on its next message — graceful degrades to lazy,
- * never lost. NB: a /new'd peer is expected to carry an initial_prompt (the report
- * directive); without one the seed is empty and the first turn delivers nothing.
+ * Drive the EAGER fresh re-launch for peers superviseTick flagged 'needs-eager-fresh'
+ * (their session died carrying a .new-eager mark — an owner /new). Async + best-effort:
+ * task='' so the seed (initial_prompt) is self-sufficient (a /new has no incoming message
+ * — the agent auto-reports "I'm up" from the seed). The relaunch is FRESH BY CONSTRUCTION:
+ * we CONSUME .new-eager here and pass resume:false so wakeOrSpawn's resolveWakeMode takes
+ * the folder-launch fresh branch WITHOUT consulting the death-cause markers. The mark is
+ * consumed BEFORE the relaunch so a relaunch failure does not loop on the same eager mark
+ * (it then fresh-wakes lazily on its next message — branch 3a — never lost). NB: a /new'd
+ * peer is expected to carry an initial_prompt; without one the first turn delivers nothing.
  */
 export async function processEagerRelaunches(
   cfg: LifecycleConfig,
@@ -740,9 +972,13 @@ export async function processEagerRelaunches(
   const results: WakeResult[] = []
   for (const o of outcomes) {
     if (o.action !== 'needs-eager-fresh' || !o.personality || !o.runtime) continue
+    clearNewEager(cfg, o.identity) // consume the eager mark — the relaunch is fresh by construction
     try {
       results.push(
-        await wakeOrSpawn({ personality: o.personality, runtime: o.runtime, task: '' }, { cfg, env: deps.env }),
+        await wakeOrSpawn(
+          { personality: o.personality, runtime: o.runtime, task: '', resume: false },
+          { cfg, env: deps.env },
+        ),
       )
     } catch (e) {
       results.push({ status: 'FAILED', woke: false, reason: e instanceof Error ? e.message : String(e) })