@agfpd/iapeer 0.1.0

package/src/lifecycle/index.ts

@@ -0,0 +1,840 @@
+// Lifecycle — wake-on-miss / supervise / reap. The warm-on-demand core: a dead
+// peer is woken (spawned) on demand, its first message delivered, and idle
+// sessions are reaped. Consolidated from Spawned-Peer spawner.ts (performSpawn)
+// + watcher.ts (boot / ready-gate / idle phases), but with the detached
+// per-session watcher COLLAPSED into the daemon: wakeOrSpawn runs boot + ready
+// inline (the daemon awaits it) and a single superviseTick drives idle-reap.
+//
+// HARD SAFETY (H4): the daemon NEVER wakes / reaps / respawns / sweeps a peer
+// that has a launchd plist (~/Library/LaunchAgents/com.iapeer.<p>.plist). Such a
+// peer is launchd-managed (KeepAlive owns its lifecycle); the daemon touching it
+// would race launchd on the live fleet. isLaunchdManaged() is checked FIRST,
+// before any wake or reap. wakeOrSpawn refuses a launchd peer; superviseTick and
+// sweepZombies skip it. Only daemon-owned (no-plist) peers are managed here.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import * as lockfile from 'proper-lockfile'
+import {
+  STATE_DIR,
+  LOGS_DIR,
+  isRuntime,
+  resolveSockDir,
+  type Runtime,
+} from '../core/constants.ts'
+import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
+import { err, ok, type Result } from '../core/errors.ts'
+import { resolveGlobalRoot } from '../storage/index.ts'
+import { readPeerProfile, resolveIdentity } from '../identity/index.ts'
+import { findPeer, publicPeerSummary, readPeersIndex, type PeerRecord, type PublicPeerSummary } from '../registry/index.ts'
+// Ф3: launch = HOW to bring up ONE session (runtime-agnostic primitive + adapter).
+// lifecycle decides WHEN/HOW-MANY and delegates the bring-up to launch.
+import {
+  getAdapter,
+  launch,
+  launchAgentsDir,
+  launchdLabel,
+  type LaunchConfig,
+  type LaunchSpec,
+} from '../launch/index.ts'
+import { composeSystemPrompt, gatherPromptInput } from '../launch/composeSystemPrompt.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface LifecycleConfig {
+  claudeBin: string
+  codexBin: string
+  sockDir: string
+  stateDir: string // ~/.iapeer/state/lifecycle
+  logDir: string // ~/.iapeer/logs/lifecycle
+  bootDeadlineSecs: number
+  readyGateSecs: number
+  idleSecs: number
+  maxAgeSecs: number
+}
+
+export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): LifecycleConfig {
+  const home = env.HOME?.trim() || homedir()
+  const root = resolveGlobalRoot(env)
+  const num = (raw: string | undefined, dflt: number): number => {
+    const n = parseInt(raw ?? '', 10)
+    return Number.isFinite(n) && n > 0 ? n : dflt
+  }
+  return {
+    claudeBin: env.IAPEER_CLAUDE_BIN ?? join(home, '.local', 'bin', 'claude'),
+    codexBin: env.IAPEER_CODEX_BIN ?? 'codex',
+    sockDir: resolveSockDir(env),
+    stateDir: join(root, STATE_DIR, 'lifecycle'),
+    logDir: join(root, LOGS_DIR, 'lifecycle'),
+    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),
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// H4 — launchd-managed detector (checked FIRST, before any wake/reap)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * True iff the peer is launchd-managed: `~/Library/LaunchAgents/
+ * com.iapeer.<personality>.plist` exists. A launchd peer is in the launchd
+ * domain — KeepAlive owns its lifecycle — and the daemon must be READ-ONLY for
+ * it (deliver to it if live, but never wake / reap / respawn / sweep it). This
+ * is the hard guard against fighting launchd on the live fleet.
+ */
+export function isLaunchdManaged(personality: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  // Label + LaunchAgents dir come from the SAME helpers the plist generator uses
+  // (launch/launchd.ts), so this H4 detector and installAlwaysOnPlist can never
+  // disagree on `com.iapeer.<personality>.plist`. IAPEER_LAUNCHAGENTS_DIR overrides
+  // the dir for tests (so an H4-guard test never touches ~/Library/LaunchAgents).
+  return existsSync(join(launchAgentsDir(env), `${launchdLabel(personality)}.plist`))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Session state — what the supervisor walks (daemon-owned sessions only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SessionState {
+  identity: string
+  runtime: Runtime
+  personality: string
+  cwd: string
+  wokeAt: number
+}
+
+function sessionStatePath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.session`)
+}
+
+function writeSessionState(cfg: LifecycleConfig, state: SessionState): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  try {
+    writeFileSync(sessionStatePath(cfg, state.identity), JSON.stringify(state), { mode: 0o600 })
+  } catch {
+    /* best-effort — supervision degrades to liveness scan, never blocks a wake */
+  }
+}
+
+function removeSessionState(cfg: LifecycleConfig, identity: string): void {
+  try {
+    rmSync(sessionStatePath(cfg, identity), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// C1 — durable stopped flag (warm-on-demand stop/start; contract ЖЦ §stop/start,
+// Демон §stopped). `stop <peer>` on a warm runtime kills the session AND drops this
+// flag → the daemon REFUSES to wake the peer (a DELIBERATE operator halt, not a
+// fault — no message queue, the sender gets an explicit "stopped" error). `start`
+// clears it (wakeable again). Distinct from idle-reap (temporary; the daemon DOES
+// wake on the next message). Lives next to the session-state, in state/lifecycle —
+// daemon-owned, durable across restarts. Keyed on IDENTITY (runtime-personality):
+// `stop <peer> <runtime>` halts one runtime; the flag is per-runtime presence.
+// always-on (launchd) peers are NOT stopped this way — their stop is launchctl
+// bootout (ЖЦ); a launchd peer never carries this flag (and the daemon is H4
+// read-only for it regardless).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function stoppedFlagPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.stopped`)
+}
+
+/** True iff the peer identity carries a durable stop flag (daemon must not wake it). */
+export function isStopped(cfg: LifecycleConfig, identity: string): boolean {
+  return existsSync(stoppedFlagPath(cfg, identity))
+}
+
+/** Drop the durable stop flag (the `stop` verb does this after killing the session). */
+export function setStopped(cfg: LifecycleConfig, identity: string): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  writeFileSync(stoppedFlagPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
+}
+
+/** Clear the durable stop flag (the `start` verb does this — peer wakeable again). */
+export function clearStopped(cfg: LifecycleConfig, identity: string): void {
+  try {
+    rmSync(stoppedFlagPath(cfg, identity), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function newMarkPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.new`)
+}
+
+/** 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))
+}
+
+/** Drop the /new mark (the agent's self-kill ritual does this before exiting). */
+export function setNewMark(cfg: LifecycleConfig, identity: string): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  writeFileSync(newMarkPath(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 {
+  try {
+    rmSync(newMarkPath(cfg, identity), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface WakeMode {
+  resume: boolean
+  resumeRef?: string
+  /** Set ONLY for an EXPLICIT resume request that found nothing to resume — the
+   *  caller must fail loud (never a silent fresh fallback). */
+  failReason?: 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).
+ */
+export function resolveWakeMode(
+  cfg: LifecycleConfig,
+  identity: string,
+  cwd: string,
+  argsResume: boolean | undefined,
+  resolveResume: (cwd: string) => { ok: boolean; ref?: string; reason?: 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 }
+  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 }
+  }
+  const r = resolveResume(cwd)
+  return r.ok ? { resume: true, resumeRef: r.ref } : { resume: false }
+}
+
+export function readSessionStates(cfg: LifecycleConfig): SessionState[] {
+  let files: string[]
+  try {
+    files = readdirSync(cfg.stateDir)
+  } catch {
+    return []
+  }
+  const out: SessionState[] = []
+  for (const f of files) {
+    if (!f.endsWith('.session')) continue
+    try {
+      const s = JSON.parse(readFileSync(join(cfg.stateDir, f), 'utf8')) as SessionState
+      if (s && s.identity && s.cwd && isRuntime(s.runtime)) out.push(s)
+    } catch {
+      /* skip garbage */
+    }
+  }
+  return out
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// H5 — wake-runtime resolution (registry-based, NO live-socket scan)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Decide which runtime to wake on a miss, WITHOUT scanning live sockets (a dead
+ * peer has none — the registry is the only source). Order: an explicit
+ * caller-supplied runtime (must be declared) → peer.runtime (registry default)
+ * → first of peer.runtimes[] → fail-loud. (blueprint-v2 §H5)
+ */
+export function resolveWakeRuntime(
+  requested: string | undefined,
+  peer: PeerRecord,
+): Result<Runtime> {
+  if (requested) {
+    if (!isRuntime(requested)) return err(`invalid runtime "${requested}"`)
+    if (peer.runtime !== requested && !peer.runtimes.includes(requested)) {
+      return err(`runtime "${requested}" is not declared for "${peer.personality}"`)
+    }
+    return ok(requested)
+  }
+  if (peer.runtime) return ok(peer.runtime)
+  if (peer.runtimes.length > 0) return ok(peer.runtimes[0])
+  return err(`cannot pick a runtime to wake "${peer.personality}"; specify runtime`)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Wake lock — serialize wake per identity (idempotent; concurrent = one spawn)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Run `fn` while holding an exclusive per-identity lock so two concurrent sends
+ * to the same dead peer produce exactly ONE spawn (the second waits, then takes
+ * the has-session fast path inside the lock). flock-style advisory lock via
+ * proper-lockfile on ~/.iapeer/state/lifecycle/<identity>.wake.lock.
+ */
+export async function withWakeLock<T>(
+  cfg: LifecycleConfig,
+  identity: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  const lockTarget = join(cfg.stateDir, `${identity}.wake.lock`)
+  writeFileSync(lockTarget, '', { flag: 'a', mode: 0o600 })
+  const release = await lockfile.lock(lockTarget, {
+    realpath: false,
+    stale: 60_000,
+    update: 5_000,
+    retries: { retries: 30, factor: 1.3, minTimeout: 100, maxTimeout: 1_000 },
+  })
+  try {
+    return await fn()
+  } finally {
+    await release()
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// tmux helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function tmux(sock: string, ...args: string[]): { ok: boolean; out: string; err: string } {
+  const r = spawnSync('tmux', ['-S', sock, ...args], { encoding: 'utf8' })
+  return { ok: r.status === 0, out: r.stdout ?? '', err: r.stderr ?? '' }
+}
+function sessionAlive(sock: string, identity: string): boolean {
+  return tmux(sock, 'has-session', '-t', identity).ok
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// System-prompt composition for a woken peer (delegates the jq doctrine-merge to
+// launch/composeSystemPrompt). The tmux launch + boot/ready + activity-proxy all
+// moved to launch/ (Ф3); lifecycle only gathers the inputs and decides when.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function gatherSystemFacts(env: NodeJS.ProcessEnv): {
+  platform: string
+  osVersion: string
+  user: string
+  hostname: string
+  today: string
+} {
+  const platform =
+    process.platform === 'darwin'
+      ? 'darwin'
+      : process.platform === 'linux'
+        ? 'linux'
+        : String(process.platform)
+  let osVersion = 'unknown'
+  if (platform === 'darwin') {
+    const r = spawnSync('sw_vers', ['-productVersion'], { encoding: 'utf8' })
+    if (r.status === 0) osVersion = (r.stdout ?? '').trim() || 'unknown'
+  } else if (platform === 'linux') {
+    try {
+      const m = readFileSync('/etc/os-release', 'utf8').match(/^VERSION_ID="?([^"\n]+)/m)
+      osVersion = m?.[1] ?? 'unknown'
+    } catch {
+      /* unknown */
+    }
+  }
+  let hostname = 'unknown'
+  const h = spawnSync('hostname', ['-s'], { encoding: 'utf8' })
+  if (h.status === 0 && (h.stdout ?? '').trim()) hostname = h.stdout.trim()
+  let user = env.USER?.trim() ?? ''
+  if (!user) {
+    const r = spawnSync('id', ['-un'], { encoding: 'utf8' })
+    user = (r.stdout ?? '').trim() || 'unknown'
+  }
+  const d = new Date()
+  const today = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+  return { platform, osVersion, user, hostname, today }
+}
+
+/**
+ * Compose the merged system prompt for a peer that carries a doctrine and write
+ * it to a per-identity file, returning its path (for --system-prompt-file /
+ * model_instructions_file).
+ *
+ * Канал A, all four layers (docs/Сборка системного промпта): 1 YAML facts +
+ * 2 IAPEER.md (global+local) + 3 normalized registry + 4 every other <DOMAIN>.md
+ * (global+local). FS discovery is delegated to gatherPromptInput; composeSystem
+ * Prompt lays out the bytes. Layers 3+4 add nothing when there are no peers and
+ * no extra domains, so the output stays golden-identical for a bare doctrine.
+ *
+ * BARE-SESSION GATE (unchanged): a peer WITHOUT a local <cwd>/.iapeer/IAPEER.md
+ * doctrine → undefined (a throwaway test peer launches bare). The local doctrine
+ * is what marks "this is a configured peer" (contract: role lives in that file).
+ */
+function composePeerPrompt(
+  peer: PeerRecord,
+  cwd: string,
+  identity: string,
+  cfg: LifecycleConfig,
+  env: NodeJS.ProcessEnv,
+  peers: PublicPeerSummary[],
+): string | undefined {
+  const peerDoctrinePath = join(cwd, '.iapeer', 'IAPEER.md')
+  if (!existsSync(peerDoctrinePath)) return undefined
+  const facts = gatherSystemFacts(env)
+  // `peers` is the registry already read for findPeer (wake path) — passed through
+  // so gatherPromptInput does NOT read+parse peers-profiles.json a second time on
+  // this hot launch path (and the corrupt-registry failure stays at that one read).
+  const input = gatherPromptInput({
+    personality: peer.personality,
+    description: peer.description,
+    cwd,
+    ...facts,
+    env,
+    peers,
+  })
+  const prompt = composeSystemPrompt(input)
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  const file = join(cfg.stateDir, `${identity}.system-prompt.md`)
+  writeFileSync(file, prompt, { mode: 0o600 })
+  return file
+}
+
+/**
+ * C2 — compose the first message delivered to a FRESH-woken session: the peer's
+ * initial_prompt (launch-seed, contract ЖЦ §initial_prompt) followed by the routed
+ * `task` (the IAP envelope), so the agent sees the opening directive THEN the message
+ * it must reply to (with its from-*). On resume (fresh=false) or with no seed → just
+ * the task. The seed is read from the local profile best-effort: a profile read error
+ * yields no seed and never blocks the wake (the seed is optional).
+ */
+export function composeFirstMessage(cwd: string, task: string, fresh: boolean): string {
+  if (!fresh) return task
+  let seed: string | undefined
+  try {
+    seed = readPeerProfile(cwd)?.initial_prompt
+  } catch {
+    /* invalid/absent profile → no seed */
+  }
+  if (!seed) return task
+  // seed + the routed message (both delivered, seed first). When there is NO incoming
+  // message (an eager /new re-launch, C4b — task is empty), the seed is self-sufficient.
+  return task ? `${seed}\n\n${task}` : seed
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wakeOrSpawn — the WakeFn (= performSpawn consolidated, boot+ready inline)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface WakeArgs {
+  personality: string
+  runtime?: string
+  topic?: string
+  /** First message delivered to the woken session (the routed envelope). */
+  task: string
+  resume?: boolean
+}
+
+export interface WakeResult {
+  status: 'READY' | 'FAILED'
+  woke: boolean
+  runtime?: Runtime
+  process_address?: string
+  reason?: string
+  /** C1: the wake was refused because the peer carries a durable stop flag (a
+   *  deliberate halt, distinct from offline/wake-failure). The sender is told the
+   *  peer is stopped, not that delivery failed transiently. */
+  stopped?: boolean
+}
+
+export interface WakeDeps {
+  env?: NodeJS.ProcessEnv
+  cfg?: LifecycleConfig
+}
+
+/**
+ * Wake (or, idempotently, reuse) a peer session and deliver `task` as its first
+ * message; resolve to READY only after the model has produced its first turn
+ * (transcript mtime advances past baseline). Serialized per-identity by
+ * withWakeLock. Refuses a launchd-managed peer (H4). Ф2 claude path; codex is a
+ * follow-up (the structure generalizes).
+ */
+export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<WakeResult> {
+  const env = deps.env ?? process.env
+  const cfg = deps.cfg ?? loadLifecycleConfig(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.
+  try {
+    superviseTick(cfg, { env })
+  } catch {
+    /* supervision must never affect this wake's outcome */
+  }
+
+  const peersIndex = readPeersIndex({ env })
+  const peer = findPeer(peersIndex, args.personality)
+  if (!peer) return { status: 'FAILED', woke: false, reason: `unknown peer "${args.personality}"` }
+
+  // H4 — never wake a launchd-managed peer (launchd KeepAlive owns it).
+  if (isLaunchdManaged(args.personality, env)) {
+    return {
+      status: 'FAILED',
+      woke: false,
+      reason: `"${args.personality}" is launchd-managed; the daemon does not wake it (launchd KeepAlive owns its lifecycle)`,
+    }
+  }
+
+  const runtimeResult = resolveWakeRuntime(args.runtime, peer)
+  if (!runtimeResult.ok) return { status: 'FAILED', woke: false, reason: runtimeResult.error.message }
+  const runtime = runtimeResult.value
+
+  // Resolve the per-runtime adapter (launch = HOW). getAdapter throws only for an
+  // unregistered runtime (claude/codex/telegram/notifier are all registered);
+  // surface that as FAILED rather than letting it escape the wake.
+  let adapter
+  try {
+    adapter = getAdapter(runtime)
+  } catch (e) {
+    return { status: 'FAILED', woke: false, runtime, reason: e instanceof Error ? e.message : String(e) }
+  }
+
+  const identity = buildProcessAddress(runtime, args.personality)
+  const sock = buildSocketPath(runtime, args.personality, cfg.sockDir)
+  const cwd = peer.cwd
+
+  // C1 — durable stopped flag: a DELIBERATELY stopped peer is NOT woken (contract
+  // ЖЦ §stop, Демон §stopped). Unlike idle-reap (temporary), `stop` is an operator
+  // 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)) {
+    return {
+      status: 'FAILED',
+      woke: false,
+      runtime,
+      stopped: true,
+      reason: `"${args.personality}" (${runtime}) is stopped and not accepting messages; start it to resume`,
+    }
+  }
+
+  return withWakeLock(cfg, identity, async () => {
+    // Re-check the refusal gates INSIDE the lock (audit #3/#11): a `stop` (C1 flag) or a
+    // plist install that completed AFTER the pre-lock check but before the lock was
+    // acquired must still be honored — else a concurrently stopped / launchd-claimed peer
+    // could be spawned live-but-flagged. These re-checks are fail-SAFE (they only add a
+    // 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)) {
+      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)) {
+      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
+    // wake already brought it up) — no second spawn.
+    if (sessionAlive(sock, identity)) {
+      writeSessionState(cfg, { identity, runtime, personality: args.personality, cwd, wokeAt: Date.now() })
+      return { status: 'READY', woke: false, runtime, process_address: identity }
+    }
+    if (!existsSync(cwd)) {
+      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))
+    if (mode.failReason) return { status: 'FAILED', woke: false, runtime, reason: mode.failReason }
+    const resume = mode.resume
+    const resumeRef = mode.resumeRef
+    const fresh = !resume
+
+    // Compose the system prompt when the peer carries a doctrine (tui runtimes);
+    // a doctrine-less peer (throwaway) → undefined → a bare session.
+    const systemPromptFile = adapter.usesDoctrine
+      ? composePeerPrompt(peer, cwd, identity, cfg, env, peersIndex.peers.map(publicPeerSummary))
+      : undefined
+
+    // Hand the fully-resolved spec to the launch primitive (HOW). lifecycle has
+    // made every WHEN/HOW-MANY decision (lock, registry, H4, runtime, resume).
+    const spec: LaunchSpec = {
+      personality: args.personality,
+      runtime,
+      cwd,
+      identity,
+      socketPath: sock,
+      systemPromptFile,
+      resume, // RESOLVED resume/fresh (C3a), not the raw caller flag
+      resumeRef,
+      extraArgs: [],
+      // Carry the peer's nature so the launch primitive can enforce an adapter's
+      // intelligence gate (telegram requires natural). From the registry record.
+      intelligence: peer.intelligence,
+    }
+    const launchCfg: LaunchConfig = {
+      claudeBin: cfg.claudeBin,
+      codexBin: cfg.codexBin,
+      sockDir: cfg.sockDir,
+      bootDeadlineSecs: cfg.bootDeadlineSecs,
+      readyGateSecs: cfg.readyGateSecs,
+      maxAgeSecs: cfg.maxAgeSecs,
+      logDir: cfg.logDir,
+      env,
+    }
+    // C2 — initial_prompt (launch-seed): on a FRESH wake, seed the first turn with
+    // the peer's initial_prompt BEFORE the routed message — the agent sees the
+    // opening directive, then the IAP message (with its from-* to reply to). NOT on
+    // resume (a resumed session already holds its context). Best-effort read: a
+    // profile read hiccup must never block the wake (the seed is optional).
+    const firstMessage = composeFirstMessage(cwd, args.task, fresh)
+    const result = await launch(spec, adapter, firstMessage, launchCfg)
+    if (result.status === 'FAILED') {
+      return { status: 'FAILED', woke: false, runtime, reason: result.reason }
+    }
+    // The session is up and the message delivered. Recording supervise-state must not
+    // turn a successful wake into a failure (audit #18): on a write hiccup the session is
+    // still bounded by its tmux self-TTL — log loudly rather than throw past a live spawn.
+    try {
+      writeSessionState(cfg, { identity, runtime, personality: args.personality, cwd, wokeAt: Date.now() })
+    } catch (e) {
+      process.stderr.write(
+        `[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`,
+      )
+    }
+    return { status: 'READY', woke: true, runtime, process_address: identity }
+  })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Reap — kill a session (used by idle-reap / supervise; H4-guarded by callers)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function killSession(sock: string, identity: string): void {
+  tmux(sock, 'kill-session', '-t', identity)
+  const sessions = tmux(sock, 'list-sessions', '-F', '#{session_name}').out
+  if (!sessions.trim()) {
+    tmux(sock, 'kill-server')
+    try {
+      rmSync(sock, { force: true })
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// superviseTick — the SINGLE H4-guarded reap pass (idle + zombie-gone)
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Walks only daemon-owned sessions (those wakeOrSpawn recorded a .session for —
+// a launchd peer never has one). For each candidate the launchd-plist check is
+// FIRST: a launchd-managed peer is skipped untouched (H4 — the daemon is
+// read-only for it; reaping it would fight launchd KeepAlive on the live fleet).
+// In this consolidation the idle-reap and the zombie-sweep are ONE guarded path,
+// so no reap can bypass H4. Called by the daemon's supervise timer AND at the
+// start of every wakeOrSpawn (heal strays before launching).
+
+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. */
+  personality?: string
+  runtime?: Runtime
+}
+
+export interface SuperviseDeps {
+  env?: NodeJS.ProcessEnv
+  nowMs?: number
+}
+
+export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): SuperviseOutcome[] {
+  const env = deps.env ?? process.env
+  const nowMs = deps.nowMs ?? Date.now()
+  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' })
+      continue
+    }
+    const sock = buildSocketPath(s.runtime, s.personality, cfg.sockDir)
+    if (!sessionAlive(sock, s.identity)) {
+      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)) {
+        out.push({
+          identity: s.identity,
+          action: 'needs-eager-fresh',
+          reason: '/new graceful mark — eager fresh re-launch',
+          personality: s.personality,
+          runtime: s.runtime,
+        })
+        continue
+      }
+      out.push({ identity: s.identity, action: 'reaped-gone', reason: 'session no longer live' })
+      continue
+    }
+    // Idle accounting via the runtime adapter's activity proxy (claude transcript
+    // / codex session mtime); fall back to wokeAt so a session that produced zero
+    // further turns is still reaped, and when no adapter exists yet (codex/telegram
+    // pre-workflow-#2 — session-states are claude-only for now anyway).
+    let mt = s.wokeAt
+    try {
+      mt = getAdapter(s.runtime).newestActivityMtime(s.cwd) ?? s.wokeAt
+    } catch {
+      /* no adapter for this runtime yet → wokeAt fallback */
+    }
+    const ageSecs = Math.floor((nowMs - mt) / 1000)
+    if (ageSecs > cfg.idleSecs) {
+      killSession(sock, s.identity)
+      removeSessionState(cfg, s.identity)
+      out.push({ identity: s.identity, action: 'reaped-idle', reason: `idle ${ageSecs}s` })
+    } else {
+      out.push({ identity: s.identity, action: 'alive' })
+    }
+  }
+  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.
+ */
+export async function processEagerRelaunches(
+  cfg: LifecycleConfig,
+  outcomes: SuperviseOutcome[],
+  deps: WakeDeps = {},
+): Promise<WakeResult[]> {
+  const results: WakeResult[] = []
+  for (const o of outcomes) {
+    if (o.action !== 'needs-eager-fresh' || !o.personality || !o.runtime) continue
+    try {
+      results.push(
+        await wakeOrSpawn({ personality: o.personality, runtime: o.runtime, task: '' }, { cfg, env: deps.env }),
+      )
+    } catch (e) {
+      results.push({ status: 'FAILED', woke: false, reason: e instanceof Error ? e.message : String(e) })
+    }
+  }
+  return results
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// folderLaunch / attachPeer — operator verbs (contract ЖЦ §Запуск из папки, §attach;
+// Примитивы §Карта verbs). Both reuse wakeOrSpawn (one bring-up path); the difference
+// is resume vs fresh and which runtime.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FolderLaunchOptions {
+  cwd: string
+  runtime?: string
+  env?: NodeJS.ProcessEnv
+  cfg?: LifecycleConfig
+}
+
+/**
+ * `iapeer <runtime>` (launch) — bring up the peer of the CURRENT cwd, ALWAYS FRESH
+ * (contract: folder-launch never resumes). personality/runtime come from the cwd's
+ * profile (resolveIdentity), not an arg. The fresh session carries the initial_prompt
+ * seed if the peer has one (composeFirstMessage), else a bare interactive session the
+ * operator drives. Goes through wakeOrSpawn (resume:false) so H4 / the wake-lock /
+ * the intelligence gate all apply — incl. H4 refusal for a launchd-managed peer (a
+ * fresh folder-launch alongside its launchd session would collide on the identity).
+ */
+export async function folderLaunch(opts: FolderLaunchOptions): Promise<WakeResult> {
+  const env = opts.env ?? process.env
+  const cfg = opts.cfg ?? loadLifecycleConfig(env)
+  const identity = resolveIdentity({ cwd: opts.cwd, env })
+  const runtime = opts.runtime ?? identity.runtime
+  const seed = composeFirstMessage(opts.cwd, '', true) // initial_prompt or '' (bare)
+  return wakeOrSpawn({ personality: identity.personality, runtime, task: seed, resume: false }, { cfg, env })
+}
+
+/**
+ * The runtime with the freshest transcript activity for a peer (contract: attach
+ * resolves the runtime by last-active transcript-mtime, NOT the profile default).
+ * undefined when no runtime has any activity (a never-run peer).
+ */
+export function lastActiveRuntime(peer: PeerRecord, cfg: LifecycleConfig): Runtime | undefined {
+  let best: Runtime | undefined
+  let bestMt = -1
+  for (const rt of peer.runtimes) {
+    try {
+      const mt = getAdapter(rt).newestActivityMtime(peer.cwd)
+      if (mt !== null && mt > bestMt) {
+        bestMt = mt
+        best = rt
+      }
+    } catch {
+      /* no adapter / no proxy for this runtime */
+    }
+  }
+  return best
+}
+
+export interface AttachOptions {
+  personality: string
+  runtime?: string
+  env?: NodeJS.ProcessEnv
+  cfg?: LifecycleConfig
+}
+export type AttachResult =
+  | { ok: true; identity: string; socketPath: string; woke: boolean; runtime: Runtime }
+  | { ok: false; reason: string }
+
+/**
+ * `iapeer attach <peer> [runtime]` — ensure the peer is live, then hand back the
+ * socket/identity for the caller to `tmux attach`. ALWAYS RESUME (contract: attach
+ * never starts fresh). Runtime: explicit arg, else the LAST-ACTIVE runtime by
+ * transcript-mtime (not the profile default), else the profile default. A warm-live
+ * session is attached directly; a warm-asleep one is woken with --resume first
+ * (fail-loud if there is nothing to resume — a never-run peer must be folder-launched).
+ */
+export async function attachPeer(opts: AttachOptions): Promise<AttachResult> {
+  const env = opts.env ?? process.env
+  const cfg = opts.cfg ?? loadLifecycleConfig(env)
+  const peer = findPeer(readPeersIndex({ env }), opts.personality)
+  if (!peer) return { ok: false, reason: `peer "${opts.personality}" is not registered` }
+  const runtimeResult = resolveWakeRuntime(opts.runtime, peer)
+  if (opts.runtime && !runtimeResult.ok) return { ok: false, reason: runtimeResult.error.message }
+  // last-active (by mtime) wins over the profile default when no runtime is given.
+  const runtime = opts.runtime ?? lastActiveRuntime(peer, cfg) ?? peer.runtime
+  const identity = buildProcessAddress(runtime, opts.personality)
+  const sock = buildSocketPath(runtime, opts.personality, cfg.sockDir)
+  if (sessionAlive(sock, identity)) return { ok: true, identity, socketPath: sock, woke: false, runtime }
+  const woke = await wakeOrSpawn({ personality: opts.personality, runtime, task: '', resume: true }, { cfg, env })
+  if (woke.status === 'FAILED') return { ok: false, reason: woke.reason ?? 'wake failed' }
+  return { ok: true, identity, socketPath: sock, woke: true, runtime }
+}