@agfpd/iapeer 0.4.33 → 0.4.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.33",
+  "version": "0.4.35",
   "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/cli/index.ts

@@ -129,7 +129,7 @@ export function listPeers(opts: CliEnvOptions = {}): PeerListing[] {
   return index.peers.map(peer => {
     const runtimes: RuntimeStatus[] = peer.runtimes.map(rt => ({
       runtime: rt,
-      status: isPeerLive(rt, peer.personality, cfg.sockDir)
+      status: isPeerLive(rt, peer.personality, cfg.sockDir, env)
         ? 'live'
         : isStopped(cfg, buildProcessAddress(rt, peer.personality))
           ? 'stopped'
@@ -248,7 +248,7 @@ export function stopPeer(personality: string, runtime: string | undefined, opts:
       // the service was already not loaded — benign for stop — but surface the detail in
       // the reason rather than silently claiming success.)
       const r = spawnSync('launchctl', ['bootout', `gui/${uid()}/${launchdLabel(personality)}`], { encoding: 'utf8' })
-      killSession(sock, identity)
+      killSession(sock, identity, env)
       out.push({ personality, runtime: rt, action: 'bootout', reason: r.status === 0 ? undefined : `launchctl bootout exited ${r.status}${(r.stderr ?? '').trim() ? `: ${(r.stderr ?? '').trim()}` : ''}` })
     } else {
       // A deliberate stop is a CLEAN PARK, not a death (stop→start must survive ≥
@@ -258,7 +258,7 @@ export function stopPeer(personality: string, runtime: string | undefined, opts:
       // no reaped-gone death class for a state the daemon knows 100%).
       setStopped(cfg, identity)
       setIdleReaped(cfg, identity)
-      killSession(sock, identity)
+      killSession(sock, identity, env)
       removeSessionState(cfg, identity)
       out.push({ personality, runtime: rt, action: 'stopped' })
     }
@@ -551,7 +551,7 @@ export async function newPeer(
   clearStopped(cfg, identity)
   clearIdleReaped(cfg, identity)
   clearNewEager(cfg, identity)
-  killSession(sock, identity) // canary-clean deliberate teardown; no-op when dead
+  killSession(sock, identity, env) // canary-clean deliberate teardown; no-op when dead
   removeSessionState(cfg, identity) // never a death class — supervise stays silent
   const wake = opts.wakeFn ?? (args => wakeOrSpawn(args, { cfg, env }))
   const r = await wake({ personality, runtime: rt, task: '', resume: false })
@@ -626,7 +626,7 @@ export async function compactPeer(
     if (!done.ok) return { personality, runtime: rt, action: 'failed', woke, reason: done.error.message }
     return null
   }
-  const liveRuntimes = peer.runtimes.filter(rt => isPeerLive(rt, personality, cfg.sockDir))
+  const liveRuntimes = peer.runtimes.filter(rt => isPeerLive(rt, personality, cfg.sockDir, env))
   if (runtime ? liveRuntimes.includes(runtime as Runtime) : liveRuntimes.length > 0) {
     const rt = (runtime as Runtime | undefined)
       ?? (liveRuntimes.includes(peer.runtime) ? peer.runtime : liveRuntimes.length === 1 ? liveRuntimes[0] : undefined)
@@ -744,7 +744,7 @@ export async function removePeerCli(
   if (!peer) return { personality, action: 'absent' }
   if (!opts.force) {
     const cfg = loadLifecycleConfig(env)
-    const liveRt = peer.runtimes.find(rt => isPeerLive(rt, personality, cfg.sockDir))
+    const liveRt = peer.runtimes.find(rt => isPeerLive(rt, personality, cfg.sockDir, env))
     if (liveRt) {
       return {
         personality,
@@ -969,7 +969,7 @@ export async function renamePeerCli(
   }
   const cfg = loadLifecycleConfig(env)
   if (!opts.force) {
-    const liveRt = peer.runtimes.find(rt => isPeerLive(rt, oldPersonality, cfg.sockDir))
+    const liveRt = peer.runtimes.find(rt => isPeerLive(rt, oldPersonality, cfg.sockDir, env))
     if (liveRt) {
       return {
         oldPersonality,
@@ -2325,7 +2325,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         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)
+        killSession(sock, identity, env)
         return 0
       }
       case 'interrupt': {

package/src/launch/index.ts

@@ -183,6 +183,7 @@ export const launch: LaunchFn = async (
       paneLogPath,
       exitLogPath: cfg.exitLogDir ? exitLogPath(cfg.exitLogDir) : undefined,
       invocation,
+      env, // sandbox the supervisor run-dir (serve-spec + detached spawn) via the injected env
     })
     if (host.ok) {
       // ROUTER (telegram/notifier): no startup dialogs and no transcript. The session is "up" the
@@ -193,7 +194,7 @@ export const launch: LaunchFn = async (
       // router's <iap>-marker stdin reader). So confirm the hosted session is live and return ready —
       // no waitHostReady (would load @xterm for nothing), no first-message deliver, no ready-gate.
       if (adapter.kind === 'router') {
-        if (hostSessionAlive(identity)) return ready(identity)
+        if (hostSessionAlive(identity, env)) return ready(identity)
         return fail(identity, 'hosted router session not alive immediately after bringup')
       }
       // BOOT: the supervisor's boot-driver dismisses startup dialogs internally; wait for the input
@@ -201,7 +202,7 @@ export const launch: LaunchFn = async (
       // the SAME shape as the tmux boot/deliver/ready-gate below, with host equivalents.
       const baselineMtime = adapter.newestActivityMtime(cwd) ?? 0
       const isReady = await waitHostReady(
-        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs, paneLogStartByte },
+        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs, paneLogStartByte, env },
         sleep,
       )
       if (!isReady) return fail(identity, 'never-became-ready (hosted: supervisor input surface not ready)')
@@ -220,12 +221,12 @@ export const launch: LaunchFn = async (
         },
         { env },
       )
-      const d = await deliverHosted(identity, firstMessage)
+      const d = await deliverHosted(identity, firstMessage, env)
       if (!d.ok) return fail(identity, `hosted deliver failed: ${d.error}`)
       const readyDeadline = Date.now() + cfg.readyGateSecs * 1000
       while (Date.now() < readyDeadline) {
         await sleep(2000)
-        if (!hostSessionAlive(identity)) return fail(identity, 'hosted session vanished during ready-gate')
+        if (!hostSessionAlive(identity, env)) return fail(identity, 'hosted session vanished during ready-gate')
         if ((adapter.newestActivityMtime(cwd) ?? 0) > baselineMtime) return ready(identity)
       }
       return fail(identity, 'model-did-not-process-task (hosted: no activity advance after delivery)')

package/src/launch/launchdRun.ts

@@ -87,7 +87,7 @@ export async function runAlwaysOn(personality: string, runtime: string, cwd: str
   // pty-only liveness: a router is supervisor-HOSTED. Probe by RUNTIME STATE (not the `.pty-host`
   // marker). On child death it goes false → block-watch exits → run-infra exits → launchd KeepAlive
   // respawns (the SOLE respawn owner; the supervisor never self-respawns — H4 held).
-  const isAlive = (): boolean => hostSessionAlive(identity)
+  const isAlive = (): boolean => hostSessionAlive(identity, env)
 
   const cfg: LaunchConfig = {
     claudeBin: env.CLAUDE_BIN ?? 'claude',
@@ -164,7 +164,7 @@ export async function runAlwaysOn(personality: string, runtime: string, cwd: str
   // kill the supervisor daemon (killPtyHost: SIGTERM → it SIGKILLs the child + cleans up sock/pid/serve)
   // so the detached child does not outlive bootout holding stale in-memory state. A NATURAL death
   // (stop=false) skips this: nothing to tear down, exit 0 → KeepAlive respawns a fresh bring-up.
-  if (stop) killPtyHost(identity)
+  if (stop) killPtyHost(identity, env)
   return 0
 }
 

package/src/launch/ptyHost.ts

@@ -27,9 +27,11 @@ export const HOST_COLS = 220
 export const HOST_ROWS = 50
 
 
-/** The supervisor's run dir (session sockets/pids/serve-specs). Env-isolatable via IAPEER_ROOT. */
-export function hostRunDir(): string {
-  return defaultRunDir()
+/** The supervisor's run dir (session sockets/pids/serve-specs). Resolved from the INJECTED env so a
+ *  sandboxed caller (cfg.env) never touches the real ~/.iapeer/state/supervisor — the isolation
+ *  invariant. Defaults to process.env for the prod daemon (env === process.env). */
+export function hostRunDir(env: NodeJS.ProcessEnv = process.env): string {
+  return defaultRunDir(env)
 }
 
 /**
@@ -39,13 +41,14 @@ export function hostRunDir(): string {
  * means rolling the marker back (rm) on a STILL-RUNNING hosted session never tears it (rm affects only
  * the NEXT spawn). Rollback of a RUNNING hosted session is therefore kill-then-rm, NOT rm-alone.
  */
-export function hostSessionAlive(identity: string): boolean {
-  return hostDaemonAlive(hostRunDir(), identity)
+export function hostSessionAlive(identity: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return hostDaemonAlive(hostRunDir(env), identity)
 }
 
-/** Reap a hosted session: SIGTERM the supervisor daemon (its shutdown SIGKILLs the child + cleans up). */
-export function killPtyHost(identity: string): void {
-  killSupervisorSession(hostRunDir(), identity)
+/** Reap a hosted session: SIGTERM the supervisor daemon (its shutdown SIGKILLs the child + cleans up).
+ *  env sandboxes the run-dir: a test with an injected root must NEVER SIGTERM a real fleet peer. */
+export function killPtyHost(identity: string, env: NodeJS.ProcessEnv = process.env): void {
+  killSupervisorSession(hostRunDir(env), identity)
 }
 
 /**
@@ -56,8 +59,8 @@ export function killPtyHost(identity: string): void {
  * a human's unfinished composer input, but NEVER for the AI's own composer output when no one is
  * attached. The host equivalent of `hasAttachedTmuxClient`.
  */
-export function hasAttachedSupervisorClient(identity: string): boolean {
-  return existsSync(attachedPath(hostRunDir(), identity))
+export function hasAttachedSupervisorClient(identity: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return existsSync(attachedPath(hostRunDir(env), identity))
 }
 
 /** Current child pty geometry of a hosted session, from the supervisor's `<session>.geometry.json`
@@ -65,8 +68,8 @@ export function hasAttachedSupervisorClient(identity: string): boolean {
  *  rather than assuming the fixed HOST geometry, because a DETACHED session keeps its last client geometry
  *  (the child is no longer reverted to serve on detach — that revert caused the reattach-duplicate bug).
  *  Reading the actual geometry keeps the pane-log composer-occupancy model aligned with the real pty size. */
-export function hostGeometry(identity: string): { cols: number; rows: number } {
-  return readGeometry(hostRunDir(), identity) ?? { cols: HOST_COLS, rows: HOST_ROWS }
+export function hostGeometry(identity: string, env: NodeJS.ProcessEnv = process.env): { cols: number; rows: number } {
+  return readGeometry(hostRunDir(env), identity) ?? { cols: HOST_COLS, rows: HOST_ROWS }
 }
 
 /**
@@ -75,9 +78,9 @@ export function hostGeometry(identity: string): { cols: number; rows: number } {
  * session FAILS rather than landing in a fresh same-named session — the host equivalent of the tmux
  * `session_id:pane_id` token. null when no daemon pid is readable.
  */
-export function hostSessionToken(identity: string): string | null {
+export function hostSessionToken(identity: string, env: NodeJS.ProcessEnv = process.env): string | null {
   try {
-    const pid = readFileSync(pidPath(hostRunDir(), identity), 'utf8').trim()
+    const pid = readFileSync(pidPath(hostRunDir(env), identity), 'utf8').trim()
     return pid ? `host:${pid}` : null
   } catch {
     return null
@@ -90,9 +93,9 @@ export function hostSessionToken(identity: string): string | null {
  * scan (and the no-runtime delivery resolve) include hosted peers. Empty + cheap when flag-off (the
  * run-dir is empty).
  */
-export function listHostedPeers(): Array<{ runtime: TmuxRuntime; personality: string }> {
+export function listHostedPeers(env: NodeJS.ProcessEnv = process.env): Array<{ runtime: TmuxRuntime; personality: string }> {
   const out: Array<{ runtime: TmuxRuntime; personality: string }> = []
-  for (const s of listSupervisorSessions(hostRunDir())) {
+  for (const s of listSupervisorSessions(hostRunDir(env))) {
     if (!s.alive) continue
     const p = parseSessionName(s.session)
     if (p) out.push({ runtime: p.runtime, personality: p.personality })
@@ -118,13 +121,16 @@ export async function startPtyHost(b: {
   paneLogPath: string
   exitLogPath?: string
   invocation: LaunchInvocation
+  /** Injected env — the run-dir (serve-spec + detached spawn) resolves from THIS, so a sandboxed
+   *  launch never writes serve secrets to / spawns a process against the real ~/.iapeer. */
+  env?: NodeJS.ProcessEnv
 }): Promise<HostStartResult> {
   try {
     const { startSupervisorDaemon } = await import('../supervisor/index.ts')
     const r = await startSupervisorDaemon({
       session: b.identity,
       runtime: b.runtime,
-      runDir: hostRunDir(),
+      runDir: hostRunDir(b.env),
       serve: {
         argv: b.invocation.argv,
         env: b.invocation.env as Record<string, string>,
@@ -148,7 +154,7 @@ export async function startPtyHost(b: {
  * 2 s cadence + bootDeadline.
  */
 export async function waitHostReady(
-  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number; paneLogStartByte?: number },
+  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number; paneLogStartByte?: number; env?: NodeJS.ProcessEnv },
   sleep: (ms: number) => Promise<void>,
 ): Promise<boolean> {
   const log = `${b.logDir}/${b.identity}.log`
@@ -160,7 +166,7 @@ export async function waitHostReady(
   // session (the first message is then lost). See readyGateModel.loadPaneLogModel.
   for (let i = 0; i < iters; i++) {
     await sleep(2000)
-    if (!hostSessionAlive(b.identity)) return false
+    if (!hostSessionAlive(b.identity, b.env)) return false
     const view = await paneLogViewport(log, HOST_COLS, HOST_ROWS, b.paneLogStartByte ?? 0)
     if (view && b.adapter.isInputReady(view)) return true
   }
@@ -168,6 +174,6 @@ export async function waitHostReady(
 }
 
 /** Deliver the first/next message to the hosted session over its supervisor socket. */
-export function deliverHosted(identity: string, message: string): Promise<DeliverResult> {
-  return deliverToHost(hostRunDir(), identity, message)
+export function deliverHosted(identity: string, message: string, env: NodeJS.ProcessEnv = process.env): Promise<DeliverResult> {
+  return deliverToHost(hostRunDir(env), identity, message)
 }

package/src/lifecycle/index.ts

@@ -715,11 +715,12 @@ export async function withWakeLock<T>(
 // liveness
 // ─────────────────────────────────────────────────────────────────────────────
 
-function sessionAlive(_sock: string, identity: string): boolean {
+function sessionAlive(_sock: string, identity: string, env: NodeJS.ProcessEnv = process.env): boolean {
   // pty-only: a peer is alive iff its supervisor session is live (a cheap pid-file check). Routing
   // liveness on the live session (not the `.pty-host` spawn-intent marker) keeps a marker rollback safe
   // on a still-running session. (`_sock` retained for call-site compatibility; no tmux sockets exist.)
-  return hostSessionAlive(identity)
+  // env sandboxes the run-dir — a test with an injected root must not read the real fleet's liveness.
+  return hostSessionAlive(identity, env)
 }
 
 /** Death-class tag for a gone session (pty-only). A gone peer is a supervisor session that ended; its
@@ -969,7 +970,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     }
     // Idempotent fast path inside the lock: a live session wins (a concurrent
     // wake already brought it up) — no second spawn.
-    if (sessionAlive(sock, identity)) {
+    if (sessionAlive(sock, identity, env)) {
       writeSessionState(cfg, { identity, runtime, personality: args.personality, cwd, wokeAt: Date.now() })
       // taskDelivered:false — the winning concurrent wake delivered ITS OWN task as
       // the boot first-message; THIS caller's task was not delivered by anything.
@@ -1069,7 +1070,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
       // path above). We do NOT flip to READY — the wake DID fail its ready-gate, the caller
       // must still hear FAILED; we only make the live remnant supervised. Best-effort: a write
       // hiccup must not mask the original FAILED reason.
-      if (sessionAlive(sock, identity)) {
+      if (sessionAlive(sock, identity, env)) {
         try {
           writeSessionState(cfg, { identity, runtime, personality: args.personality, cwd, wokeAt: Date.now() })
         } catch { /* keep the original FAILED reason — enroll is best-effort */ }
@@ -1108,11 +1109,12 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
 // Reap — kill a session (used by idle-reap / supervise; H4-guarded by callers)
 // ─────────────────────────────────────────────────────────────────────────────
 
-export function killSession(_sock: string, identity: string): void {
+export function killSession(_sock: string, identity: string, env: NodeJS.ProcessEnv = process.env): void {
   // pty-only: SIGTERM the supervisor daemon — its shutdown SIGKILLs the child and removes the
   // sock/pid/serve-spec/markers. Idempotent if the session is already gone. (`_sock` retained for
-  // call-site compatibility; no tmux sockets exist.)
-  killPtyHost(identity)
+  // call-site compatibility; no tmux sockets exist.) env sandboxes the run-dir — a test with an
+  // injected root must NEVER SIGTERM a real fleet peer's supervisor.
+  killPtyHost(identity, env)
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1150,6 +1152,9 @@ export interface SuperviseDeps {
   /** Liveness seam (default: the real `sessionAlive` = pty-host pid-file check). Tests inject a fixed
    *  verdict so the idle path is exercised hermetically — no live pty session needed. */
   sessionAlive?: (sock: string, identity: string) => boolean
+  /** Reap seam (default: the real `killSession` = SIGTERM the supervisor daemon). Tests inject a no-op
+   *  so exercising the reap path NEVER SIGTERMs a real process — the destructive-kill isolation guard. */
+  killSession?: (sock: string, identity: string) => void
 }
 
 /** Resolved per-tick context threaded into superviseOnePeer (deps already defaulted by superviseTick). */
@@ -1159,6 +1164,7 @@ interface SuperviseCtx {
   nowMs: number
   lastTurnMt: (runtime: string, cwd: string) => number | null
   isAlive: (sock: string, identity: string) => boolean
+  kill: (sock: string, identity: string) => void
   verbose: boolean
   trace: (fields: Record<string, string | number | undefined>) => void
 }
@@ -1171,7 +1177,7 @@ interface SuperviseCtx {
  * returns exactly one outcome; the trace side-effects mirror the prior inline behaviour.
  */
 function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome {
-  const { cfg, env, nowMs, lastTurnMt, isAlive, verbose, trace } = ctx
+  const { cfg, env, nowMs, lastTurnMt, isAlive, kill, verbose, trace } = ctx
   // H4 — FIRST, before any reap. A launchd-managed peer is read-only.
   if (isLaunchdManaged(s.personality, env)) {
     if (verbose) trace({ identity: s.identity, action: 'skipped-launchd', outcome: 'read-only-h4' })
@@ -1252,7 +1258,7 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
   // Deliberate, policy-driven death: NO .idle-reaped (an ephemeral peer never resumes)
   // and NO recordDeath (the crash-loop ring counts faults, not policy reaps).
   if (ephemeral && hasEphemeralArmed(cfg, s.identity) && ageSecs > cfg.ephemeralQuietSecs) {
-    killSession(sock, s.identity)
+    kill(sock, s.identity)
     clearEphemeralArmed(cfg, s.identity)
     removeSessionState(cfg, s.identity)
     trace({ identity: s.identity, action: 'reaped-ephemeral', age: `${ageSecs}s`, outcome: 'ephemeral-done' })
@@ -1278,7 +1284,7 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
   // tool, no reply yet) keeps the pane-log fresh via the TUI render, so it is no longer
   // reaped mid-task — only a genuinely idle/wedged unarmed session crosses this bound.
   if (ephemeral && ageSecs > cfg.ephemeralUnarmedIdleSecs) {
-    killSession(sock, s.identity)
+    kill(sock, s.identity)
     clearEphemeralArmed(cfg, s.identity)
     removeSessionState(cfg, s.identity)
     trace({ identity: s.identity, action: 'reaped-ephemeral', age: `${ageSecs}s`, outcome: 'ephemeral-unarmed-bound' })
@@ -1295,7 +1301,7 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
     // 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)
+    kill(sock, s.identity)
     setIdleReaped(cfg, s.identity)
     removeSessionState(cfg, s.identity)
     trace({ identity: s.identity, action: 'reaped-idle', age: `${ageSecs}s`, outcome: 'resume-eligible' })
@@ -1311,7 +1317,9 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
   const env = deps.env ?? process.env
   const nowMs = deps.nowMs ?? Date.now()
   const lastTurnMt = deps.lastTurnMtime ?? ((rt: string, c: string) => getAdapter(rt as Runtime).lastTurnMtime(c))
-  const isAlive = deps.sessionAlive ?? sessionAlive
+  // Default seams bind the injected env so a sandboxed tick never reads/kills the real fleet.
+  const isAlive = deps.sessionAlive ?? ((sock: string, identity: string) => sessionAlive(sock, identity, env))
+  const kill = deps.killSession ?? ((sock: string, identity: string) => killSession(sock, identity, env))
   const verbose = superviseLogVerbose(env)
   // Pane-log volume cap (launch/cmdlog.ts capPaneLogs): the per-identity pane-log
   // (<logDir>/<identity>.log) is the RAW TUI byte stream pipe-pane/the supervisor
@@ -1328,7 +1336,7 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
   const trace = (fields: Record<string, string | number | undefined>): void =>
     appendLifecycleEvent(cfg.eventLogDir, { ev: 'supervise', ...fields }, { env, nowMs })
   const out: SuperviseOutcome[] = []
-  const ctx: SuperviseCtx = { cfg, env, nowMs, lastTurnMt, isAlive, verbose, trace }
+  const ctx: SuperviseCtx = { cfg, env, nowMs, lastTurnMt, isAlive, kill, verbose, trace }
   for (const s of readSessionStates(cfg)) {
     // Per-peer ISOLATION: a throw while evaluating ONE peer must NOT abort the whole sweep — that is
     // the silent fleet-wide reap-outage class (one malformed peer-state and NO peer gets reaped, the
@@ -1434,7 +1442,7 @@ export async function drainEphemeralQueue(
   const env = deps.env ?? process.env
   const identity = buildProcessAddress(runtime, personality)
   const sock = buildSocketPath(runtime, personality, cfg.sockDir)
-  if (sessionAlive(sock, identity)) return null // one task per session — wait for its reap
+  if (sessionAlive(sock, identity, env)) return null // one task per session — wait for its reap
   const item = peekEphemeralTask(cfg, identity)
   if (!item) return null
   // Durable drain trace: which item, how deep the queue.
@@ -1540,9 +1548,9 @@ export function lastActiveRuntime(peer: PeerRecord, cfg: LifecycleConfig): Runti
 
 /** Runtimes of `peer` whose session is LIVE right now (lifecycle-local liveness,
  *  same `sessionAlive` predicate the wake/attach paths use). */
-function liveRuntimesOf(peer: PeerRecord, cfg: LifecycleConfig): Runtime[] {
+function liveRuntimesOf(peer: PeerRecord, cfg: LifecycleConfig, env: NodeJS.ProcessEnv = process.env): Runtime[] {
   return peer.runtimes.filter(rt =>
-    sessionAlive(buildSocketPath(rt, peer.personality, cfg.sockDir), buildProcessAddress(rt, peer.personality)),
+    sessionAlive(buildSocketPath(rt, peer.personality, cfg.sockDir), buildProcessAddress(rt, peer.personality), env),
   )
 }
 
@@ -1570,9 +1578,9 @@ function liveRuntimesOf(peer: PeerRecord, cfg: LifecycleConfig): Runtime[] {
  * arg) resolve to codex, set the peer's default to codex once; per-command runtime
  * args remain the explicit override.
  */
-export function resolvePeerRuntime(peer: PeerRecord, cfg: LifecycleConfig): Runtime {
+export function resolvePeerRuntime(peer: PeerRecord, cfg: LifecycleConfig, env: NodeJS.ProcessEnv = process.env): Runtime {
   if (peer.runtimes.length === 1) return peer.runtimes[0]
-  const live = liveRuntimesOf(peer, cfg)
+  const live = liveRuntimesOf(peer, cfg, env)
   if (live.includes(peer.runtime)) return peer.runtime
   if (live.length === 1) return live[0]
   return peer.runtime
@@ -1610,7 +1618,7 @@ export async function attachPeer(opts: AttachOptions): Promise<AttachResult> {
   const runtime = opts.runtime ?? resolvePeerRuntime(peer, cfg)
   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 }
+  if (sessionAlive(sock, identity, env)) 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 }

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)
 }

package/src/transport/index.ts

@@ -79,22 +79,23 @@ function monotonicMs(): number {
   return Number(process.hrtime.bigint() / 1_000_000n)
 }
 
-function sessionAlive(_sock: string, address: string): boolean {
+function sessionAlive(_sock: string, address: string, env: NodeJS.ProcessEnv = process.env): boolean {
   // pty-only: a peer's liveness is its supervisor daemon (a cheap pid-file check). `address` IS the
   // identity. (`_sock` is retained for call-site compatibility; tmux sockets no longer exist.)
-  return hostSessionAlive(address)
+  // env sandboxes the run-dir — an env-injected verb must not read the real fleet's liveness.
+  return hostSessionAlive(address, env)
 }
 
 /** Is the (runtime,personality) endpoint live right now? Public liveness predicate. */
-export function isPeerLive(runtime: string, personality: string, sockDir = resolveSockDir()): boolean {
+export function isPeerLive(runtime: string, personality: string, sockDir = resolveSockDir(), env: NodeJS.ProcessEnv = process.env): boolean {
   const socketPath = buildSocketPath(runtime, personality, sockDir)
-  return sessionAlive(socketPath, buildProcessAddress(runtime, personality))
+  return sessionAlive(socketPath, buildProcessAddress(runtime, personality), env)
 }
 
-export function listOnlinePeers(_sockDir = resolveSockDir()): OnlinePeer[] {
+export function listOnlinePeers(_sockDir = resolveSockDir(), env: NodeJS.ProcessEnv = process.env): OnlinePeer[] {
   // pty-only: every live peer is a supervisor-hosted session (no tmux sockets to scan).
   const out = new Map<string, OnlinePeer>()
-  for (const h of listHostedPeers()) {
+  for (const h of listHostedPeers(env)) {
     out.set(buildProcessAddress(h.runtime, h.personality), { personality: h.personality, runtime: h.runtime })
   }
   return Array.from(out.values()).sort(