@agfpd/iapeer 0.4.34 → 0.4.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.34",
+  "version": "0.4.36",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/lifecycle/index.ts

@@ -12,7 +12,7 @@
 // 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, statSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { spawnSync } from 'child_process'
@@ -90,6 +90,10 @@ export interface LifecycleConfig {
    *  A still-WORKING silent-tool worker keeps the pane-log fresh via the TUI render, so it
    *  is no longer reaped mid-task — only a genuinely idle/wedged session crosses this. */
   ephemeralUnarmedIdleSecs: number
+  /** Wake-lock acquisition retries (proper-lockfile). The budget is intentionally MODEST (a full
+   *  boot can exceed it) — an exhausted budget surfaces as a RETRYABLE FAILED, not a raw ELOCKED, so
+   *  the sender retries and routeSend logs the outcome. Tunable via IAPEER_WAKE_LOCK_RETRIES. */
+  wakeLockRetries: number
 }
 
 export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): LifecycleConfig {
@@ -113,6 +117,10 @@ export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): Lifec
     crashLoopWindowSecs: num(env.IAPEER_CRASHLOOP_WINDOW_SECS, 300),
     ephemeralQuietSecs: num(env.IAPEER_EPHEMERAL_QUIET_SECS, 20),
     ephemeralUnarmedIdleSecs: num(env.IAPEER_EPHEMERAL_UNARMED_IDLE_SECS, 600),
+    wakeLockRetries: (() => {
+      const n = parseInt(env.IAPEER_WAKE_LOCK_RETRIES ?? '', 10)
+      return Number.isFinite(n) && n >= 0 ? n : 30
+    })(),
   }
 }
 
@@ -171,6 +179,22 @@ export function removeSessionState(cfg: LifecycleConfig, identity: string): void
   }
 }
 
+/** Atomically CLAIM a dead session for reaping: rename `.session` → `.session.reaping`. Returns true
+ *  iff THIS caller won the rename. superviseTick runs from BOTH the daemon timer AND the prelude of
+ *  every wakeOrSpawn (in whatever process called it), so two passes can see the same dead `.session`
+ *  in the same sub-second window; without a claim BOTH would recordDeath, and TWO deaths for ONE real
+ *  death can trip the crash-loop guard prematurely (a peer refused to wake for the whole window). The
+ *  rename is atomic on a single filesystem — the loser gets ENOENT → false and skips recordDeath/eager.
+ *  A leftover `.reaping` (crash mid-reap) is ignored by readSessionStates (it filters `.session`). */
+function claimDeadSession(cfg: LifecycleConfig, identity: string): boolean {
+  try {
+    renameSync(sessionStatePath(cfg, identity), `${sessionStatePath(cfg, identity)}.reaping`)
+    return true
+  } catch {
+    return false // ENOENT — another pass already claimed this death (or the file vanished)
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // 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
@@ -702,7 +726,7 @@ export async function withWakeLock<T>(
     realpath: false,
     stale: 60_000,
     update: 5_000,
-    retries: { retries: 30, factor: 1.3, minTimeout: 100, maxTimeout: 1_000 },
+    retries: { retries: cfg.wakeLockRetries, factor: 1.3, minTimeout: 100, maxTimeout: 1_000 },
   })
   try {
     return await fn()
@@ -953,7 +977,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     }
   }
 
-  return withWakeLock(cfg, identity, async () => {
+  const runWake = async (): Promise<WakeResult> => {
     // 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
@@ -1074,6 +1098,14 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
         try {
           writeSessionState(cfg, { identity, runtime, personality: args.personality, cwd, wokeAt: Date.now() })
         } catch { /* keep the original FAILED reason — enroll is best-effort */ }
+      } else {
+        // В14 — the launch FAILED and left NO live remnant → a genuine boot-crash (broken binary /
+        // doctrine, process died before READY). It writes NO .session, so superviseTick never sees it
+        // and never records the death → countRecentDeaths stays 0 and the crash-loop guard NEVER fires.
+        // Every next message / ephemeral-drain then re-runs the doomed launch (up to bootDeadline each)
+        // forever. Count the fault here so the guard bounds the loop after crashLoopMax in the window.
+        // (No claim needed — there is no .session for a concurrent pass to race on.)
+        recordDeath(cfg, identity, Date.now())
       }
       return { status: 'FAILED', woke: false, runtime, reason: result.reason }
     }
@@ -1102,7 +1134,29 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     addTopic(cfg, identity, args.topic?.trim() ?? '')
     trimDeaths(cfg, identity, cfg.crashLoopWindowSecs, Date.now())
     return { status: 'READY', woke: true, runtime, process_address: identity, taskDelivered: true }
-  })
+  }
+
+  try {
+    return await withWakeLock(cfg, identity, runWake)
+  } catch (e) {
+    // В15 — the wake-lock retry budget (~25s) is shorter than a legitimate boot (bootDeadline +
+    // readyGate, up to minutes). A concurrent send to a WAKING peer can exhaust it → proper-lockfile
+    // throws ELOCKED, which otherwise escaped through routeSend as a raw protocol error with NO
+    // delivery.log line (a hole in the very log that reconstructs a suspected loss). Convert it to a
+    // RETRYABLE FAILED: the sender retries, the fast path then finds the now-live session, and routeSend
+    // records the outcome. re-resolving each retry = verify-before-act (no false-OK).
+    const msg = e instanceof Error ? e.message : String(e)
+    if ((e as NodeJS.ErrnoException).code === 'ELOCKED' || /\bELOCKED\b|lock.*already.*held/i.test(msg)) {
+      logWake({ identity, runtime, mode: 'refused', cause: 'wake-lock-held' })
+      return {
+        status: 'FAILED',
+        woke: false,
+        runtime,
+        reason: `"${args.personality}" (${runtime}) wake already in progress (another wake holds the lock) — retry shortly`,
+      }
+    }
+    throw e
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1200,8 +1254,15 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
     // 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.
+    // ATOMIC CLAIM (В16): a concurrent supervise pass (daemon timer + a CLI-process
+    // wakeOrSpawn prelude) must not BOTH recordDeath — two deaths for one real death can
+    // trip the crash-loop guard prematurely. The rename-claim makes recordDeath + eager
+    // happen exactly once; the loser reports a benign concurrently-reaped outcome.
+    if (!claimDeadSession(cfg, s.identity)) {
+      return { identity: s.identity, action: 'reaped-gone', reason: 'concurrently reaped by another supervise pass' }
+    }
     recordDeath(cfg, s.identity, nowMs)
-    removeSessionState(cfg, s.identity)
+    rmSync(`${sessionStatePath(cfg, s.identity)}.reaping`, { force: true }) // claim token consumed
     // The .ephemeral-armed mark belongs to THIS (now dead) session — it armed on its
     // outbound reply. Clear it with the session, so a successor session can never be
     // quiet-reaped on a stale mark before answering its own task. No-op otherwise.
@@ -1229,6 +1290,21 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
     trace({ identity: s.identity, action: 'reaped-gone', death: gone.death, reason: gone.reason, outcome: 'fresh-next-msg' })
     return { identity: s.identity, action: 'reaped-gone', reason: gone.reason }
   }
+  // В17 — a LIVE session carrying the .stopped flag is an illegitimate state: `stop` takes no wake-lock,
+  // so a stop that raced an in-flight wake killed the pre-pidfile session as a no-op and the wake then
+  // drove a NEW session to READY → alive + .stopped. The live path (routeSend) does not re-check
+  // .stopped, so this peer keeps accepting messages until idle-reap (up to 1h) — the operator halt
+  // silently failed. Reap it now (catch-up for the window the wake-lock cannot cover). H4 is already
+  // cleared above; no legitimate alive+stopped state exists. Park like the stop verb (.idle-reaped is
+  // idempotent with it) — .stopped keeps the peer down until `start`, .idle-reaped makes it resume-clean.
+  if (isStopped(cfg, s.identity)) {
+    kill(sock, s.identity)
+    setIdleReaped(cfg, s.identity)
+    clearEphemeralArmed(cfg, s.identity)
+    removeSessionState(cfg, s.identity)
+    trace({ identity: s.identity, action: 'reaped-idle', reason: 'alive-but-stopped', outcome: 'operator-halt-enforced' })
+    return { identity: s.identity, action: 'reaped-idle', reason: 'live session carried .stopped — operator halt enforced (stop-vs-wake race)' }
+  }
   // Idle accounting via the LAST MEANINGFUL TRANSCRIPT ENTRY's content-timestamp (adapter.lastTurnMtime)
   // — the only RELIABLE idle signal. The two raw mtimes both report FALSE freshness for an idle session:
   //   • pane-log mtime — a statusline / footer re-render writes pty bytes at idle (the clock/usage/ctx%

package/src/registry/index.ts

@@ -9,10 +9,10 @@
 // is no unlocked path to the registry file anywhere in the package.
 
 import * as lockfile from 'proper-lockfile'
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { randomUUID } from 'crypto'
+import { writeFileAtomicRaw } from '../storage/atomicWrite.ts'
 import {
   IAPEER_DIR,
   MAX_DESCRIPTION_LEN,
@@ -313,7 +313,6 @@ export async function withPeersLock<T>(
  * sanctioned write path for the registry file (#3).
  */
 function writePeersIndexAtomic(paths: PeersPaths, index: PeersIndex): void {
-  const tmp = join(paths.tmpDir, `.${PEERS_PROFILES_FILE}.${process.pid}.${randomUUID()}.tmp`)
   // Persist the RAW intelligence verbatim (legacy-safe round-trip) and DROP the
   // intelligenceRaw shadow field from the on-disk shape — the file carries the
   // legacy vocab the live IAP reads, never the foundation's in-memory normalization.
@@ -333,8 +332,10 @@ function writePeersIndexAtomic(paths: PeersPaths, index: PeersIndex): void {
       ...(peer.interfaces ? { interfaces: peer.interfaces } : {}),
     }))
   const normalized = { version: PEERS_SCHEMA_VERSION, peers: peersForDisk }
-  writeFileSync(tmp, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 })
-  renameSync(tmp, paths.peersFile)
+  // Route through the SHARED atomic-write core (fsync-before-rename + looped writeSync) — the private
+  // registry writer no longer keeps its own copy that drifted off the durability protocol. tmpDir is
+  // paths.tmpDir (same filesystem as peersFile → the rename stays atomic).
+  writeFileAtomicRaw(paths.peersFile, `${JSON.stringify(normalized, null, 2)}\n`, 0o600, paths.tmpDir)
 }
 
 export async function updatePeersIndex(

package/src/storage/atomicWrite.ts

@@ -0,0 +1,60 @@
+// The guard-FREE atomic-write CORE — the single durability implementation shared by
+// storage.writeFileAtomic (public, basename-guarded) and registry's private
+// peers-profiles writer (which bypasses that guard legitimately: it is the sole writer
+// under withPeersLock). Factored out because the registry kept its OWN copy of the
+// atomic-rename, and that copy DRIFTED — it lost the fsync the storage primitive has,
+// re-opening the power-loss hole on the most critical file of the host (the fleet
+// registry). One implementation → the durability protocol can never drift again.
+
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+const DIR_MODE = 0o700
+
+/**
+ * Atomically write `data` to `target`:
+ *   1. write to a unique tmp in `tmpDir` (default: the target's directory — which MUST be the same
+ *      filesystem as `target`, or the rename is not atomic),
+ *   2. fsync the tmp BEFORE the rename — rename is atomic on one fs, but without flushing the bytes
+ *      first a power-loss can publish a zero-length / partial file,
+ *   3. rename the tmp over `target`.
+ *
+ * writeSync is LOOPED over a Buffer: a single writeSync can write FEWER bytes than requested (on
+ * ENOSPC / a signal, write(2) returns a partial count WITHOUT throwing), which would otherwise publish
+ * a truncated file — the exact failure the atomic primitive exists to prevent. The tmp is always
+ * cleaned up on failure so a partial write never leaks.
+ */
+export function writeFileAtomicRaw(
+  target: string,
+  data: string,
+  mode: number,
+  tmpDir: string = dirname(target),
+): void {
+  mkdirSync(dirname(target), { recursive: true, mode: DIR_MODE })
+  if (tmpDir !== dirname(target)) mkdirSync(tmpDir, { recursive: true, mode: DIR_MODE })
+  const tmp = join(tmpDir, `.${basename(target)}.${process.pid}.${randomUUID()}.tmp`)
+  try {
+    const fd = openSync(tmp, 'w', mode)
+    try {
+      const buf = Buffer.from(data, 'utf8')
+      let written = 0
+      while (written < buf.length) {
+        const n = writeSync(fd, buf, written, buf.length - written)
+        if (n <= 0) throw new Error(`writeSync made no progress writing ${target} (${written}/${buf.length} bytes)`)
+        written += n
+      }
+      fsyncSync(fd)
+    } finally {
+      closeSync(fd)
+    }
+    renameSync(tmp, target)
+  } catch (e) {
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp)
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw e
+  }
+}

package/src/storage/index.ts

@@ -10,21 +10,10 @@
 // reaching for the generic atomic-write primitive. The registry keeps its own
 // private writer (see registry/index.ts) used only inside withPeersLock.
 
-import {
-  closeSync,
-  existsSync,
-  fsyncSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  readdirSync,
-  renameSync,
-  unlinkSync,
-  writeSync,
-} from 'fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync } from 'fs'
 import { homedir } from 'os'
 import { basename, dirname, join } from 'path'
-import { randomUUID } from 'crypto'
+import { writeFileAtomicRaw } from './atomicWrite.ts'
 import {
   CACHE_DIR,
   IAPEER_DIR,
@@ -304,28 +293,6 @@ export function writeFileAtomic(path: string, data: string, mode: number = FILE_
       `refusing to write ${PEERS_PROFILES_FILE} via storage.writeFileAtomic — it is the registry's locked write target; use registry.upsertPeer/removePeer/renamePeer`,
     )
   }
-  const dir = dirname(path)
-  mkdirSync(dir, { recursive: true, mode: DIR_MODE })
-  const tmp = join(dir, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`)
-  try {
-    // fsync the tmp file BEFORE the rename: rename is atomic on a single fs, but
-    // without flushing the bytes first a power-loss can publish a zero-length /
-    // partial shared file (codex config.toml, .mcp.json, router.json, plists).
-    const fd = openSync(tmp, 'w', mode)
-    try {
-      writeSync(fd, data)
-      fsyncSync(fd)
-    } finally {
-      closeSync(fd)
-    }
-    renameSync(tmp, path)
-  } catch (e) {
-    // Never leak the tmp file when the write/rename fails (#audit).
-    try {
-      if (existsSync(tmp)) unlinkSync(tmp)
-    } catch {
-      /* best-effort cleanup */
-    }
-    throw e
-  }
+  // The durability core (fsync-before-rename + looped writeSync) lives in ONE place — see atomicWrite.ts.
+  writeFileAtomicRaw(path, data, mode)
 }