@agfpd/iapeer 0.2.43 → 0.2.45

package/package.json

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

package/src/cli/cli.test.ts

@@ -7,7 +7,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
-import { formatListTable, listPeers, newPeer, parseArgs, removePeerCli, runCli, sendMessage, startPeer, stopPeer } from './index.ts'
+import { addRuntime, defaultRuntime, formatListTable, listPeers, newPeer, parseArgs, removePeerCli, runCli, sendMessage, startPeer, stopPeer } from './index.ts'
 import { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
 import { hasIdleReaped, isStopped, loadLifecycleConfig, setIdleReaped, setStopped } from '../lifecycle/index.ts'
 import { launchdPlistPath } from '../launch/launchd.ts'
@@ -451,3 +451,61 @@ describe('new (unconditional fresh restart)', () => {
     await expect(newPeer('ghost-nobody', undefined, { env: e })).rejects.toThrow('not registered')
   })
 })
+
+// ─── add-runtime / default-runtime — the fleet-switch levers (codex-parity) ───
+
+describe('add-runtime / default-runtime (fleet-switch levers)', () => {
+  test('add-runtime merges the runtime into profile+registry; idempotent; infra peers skipped', async () => {
+    const e = env()
+    // a claude-only peer with a REAL cwd (initPeer scaffolds it)
+    const cwd = join(root, 'peers', 'aud1')
+    mkdirSync(cwd, { recursive: true })
+    await upsertPeer({ personality: 'aud1', runtime: 'claude', cwd, intelligence: 'artificial' }, { rootDir: root })
+    const { initPeer } = await import('../init/index.ts')
+    await initPeer({ cwd, runtime: 'claude', env: e }) // give it a local profile (claude-only)
+    // an infra peer in the registry — must be skipped by --all
+    await register('tginfra', 'telegram', 'natural')
+    const outcomes = await addRuntime('codex', { all: true, env: e })
+    const aud1 = outcomes.find(o => o.personality === 'aud1')!
+    expect(aud1.action).toBe('added')
+    expect(outcomes.find(o => o.personality === 'tginfra')!.action).toBe('skipped-infra-peer')
+    // profile + registry both carry codex now; default untouched
+    const { readPeerProfile } = await import('../identity/index.ts')
+    const prof = readPeerProfile(cwd)!
+    expect(prof.runtimes).toContain('codex')
+    expect(prof.runtime).toBe('claude') // default_runtime NOT flipped
+    const rec = findPeer(readPeersIndex({ env: e }), 'aud1')!
+    expect(rec.runtimes).toContain('codex')
+    // idempotent
+    expect((await addRuntime('codex', { peer: 'aud1', env: e }))[0].action).toBe('already')
+  })
+
+  test('add-runtime refuses an infra runtime as the argument', async () => {
+    await register('x1')
+    await expect(addRuntime('telegram', { peer: 'x1', env: env() })).rejects.toThrow('infra runtime')
+  })
+
+  test('default-runtime flips the primary (profile + registry in one command); refuses undeclared; symmetric back', async () => {
+    const e = env()
+    const cwd = join(root, 'peers', 'aud2')
+    mkdirSync(cwd, { recursive: true })
+    await upsertPeer({ personality: 'aud2', runtime: 'claude', cwd, intelligence: 'artificial' }, { rootDir: root })
+    const { initPeer } = await import('../init/index.ts')
+    await initPeer({ cwd, runtime: 'claude', env: e })
+    // undeclared codex → explicit refusal with the add-runtime hint
+    const refused = await defaultRuntime('codex', { peer: 'aud2', env: e })
+    expect(refused[0].action).toBe('refused-undeclared-runtime')
+    expect(refused[0].detail).toContain('add-runtime')
+    // declare codex, then flip
+    await addRuntime('codex', { peer: 'aud2', env: e })
+    expect((await defaultRuntime('codex', { peer: 'aud2', env: e }))[0].action).toBe('flipped')
+    const { readPeerProfile } = await import('../identity/index.ts')
+    expect(readPeerProfile(cwd)!.runtime).toBe('codex')
+    expect(readPeerProfile(cwd)!.runtimes[0]).toBe('codex') // normalizeRuntimes prepends the default
+    expect(findPeer(readPeersIndex({ env: e }), 'aud2')!.runtime).toBe('codex') // registry healed same-command
+    // idempotent + symmetric revert
+    expect((await defaultRuntime('codex', { peer: 'aud2', env: e }))[0].action).toBe('already')
+    expect((await defaultRuntime('claude', { peer: 'aud2', env: e }))[0].action).toBe('flipped')
+    expect(findPeer(readPeersIndex({ env: e }), 'aud2')!.runtime).toBe('claude')
+  })
+})

package/src/cli/index.ts

@@ -46,8 +46,8 @@ import {
   type WakeResult,
 } from '../lifecycle/index.ts'
 import { getAdapter } from '../launch/index.ts'
-import { isFoundationOwnedPlist, kickstartDaemon, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
-import { resolveCallerIdentity, resolveIdentity } from '../identity/index.ts'
+import { cycleDaemon, isFoundationOwnedPlist, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
+import { readPeerProfile, resolveCallerIdentity, resolveIdentity, writePeerProfileAtomic } from '../identity/index.ts'
 import { peerProfilePath } from '../storage/index.ts'
 import {
   isConformant,
@@ -272,6 +272,123 @@ export function startPeer(personality: string, runtime: string | undefined, opts
   return out
 }
 
+export interface AddRuntimeOutcome {
+  personality: string
+  action: 'added' | 'already' | 'skipped-infra-peer' | 'failed'
+  detail?: string
+}
+
+/**
+ * add-runtime <runtime> (--peer <p> | --all) — give EXISTING peers an additional
+ * AGENTIC runtime in one command (codex-parity audit, директива Артура 12.06: the
+ * fleet-switch enabler — 14/23 peers were claude-only with nothing to switch to).
+ * Per target: initPeer({cwd, runtime}) — ensurePeerProfile MERGES runtimes (the
+ * default_runtime lever is deliberately untouched — capability ≠ routing flip; see
+ * `default-runtime`), scaffolds the runtime scope, and the codex side runs its
+ * whole birth chain: cwd pre-trust, native-memory lever, memory provision
+ * (occasion=birth), host-wide MCP block + update-check-off. Idempotent by
+ * construction (merge + append-if-absent everywhere). Infra PEERS (telegram/
+ * notifier defaults) are skipped — adding an agentic runtime to a router peer is
+ * an operator decision, not a sweep.
+ */
+export async function addRuntime(
+  runtime: string,
+  opts: CliEnvOptions & { peer?: string; all?: boolean },
+): Promise<AddRuntimeOutcome[]> {
+  const env = opts.env ?? process.env
+  if (!isRuntime(runtime)) throw new Error(`invalid runtime "${runtime}"`)
+  if (isInfraRuntime(runtime)) {
+    throw new Error(`"${runtime}" is an infra runtime — infra presence is operator-add via \`iapeer create\` (plist semantics), not a sweep`)
+  }
+  const index = readPeersIndex({ env })
+  const targets = opts.all === true ? index.peers : index.peers.filter(p => p.personality === opts.peer)
+  if (targets.length === 0) throw new Error(opts.peer ? `peer "${opts.peer}" is not registered` : 'no targets — pass --peer <p> or --all')
+  const { initPeer } = await import('../init/index.ts')
+  const out: AddRuntimeOutcome[] = []
+  for (const p of targets) {
+    if (isInfraRuntime(p.runtime)) {
+      out.push({ personality: p.personality, action: 'skipped-infra-peer', detail: `default runtime "${p.runtime}" is infra` })
+      continue
+    }
+    if (p.runtimes.includes(runtime as Runtime)) {
+      out.push({ personality: p.personality, action: 'already' })
+      continue
+    }
+    try {
+      const warns: string[] = []
+      await initPeer({ cwd: p.cwd, runtime: runtime as Runtime, env, warn: m => warns.push(m) })
+      out.push({ personality: p.personality, action: 'added', detail: warns.length ? warns.join(' | ') : undefined })
+    } catch (e) {
+      out.push({ personality: p.personality, action: 'failed', detail: e instanceof Error ? e.message : String(e) })
+    }
+  }
+  return out
+}
+
+export interface DefaultRuntimeOutcome {
+  personality: string
+  action: 'flipped' | 'already' | 'refused-undeclared-runtime' | 'skipped-infra-peer' | 'failed'
+  detail?: string
+}
+
+/**
+ * default-runtime <runtime> (--peer <p> | --all) — flip the PRIMARY lever
+ * (contract Идентичность: primary держит default_runtime, НЕ порядок runtimes[];
+ * linus precedent 11.06). This is the routing/wake/first-launch default — the
+ * actual fleet-switch moment is a mass flip of exactly this field. The local
+ * profile is rewritten through the H1 merge-writer (default_runtime + the legacy
+ * in-sync mirror; normalizeRuntimes re-prepends the new default), then the
+ * registry is self-healed from the flipped locals (the reindex REPLACE rail —
+ * same as `verify --fix`), so routing flips in the same command. REFUSES a peer
+ * that does not declare the runtime (add-runtime first) and skips infra peers.
+ * Symmetric back: `default-runtime claude --all` reverts the fleet.
+ */
+export async function defaultRuntime(
+  runtime: string,
+  opts: CliEnvOptions & { peer?: string; all?: boolean },
+): Promise<DefaultRuntimeOutcome[]> {
+  const env = opts.env ?? process.env
+  if (!isRuntime(runtime)) throw new Error(`invalid runtime "${runtime}"`)
+  if (isInfraRuntime(runtime)) throw new Error(`"${runtime}" is an infra runtime — not a warm routing default`)
+  const index = readPeersIndex({ env })
+  const targets = opts.all === true ? index.peers : index.peers.filter(p => p.personality === opts.peer)
+  if (targets.length === 0) throw new Error(opts.peer ? `peer "${opts.peer}" is not registered` : 'no targets — pass --peer <p> or --all')
+  const out: DefaultRuntimeOutcome[] = []
+  for (const p of targets) {
+    if (isInfraRuntime(p.runtime)) {
+      out.push({ personality: p.personality, action: 'skipped-infra-peer', detail: `default runtime "${p.runtime}" is infra` })
+      continue
+    }
+    try {
+      const profile = readPeerProfile(p.cwd)
+      if (!profile) {
+        out.push({ personality: p.personality, action: 'failed', detail: `no local profile at ${p.cwd}` })
+        continue
+      }
+      if (profile.runtime === runtime) {
+        out.push({ personality: p.personality, action: 'already' })
+        continue
+      }
+      if (!profile.runtimes.includes(runtime as Runtime)) {
+        out.push({
+          personality: p.personality,
+          action: 'refused-undeclared-runtime',
+          detail: `declares [${profile.runtimes.join(', ')}] — run \`iapeer add-runtime ${runtime} --peer ${p.personality}\` first`,
+        })
+        continue
+      }
+      writePeerProfileAtomic(p.cwd, { ...profile, runtime: runtime as Runtime })
+      out.push({ personality: p.personality, action: 'flipped' })
+    } catch (e) {
+      out.push({ personality: p.personality, action: 'failed', detail: e instanceof Error ? e.message : String(e) })
+    }
+  }
+  // Self-heal the registry from the flipped locals so routing flips in the same
+  // command (REPLACE projection — the verify --fix rail).
+  if (out.some(o => o.action === 'flipped')) await reindexFromLocals({ env })
+  return out
+}
+
 export interface NewPeerOutcome {
   personality: string
   runtime: string
@@ -653,6 +770,8 @@ const USAGE = `usage: iapeer <verb> [args]
   connect telegram <peer> [--token <t>]                          attach a telegram bot to a peer (bot add → interface → router restart; asks only the token)
   enable <plugin> [peer] [--no-setup]                            install + enable an agfpd capability for a peer
   new <peer> [runtime]                                           UNCONDITIONAL fresh restart: canary-clean kill + fresh wake (emergency lever for a hung/dead session — bypasses the peer; exit 0 = fresh session up+ready)
+  add-runtime <runtime> (--peer <p> | --all)                     add an agentic runtime to existing peer(s): runtimes-merge + scaffold + codex birth chain (pre-trust, native-memory, memory provision, MCP). default_runtime untouched
+  default-runtime <runtime> (--peer <p> | --all)                 flip the PRIMARY (routing/wake default) — the fleet-switch lever; refuses an undeclared runtime; registry self-healed in the same command
   attach <peer> [runtime]                                        ensure-live + resume, then tmux attach
   interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
   compact <peer> [runtime]                                       compact the peer's context (/compact)
@@ -1036,6 +1155,27 @@ 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 'add-runtime': {
+        // Fleet-switch enabler (codex-parity audit): add an agentic runtime to
+        // existing peer(s) — full codex birth chain per target, idempotent.
+        const rt = positionals[0]
+        if (!rt) return usage(errOut)
+        const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
+        if (flags.all !== true && !peerName) return usage(errOut)
+        const outcomes = await addRuntime(rt, { peer: peerName, all: flags.all === true, env })
+        for (const o of outcomes) out(`${o.personality}: ${o.action}${o.detail ? ` — ${o.detail}` : ''}\n`)
+        return outcomes.some(o => o.action === 'failed') ? 1 : 0
+      }
+      case 'default-runtime': {
+        // The PRIMARY flip (routing/wake default) — the fleet-switch moment itself.
+        const rt = positionals[0]
+        if (!rt) return usage(errOut)
+        const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
+        if (flags.all !== true && !peerName) return usage(errOut)
+        const outcomes = await defaultRuntime(rt, { peer: peerName, all: flags.all === true, env })
+        for (const o of outcomes) out(`${o.personality}: ${o.action}${o.detail ? ` — ${o.detail}` : ''}\n`)
+        return outcomes.some(o => o.action === 'failed') ? 1 : 0
+      }
       case 'new': {
         // UNCONDITIONAL fresh restart (control, system class — docs/Control-команды
         // §new): the emergency lever for a hung/dead session, bypasses the peer.
@@ -1193,7 +1333,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',