@agfpd/iapeer 0.2.15 → 0.2.16

package/package.json

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

package/src/cli/cli.test.ts

@@ -4,12 +4,12 @@
 // persistent-peer launchd plist must be refused.
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { formatListTable, listPeers, parseArgs, removePeerCli, runCli, sendMessage, startPeer, stopPeer } from './index.ts'
 import { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
-import { isStopped, loadLifecycleConfig, setStopped } from '../lifecycle/index.ts'
+import { hasIdleReaped, isStopped, loadLifecycleConfig, setStopped } from '../lifecycle/index.ts'
 import { launchdPlistPath } from '../launch/launchd.ts'
 
 let root: string
@@ -73,6 +73,24 @@ describe('stop / start (C1 durable flag, warm runtime)', () => {
   test('stop an unregistered peer → throws', () => {
     expect(() => stopPeer('nobody', undefined, { env: env() })).toThrow(/not registered/)
   })
+  test('stop is a CLEAN PARK: leaves the resume marker and drops the session-state (boris 10.06)', async () => {
+    await register('parked')
+    const e = env()
+    const cfg = loadLifecycleConfig(e)
+    // a live session-state the daemon would otherwise tag as a death post-kill
+    mkdirSync(cfg.stateDir, { recursive: true })
+    writeFileSync(
+      join(cfg.stateDir, 'claude-parked.session'),
+      JSON.stringify({ identity: 'claude-parked', runtime: 'claude', personality: 'parked', cwd: '/tmp/parked', wokeAt: Date.now() }),
+    )
+    stopPeer('parked', undefined, { env: e })
+    expect(hasIdleReaped(cfg, 'claude-parked')).toBe(true) // park marker → post-start wake RESUMES
+    expect(existsSync(join(cfg.stateDir, 'claude-parked.session'))).toBe(false) // not a death for supervise
+    // start clears only the stop flag — the park marker survives for the wake
+    startPeer('parked', undefined, { env: e })
+    expect(isStopped(cfg, 'claude-parked')).toBe(false)
+    expect(hasIdleReaped(cfg, 'claude-parked')).toBe(true)
+  })
 })
 
 describe('FLEET GUARD (H4) — foreign persistent-peer launchd plist is off-limits', () => {

package/src/cli/index.ts

@@ -33,6 +33,8 @@ import {
   isStopped,
   killSession,
   loadLifecycleConfig,
+  removeSessionState,
+  setIdleReaped,
   setNewEager,
   setStopped,
   wakeOrSpawn,
@@ -196,8 +198,15 @@ export function stopPeer(personality: string, runtime: string | undefined, opts:
       killSession(sock, identity)
       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 (boris 10.06 — stop→start
+      // must survive ≥ idle-reap): park-mark BEFORE the kill so the post-`start`
+      // wake RESUMES, and drop the supervise session-state with the session so
+      // the tick never tags this kill as a death (crash-loop ring stays clean,
+      // no reaped-gone death class for a state the daemon knows 100%).
       setStopped(cfg, identity)
+      setIdleReaped(cfg, identity)
       killSession(sock, identity)
+      removeSessionState(cfg, identity)
       out.push({ personality, runtime: rt, action: 'stopped' })
     }
   }

package/src/lifecycle/index.ts

@@ -148,7 +148,10 @@ function writeSessionState(cfg: LifecycleConfig, state: SessionState): void {
   }
 }
 
-function removeSessionState(cfg: LifecycleConfig, identity: string): void {
+/** Drop the supervise session-state. Exported for the STOP verb: a deliberate stop
+ *  removes the state with the session so superviseTick never tags the kill as a
+ *  death (no crash-loop entry, no reaped-gone death class). */
+export function removeSessionState(cfg: LifecycleConfig, identity: string): void {
   try {
     rmSync(sessionStatePath(cfg, identity), { force: true })
   } catch {
@@ -198,10 +201,12 @@ export function clearStopped(cfg: LifecycleConfig, identity: string): void {
 // 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.)
+//   .idle-reaped : the CLEAN-PARK marker — written when the daemon idle-reaps the
+//     session AND by the deliberate `stop` verb (both are daemon/operator-initiated
+//     parks, not faults; boris 10.06: stop→start must survive ≥ idle-reap).
+//     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.
@@ -230,7 +235,9 @@ export function hasIdleReaped(cfg: LifecycleConfig, identity: string): boolean {
   return existsSync(idleReapedPath(cfg, identity))
 }
 
-/** Write the idle-reaped marker — ONLY the idle-reap path in superviseTick does this. */
+/** Write the clean-park marker. Three writers, all deliberate parks: the idle-reap
+ *  path in superviseTick, the `stop` verb (park before kill), and superviseTick's
+ *  stopped-catch-up branch (a stop that raced the tick). Never a crash path. */
 export function setIdleReaped(cfg: LifecycleConfig, identity: string): void {
   mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
   writeFileSync(idleReapedPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
@@ -462,8 +469,15 @@ export function resolveWakeMode(
     clearIdleReaped(cfg, identity)
     return { resume: false, cause: 'ephemeral-policy' }
   }
-  // 3a. NOT idle-reaped → it died on its own (crash / self-close) → clean FRESH.
-  if (!hasIdleReaped(cfg, identity)) return { resume: false, cause: 'crash-or-self-close' }
+  // 3a. NOT parked-clean → FRESH either way, but tell the two cases apart in the
+  // cause (boris finding, 10.06): a peer with NO transcript at all never ran here —
+  // that is its FIRST-ever wake, not a crash. (A peer whose transcripts were rotated
+  // away also reads first-wake — equally honest: there is nothing it could resume.)
+  if (!hasIdleReaped(cfg, identity)) {
+    return resolveResume(cwd).ok
+      ? { resume: false, cause: 'crash-or-self-close' }
+      : { resume: false, cause: 'first-wake' }
+  }
   // 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.
@@ -967,7 +981,7 @@ export function killSession(sock: string, identity: string): void {
 
 export interface SuperviseOutcome {
   identity: string
-  action: 'reaped-idle' | 'reaped-gone' | 'reaped-ephemeral' | 'skipped-launchd' | 'alive' | 'needs-eager-fresh'
+  action: 'reaped-idle' | 'reaped-gone' | 'reaped-ephemeral' | 'skipped-launchd' | 'skipped-stopped' | 'alive' | 'needs-eager-fresh'
   reason?: string
   /** 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.
@@ -1002,6 +1016,19 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
     }
     const sock = buildSocketPath(s.runtime, s.personality, cfg.sockDir)
     if (!sessionAlive(sock, s.identity)) {
+      // A DELIBERATE stop is not a death (boris 10.06): the stop verb parks clean
+      // (.stopped + .idle-reaped) and kills the session itself. Catch-up branch for
+      // a stop that raced this tick (or a pre-fix stop): drop the state quietly —
+      // no crash-loop entry, no death class — and ensure the clean-park marker so
+      // the post-`start` wake RESUMES (stop→start must survive ≥ idle-reap).
+      if (isStopped(cfg, s.identity)) {
+        removeSessionState(cfg, s.identity)
+        clearEphemeralArmed(cfg, s.identity)
+        setIdleReaped(cfg, s.identity) // idempotent with the stop verb's own park
+        out.push({ identity: s.identity, action: 'skipped-stopped', reason: 'deliberate stop — parked clean, resumes on start' })
+        trace({ identity: s.identity, action: 'skipped-stopped', outcome: 'resume-on-start' })
+        continue
+      }
       // 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.

package/src/lifecycle/lifecycle.test.ts

@@ -218,6 +218,24 @@ describe('superviseTick H4 guard', () => {
     expect(existsSync(join(stateDir, `${id}.session`))).toBe(true)
   })
 
+  test('a STOPPED peer with a dead session → skipped-stopped: no death record, park marker ensured', () => {
+    // boris repro (10.06): `iapeer stop` → next tick used to tag reaped-gone
+    // death=server-dead + recordDeath → post-start wake came up FRESH. A deliberate
+    // stop is a clean park the daemon knows 100% — never a death.
+    const c = cfg()
+    const id = writeState('iapeer-supstopped')
+    setStopped(c, id)
+    const out = superviseTick(c, { env: env(), nowMs: Date.now() })
+    const o = out.find(x => x.identity === id)
+    expect(o?.action).toBe('skipped-stopped')
+    expect(existsSync(join(stateDir, `${id}.session`))).toBe(false) // state dropped quietly
+    expect(readDeaths(c, id).length).toBe(0) // NOT a death — crash-loop ring untouched
+    expect(hasIdleReaped(c, id)).toBe(true) // clean park → post-start wake resumes
+    const logged = readFileSync(join(c.eventLogDir, 'lifecycle.log'), 'utf8')
+    expect(logged).toContain(`identity=${id} action=skipped-stopped`)
+    expect(logged).not.toContain('death=') // no death class for a deliberate stop
+  })
+
   test('a no-plist peer with a dead session → reaped-gone, state removed', () => {
     const c = cfg()
     const id = writeState('iapeer-supgone') // no plist, no live tmux session
@@ -433,6 +451,19 @@ describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
     expect(resolveWakeMode(cfg(), 'claude-p', cwd(), undefined, hasTranscript)).toEqual({ resume: false, cause: 'crash-or-self-close' })
   })
 
+  test('DEFAULT + NOT idle-reaped + NO transcript at all → FRESH with cause=first-wake (not a crash)', () => {
+    // boris finding (10.06): the first-ever wake of a freshly created peer used to
+    // read crash-or-self-close — a mis-classification. No transcript = never ran.
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), undefined, noTranscript)).toEqual({ resume: false, cause: 'first-wake' })
+  })
+
+  // ── stop→start is a CLEAN PARK (boris 10.06): the park marker → RESUME ────────
+  test('stop→start path: clean-park marker set by stop → the next default wake RESUMES', () => {
+    const c = cfg()
+    setIdleReaped(c, 'claude-p') // what the stop verb writes before killing
+    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1', cause: 'idle-reaped-resume' })
+  })
+
   // ── branch 3b: default + idle-reaped → resume-eligible, CONSUME the marker ───
   test('DEFAULT + idle-reaped + human-conversational (interfaces.telegram) → RESUME, marker consumed', () => {
     const c = cfg()