@agfpd/iapeer 0.1.2 → 0.2.0

package/package.json

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

package/src/cli/index.ts

@@ -19,7 +19,7 @@ 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 { isPeerLive, routeControl, routeSend, type WakeFn } from '../transport/index.ts'
@@ -31,6 +31,7 @@ import {
   isStopped,
   killSession,
   loadLifecycleConfig,
+  setNewEager,
   setStopped,
   wakeOrSpawn,
 } from '../lifecycle/index.ts'
@@ -314,6 +315,7 @@ const USAGE = `usage: iapeer <verb> [args]
   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> {
@@ -543,6 +545,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/daemon/main.ts

@@ -99,8 +99,8 @@ 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).
       tick: async () => {
         const outcomes = superviseTick(cfg, { env })
         await processEagerRelaunches(cfg, outcomes, { env })

package/src/lifecycle/index.ts

@@ -55,6 +55,10 @@ export interface LifecycleConfig {
   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 {
@@ -74,6 +78,8 @@ export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): Lifec
     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 +174,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 carries a /new graceful mark (→ eager fresh + seed). */
-export function hasNewMark(cfg: LifecycleConfig, identity: string): boolean {
-  return existsSync(newMarkPath(cfg, identity))
+/** 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))
 }
 
-/** Drop the /new mark (the agent's self-kill ritual does this before exiting). */
-export function setNewMark(cfg: LifecycleConfig, identity: string): void {
+/** 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(newMarkPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
+  writeFileSync(idleReapedPath(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 idle-reaped marker (the resolver does this on the resume decision). */
+export function clearIdleReaped(cfg: LifecycleConfig, identity: string): void {
   try {
-    rmSync(newMarkPath(cfg, identity), { force: true })
+    rmSync(idleReapedPath(cfg, identity), { force: true })
   } catch {
     /* already gone */
   }
 }
 
+function newEagerPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.new-eager`)
+}
+
+/** 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(newEagerPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
+}
+
+/** Consume the /new eager-fresh mark (the daemon does this on the eager relaunch). */
+export function clearNewEager(cfg: LifecycleConfig, identity: string): void {
+  try {
+    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 {
@@ -215,14 +334,33 @@ export interface WakeMode {
 }
 
 /**
- * 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,17 +368,30 @@ 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 }
-  }
+  // 1. folder-launch → always fresh.
   if (argsResume === false) return { resume: false }
+  // 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 }
   }
+  // 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 }
+  // 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 }
+  }
+  // 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 }
   const r = resolveResume(cwd)
   return r.ok ? { resume: true, resumeRef: r.ref } : { resume: false }
 }
@@ -562,9 +713,25 @@ 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) {
+      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)
     if (mode.failReason) return { status: 'FAILED', woke: false, runtime, reason: mode.failReason }
     const resume = mode.resume
     const resumeRef = mode.resumeRef
@@ -622,6 +789,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 +830,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
 }
@@ -682,21 +853,26 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
     }
     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,
         })
         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' })
       continue
     }
@@ -712,7 +888,12 @@ 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` })
     } else {
@@ -723,14 +904,15 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
 }
 
 /**
- * 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 +922,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) })

package/src/lifecycle/lifecycle.test.ts

@@ -4,22 +4,29 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import {
   attachPeer,
-  clearNewMark,
+  clearNewEager,
   clearStopped,
   composeFirstMessage,
+  countRecentDeaths,
   folderLaunch,
-  hasNewMark,
+  hasIdleReaped,
+  hasNewEager,
   isLaunchdManaged,
   isStopped,
   lastActiveRuntime,
   loadLifecycleConfig,
+  readDeaths,
+  readTopic,
+  recordDeath,
   resolveWakeMode,
   resolveWakeRuntime,
-  setNewMark,
+  setIdleReaped,
+  setNewEager,
   setStopped,
   superviseTick,
   wakeOrSpawn,
   withWakeLock,
+  writeTopic,
   type LifecycleConfig,
 } from './index.ts'
 import { upsertPeer, type PeerRecord } from '../registry/index.ts'
@@ -72,10 +79,12 @@ describe('resolveWakeRuntime (H5)', () => {
 // ─────────────────────────────────────────────────────────────────────────────
 
 describe('isLaunchdManaged (H4 detector, live read-only)', () => {
-  test('a launchd-managed peer (boris has com.iapeer.boris.plist) → true', () => {
-    // The live host has com.iapeer.boris.plist — the daemon must treat boris as
-    // READ-ONLY (never wake/reap). This proves the detector fires on the fleet.
-    expect(isLaunchdManaged('boris')).toBe(true)
+  test('a launchd-managed peer (timer has com.iapeer.timer.plist) → true', () => {
+    // Post foundation-migration the always-on INFRA peers (timer/watcher/arthur) keep
+    // their com.iapeer.<p>.plist; the daemon must treat them READ-ONLY (never
+    // wake/reap). This proves the detector fires on the live fleet. (boris and the
+    // agent peers became warm-on-demand — plist relocated — so they are NOT managed.)
+    expect(isLaunchdManaged('timer')).toBe(true)
   })
 
   test('a made-up daemon-owned name (no plist) → false', () => {
@@ -338,54 +347,119 @@ describe('C2 initial_prompt (composeFirstMessage)', () => {
 })
 
 // ─────────────────────────────────────────────────────────────────────────────
-// C3a + C4a — resolveWakeMode (resume-vs-fresh; the contract-divergence fix)
+// resolveWakeMode — TARGET redesign (daemon decides fresh-vs-resume by DEATH CAUSE
+// = .idle-reaped marker, plus peer-type/topic; NO agent-dropped fresh mark).
 // ─────────────────────────────────────────────────────────────────────────────
 
-describe('resolveWakeMode (C3a default-resume + C4a /new-mark)', () => {
+/** A temp cwd with a peer-profile; interfaces.telegram present → human-conversational. */
+function profileCwd(human: boolean): string {
+  const cwd = mkdtempSync(join(tmpdir(), 'iapeer-wm-cwd-'))
+  mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+  writeFileSync(
+    join(cwd, '.iapeer', 'peer-profile.json'),
+    JSON.stringify({
+      personality: 'p',
+      runtime: 'claude',
+      runtimes: ['claude'],
+      intelligence: human ? 'natural' : 'artificial',
+      ...(human ? { interfaces: { telegram: { user_id: 1 } } } : {}),
+    }),
+  )
+  return cwd
+}
+
+describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
   let stateDir: string
+  let cwds: string[]
   beforeEach(() => {
     stateDir = mkdtempSync(join(tmpdir(), 'iapeer-wakemode-'))
+    cwds = []
   })
   afterEach(() => {
     rmSync(stateDir, { recursive: true, force: true })
+    for (const c of cwds) rmSync(c, { recursive: true, force: true })
   })
   const cfg = () => ({ stateDir } as LifecycleConfig)
+  const cwd = (human = false) => {
+    const c = profileCwd(human)
+    cwds.push(c)
+    return c
+  }
   const hasTranscript = () => ({ ok: true, ref: 'uuid-1' })
   const noTranscript = () => ({ ok: false, reason: 'no transcript to resume' })
 
-  test('DEFAULT (undefined) + transcript exists → RESUME (the warm-asleep contract fix)', () => {
-    expect(resolveWakeMode(cfg(), 'claude-p', '/cwd', undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1' })
+  // ── 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 })
   })
-  test('DEFAULT + NO transcript → FRESH (first-ever launch, not an error)', () => {
-    expect(resolveWakeMode(cfg(), 'claude-p', '/cwd', undefined, noTranscript)).toEqual({ resume: false })
+  test('argsResume=true (attach) + transcript → RESUME', () => {
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), true, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1' })
   })
-  test('explicit resume=true + nothing to resume → FAIL-LOUD (failReason, no silent fresh)', () => {
-    const m = resolveWakeMode(cfg(), 'claude-p', '/cwd', true, noTranscript)
+  test('argsResume=true + nothing to resume → FAIL-LOUD (failReason, no silent fresh)', () => {
+    const m = resolveWakeMode(cfg(), 'claude-p', cwd(), true, noTranscript)
     expect(m.resume).toBe(false)
     expect(m.failReason).toMatch(/nothing to resume|no transcript/)
   })
-  test('explicit resume=false → FRESH', () => {
-    expect(resolveWakeMode(cfg(), 'claude-p', '/cwd', false, hasTranscript)).toEqual({ resume: false })
+
+  // ── branch 3a: default + NOT idle-reaped → it died on its own → FRESH ────────
+  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 })
+  })
+
+  // ── branch 3b: default + idle-reaped → resume-eligible, CONSUME the marker ───
+  test('DEFAULT + idle-reaped + human-conversational (interfaces.telegram) → RESUME, marker consumed', () => {
+    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(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' })
+  })
+  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' })
   })
-  test('/new-mark present → FRESH and CONSUMES the mark (even if a transcript exists)', () => {
+  test('DEFAULT + idle-reaped + executor + DIFFERENT topic → FRESH (new work), marker consumed', () => {
     const c = cfg()
-    setNewMark(c, 'claude-p')
-    expect(hasNewMark(c, 'claude-p')).toBe(true)
-    expect(resolveWakeMode(c, 'claude-p', '/cwd', undefined, hasTranscript)).toEqual({ resume: false })
-    expect(hasNewMark(c, 'claude-p')).toBe(false) // consumed
+    setIdleReaped(c, 'claude-p')
+    writeTopic(c, 'claude-p', 'deploy')
+    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript, 'unrelated-bug')).toEqual({ resume: false })
+    expect(hasIdleReaped(c, 'claude-p')).toBe(false) // consumed even on the fresh executor branch
+  })
+})
+
+describe('idle-reaped marker round-trip', () => {
+  test('set/has/clear', () => {
+    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-idlereap-'))
+    const cfg = { stateDir } as LifecycleConfig
+    try {
+      expect(hasIdleReaped(cfg, 'claude-y')).toBe(false)
+      setIdleReaped(cfg, 'claude-y')
+      expect(hasIdleReaped(cfg, 'claude-y')).toBe(true)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
   })
 })
 
-describe('C4a /new-mark round-trip', () => {
+describe('new-eager marker round-trip', () => {
   test('set/has/clear', () => {
-    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-newmark-'))
+    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-neweager-'))
     const cfg = { stateDir } as LifecycleConfig
     try {
-      expect(hasNewMark(cfg, 'claude-y')).toBe(false)
-      setNewMark(cfg, 'claude-y')
-      expect(hasNewMark(cfg, 'claude-y')).toBe(true)
-      clearNewMark(cfg, 'claude-y')
-      expect(hasNewMark(cfg, 'claude-y')).toBe(false)
+      expect(hasNewEager(cfg, 'claude-y')).toBe(false)
+      setNewEager(cfg, 'claude-y')
+      expect(hasNewEager(cfg, 'claude-y')).toBe(true)
+      clearNewEager(cfg, 'claude-y')
+      expect(hasNewEager(cfg, 'claude-y')).toBe(false)
     } finally {
       rmSync(stateDir, { recursive: true, force: true })
     }
@@ -393,55 +467,54 @@ describe('C4a /new-mark round-trip', () => {
 })
 
 // ─────────────────────────────────────────────────────────────────────────────
-// C4b — eager fresh re-launch detection (superviseTick flags a dead +/new session)
+// superviseTick — death-cause accounting (TARGET redesign)
+//  • idle-reap is the ONLY place .idle-reaped is written
+//  • a crash/self-close death writes NO marker (lazy fresh on next message)
+//  • a dead session carrying .new-eager → needs-eager-fresh (mark LEFT for relaunch)
+//  • every dead session records a death (crash-loop accounting)
 // ─────────────────────────────────────────────────────────────────────────────
 
-describe('C4b eager fresh re-launch (superviseTick detection)', () => {
-  test('a DEAD session carrying a /new-mark → needs-eager-fresh (mark LEFT for relaunch)', () => {
-    const root = mkdtempSync(join(tmpdir(), 'iapeer-c4b-root-'))
-    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-c4b-la-')) // empty → not launchd-managed
+describe('superviseTick death-cause accounting (TARGET)', () => {
+  function deadSessionEnv(personality: string): { env: NodeJS.ProcessEnv; cfg: LifecycleConfig; root: string; laDir: string } {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-sup-tgt-root-'))
+    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-sup-tgt-la-')) // empty → not launchd-managed
+    const env = { ...process.env, IAPEER_ROOT: root, IAPEER_LAUNCHAGENTS_DIR: laDir, IAPEER_SOCK_DIR: join(root, 'socks') }
+    const cfg = loadLifecycleConfig(env)
+    mkdirSync(cfg.stateDir, { recursive: true })
+    writeFileSync(
+      join(cfg.stateDir, `claude-${personality}.session`),
+      JSON.stringify({ identity: `claude-${personality}`, runtime: 'claude', personality, cwd: `/tmp/${personality}`, wokeAt: Date.now() }),
+    )
+    return { env, cfg, root, laDir }
+  }
+
+  test('a DEAD session carrying .new-eager → needs-eager-fresh (mark LEFT for relaunch), death recorded', () => {
+    const { env, cfg, root, laDir } = deadSessionEnv('z')
     try {
-      const env = {
-        ...process.env,
-        IAPEER_ROOT: root,
-        IAPEER_LAUNCHAGENTS_DIR: laDir,
-        IAPEER_SOCK_DIR: join(root, 'socks'), // isolated, no live session here → dead
-      }
-      const cfg = loadLifecycleConfig(env)
-      mkdirSync(cfg.stateDir, { recursive: true })
-      // a session-state for a peer whose session is NOT live (dead)
-      writeFileSync(
-        join(cfg.stateDir, 'claude-z.session'),
-        JSON.stringify({ identity: 'claude-z', runtime: 'claude', personality: 'z', cwd: '/tmp/z', wokeAt: Date.now() }),
-      )
-      setNewMark(cfg, 'claude-z')
+      setNewEager(cfg, 'claude-z')
       const out = superviseTick(cfg, { env })
       const o = out.find(x => x.identity === 'claude-z')
       expect(o?.action).toBe('needs-eager-fresh')
       expect(o?.personality).toBe('z')
       expect(o?.runtime).toBe('claude')
-      // the session-state is removed, but the /new-mark is LEFT for the eager
-      // relaunch's resolveWakeMode to consume (so the relaunch resolves to fresh).
-      expect(hasNewMark(cfg, 'claude-z')).toBe(true)
+      // the eager mark is LEFT for processEagerRelaunches to consume
+      expect(hasNewEager(cfg, 'claude-z')).toBe(true)
+      // every dead session records a death for the crash-loop ring
+      expect(readDeaths(cfg, 'claude-z').length).toBe(1)
     } finally {
       rmSync(root, { recursive: true, force: true })
       rmSync(laDir, { recursive: true, force: true })
     }
   })
 
-  test('a DEAD session with NO /new-mark → reaped-gone (not eager)', () => {
-    const root = mkdtempSync(join(tmpdir(), 'iapeer-c4b2-root-'))
-    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-c4b2-la-'))
+  test('a DEAD session with NO .new-eager → reaped-gone, NO .idle-reaped written (crash leaves no marker)', () => {
+    const { env, cfg, root, laDir } = deadSessionEnv('w')
     try {
-      const env = { ...process.env, IAPEER_ROOT: root, IAPEER_LAUNCHAGENTS_DIR: laDir, IAPEER_SOCK_DIR: join(root, 'socks') }
-      const cfg = loadLifecycleConfig(env)
-      mkdirSync(cfg.stateDir, { recursive: true })
-      writeFileSync(
-        join(cfg.stateDir, 'claude-w.session'),
-        JSON.stringify({ identity: 'claude-w', runtime: 'claude', personality: 'w', cwd: '/tmp/w', wokeAt: Date.now() }),
-      )
       const out = superviseTick(cfg, { env })
       expect(out.find(x => x.identity === 'claude-w')?.action).toBe('reaped-gone')
+      // a crash/self-close is NOT daemon-initiated → no idle-reaped marker → next wake FRESH
+      expect(hasIdleReaped(cfg, 'claude-w')).toBe(false)
+      expect(readDeaths(cfg, 'claude-w').length).toBe(1)
     } finally {
       rmSync(root, { recursive: true, force: true })
       rmSync(laDir, { recursive: true, force: true })
@@ -449,6 +522,71 @@ describe('C4b eager fresh re-launch (superviseTick detection)', () => {
   })
 })
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Crash-loop guard — wakeOrSpawn refuses to (re)launch after N deaths in the window
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('crash-loop guard', () => {
+  test('countRecentDeaths windows correctly; recordDeath rings', () => {
+    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-deaths-'))
+    const cfg = { stateDir } as LifecycleConfig
+    try {
+      const now = 1_000_000
+      recordDeath(cfg, 'claude-d', now - 400_000) // outside a 300s window
+      recordDeath(cfg, 'claude-d', now - 10_000)
+      recordDeath(cfg, 'claude-d', now - 5_000)
+      expect(countRecentDeaths(cfg, 'claude-d', 300, now)).toBe(2)
+      expect(countRecentDeaths(cfg, 'claude-d', 600, now)).toBe(3)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+
+  test('wakeOrSpawn REFUSES after crashLoopMax deaths within the window (FAILED, no launch)', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-clg-root-'))
+    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-clg-la-')) // empty → not launchd-managed
+    const peerCwd = mkdtempSync(join(tmpdir(), 'iapeer-clg-cwd-')) // REAL cwd so the cwd-existence check passes and the guard is what fires
+    try {
+      await upsertPeer(
+        { personality: 'clg', runtime: 'claude', cwd: peerCwd, intelligence: 'artificial' },
+        { rootDir: root },
+      )
+      const env = { ...process.env, IAPEER_ROOT: root, IAPEER_LAUNCHAGENTS_DIR: laDir, IAPEER_SOCK_DIR: join(root, 'socks'), IAPEER_CRASHLOOP_MAX: '3', IAPEER_CRASHLOOP_WINDOW_SECS: '300' }
+      const cfg = loadLifecycleConfig(env)
+      const now = Date.now()
+      recordDeath(cfg, 'claude-clg', now)
+      recordDeath(cfg, 'claude-clg', now)
+      recordDeath(cfg, 'claude-clg', now)
+      const r = await wakeOrSpawn({ personality: 'clg', runtime: 'claude', task: 'must not launch' }, { env })
+      expect(r.status).toBe('FAILED')
+      expect(r.woke).toBe(false)
+      expect(r.reason).toMatch(/crash-loop guard/)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+      rmSync(laDir, { recursive: true, force: true })
+      rmSync(peerCwd, { recursive: true, force: true })
+    }
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// .topic — executor discriminator round-trip
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('topic marker round-trip', () => {
+  test('writeTopic/readTopic', () => {
+    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-topic-'))
+    const cfg = { stateDir } as LifecycleConfig
+    try {
+      expect(readTopic(cfg, 'claude-t')).toBe('')
+      writeTopic(cfg, 'claude-t', 'deploy-pipeline')
+      expect(readTopic(cfg, 'claude-t')).toBe('deploy-pipeline')
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+})
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Ф-D launch / attach — operator verbs (error paths; success paths are live-verified)
 // ─────────────────────────────────────────────────────────────────────────────