@agfpd/iapeer 0.4.20 → 0.4.22

package/CHANGELOG.md

@@ -10,6 +10,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.22] - 2026-06-22
+
+### Added
+
+- **`iapeer live-runtime <peer>`** — prints the peer's CURRENT live runtime: the
+  freshest-pane-log among its **pid-alive** supervisor sessions (a peer can be alive on
+  more than one runtime at once — a `/codex` flip can leave the old session running
+  alongside the new). This is the authoritative, real-time signal for "what runtime is
+  this peer running right now" — NOT `default_runtime` (only the wake-default) and NOT a
+  `.session` wake-record (alive-filtered only on a supervise-tick latency). Exit 0 + the
+  runtime on stdout when one is live; exit 1 + no output when none is alive. For external
+  consumers (e.g. telegram-runtime's typing/tool-use indicator) that must resolve the live
+  runtime of a peer running on a non-default runtime, instead of inferring it. Exposed as
+  `resolveLiveRuntime` (transport).
+
+## [0.4.21] - 2026-06-22
+
+### Fixed
+
+- **`iapeer remove` of an always-on peer no longer leaves an orphan launchd plist.** An
+  infra peer (notifier/telegram/voicetalk) has a `com.iapeer.<p>` plist with KeepAlive;
+  `remove` dropped only the registry record, so launchd kept relaunching `iapeer run-infra
+  <p> <rt>` against the now-deleted record → crash-loop (the SRE peer alerted
+  "gone-without-disable"). `remove` now boots out + removes the **foundation-owned** plist
+  BEFORE the registry remove (closing the crash-loop window), and the **H4 fleet-guard**
+  refuses a FOREIGN persistent-peer plist (`--force` drops only the registry record and
+  leaves the foreign plist intact). A warm peer (no plist) is unaffected.
+
 ## [0.4.20] - 2026-06-22
 
 ### Fixed
@@ -312,7 +340,9 @@ Initial public release — the foundation core of the iapeer multi-agent ecosyst
 - **Heterogeneous peers** — AI agents (Claude, Codex), humans (Telegram), and services
   (timer = cron, watcher = event) are all first-class and addressed the same way.
 
-[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.20...HEAD
+[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.22...HEAD
+[0.4.22]: https://github.com/agfpd/iapeer/compare/v0.4.21...v0.4.22
+[0.4.21]: https://github.com/agfpd/iapeer/compare/v0.4.20...v0.4.21
 [0.4.20]: https://github.com/agfpd/iapeer/compare/v0.4.19...v0.4.20
 [0.4.19]: https://github.com/agfpd/iapeer/compare/v0.4.18...v0.4.19
 [0.4.18]: https://github.com/agfpd/iapeer/compare/v0.4.17...v0.4.18

package/package.json

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

package/src/cli/index.ts

@@ -11,7 +11,7 @@
 // sentinel-marked always-on plist) are stop/start-able.
 
 import { spawnSync } from 'child_process'
-import { existsSync, readFileSync, renameSync } from 'fs'
+import { existsSync, readFileSync, renameSync, rmSync } from 'fs'
 import { fileURLToPath } from 'url'
 import { dirname, join } from 'path'
 import {
@@ -693,8 +693,13 @@ export async function compactPeer(
 
 export interface RemoveOutcome {
   personality: string
-  action: 'removed' | 'absent' | 'refused-live'
+  action: 'removed' | 'absent' | 'refused-live' | 'refused-foreign-launchd'
   reason?: string
+  /** Always-on plist teardown outcome (`bootout + plist removed` / `skipped-sandbox` /
+   *  `skipped-foreign …`). Present only when the peer had a com.iapeer.<p> plist — an
+   *  always-on (infra) peer. Without this, remove orphaned the loaded plist → launchd
+   *  KeepAlive crash-looped `run-infra` against the deleted record. */
+  plistTeardown?: string
   /** The removed peer's cwd (registry fact, captured BEFORE the removal). remove
    *  deliberately keeps the folder — user data is never deleted by a registry reap
    *  (say so in the output instead of leaving silent orphans). */
@@ -744,6 +749,47 @@ export async function removePeerCli(
       }
     }
   }
+  // PLIST TEARDOWN (the always-on / launchd-managed peer). An infra peer
+  // (notifier/telegram/voicetalk) has a com.iapeer.<p> plist with KeepAlive. Removing
+  // ONLY the registry record leaves the plist LOADED → launchd keeps relaunching
+  // `iapeer run-infra <p> <rt>` against the now-deleted record → CRASH-LOOP (doc alerts
+  // "gone-without-disable"). So bootout the job BEFORE the registry remove (stop KeepAlive
+  // before its target vanishes — no crash-loop window), then rm the plist file.
+  // FLEET GUARD (H4): a FOREIGN persistent-peer plist is off-limits — refuse (unless
+  // --force, which then drops ONLY the registry record and leaves the foreign plist intact).
+  let plistTeardown: string | undefined
+  if (isLaunchdManaged(personality, env)) {
+    if (isForeignLaunchd(personality, env)) {
+      if (!opts.force) {
+        return {
+          personality,
+          action: 'refused-foreign-launchd',
+          reason: `"${personality}" is managed by persistent-peer (foreign launchd plist) — the foundation will not remove it (H4). Use persistent-peer tooling, or --force to drop ONLY the registry record (the foreign plist is left intact).`,
+        }
+      }
+      plistTeardown = 'skipped-foreign (H4 — foreign plist left intact; --force dropped only the registry record)'
+    } else {
+      const plistPath = launchdPlistPath(personality, env)
+      // Sandbox/test: never invoke real launchctl (a test peer's label isn't a real job);
+      // still remove the (temp-dir) plist file so the teardown is observable.
+      let bootoutNote: string
+      if (env.IAPEER_TEST_SANDBOX === '1') {
+        bootoutNote = 'skipped-sandbox'
+      } else {
+        const r = spawnSync('launchctl', ['bootout', `gui/${uid()}/${launchdLabel(personality)}`], { encoding: 'utf8' })
+        // bootout exits non-zero when the job was already unloaded — benign for a teardown.
+        bootoutNote = r.status === 0 ? 'bootout' : `bootout (exit ${r.status}${(r.stderr ?? '').trim() ? `: ${(r.stderr ?? '').trim()}` : ''})`
+      }
+      let rmNote: string
+      try {
+        rmSync(plistPath, { force: true })
+        rmNote = ' + plist removed'
+      } catch (e) {
+        rmNote = ` (plist rm FAILED: ${e instanceof Error ? e.message : String(e)} — remove ${plistPath} manually)`
+      }
+      plistTeardown = `${bootoutNote}${rmNote}`
+    }
+  }
   await removePeer(personality, { env })
   // v1.2 UNPROVISION joint (контракт §Provision провайдера): a provision-declaring
   // slot gets its unprovision command per agentic runtime with occasion=remove —
@@ -822,6 +868,7 @@ export async function removePeerCli(
     action: 'removed',
     cwd: peer.cwd,
     purgedState,
+    ...(plistTeardown ? { plistTeardown } : {}),
     ...(unprovisionOutcomes.length ? { unprovision: unprovisionOutcomes } : {}),
     ...(trustCleaned ? { codexTrust: trustCleaned } : {}),
     ...(hooksTrustCleaned ? { codexHooksTrust: hooksTrustCleaned } : {}),
@@ -1092,6 +1139,7 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory → voice (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
   },
   { sig: 'status', desc: 'host snapshot: version, daemon health, memory + voice slots (<provider> | none)' },
+  { sig: 'live-runtime <peer>', desc: 'print the peer\'s CURRENT live runtime (freshest pane-log among pid-alive sessions; NOT default_runtime). Exit 1 + no output if none alive' },
   { sig: 'install-runtime <runtime> [--package pkg] [--npx]', desc: 'npx-install a runtime package + deploy its declared peer-set' },
   { sig: 'update-runtime <runtime> | --all [--force]', desc: "version-gate → re-install + re-provision declared set → restart the runtime's peers" },
   { sig: 'init [cwd] [--runtime r] [--description d]', desc: 'onboard the CURRENT folder as a peer (name = folder name; identity + MCP + doctrine)' },
@@ -1454,6 +1502,21 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(formatHostStatus(s))
         return s.daemon.healthy ? 0 : 1
       }
+      case 'live-runtime': {
+        // The AUTHORITATIVE current live runtime of a peer (machine-readable, for external
+        // consumers like telegram-runtime's typing indicator). Prints the runtime the peer
+        // is RUNNING right now — the freshest-pane-log among its PID-alive supervisor
+        // sessions — NOT default_runtime (the wake-default) and NOT a .session wake-record.
+        // A peer can be alive on >1 runtime (a /codex flip leaves both); this picks the
+        // currently-active. Exit 0 + the runtime on stdout when one is live; exit 1 + no
+        // output when none is alive (queryable: `rt=$(iapeer live-runtime <p>) || handle-down`).
+        if (!positionals[0]) return argErr(errOut, 'live-runtime needs a peer name — usage: iapeer live-runtime <peer>')
+        const { resolveLiveRuntime } = await import('../transport/index.ts')
+        const rt = resolveLiveRuntime(positionals[0])
+        if (!rt) return 1 // no live session — no output, non-zero
+        out(`${rt}\n`)
+        return 0
+      }
       case 'install-runtime': {
         // §6 onboard a runtime END-TO-END: npx-install the package (auto-resolved from
         // the built-in runtime→package registry, or --package; self-deploys bin +
@@ -1806,6 +1869,11 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         const o = await removePeerCli(positionals[0], { force: flags.force === true, env })
         if (o.action === 'removed') {
           out(`removed "${o.personality}" from the registry\n`)
+          // Always-on plist teardown (bootout + rm) — an orphan loaded plist would
+          // KeepAlive-crash-loop run-infra against the deleted record.
+          if (o.plistTeardown) {
+            out(`launchd plist: ${o.plistTeardown}\n`)
+          }
           // v1.2: the provider unwound its surfaces (occasion=remove) — say how it went.
           if (o.unprovision?.length) {
             out(`memory unprovision: ${o.unprovision.join(', ')}\n`)
@@ -1830,7 +1898,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           }
         } else if (o.action === 'absent') out(`"${o.personality}" not registered — no-op\n`)
         else errOut(`remove: ${o.reason}\n`)
-        return o.action === 'refused-live' ? 1 : 0
+        return o.action === 'refused-live' || o.action === 'refused-foreign-launchd' ? 1 : 0
       }
       case 'rename': {
         // FULL folder rename (Arthur's invariant: personality == basename(cwd)): mv the

package/src/transport/index.ts

@@ -279,6 +279,33 @@ function defaultPaneLogMtime(address: string): number | null {
   }
 }
 
+/**
+ * The CURRENT live runtime of a peer — the AUTHORITATIVE, real-time signal for "what
+ * runtime is this peer running right now" (NOT default_runtime, which is only the wake
+ * DEFAULT, and NOT a `.session` file, a wake-record cleaned on a supervise-tick latency).
+ *
+ * Resolution: among the peer's PID-ALIVE supervisor sessions (listHostedPeers — the same
+ * source delivery uses; `sessionAlive` = pidfile exists AND kill-0), pick the one with the
+ * FRESHEST pane-log. A peer can be alive on >1 runtime at once (a `/codex` flip can leave
+ * the old session running alongside the new), so the freshest-pane-log among the alive set
+ * is the currently-active surface. The alive-filter is what fixes the flip-race: a
+ * just-died runtime's pane-log / .sock / .session all LINGER, but its pid is dead → it is
+ * excluded here. Returns null when no session is alive.
+ *
+ * Deps are injectable for hermetic tests (the defaults read the real run-dir + pane-logs).
+ */
+export function resolveLiveRuntime(
+  personality: string,
+  deps: { aliveRuntimes?: (p: string) => string[]; paneLogMtime?: (address: string) => number | null } = {},
+): string | null {
+  const aliveOf = deps.aliveRuntimes ?? ((p: string) => listHostedPeers().filter(h => h.personality === p).map(h => h.runtime))
+  const paneMt = deps.paneLogMtime ?? defaultPaneLogMtime
+  const alive = aliveOf(personality)
+  if (alive.length <= 1) return alive[0] ?? null
+  // >1 alive → the freshest pane-log mtime (the currently-rendering turn surface).
+  return alive.reduce((best, rt) => ((paneMt(`${rt}-${personality}`) ?? 0) > (paneMt(`${best}-${personality}`) ?? 0) ? rt : best))
+}
+
 
 // ─── Compact done gate (dialogue control must report FACT, not keystroke delivery) ──