@agfpd/iapeer 0.2.43 → 0.2.44

package/package.json

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

package/src/cli/index.ts

@@ -46,7 +46,7 @@ import {
   type WakeResult,
 } from '../lifecycle/index.ts'
 import { getAdapter } from '../launch/index.ts'
-import { isFoundationOwnedPlist, kickstartDaemon, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
+import { cycleDaemon, isFoundationOwnedPlist, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
 import { resolveCallerIdentity, resolveIdentity } from '../identity/index.ts'
 import { peerProfilePath } from '../storage/index.ts'
 import {
@@ -1193,7 +1193,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           errOut(`rollback failed: ${rb.reason}\n`)
           return 1
         }
-        const restart = kickstartDaemon(env)
+        const restart = cycleDaemon(env)
         if (restart.state === 'restarted') {
           const h = await waitForDaemonHealthy({ env })
           out(

package/src/install/index.ts

@@ -112,7 +112,7 @@ export interface RollbackResult {
  * foundation keeps a single `.prev`, not a history stack): rollback restores the
  * binary that was live BEFORE the most recent install. Atomic (copy .prev → .tmp →
  * rename over the binary), so the binary is never absent. The CALLER restarts the
- * daemon afterwards (kickstartDaemon) — rollback only swaps the bytes. Sandbox-guarded.
+ * daemon afterwards (cycleDaemon) — rollback only swaps the bytes. Sandbox-guarded.
  */
 export function rollbackIapeer(env: NodeJS.ProcessEnv = process.env): RollbackResult {
   const binPath = iapeerBinPath(env)

package/src/launch/index.ts

@@ -61,6 +61,8 @@ export {
   isFoundationOwnedPlist,
   launchctlBootstrap,
   bootstrapJobCore,
+  cycleDaemon,
+  cycleDaemonCore,
   resolveExecutable,
   IAPEER_PLIST_OWNER_KEY,
 } from './launchd.ts'
@@ -71,6 +73,8 @@ export type {
   BootstrapState,
   BootstrapCoreDeps,
   BootstrapCoreResult,
+  DaemonRestartResult,
+  DaemonRestartState,
   LaunchctlRunner,
 } from './launchd.ts'
 

package/src/launch/launchd.test.ts

@@ -11,6 +11,7 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import {
   bootstrapJobCore,
+  cycleDaemonCore,
   getAdapter,
   installAlwaysOnPlist,
   isFoundationOwnedPlist,
@@ -430,3 +431,69 @@ describe('buildAlwaysOnSpec carries intelligence (telegram crash-loop guard)', (
     rmSync(cwd, { recursive: true, force: true })
   })
 })
+
+// ─── cycleDaemonCore — the LWCR-safe deploy restart (bootout+bootstrap) ───────
+// Proven live 12.06 twice: a kickstart after a binary replacement respawns into
+// an EX_CONFIG(78) crash-loop when launchd's managed Launch Constraint still
+// pins the OLD binary's signature (com.iapeer.arthur, then com.agfpd.iapeer
+// itself on the 0.2.43 deploy). The cure — and now the ONLY restart form the
+// update pipeline uses — is a full re-registration.
+
+describe('cycleDaemonCore (LWCR-safe bootout+bootstrap)', () => {
+  function harness(script: { printStatuses: number[]; bootoutStatus?: number; bootstrapStatuses?: number[] }) {
+    const calls: string[][] = []
+    let printI = 0
+    let bootI = 0
+    const run = (args: string[]) => {
+      calls.push(args)
+      if (args[0] === 'print') {
+        const status = script.printStatuses[Math.min(printI, script.printStatuses.length - 1)]!
+        printI++
+        return { status, stderr: '' }
+      }
+      if (args[0] === 'bootout') return { status: script.bootoutStatus ?? 0, stderr: script.bootoutStatus ? 'boom' : '' }
+      const status = (script.bootstrapStatuses ?? [0])[Math.min(bootI, (script.bootstrapStatuses ?? [0]).length - 1)]!
+      bootI++
+      return { status, stderr: status === 0 ? '' : 'Bootstrap failed' }
+    }
+    return { calls, deps: { run, sleepMs: () => {} } }
+  }
+
+  test('loaded job: bootout → gone → bootstrap → restarted', () => {
+    // print: loaded (pre-check) → gone (core wait) → bootstrap ok
+    const h = harness({ printStatuses: [0, 1], bootstrapStatuses: [0] })
+    expect(cycleDaemonCore('501', '/p.plist', h.deps)).toEqual({ state: 'restarted' })
+    expect(h.calls.some(c => c[0] === 'bootout')).toBe(true)
+    expect(h.calls.some(c => c[0] === 'bootstrap')).toBe(true)
+  })
+
+  test('not loaded → not-loaded, NOTHING booted out', () => {
+    const h = harness({ printStatuses: [1] })
+    expect(cycleDaemonCore('501', '/p.plist', h.deps)).toEqual({ state: 'not-loaded' })
+    expect(h.calls.some(c => c[0] === 'bootout')).toBe(false)
+  })
+
+  test('bootout fails → failed loud, no bootstrap attempt', () => {
+    const h = harness({ printStatuses: [0], bootoutStatus: 9 })
+    const r = cycleDaemonCore('501', '/p.plist', h.deps)
+    expect(r.state).toBe('failed')
+    expect(r.detail).toContain('bootout failed')
+    expect(h.calls.some(c => c[0] === 'bootstrap')).toBe(false)
+  })
+
+  test('job never unloads after bootout (undead beyond budget) → failed with the manual recipe', () => {
+    // print: loaded (pre-check), then loaded FOREVER (the core wait + retries see it listed)
+    const h = harness({ printStatuses: [0, 0] })
+    const r = cycleDaemonCore('501', '/p.plist', h.deps)
+    expect(r.state).toBe('failed')
+    expect(r.detail).toContain('manual rescue')
+  })
+
+  test('bootstrap retries exhausted → failed with rescue hint', () => {
+    // pre-check loaded → gone for the wait → every bootstrap attempt fails, re-checks stay gone
+    const h = harness({ printStatuses: [0, 1], bootstrapStatuses: [5, 5, 5, 5] })
+    const r = cycleDaemonCore('501', '/p.plist', h.deps)
+    expect(r.state).toBe('failed')
+    expect(r.detail).toContain('manual rescue')
+  })
+})

package/src/launch/launchd.ts

@@ -299,34 +299,87 @@ export function bootstrapJobCore(
 }
 
 export type DaemonRestartState =
-  | 'restarted' // kickstart -k succeeded → the daemon is now on the freshly-installed binary
+  | 'restarted' // bootout + bootstrap succeeded → the daemon runs the freshly-installed binary
   | 'not-loaded' // com.agfpd.iapeer is not in the gui domain → nothing to restart (new binary
   //                will be used whenever it IS next started; nothing to do here)
   | 'skipped-sandbox' // IAPEER_TEST_SANDBOX=1 → never touch the real launchd
-  | 'failed' // launchctl kickstart exited non-zero
+  | 'failed' // bootout/bootstrap failed — the result carries the manual rescue recipe
 
 export interface DaemonRestartResult {
   state: DaemonRestartState
   detail?: string
 }
 
+/**
+ * DI core of cycleDaemon (unit-testable without launchctl): bootout → wait-for-gone
+ * → bootstrap, composed on bootstrapJobCore's undead-job-safe wait/backoff.
+ * Disambiguation of bootstrapJobCore's 'already-loaded': at attempts=0 it means the
+ * job NEVER unloaded after our bootout (undead beyond budget) → FAIL loud with the
+ * manual recipe; at attempts>0 it means a retry found the job loaded (our previous
+ * attempt half-succeeded or KeepAlive raced us in) → the job IS up → success.
+ */
+export function cycleDaemonCore(
+  uid: string,
+  plistPath: string,
+  deps: BootstrapCoreDeps,
+): DaemonRestartResult {
+  const listed = () => deps.run(['print', `gui/${uid}/${DAEMON_PLIST_LABEL}`]).status === 0
+  if (!listed()) return { state: 'not-loaded' }
+  const bo = deps.run(['bootout', `gui/${uid}/${DAEMON_PLIST_LABEL}`])
+  if (bo.status !== 0) {
+    return { state: 'failed', detail: `launchctl bootout failed: ${bo.stderr.trim() || `exit ${bo.status}`}` }
+  }
+  const core = bootstrapJobCore(uid, DAEMON_PLIST_LABEL, plistPath, deps)
+  if (core.state === 'loaded' || (core.state === 'already-loaded' && core.attempts > 0)) {
+    return { state: 'restarted' }
+  }
+  if (core.state === 'already-loaded') {
+    return {
+      state: 'failed',
+      detail:
+        `job never unloaded after bootout (undead beyond budget) — manual rescue: ` +
+        `launchctl bootout gui/${uid}/${DAEMON_PLIST_LABEL} && launchctl bootstrap gui/${uid} ${plistPath}`,
+    }
+  }
+  return {
+    state: 'failed',
+    detail: `${core.detail ?? 'bootstrap failed'} — manual rescue: launchctl bootstrap gui/${uid} ${plistPath}`,
+  }
+}
+
 /**
  * Restart the foundation daemon (`com.agfpd.iapeer`) onto the binary currently on
- * disk — `launchctl kickstart -k gui/<uid>/com.agfpd.iapeer`. This is the "activate
- * the freshly-installed binary" step of `iapeer update`: a compiled daemon holds its
- * old code in memory until restarted, and `-k` SIGKILLs + relaunches it (KeepAlive
- * brings it right back). Only restarts when the service is actually loaded — a
- * not-loaded daemon needs no restart (the new binary is taken on its next start).
- * Never touches the plist (the launch path is version-stable). Sandbox-safe.
+ * disk — `launchctl bootout` + `bootstrap`, DELIBERATELY NOT `kickstart -k`.
+ *
+ * LWCR (launch constraints, the deploy bomb — PROVEN LIVE 12.06 twice): after a
+ * binary replacement, launchd's managed Launch Constraint for the REGISTERED job
+ * can still pin the OLD binary's signature — a kickstart then respawns into an
+ * EX_CONFIG(78) crash-loop (`state = spawn scheduled`, exit 78 from launchd
+ * itself; the binary runs fine by hand). Reproduced on com.iapeer.arthur
+ * (telegram-runtime's v0.14.0 deploy, bridge down 6 min) AND on com.agfpd.iapeer
+ * itself (the 0.2.43 deploy — daemon down until the manual cure). The ONLY cure
+ * is a full re-registration: bootout drops the job (and its constraint),
+ * bootstrap registers it against the binary now on disk. kickstart is
+ * structurally insufficient for this class.
+ *
+ * Composed on bootstrapJobCore (undead-job-safe wait-for-gone + backoff). Only
+ * cycles when the service is actually loaded — a not-loaded daemon needs no
+ * restart (the new binary is taken on its next start). The plist itself is
+ * version-stable (write-if-changed) and is NOT rewritten here. Sandbox-safe.
  */
-export function kickstartDaemon(env: NodeJS.ProcessEnv = process.env): DaemonRestartResult {
-  if (env.IAPEER_TEST_SANDBOX === '1') return { state: 'skipped-sandbox' }
+export function cycleDaemon(env: NodeJS.ProcessEnv = process.env): DaemonRestartResult {
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') {
+    return { state: 'skipped-sandbox' }
+  }
   const uid = currentUid()
-  if (!isLaunchdLoaded(DAEMON_PLIST_LABEL, uid)) return { state: 'not-loaded' }
-  const r = spawnSync('launchctl', ['kickstart', '-k', `gui/${uid}/${DAEMON_PLIST_LABEL}`], { encoding: 'utf8' })
-  return r.status === 0
-    ? { state: 'restarted' }
-    : { state: 'failed', detail: (r.stderr ?? '').trim() || `launchctl kickstart exit ${r.status}` }
+  const plistPath = join(launchAgentsDir(env), `${DAEMON_PLIST_LABEL}.plist`)
+  return cycleDaemonCore(uid, plistPath, {
+    run: args => {
+      const r = spawnSync('launchctl', args, { encoding: 'utf8' })
+      return { status: r.status, stderr: r.stderr ?? '' }
+    },
+    sleepMs: ms => spawnSync('sleep', [String(ms / 1000)]),
+  })
 }
 
 /**

package/src/update/index.ts

@@ -10,7 +10,7 @@
 //      COMPILED binary can't rebuild itself, so we pull the freshly-published package
 //      and run ITS own source installer. DELIBERATELY NOT `npx … install` (see
 //      defaultRunInstall for why npx is unsafe here).
-//   4. kickstart com.agfpd.iapeer IF loaded                (activate the new binary)
+//   4. cycle com.agfpd.iapeer IF loaded (bootout+bootstrap) (activate the new binary; kickstart hits the LWCR EX_CONFIG(78) bomb)
 //
 // Scope: the foundation ONLY (the @agfpd/iapeer binary + its daemon). It never
 // touches the plist (version-stable launch path) and never touches other packages
@@ -27,7 +27,7 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import { IapError } from '../core/errors.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
-import { kickstartDaemon, type DaemonRestartResult } from '../launch/launchd.ts'
+import { cycleDaemon, type DaemonRestartResult } from '../launch/launchd.ts'
 import { defaultDaemonSocketPath } from '../daemon/index.ts'
 
 /** The npm package the foundation publishes / updates from. */
@@ -48,7 +48,7 @@ export interface UpdateDeps {
   /** Pull + rebuild the binary for `version` (default: `npx @agfpd/iapeer@<v> install`).
    *  Returns true on success. */
   runInstall?: (version: string, env: NodeJS.ProcessEnv) => boolean
-  /** Restart the daemon onto the new binary (default: kickstartDaemon). */
+  /** Restart the daemon onto the new binary (default: cycleDaemon — bootout+bootstrap, the LWCR-safe cycle). */
   restartDaemon?: (env: NodeJS.ProcessEnv) => DaemonRestartResult
 }
 
@@ -68,7 +68,7 @@ export interface UpdateResult {
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Post-restart health — verify the daemon actually came up, not just that
-// `launchctl kickstart` exited 0. A new binary that fails to boot would otherwise
+// the daemon job cycle exited 0. A new binary that fails to boot would otherwise
 // be reported as a successful "restarted". The probe connects to the daemon's unix
 // socket (the always-present same-uid listener it binds right before printing READY);
 // a refused connection = not serving. Requires a short STREAK of successes so a
@@ -240,7 +240,7 @@ export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
     }
   }
 
-  const restart = deps.restartDaemon ?? kickstartDaemon
+  const restart = deps.restartDaemon ?? cycleDaemon
   const d = restart(env)
   return {
     status: 'updated',