@agfpd/iapeer 0.2.42 → 0.2.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.42",
+  "version": "0.2.44",
   "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, parseArgs, removePeerCli, runCli, sendMessage, startPeer, stopPeer } from './index.ts'
+import { 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'
@@ -397,3 +397,57 @@ describe('parseArgs (audit #27 — value beginning with --)', () => {
     expect(parseArgs(['x', '--description=']).flags.description).toBe('')
   })
 })
+
+// ─── new — the UNCONDITIONAL fresh-restart control (docs/Control-команды §new) ─
+
+describe('new (unconditional fresh restart)', () => {
+  test('happy path: fresh-slate (un-park + stale markers cleared) → fresh wake with resume:false task:"" → action fresh', async () => {
+    await register('alpha')
+    const e = env()
+    const cfg = loadLifecycleConfig(e)
+    // a parked peer with stale markers — /new must override ALL of it
+    setStopped(cfg, 'claude-alpha')
+    setIdleReaped(cfg, 'claude-alpha')
+    const calls: Array<{ personality: string; runtime: string; task: string; resume: boolean }> = []
+    const o = await newPeer('alpha', undefined, {
+      env: e,
+      wakeFn: async args => {
+        calls.push(args)
+        return { status: 'READY', woke: true, runtime: args.runtime, process_address: `${args.runtime}-${args.personality}`, taskDelivered: true }
+      },
+    })
+    expect(o.action).toBe('fresh')
+    expect(o.runtime).toBe('claude')
+    expect(calls).toEqual([{ personality: 'alpha', runtime: 'claude', task: '', resume: false }])
+    expect(isStopped(cfg, 'claude-alpha')).toBe(false) // un-parked: /new outranks the C1 stop
+    expect(hasIdleReaped(cfg, 'claude-alpha')).toBe(false) // stale marker cleared
+  })
+
+  test('wake FAILED → action failed with the reason (exit-1 contract for the bot)', async () => {
+    await register('beta2')
+    const o = await newPeer('beta2', undefined, {
+      env: env(),
+      wakeFn: async () => ({ status: 'FAILED', woke: false, reason: 'boot hang' }),
+    })
+    expect(o.action).toBe('failed')
+    expect(o.reason).toBe('boot hang')
+  })
+
+  test('refusals are explicit: foreign launchd / infra runtime / undeclared runtime / unknown peer', async () => {
+    const e = env()
+    // foreign PP plist → fleet guard
+    await register('boris')
+    writeFileSync(launchdPlistPath('boris', e), '<?xml version="1.0"?>\n<plist><dict><key>Label</key><string>com.iapeer.boris</string></dict></plist>\n')
+    expect((await newPeer('boris', undefined, { env: e })).action).toBe('refused-foreign-launchd')
+    // infra runtime → launchd-held, kickstart hint
+    await register('tg', 'telegram', 'natural')
+    const infra = await newPeer('tg', undefined, { env: e })
+    expect(infra.action).toBe('refused-infra')
+    expect(infra.reason).toContain('kickstart')
+    // undeclared runtime → explicit refusal, no silent launch
+    await register('gamma2')
+    expect((await newPeer('gamma2', 'codex', { env: e })).action).toBe('refused-undeclared-runtime')
+    // unknown peer → throws (same contract as stop/start)
+    await expect(newPeer('ghost-nobody', undefined, { env: e })).rejects.toThrow('not registered')
+  })
+})

package/src/cli/index.ts

@@ -27,6 +27,8 @@ import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../regist
 import { isPeerLive, routeControl, routeSend, type WakeFn } from '../transport/index.ts'
 import {
   attachPeer,
+  clearIdleReaped,
+  clearNewEager,
   clearStopped,
   folderLaunch,
   isLaunchdManaged,
@@ -41,9 +43,10 @@ import {
   setNewEager,
   setStopped,
   wakeOrSpawn,
+  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 {
@@ -269,6 +272,90 @@ export function startPeer(personality: string, runtime: string | undefined, opts
   return out
 }
 
+export interface NewPeerOutcome {
+  personality: string
+  runtime: string
+  action: 'fresh' | 'refused-foreign-launchd' | 'refused-infra' | 'refused-undeclared-runtime' | 'failed'
+  reason?: string
+}
+
+/**
+ * new <peer> [runtime] — the UNCONDITIONAL fresh-restart control command
+ * (docs/Control-команды §new; постановка boris 01:32 12.06, санкция Артура).
+ *
+ * The emergency lever for a HUNG or dead agent session: /alias-new covers only
+ * the COOPERATIVE path (a live peer reads the expanded prompt and runs
+ * `iapeer self-fresh`); a stuck/raving/dead peer never reads a prompt — this
+ * command restarts it MECHANICALLY, bypassing the peer entirely:
+ *   fresh-slate markers (un-park C1 stop, clear stale .idle-reaped/.new-eager) →
+ *   canary-clean teardown of any live session (killSession — a deliberate kill,
+ *   never a death class; session-state dropped so supervise stays silent) →
+ *   wakeOrSpawn(resume:false, task:'') — fresh BY CONSTRUCTION, the same recipe
+ *   as the eager relaunch (the C2 initial_prompt seeds the first turn).
+ *
+ * exit-0 contract (сверка telegram-runtime): success ⟺ the fresh session is UP
+ * and READY (verified by the wake's ready gate, not merely scheduled) — for a
+ * sleeping, dead AND hung target alike. Duration is a real TUI boot: typically
+ * 5–30 s, bounded by cfg.bootDeadlineSecs. Idempotent in effect: each repeat
+ * leaves exactly one fresh live session (concurrent calls serialize on the
+ * wake lock). REFUSES foreign-launchd peers (fleet guard) and infra runtimes
+ * (launchd-held — their restart is `launchctl kickstart`'s domain), like
+ * stop/start; an explicitly-passed runtime the peer does not declare is an
+ * explicit refusal (never a silent launch of an undeclared runtime).
+ */
+export async function newPeer(
+  personality: string,
+  runtime: string | undefined,
+  opts: CliEnvOptions & { wakeFn?: (args: { personality: string; runtime: Runtime; task: string; resume: false }) => Promise<WakeResult> } = {},
+): Promise<NewPeerOutcome> {
+  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`)
+  if (isForeignLaunchd(personality, env)) {
+    return {
+      personality,
+      runtime: peer.runtime,
+      action: 'refused-foreign-launchd',
+      reason: `"${personality}" is managed by persistent-peer (foreign launchd plist) — the foundation does not restart it`,
+    }
+  }
+  if (runtime && !isRuntime(runtime)) throw new Error(`invalid runtime "${runtime}"`)
+  const rt: Runtime = (runtime as Runtime | undefined) ?? peer.runtime
+  if (!peer.runtimes.includes(rt)) {
+    return {
+      personality,
+      runtime: rt,
+      action: 'refused-undeclared-runtime',
+      reason: `peer "${personality}" does not declare runtime "${rt}" (declared: ${peer.runtimes.join(', ')})`,
+    }
+  }
+  if (isInfraRuntime(rt)) {
+    return {
+      personality,
+      runtime: rt,
+      action: 'refused-infra',
+      reason: `infra runtime "${rt}" is launchd-held — restart it with: launchctl kickstart -k gui/$(id -u)/${launchdLabel(personality)}`,
+    }
+  }
+  const identity = buildProcessAddress(rt, personality)
+  const sock = buildSocketPath(rt, personality, cfg.sockDir)
+  // Fresh slate: an explicit operator /new outranks a C1 park (it demands a live
+  // fresh session NOW) and any stale death/fresh markers (the wake below is fresh
+  // by construction — markers must not leak into a LATER wake's decision).
+  clearStopped(cfg, identity)
+  clearIdleReaped(cfg, identity)
+  clearNewEager(cfg, identity)
+  killSession(sock, identity) // canary-clean deliberate teardown; no-op when dead
+  removeSessionState(cfg, identity) // never a death class — supervise stays silent
+  const wake = opts.wakeFn ?? (args => wakeOrSpawn(args, { cfg, env }))
+  const r = await wake({ personality, runtime: rt, task: '', resume: false })
+  if (r.status !== 'READY') {
+    return { personality, runtime: rt, action: 'failed', reason: r.reason ?? 'wake failed' }
+  }
+  return { personality, runtime: rt, action: 'fresh' }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // remove — delete a peer's record from the registry through the LOCKED writer
 // (registry.removePeer). Direct edits of peers-profiles.json are refused at
@@ -565,6 +652,7 @@ const USAGE = `usage: iapeer <verb> [args]
   <runtime>                                                      launch the cwd's peer (ALWAYS fresh)
   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)
   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)
@@ -948,6 +1036,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 'new': {
+        // UNCONDITIONAL fresh restart (control, system class — docs/Control-команды
+        // §new): the emergency lever for a hung/dead session, bypasses the peer.
+        // Source: operator CLI, or telegram-runtime's clean-/new detect (their bot
+        // shells `iapeer new <peer> <runtime>` — exit 0 ⟺ fresh session up+ready).
+        if (!positionals[0]) return usage(errOut)
+        const o = await newPeer(positionals[0], positionals[1], { env })
+        if (o.action === 'fresh') {
+          out(`new: ${o.runtime}-${o.personality} fresh session up\n`)
+          return 0
+        }
+        errOut(`new: ${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
+        return 1
+      }
       case 'start': {
         // --all re-enables every REGISTERED peer (mirror of `stop --all` — the 11.06
         // incident: bringing a stopped fleet back required a manual loop over ~25
@@ -1091,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/adapters/codex.ts

@@ -319,11 +319,16 @@ export const codexAdapter: RuntimeAdapter = {
    *     interrupts the turn — NOT a double. (Codex's own footer says "esc to
    *     interrupt"; one Escape yields "■ Conversation interrupted". The contract's
    *     open "×1/×2?" is resolved to ×1, same as claude.) Session + context intact.
-   *   - compact → null (codex has no '/compact'; context management is its own).
+   *   - compact → type '/compact' then Enter. SNAPPED LIVE 12.06 (codex-cli
+   *     0.138.0): the slash EXISTS now — autocomplete documents it («summarize
+   *     conversation to prevent hitting the context limit») and a live run
+   *     yields «• Context compacted». The 0.136-era "codex has no /compact"
+   *     finding is stale; the mapping is keyboard-identical to claude's.
    *   - anything else → null.
    */
   executeControl(command: ControlCommand): ControlPlan | null {
     if (command.name === 'interrupt') return { sequence: [['Escape']] }
+    if (command.name === 'compact') return { sequence: [['-l', '/compact'], ['Enter']], stepDelayMs: 300 }
     return null
   },
 }

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/launch.test.ts

@@ -296,9 +296,10 @@ describe('executeControl (Ф-E control commands)', () => {
     expect(claudeAdapter.executeControl({ name: 'compact' })).toEqual({ sequence: [['-l', '/compact'], ['Enter']], stepDelayMs: 300 })
     expect(claudeAdapter.executeControl({ name: 'bogus' })).toBeNull()
   })
-  test('codex: interrupt → [Escape] (×1 baseline; ×2 snapped live); compact → null', () => {
+  test('codex: interrupt → [Escape] (×1, snapped live); compact → /compact + Enter (snapped live 12.06, codex-cli 0.138)', () => {
     expect(codexAdapter.executeControl({ name: 'interrupt' })).toEqual({ sequence: [['Escape']] })
-    expect(codexAdapter.executeControl({ name: 'compact' })).toBeNull()
+    expect(codexAdapter.executeControl({ name: 'compact' })).toEqual({ sequence: [['-l', '/compact'], ['Enter']], stepDelayMs: 300 })
+    expect(codexAdapter.executeControl({ name: 'bogus' })).toBeNull()
   })
   test('routers (telegram/notifier) refuse all control (no TUI turn)', () => {
     expect(telegramAdapter.executeControl({ name: 'interrupt' })).toBeNull()

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',