@agfpd/iapeer 0.2.91 → 0.2.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.91",
+  "version": "0.2.92",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -41,6 +41,7 @@ import {
   purgeIdentityState,
   removeSessionState,
   setEphemeralArmed,
+  setFreshNext,
   setIdleReaped,
   setNewEager,
   setStopped,
@@ -292,6 +293,41 @@ export function startPeer(personality: string, runtime: string | undefined, opts
   return out
 }
 
+export interface RefreshOutcome {
+  personality: string
+  runtime: Runtime
+  action: 'refresh-armed' | 'skipped-non-agentic'
+}
+
+/** Runtimes that consume the layered system prompt (doctrine/fragments) — the only ones a soft-reload
+ *  affects. Routers (notifier/telegram) and absent runtimes carry no doctrine. */
+const AGENTIC_RUNTIMES: ReadonlySet<string> = new Set(['claude', 'codex'])
+
+/**
+ * refresh <peer> [runtime] (or --all): arm a LAZY soft-reload. Each agentic (claude/codex) runtime of the
+ * peer comes up FRESH on its NEXT natural wake — re-reading doctrine/fragments from disk — WITHOUT killing
+ * the live session and WITHOUT eager-relaunch / burst-wake. Non-agentic runtimes (notifier/telegram/absent)
+ * are skipped (no doctrine). H4-safe: writes a `.fresh-next` marker only — never wakes / reaps / kills, so
+ * it is inert for launchd-managed peers (their lifecycle is KeepAlive's, resolveWakeMode is not their path).
+ * The lazy counterpart to `iapeer new` (hard kill) and self-fresh/.new-eager (eager relaunch + burst wake).
+ */
+export function refreshPeer(personality: string, runtime: string | undefined, opts: CliEnvOptions = {}): RefreshOutcome[] {
+  const env = opts.env ?? process.env
+  const cfg = loadLifecycleConfig(env)
+  const peer = findPeer(readPeersIndex({ env }), personality)
+  if (!peer) throw new Error(`peer "${personality}" is not registered`)
+  const out: RefreshOutcome[] = []
+  for (const rt of targetRuntimes(peer, runtime)) {
+    if (!AGENTIC_RUNTIMES.has(rt)) {
+      out.push({ personality, runtime: rt, action: 'skipped-non-agentic' })
+      continue
+    }
+    setFreshNext(cfg, buildProcessAddress(rt, personality))
+    out.push({ personality, runtime: rt, action: 'refresh-armed' })
+  }
+  return out
+}
+
 export interface AddRuntimeOutcome {
   personality: string
   action: 'added' | 'already' | 'skipped-infra-peer' | 'failed'
@@ -923,6 +959,8 @@ const USAGE = `usage: iapeer <verb> [args]
                                                                  until \`start\`; always-on (notifier/telegram): launchctl bootout. --all = every registered peer
   start <peer> [runtime] | --all                                 warm peer: clear the stop-flag — wakeable again; does NOT launch a session (the daemon brings
                                                                  it up on the peer's first message); always-on: launchctl bootstrap. --all = every registered peer
+  refresh <peer> [runtime] | --all                               LAZY soft-reload: agentic peer comes up FRESH (re-reads doctrine) on its NEXT natural wake — no
+                                                                 kill, no burst-wake; non-agentic runtimes skipped. --all = whole fleet. (eager: \`new\`/self-fresh)
   remove <peer> [--force]                                        delete a peer's registry record (locked writer); refuses a LIVE peer unless --force
   send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]   manual IAP send (fallback)
   <runtime>                                                      launch the cwd's peer FRESH; on a TTY drop into it (like attach), else detached
@@ -1383,6 +1421,20 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
         return outcomes.some(o => o.action === 'refused-foreign-launchd') ? 1 : 0
       }
+      case 'refresh': {
+        // LAZY soft-reload (fleet doctrine refresh): arm `.fresh-next` so each agentic peer comes up FRESH
+        // on its NEXT natural wake (re-reads doctrine/fragments) — no kill, no eager relaunch, no burst-wake.
+        // --all marks the whole registered fleet. H4-safe (marker only); non-agentic runtimes are skipped.
+        const peers = flags.all === true
+          ? readPeersIndex({ env }).peers.map(p => p.personality)
+          : positionals[0]
+            ? [positionals[0]]
+            : null
+        if (!peers) return usage(errOut)
+        const outcomes = peers.flatMap(p => refreshPeer(p, flags.all === true ? undefined : positionals[1], { env }))
+        for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}\n`)
+        return 0
+      }
       case 'remove': {
         // Reap a registry record through the locked writer (the operator path over
         // registry.removePeer). Idempotent on an absent peer (exit 0). Refuses a LIVE

package/src/lifecycle/index.ts

@@ -292,6 +292,32 @@ export function clearNewEager(cfg: LifecycleConfig, identity: string): void {
   }
 }
 
+function freshNextPath(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.fresh-next`)
+}
+
+/** True iff the identity carries a LAZY soft-reload mark (→ FRESH on its next natural wake,
+ *  re-reading doctrine/fragments from disk). Unlike .new-eager this is NOT eager — no relaunch,
+ *  no burst-wake; it only changes the resume decision when the peer next wakes on its own. */
+export function hasFreshNext(cfg: LifecycleConfig, identity: string): boolean {
+  return existsSync(freshNextPath(cfg, identity))
+}
+
+/** Set the lazy soft-reload mark (the `iapeer refresh` verb does this — no kill, no relaunch). */
+export function setFreshNext(cfg: LifecycleConfig, identity: string): void {
+  mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
+  writeFileSync(freshNextPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
+}
+
+/** Consume the lazy soft-reload mark (resolveWakeMode does this on the fresh decision). */
+export function clearFreshNext(cfg: LifecycleConfig, identity: string): void {
+  try {
+    rmSync(freshNextPath(cfg, identity), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
 function ephemeralArmedPath(cfg: LifecycleConfig, identity: string): string {
   return join(cfg.stateDir, `${identity}.ephemeral-armed`)
 }
@@ -564,6 +590,18 @@ export function resolveWakeMode(
     if (!r.ok) return { resume: false, failReason: r.reason ?? 'resume requested but nothing to resume', cause: 'attach-nothing-to-resume' }
     return { resume: true, resumeRef: r.ref, cause: 'attach' }
   }
+  // 3-soft-reload (LAZY fleet refresh, `iapeer refresh`): a `.fresh-next` mark means "come up FRESH on the
+  // next natural wake" — re-read doctrine/fragments from disk WITHOUT killing the live session or burst-
+  // waking the fleet. Checked at the TOP of branch 3, BEFORE the type/death-cause logic, so it overrides
+  // resume for ALL peer types — including telegram-fronted (human-conversational) ones, which otherwise
+  // RESUME and chew stale doctrine session-after-session until an explicit /new. Consume-on-fire: clear
+  // .fresh-next AND .idle-reaped (mirror the ephemeral hygiene below — else a stale .idle-reaped would make
+  // a later CRASH read as a clean park in 3b → RESUME a killed context, exactly the 3a hazard).
+  if (hasFreshNext(cfg, identity)) {
+    clearFreshNext(cfg, identity)
+    clearIdleReaped(cfg, identity)
+    return { resume: false, cause: 'soft-reload' }
+  }
   // 3. default (a message woke a dead/asleep peer): decide by the death cause.
   // 3-ephemeral (M1): a stateless worker ALWAYS wakes fresh on delivery — never resume,
   // regardless of death cause or topic. Its clean-window-per-task is the whole point.