@agfpd/iapeer 0.2.15 → 0.2.17

package/package.json

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

package/src/cli/cli.test.ts

@@ -4,12 +4,12 @@
 // persistent-peer launchd plist must be refused.
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+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 { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
-import { isStopped, loadLifecycleConfig, setStopped } from '../lifecycle/index.ts'
+import { hasIdleReaped, isStopped, loadLifecycleConfig, setStopped } from '../lifecycle/index.ts'
 import { launchdPlistPath } from '../launch/launchd.ts'
 
 let root: string
@@ -73,6 +73,24 @@ describe('stop / start (C1 durable flag, warm runtime)', () => {
   test('stop an unregistered peer → throws', () => {
     expect(() => stopPeer('nobody', undefined, { env: env() })).toThrow(/not registered/)
   })
+  test('stop is a CLEAN PARK: leaves the resume marker and drops the session-state (boris 10.06)', async () => {
+    await register('parked')
+    const e = env()
+    const cfg = loadLifecycleConfig(e)
+    // a live session-state the daemon would otherwise tag as a death post-kill
+    mkdirSync(cfg.stateDir, { recursive: true })
+    writeFileSync(
+      join(cfg.stateDir, 'claude-parked.session'),
+      JSON.stringify({ identity: 'claude-parked', runtime: 'claude', personality: 'parked', cwd: '/tmp/parked', wokeAt: Date.now() }),
+    )
+    stopPeer('parked', undefined, { env: e })
+    expect(hasIdleReaped(cfg, 'claude-parked')).toBe(true) // park marker → post-start wake RESUMES
+    expect(existsSync(join(cfg.stateDir, 'claude-parked.session'))).toBe(false) // not a death for supervise
+    // start clears only the stop flag — the park marker survives for the wake
+    startPeer('parked', undefined, { env: e })
+    expect(isStopped(cfg, 'claude-parked')).toBe(false)
+    expect(hasIdleReaped(cfg, 'claude-parked')).toBe(true)
+  })
 })
 
 describe('FLEET GUARD (H4) — foreign persistent-peer launchd plist is off-limits', () => {

package/src/cli/index.ts

@@ -33,6 +33,8 @@ import {
   isStopped,
   killSession,
   loadLifecycleConfig,
+  removeSessionState,
+  setIdleReaped,
   setNewEager,
   setStopped,
   wakeOrSpawn,
@@ -196,8 +198,15 @@ export function stopPeer(personality: string, runtime: string | undefined, opts:
       killSession(sock, identity)
       out.push({ personality, runtime: rt, action: 'bootout', reason: r.status === 0 ? undefined : `launchctl bootout exited ${r.status}${(r.stderr ?? '').trim() ? `: ${(r.stderr ?? '').trim()}` : ''}` })
     } else {
+      // A deliberate stop is a CLEAN PARK, not a death (boris 10.06 — stop→start
+      // must survive ≥ idle-reap): park-mark BEFORE the kill so the post-`start`
+      // wake RESUMES, and drop the supervise session-state with the session so
+      // the tick never tags this kill as a death (crash-loop ring stays clean,
+      // no reaped-gone death class for a state the daemon knows 100%).
       setStopped(cfg, identity)
+      setIdleReaped(cfg, identity)
       killSession(sock, identity)
+      removeSessionState(cfg, identity)
       out.push({ personality, runtime: rt, action: 'stopped' })
     }
   }
@@ -363,6 +372,7 @@ const USAGE = `usage: iapeer <verb> [args]
                                                                  backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES)
   status                                                         host snapshot: version, daemon health, memory slot (<provider> | none)
   install-runtime <runtime> [--package pkg] [--npx]              npx-install a runtime package + deploy its declared peer-set
+  update-runtime <runtime> | --all [--force]                     version-gate → re-install + re-provision declared set → restart the runtime's peers
   init [cwd] [--personality p] [--runtime r] [--description d]   onboard the CURRENT folder as a peer (identity + MCP + doctrine)
   create <personality> [--runtime r] [--path dir] [--bin abs]   create a peer anywhere (default ~/.iapeer/peers/<p>) + provision
   list [--json]                                                  registered peers + per-runtime liveness
@@ -371,6 +381,7 @@ const USAGE = `usage: iapeer <verb> [args]
   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 (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
   attach <peer> [runtime]                                        ensure-live + resume, then tmux attach
   interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
@@ -543,6 +554,29 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(`deployed runtime "${d.runtime}" (${d.peers.length} peer(s))\n`)
         return d.peers.some(p => p.bootstrap === 'failed' || p.selfConfig === 'failed') ? 1 : 0
       }
+      case 'update-runtime': {
+        // §(г) runtime-package update: version-gate (npm vs the manifest stamp) →
+        // forced re-npx → idempotent re-provision (same path as install-runtime) →
+        // restart the runtime's peers via the regular stop/start. The core's own
+        // `update` stays foundation-only — this is the runtimes' counterpart.
+        const all = flags.all === true
+        if (!all && !positionals[0]) return usage(errOut)
+        const { updateRuntime, updateAllRuntimes } = await import('../runtime/update.ts')
+        const results = all
+          ? await updateAllRuntimes({ force: flags.force === true, env, warn: m => errOut(`warn: ${m}\n`) })
+          : [await updateRuntime({ runtime: positionals[0] as Runtime, force: flags.force === true, env, warn: m => errOut(`warn: ${m}\n`) })]
+        let failed = false
+        for (const r of results) {
+          const ver = r.from || r.to ? ` ${r.from ?? '?'} → ${r.to ?? '?'}` : ''
+          out(`${r.runtime}: ${r.state}${ver}${r.detail ? ` — ${r.detail}` : ''}\n`)
+          for (const p of r.peers) out(`  re-provisioned ${p.personality}: self-config ${p.selfConfig ?? 'n/a'}\n`)
+          for (const p of r.restarted) out(`  restart ${p.personality}: ${p.state}${p.detail ? ` — ${p.detail}` : ''}\n`)
+          if (r.state === 'install-failed' || r.state === 'deploy-failed' || r.state === 'npm-unreachable') failed = true
+          if (r.restarted.some(p => p.state === 'failed')) failed = true
+          if (!all && r.state === 'not-installed') failed = true
+        }
+        return failed ? 1 : 0
+      }
       case 'init': {
         // cwd-DEPENDENT: onboard the CURRENT folder (or positional cwd) as a peer —
         // identity + MCP wiring + doctrine, runtime resolved from the cwd's markers
@@ -830,6 +864,36 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(`${verb} → ${r.value.controlled.personality} (${r.value.controlled.runtime})\n`)
         return 0
       }
+      case 'connect': {
+        // Per-peer channel attachment in ONE flow (design «Onboard костяка» §(в)):
+        // `connect telegram <peer> [--token <t>]`. The human owes only the token;
+        // alias/bot-add/interface/router-restart are resolved by the system. The
+        // FIRST message from the human to the bot activates the chat (platform rule).
+        if (positionals[0] !== 'telegram' || !positionals[1]) return usage(errOut)
+        const { connectTelegram } = await import('../connect/index.ts')
+        const r = await connectTelegram({
+          peer: positionals[1],
+          token: typeof flags.token === 'string' ? flags.token : undefined,
+          env,
+        })
+        if (r.state === 'noop-same-token') {
+          out(`connect telegram ${r.peer}: ${r.detail}\n`)
+          return 0
+        }
+        if (r.state !== 'connected') {
+          errOut(`connect telegram ${r.peer}: ${r.state}${r.detail ? ` — ${r.detail}` : ''}\n`)
+          return 1
+        }
+        const rs = r.restart!
+        out(`bot ${r.username ?? `for "${r.peer}"`} added + interfaced to "${r.peer}"\n`)
+        out(
+          rs.state === 'restarted'
+            ? `router restarted — credentials loaded\n`
+            : `router restart ${rs.state}${rs.detail ? ` — ${rs.detail}` : ''} (the channel stays dead until the router restarts)\n`,
+        )
+        out(`activation: send the bot ${r.username ?? '(see @BotFather)'} its FIRST message — Telegram does not let a bot start the chat\n`)
+        return rs.state === 'restarted' ? 0 : 1
+      }
       case 'enable': {
         // Per-peer capability install (contract Установка §3): install <plugin>@agfpd
         // per-runtime (claude project-scope IN the peer cwd / codex global) + enable +

package/src/connect/connect.test.ts

@@ -0,0 +1,144 @@
+// connect telegram — the one-flow channel attachment (design §(в)). Sandboxed:
+// IAPEER_ROOT temp dirs, injected telegram-runtime runner + router restart. The
+// runner stub mimics the package: `bot add` writes bots/<alias>/.env (stable ABI).
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { dirname } from 'path'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { botEnvPath, connectTelegram, type RestartOutcome, type TgRunner } from './index.ts'
+import { writeRuntimeManifest } from '../runtime/index.ts'
+import { upsertPeer } from '../registry/index.ts'
+
+const roots: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-connect-'))
+  roots.push(d)
+  return d
+}
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function envFor(root: string): NodeJS.ProcessEnv {
+  return {
+    IAPEER_ROOT: join(root, 'iapeer'),
+    IAPEER_LAUNCHAGENTS_DIR: join(root, 'LA'),
+    IAPEER_TEST_SANDBOX: '1',
+    HOME: root,
+  } as NodeJS.ProcessEnv
+}
+
+async function fixture(): Promise<{ env: NodeJS.ProcessEnv; calls: string[][]; runTg: TgRunner; restarts: string[] }> {
+  const env = envFor(mkTmp())
+  writeRuntimeManifest({ runtime: 'telegram', selfConfig: { command: '/stub/telegram-runtime', args: ['self-config'] } }, { env })
+  await upsertPeer({ personality: 'leo', runtime: 'claude', cwd: '/tmp/leo', intelligence: 'artificial' }, { env })
+  await upsertPeer({ personality: 'arthur', runtime: 'telegram', cwd: '/tmp/arthur', intelligence: 'natural' }, { env })
+  const calls: string[][] = []
+  const runTg: TgRunner = (args, e) => {
+    calls.push(args)
+    if (args[0] === 'bot' && args[1] === 'add') {
+      // the package's behavior: token → bots/<alias>/.env; prints the validated @username
+      const p = botEnvPath(args[2]!, e)
+      mkdirSync(dirname(p), { recursive: true })
+      writeFileSync(p, `TELEGRAM_BOT_TOKEN=${args[4]}\n`)
+      return { status: 0, stdout: 'bot added: @leo_test_bot\n', stderr: '' }
+    }
+    return { status: 0, stdout: '', stderr: '' }
+  }
+  const restarts: string[] = []
+  return { env, calls, runTg, restarts }
+}
+
+const okRestart =
+  (restarts: string[]) =>
+  (human: string): RestartOutcome => {
+    restarts.push(human)
+    return { state: 'restarted' }
+  }
+
+describe('connectTelegram (one flow: bot add → interface → restart → activation)', () => {
+  test('happy path: adds the bot, interfaces the peer, restarts the HUMAN router, surfaces @username', async () => {
+    const { env, calls, runTg, restarts } = await fixture()
+    const r = await connectTelegram({ peer: 'leo', token: 'T1:abc', env, runTg, restart: okRestart(restarts) })
+    expect(r.state).toBe('connected')
+    expect(r.username).toBe('@leo_test_bot')
+    expect(r.restart?.state).toBe('restarted')
+    expect(restarts).toEqual(['arthur']) // the router = the natural telegram peer, not leo
+    expect(calls[0]).toEqual(['bot', 'add', 'leo', '--token', 'T1:abc'])
+    expect(calls[1]).toEqual(['interface', 'bot', 'leo', '--peer', 'leo'])
+  })
+
+  test('IDEMPOTENT: the same token is a byte-stable no-op — router NOT restarted', async () => {
+    const { env, runTg, restarts } = await fixture()
+    expect((await connectTelegram({ peer: 'leo', token: 'T1:abc', env, runTg, restart: okRestart(restarts) })).state).toBe('connected')
+    const second = await connectTelegram({ peer: 'leo', token: 'T1:abc', env, runTg, restart: okRestart(restarts) })
+    expect(second.state).toBe('noop-same-token')
+    expect(restarts).toEqual(['arthur']) // exactly ONE restart — the first connect
+  })
+
+  test('a NEW token replaces and RESTARTS again (credentials load at start)', async () => {
+    const { env, runTg, restarts } = await fixture()
+    await connectTelegram({ peer: 'leo', token: 'T1:abc', env, runTg, restart: okRestart(restarts) })
+    const r = await connectTelegram({ peer: 'leo', token: 'T2:new', env, runTg, restart: okRestart(restarts) })
+    expect(r.state).toBe('connected')
+    expect(restarts).toEqual(['arthur', 'arthur'])
+  })
+
+  test('unregistered peer → refused BEFORE any bot add (interface precondition)', async () => {
+    const { env, calls, runTg } = await fixture()
+    const r = await connectTelegram({ peer: 'ghost', token: 'T', env, runTg })
+    expect(r.state).toBe('unregistered-peer')
+    expect(calls.length).toBe(0)
+  })
+
+  test('no telegram manifest → runtime-missing with the install recipe', async () => {
+    const env = envFor(mkTmp())
+    await upsertPeer({ personality: 'leo', runtime: 'claude', cwd: '/tmp/leo', intelligence: 'artificial' }, { env })
+    const r = await connectTelegram({ peer: 'leo', token: 'T', env })
+    expect(r.state).toBe('runtime-missing')
+    expect(r.detail).toContain('install-runtime telegram')
+  })
+
+  test('non-tty without --token → explicit refusal with the BotFather recipe', async () => {
+    const { env, runTg } = await fixture()
+    const r = await connectTelegram({ peer: 'leo', env, runTg, isTty: false })
+    expect(r.state).toBe('refused-no-token')
+    expect(r.detail).toContain('@BotFather')
+  })
+
+  test('tty prompt path: the asked token flows in; empty answer → refusal', async () => {
+    const { env, runTg, restarts } = await fixture()
+    const r = await connectTelegram({ peer: 'leo', env, runTg, isTty: true, ask: async () => 'T9:asked', restart: okRestart(restarts) })
+    expect(r.state).toBe('connected')
+    const r2 = await connectTelegram({ peer: 'leo', env, runTg, isTty: true, ask: async () => '' })
+    expect(r2.state).toBe('refused-no-token')
+  })
+
+  test('bot add failure (getMe refusal on a bad token) → bot-add-failed with the package detail', async () => {
+    const { env } = await fixture()
+    const failTg: TgRunner = args =>
+      args[0] === 'bot' ? { status: 1, stdout: '', stderr: 'getMe failed: 401 Unauthorized' } : { status: 0, stdout: '', stderr: '' }
+    const r = await connectTelegram({ peer: 'leo', token: 'bad', env, runTg: failTg })
+    expect(r.state).toBe('bot-add-failed')
+    expect(r.detail).toContain('401')
+  })
+
+  test('no natural telegram peer in the registry → connected but restart=no-router (loud)', async () => {
+    const env = envFor(mkTmp())
+    writeRuntimeManifest({ runtime: 'telegram', selfConfig: '/stub/telegram-runtime self-config' }, { env })
+    await upsertPeer({ personality: 'leo', runtime: 'claude', cwd: '/tmp/leo', intelligence: 'artificial' }, { env })
+    const runTg: TgRunner = (args, e) => {
+      if (args[0] === 'bot') {
+        const p = botEnvPath('leo', e)
+        mkdirSync(dirname(p), { recursive: true })
+        writeFileSync(p, 'TELEGRAM_BOT_TOKEN=T\n')
+      }
+      return { status: 0, stdout: '', stderr: '' }
+    }
+    const r = await connectTelegram({ peer: 'leo', token: 'T', env, runTg })
+    expect(r.state).toBe('connected')
+    expect(r.restart?.state).toBe('no-router')
+  })
+})

package/src/connect/index.ts

@@ -0,0 +1,212 @@
+// connect — per-peer channel attachment in ONE flow (design «Onboard костяка» §(в),
+// FINAL 10.06; flow facts confirmed by the telegram-runtime owner against v0.10.3).
+// Namespace: `iapeer connect <channel> <peer>` — extensible to future channels;
+// v1 implements `connect telegram <peer> [--token <t>]`.
+//
+// The human owes EXACTLY ONE external fact: the bot token (prompt walks them
+// through @BotFather → /newbot). Everything else the system resolves: the bot
+// alias (= the peer's personality), `telegram-runtime bot add` (owner adds getMe
+// validation — an invalid token fails THERE, early), `telegram-runtime interface
+// bot` (profile merge; precondition: the peer is registered), then the MANDATORY
+// router-session restart (the live poller reads bots/ ONCE at start, no fs-watch —
+// without the restart the channel is dead both ways), and the activation hint:
+// the FIRST message from the human to the bot opens the chat (a Telegram platform
+// rule — a bot cannot initiate; outbound into an unopened chat is 403).
+//
+// IDEMPOTENT: the same token is a byte-stable no-op (bots/<alias>/.env unchanged →
+// no restart needed); a NEW token replaces with an explicit message AND restarts
+// (credentials load at start).
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import { normalizeIntelligenceValue } from '../core/constants.ts'
+import { runtimeRoot } from '../storage/index.ts'
+import { findPeer, readPeersIndex } from '../registry/index.ts'
+import { readRuntimeManifest } from '../runtime/index.ts'
+
+export interface TgRunResult {
+  status: number | null
+  stdout: string
+  stderr: string
+}
+export type TgRunner = (args: string[], env: NodeJS.ProcessEnv) => TgRunResult
+
+export interface RestartOutcome {
+  state: 'restarted' | 'refused-foreign-launchd' | 'failed' | 'no-router'
+  detail?: string
+}
+export type RestartFn = (humanPeer: string, env: NodeJS.ProcessEnv) => RestartOutcome
+
+export interface ConnectTelegramOptions {
+  peer: string
+  /** --token; absent → tty prompt (BotFather recipe) / non-tty refusal. */
+  token?: string
+  env?: NodeJS.ProcessEnv
+  /** Injectable prompt (tests). Default: readline on the live tty. */
+  ask?: (question: string) => Promise<string>
+  /** Override tty detection (tests). */
+  isTty?: boolean
+  /** Injectable telegram-runtime invoker (tests). Default: spawn the manifest's bin. */
+  runTg?: TgRunner
+  /** Injectable router restart (tests). Default: stopPeer→startPeer strictly in order. */
+  restart?: RestartFn
+}
+
+export interface ConnectTelegramResult {
+  state:
+    | 'connected' // bot added + interfaced + router restarted — channel live after activation
+    | 'noop-same-token' // byte-stable .env → nothing changed, no restart
+    | 'refused-no-token' // non-tty and no --token (or an empty tty answer)
+    | 'unregistered-peer' // precondition: the peer must be in the registry
+    | 'runtime-missing' // no telegram runtime manifest — install it first
+    | 'bot-add-failed' // telegram-runtime bot add exited non-zero (incl. getMe refusal)
+    | 'interface-failed' // telegram-runtime interface bot exited non-zero
+  peer: string
+  /** Bot @username when `bot add` surfaced one (owner obligation) — best-effort. */
+  username?: string
+  restart?: RestartOutcome
+  detail?: string
+}
+
+async function ttyAsk(question: string): Promise<string> {
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await rl.question(question)).trim()
+  } finally {
+    rl.close()
+  }
+}
+
+/** bots/<alias>/.env under the telegram runtime scope (stable ABI — owner's fact). */
+export function botEnvPath(alias: string, env: NodeJS.ProcessEnv): string {
+  return join(runtimeRoot('telegram', { env }), 'bots', alias, '.env')
+}
+
+function readBotEnv(alias: string, env: NodeJS.ProcessEnv): string | null {
+  try {
+    const p = botEnvPath(alias, env)
+    return existsSync(p) ? readFileSync(p, 'utf8') : null
+  } catch {
+    return null
+  }
+}
+
+/** Resolve the telegram-runtime CLI bin from the manifest's selfConfig command (the
+ *  package's own absolute bin — PATH-independent, launchd-safe). */
+function resolveTgBin(env: NodeJS.ProcessEnv): string | null {
+  const manifest = readRuntimeManifest('telegram', { env })
+  if (!manifest) return null
+  const sc = manifest.selfConfig
+  if (typeof sc === 'string' && sc.trim()) return sc.trim().split(/\s+/)[0]!
+  if (sc && typeof sc === 'object' && sc.command) return sc.command
+  return 'telegram-runtime' // manifest present but no hook — fall back to PATH
+}
+
+const defaultRunTg =
+  (bin: string): TgRunner =>
+  (args, env) => {
+    const r = spawnSync(bin, args, { encoding: 'utf8', env: env as Record<string, string> })
+    return { status: r.error ? null : r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? (r.error?.message ?? '') }
+  }
+
+/** The default router restart: stop→start of the human peer's telegram runtime,
+ *  STRICTLY sequential (the per-bot runtime.lock with live-pid detection refuses a
+ *  parallel process — a feature). Deferred import: connect → cli would otherwise be
+ *  a static cycle (cli imports connect). */
+async function defaultRestart(humanPeer: string, env: NodeJS.ProcessEnv): Promise<RestartOutcome> {
+  const { stopPeer, startPeer } = await import('../cli/index.ts')
+  try {
+    const stops = stopPeer(humanPeer, 'telegram', { env })
+    if (stops.some(o => o.action === 'refused-foreign-launchd')) {
+      return {
+        state: 'refused-foreign-launchd',
+        detail: `router "${humanPeer}" is persistent-peer-managed (H4 read-only) — restart it yourself to load the new bot`,
+      }
+    }
+    const starts = startPeer(humanPeer, 'telegram', { env })
+    const bad = starts.find(o => o.reason && o.action === 'bootstrap')
+    return bad ? { state: 'failed', detail: bad.reason } : { state: 'restarted' }
+  } catch (e) {
+    return { state: 'failed', detail: e instanceof Error ? e.message : String(e) }
+  }
+}
+
+/** The registry's natural peer — the router-session owner (ONE poller serves all
+ *  bots; it runs under the human peer's telegram runtime). */
+function findRouterHuman(env: NodeJS.ProcessEnv): string | null {
+  try {
+    const naturals = readPeersIndex({ env }).peers.filter(
+      p => normalizeIntelligenceValue(p.intelligence) === 'natural' && (p.runtime === 'telegram' || p.runtimes.includes('telegram')),
+    )
+    return naturals[0]?.personality ?? null
+  } catch {
+    return null
+  }
+}
+
+export async function connectTelegram(opts: ConnectTelegramOptions): Promise<ConnectTelegramResult> {
+  const env = opts.env ?? process.env
+  const peer = opts.peer.trim()
+
+  // Precondition (owner's fact): `interface bot` merges into the peer's profile —
+  // the peer must exist in the registry first.
+  if (!findPeer(readPeersIndex({ env }), peer)) {
+    return { state: 'unregistered-peer', peer, detail: `peer "${peer}" is not registered — create it first (iapeer create ${peer})` }
+  }
+
+  const tgBin = resolveTgBin(env)
+  if (!tgBin) {
+    return { state: 'runtime-missing', peer, detail: 'telegram runtime is not installed — run: iapeer install-runtime telegram' }
+  }
+
+  // The ONE human-owed fact: the bot token.
+  let token = opts.token?.trim()
+  if (!token) {
+    const tty = opts.isTty ?? (process.stdin.isTTY === true && process.stdout.isTTY === true)
+    if (!tty) {
+      return { state: 'refused-no-token', peer, detail: 'no tty and no --token — re-run with --token <bot-token> (create one: @BotFather → /newbot)' }
+    }
+    const ask = opts.ask ?? ttyAsk
+    token = (await ask(`bot token for "${peer}" (create: message @BotFather → /newbot → copy the token): `)).trim()
+    if (!token) return { state: 'refused-no-token', peer, detail: 'no answer — nothing connected' }
+  }
+
+  const runTg = opts.runTg ?? defaultRunTg(tgBin)
+  const alias = peer // bot alias = the peer's personality (design §(в); passes the owner's NAME_RE)
+  const before = readBotEnv(alias, env)
+
+  // (1) bot add — token → bots/<alias>/.env. Owner adds getMe validation here: an
+  // invalid token fails EARLY with the platform's reason; we surface it verbatim.
+  const add = runTg(['bot', 'add', alias, '--token', token], env)
+  if (add.status !== 0) {
+    return { state: 'bot-add-failed', peer, detail: (add.stderr || add.stdout || `exit ${add.status}`).trim() }
+  }
+  const username = add.stdout.match(/@[A-Za-z0-9_]{3,}/)?.[0]
+
+  // (2) interface bot — merge the channel binding into the peer's profile.
+  const iface = runTg(['interface', 'bot', alias, '--peer', peer], env)
+  if (iface.status !== 0) {
+    return { state: 'interface-failed', peer, username, detail: (iface.stderr || iface.stdout || `exit ${iface.status}`).trim() }
+  }
+
+  // (3) Idempotency gate: the SAME token leaves bots/<alias>/.env byte-stable →
+  // the live poller already loaded these credentials → NO restart, clean no-op.
+  const after = readBotEnv(alias, env)
+  if (before !== null && after === before) {
+    return { state: 'noop-same-token', peer, username, detail: 'same token — byte-stable no-op, router not restarted' }
+  }
+
+  // (4) MANDATORY router restart (new/changed credentials load only at start).
+  // Cost: a seconds-long delivery blip for the whole fleet; inbound is NOT lost
+  // (long-polling offset, Telegram holds up to 24 h) — known, accepted (design).
+  const human = findRouterHuman(env)
+  const restart: RestartOutcome = human
+    ? opts.restart
+      ? opts.restart(human, env)
+      : await defaultRestart(human, env)
+    : { state: 'no-router', detail: 'no natural telegram peer in the registry — start the router manually after onboarding the human' }
+
+  return { state: 'connected', peer, username, restart }
+}

package/src/lifecycle/index.ts

@@ -148,7 +148,10 @@ function writeSessionState(cfg: LifecycleConfig, state: SessionState): void {
   }
 }
 
-function removeSessionState(cfg: LifecycleConfig, identity: string): void {
+/** Drop the supervise session-state. Exported for the STOP verb: a deliberate stop
+ *  removes the state with the session so superviseTick never tags the kill as a
+ *  death (no crash-loop entry, no reaped-gone death class). */
+export function removeSessionState(cfg: LifecycleConfig, identity: string): void {
   try {
     rmSync(sessionStatePath(cfg, identity), { force: true })
   } catch {
@@ -198,10 +201,12 @@ export function clearStopped(cfg: LifecycleConfig, identity: string): void {
 // Lifecycle markers — the DAEMON decides fresh-vs-resume by the DEATH CAUSE it
 // tracks itself (TARGET redesign). Plain files in state/lifecycle/<identity>.* :
 //
-//   .idle-reaped : written ONLY when the daemon idle-reaps the session (the only
-//     death the daemon initiates). Presence on the next wake = session was parked
-//     cleanly = RESUME-eligible. ABSENT on a dead session = it died on its own
-//     (crash / self-close) = FRESH. (resolver branch 3.)
+//   .idle-reaped : the CLEAN-PARK marker — written when the daemon idle-reaps the
+//     session AND by the deliberate `stop` verb (both are daemon/operator-initiated
+//     parks, not faults; boris 10.06: stop→start must survive ≥ idle-reap).
+//     Presence on the next wake = session was parked cleanly = RESUME-eligible.
+//     ABSENT on a dead session = it died on its own (crash / self-close) = FRESH.
+//     (resolver branch 3.)
 //   .new-eager   : set when /new is invoked (owner reset, via `iapeer self-fresh`).
 //     Presence on a dead session = the daemon EAGERLY relaunches FRESH (does NOT
 //     wait for a message) and injects initial_prompt. Consumed on the relaunch.
@@ -230,7 +235,9 @@ export function hasIdleReaped(cfg: LifecycleConfig, identity: string): boolean {
   return existsSync(idleReapedPath(cfg, identity))
 }
 
-/** Write the idle-reaped marker — ONLY the idle-reap path in superviseTick does this. */
+/** Write the clean-park marker. Three writers, all deliberate parks: the idle-reap
+ *  path in superviseTick, the `stop` verb (park before kill), and superviseTick's
+ *  stopped-catch-up branch (a stop that raced the tick). Never a crash path. */
 export function setIdleReaped(cfg: LifecycleConfig, identity: string): void {
   mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
   writeFileSync(idleReapedPath(cfg, identity), `${new Date().toISOString()}\n`, { mode: 0o600 })
@@ -462,8 +469,15 @@ export function resolveWakeMode(
     clearIdleReaped(cfg, identity)
     return { resume: false, cause: 'ephemeral-policy' }
   }
-  // 3a. NOT idle-reaped → it died on its own (crash / self-close) → clean FRESH.
-  if (!hasIdleReaped(cfg, identity)) return { resume: false, cause: 'crash-or-self-close' }
+  // 3a. NOT parked-clean → FRESH either way, but tell the two cases apart in the
+  // cause (boris finding, 10.06): a peer with NO transcript at all never ran here —
+  // that is its FIRST-ever wake, not a crash. (A peer whose transcripts were rotated
+  // away also reads first-wake — equally honest: there is nothing it could resume.)
+  if (!hasIdleReaped(cfg, identity)) {
+    return resolveResume(cwd).ok
+      ? { resume: false, cause: 'crash-or-self-close' }
+      : { resume: false, cause: 'first-wake' }
+  }
   // 3b. idle-reaped → resume-eligible. Consume the marker now (it has done its job).
   clearIdleReaped(cfg, identity)
   // human-conversational dialogue never auto-freshes; only an explicit /new resets it.
@@ -967,7 +981,7 @@ export function killSession(sock: string, identity: string): void {
 
 export interface SuperviseOutcome {
   identity: string
-  action: 'reaped-idle' | 'reaped-gone' | 'reaped-ephemeral' | 'skipped-launchd' | 'alive' | 'needs-eager-fresh'
+  action: 'reaped-idle' | 'reaped-gone' | 'reaped-ephemeral' | 'skipped-launchd' | 'skipped-stopped' | 'alive' | 'needs-eager-fresh'
   reason?: string
   /** For 'needs-eager-fresh': the peer to EAGERLY re-launch fresh (its session died
    *  carrying a .new-eager mark). The daemon timer drives the async relaunch.
@@ -1002,6 +1016,19 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
     }
     const sock = buildSocketPath(s.runtime, s.personality, cfg.sockDir)
     if (!sessionAlive(sock, s.identity)) {
+      // A DELIBERATE stop is not a death (boris 10.06): the stop verb parks clean
+      // (.stopped + .idle-reaped) and kills the session itself. Catch-up branch for
+      // a stop that raced this tick (or a pre-fix stop): drop the state quietly —
+      // no crash-loop entry, no death class — and ensure the clean-park marker so
+      // the post-`start` wake RESUMES (stop→start must survive ≥ idle-reap).
+      if (isStopped(cfg, s.identity)) {
+        removeSessionState(cfg, s.identity)
+        clearEphemeralArmed(cfg, s.identity)
+        setIdleReaped(cfg, s.identity) // idempotent with the stop verb's own park
+        out.push({ identity: s.identity, action: 'skipped-stopped', reason: 'deliberate stop — parked clean, resumes on start' })
+        trace({ identity: s.identity, action: 'skipped-stopped', outcome: 'resume-on-start' })
+        continue
+      }
       // A dead session: record a death for crash-loop accounting, then branch on the
       // .new-eager mark. This death was NOT daemon-initiated (the daemon only initiates
       // the idle-reap below) → it died on its own → do NOT write .idle-reaped here.

package/src/lifecycle/lifecycle.test.ts

@@ -218,6 +218,24 @@ describe('superviseTick H4 guard', () => {
     expect(existsSync(join(stateDir, `${id}.session`))).toBe(true)
   })
 
+  test('a STOPPED peer with a dead session → skipped-stopped: no death record, park marker ensured', () => {
+    // boris repro (10.06): `iapeer stop` → next tick used to tag reaped-gone
+    // death=server-dead + recordDeath → post-start wake came up FRESH. A deliberate
+    // stop is a clean park the daemon knows 100% — never a death.
+    const c = cfg()
+    const id = writeState('iapeer-supstopped')
+    setStopped(c, id)
+    const out = superviseTick(c, { env: env(), nowMs: Date.now() })
+    const o = out.find(x => x.identity === id)
+    expect(o?.action).toBe('skipped-stopped')
+    expect(existsSync(join(stateDir, `${id}.session`))).toBe(false) // state dropped quietly
+    expect(readDeaths(c, id).length).toBe(0) // NOT a death — crash-loop ring untouched
+    expect(hasIdleReaped(c, id)).toBe(true) // clean park → post-start wake resumes
+    const logged = readFileSync(join(c.eventLogDir, 'lifecycle.log'), 'utf8')
+    expect(logged).toContain(`identity=${id} action=skipped-stopped`)
+    expect(logged).not.toContain('death=') // no death class for a deliberate stop
+  })
+
   test('a no-plist peer with a dead session → reaped-gone, state removed', () => {
     const c = cfg()
     const id = writeState('iapeer-supgone') // no plist, no live tmux session
@@ -433,6 +451,19 @@ describe('resolveWakeMode (TARGET: death-cause + peer-type/topic)', () => {
     expect(resolveWakeMode(cfg(), 'claude-p', cwd(), undefined, hasTranscript)).toEqual({ resume: false, cause: 'crash-or-self-close' })
   })
 
+  test('DEFAULT + NOT idle-reaped + NO transcript at all → FRESH with cause=first-wake (not a crash)', () => {
+    // boris finding (10.06): the first-ever wake of a freshly created peer used to
+    // read crash-or-self-close — a mis-classification. No transcript = never ran.
+    expect(resolveWakeMode(cfg(), 'claude-p', cwd(), undefined, noTranscript)).toEqual({ resume: false, cause: 'first-wake' })
+  })
+
+  // ── stop→start is a CLEAN PARK (boris 10.06): the park marker → RESUME ────────
+  test('stop→start path: clean-park marker set by stop → the next default wake RESUMES', () => {
+    const c = cfg()
+    setIdleReaped(c, 'claude-p') // what the stop verb writes before killing
+    expect(resolveWakeMode(c, 'claude-p', cwd(false), undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1', cause: 'idle-reaped-resume' })
+  })
+
   // ── branch 3b: default + idle-reaped → resume-eligible, CONSUME the marker ───
   test('DEFAULT + idle-reaped + human-conversational (interfaces.telegram) → RESUME, marker consumed', () => {
     const c = cfg()

package/src/onboard/index.ts

@@ -64,8 +64,12 @@ function isExecutable(binOrName: string): boolean {
       return false
     }
   }
-  // bare name → resolved by spawnSync against PATH; probe with `which`-free spawn
-  const r = spawnSync(binOrName, ['--version'], { stdio: 'ignore' })
+  // bare name → resolved by spawnSync against PATH; probe with `which`-free spawn.
+  // HARD TIMEOUT (live find 10.06): `codex --version` HANGS FOREVER in a non-tty
+  // environment (three stray probes sat 25+ min; an onboard --dry-run piped to a
+  // file never printed a byte). A hung probe must degrade to 'runtime-missing',
+  // not wedge the whole onboard.
+  const r = spawnSync(binOrName, ['--version'], { stdio: 'ignore', timeout: 10_000 })
   return r.error === undefined && r.status !== null
 }
 

package/src/runtime/index.ts

@@ -51,6 +51,10 @@ export interface RuntimePeerDecl {
 export interface RuntimeManifest {
   /** The runtime id this manifest describes (must match the folder it lives in). */
   runtime: Runtime
+  /** OPTIONAL installed package version (the owners' self-install stamp — the
+   *  telegram owner's 10.06 obligation). `update-runtime` version-gates on it;
+   *  absent → no gate, the update re-installs idempotently. */
+  version?: string
   /** OPTIONAL per-peer self-config hook (the shared contract both modes call). */
   selfConfig?: SelfConfigDescriptor
   /** OPTIONAL fixed peer-set (mode a). Omitted by an operator-add runtime (mode b). */
@@ -108,7 +112,8 @@ function normalizeManifest(raw: unknown, runtime: Runtime): RuntimeManifest {
       ]
     })
   }
-  return { runtime: declaredRuntime, ...(selfConfig ? { selfConfig } : {}), ...(peers ? { peers } : {}) }
+  const version = typeof obj.version === 'string' && obj.version.trim() ? obj.version.trim() : undefined
+  return { runtime: declaredRuntime, ...(version ? { version } : {}), ...(selfConfig ? { selfConfig } : {}), ...(peers ? { peers } : {}) }
 }
 
 /** Read a runtime's manifest (~/.iapeer/runtimes/<runtime>/runtime.json), or null when

package/src/runtime/update.test.ts

@@ -0,0 +1,192 @@
+// update-runtime (§(г)) — version-gate / forced re-install / idempotent re-provision /
+// peer restart. Sandboxed (IAPEER_ROOT temp dirs, IAPEER_TEST_SANDBOX), injected
+// npx + npm-version + restart.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { updateAllRuntimes, updateRuntime, type RestartedPeer } from './update.ts'
+import { readRuntimeManifest, writeRuntimeManifest, type RuntimeManifest } from './index.ts'
+import { upsertPeer } from '../registry/index.ts'
+
+const roots: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-rtup-'))
+  roots.push(d)
+  return d
+}
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function envFor(root: string, path?: string): NodeJS.ProcessEnv {
+  return {
+    IAPEER_ROOT: join(root, 'iapeer'),
+    IAPEER_LAUNCHAGENTS_DIR: join(root, 'LA'),
+    IAPEER_TEST_SANDBOX: '1',
+    HOME: root,
+    ...(path ? { PATH: path } : {}),
+  } as NodeJS.ProcessEnv
+}
+
+function stubBins(): { dir: string; hook: string } {
+  const dir = mkTmp()
+  writeFileSync(join(dir, 'notifier-runtime'), '#!/bin/sh\nexec sleep 1\n', { mode: 0o755 })
+  const hook = join(dir, 'sc.sh')
+  writeFileSync(hook, '#!/bin/sh\nexit 0\n', { mode: 0o755 })
+  return { dir, hook }
+}
+
+const restartOk =
+  (log: string[]) =>
+  (personality: string): RestartedPeer => {
+    log.push(personality)
+    return { personality, state: 'restarted' }
+  }
+
+describe('updateRuntime (§(г): gate → re-install → re-provision → restart)', () => {
+  test('full update: re-npx forced, declared set re-provisioned, peers restarted', async () => {
+    const root = mkTmp()
+    const { dir, hook } = stubBins()
+    const env = envFor(root, dir)
+    writeRuntimeManifest(
+      { runtime: 'notifier', version: '0.1.0', selfConfig: hook, peers: [{ personality: 'timer', intelligence: 'absent' }] },
+      { env },
+    )
+    // the live-host layout: the declared peer already sits in its DEFAULT location
+    // (re-provision must be a no-clobber pass over it, not an identity conflict)
+    await upsertPeer(
+      { personality: 'timer', runtime: 'notifier', cwd: join(root, 'iapeer', 'peers', 'timer'), intelligence: 'absent' },
+      { env },
+    )
+    let npxRan = false
+    const restarts: string[] = []
+    const r = await updateRuntime({
+      runtime: 'notifier',
+      env,
+      runNpx: (_pkg, e) => {
+        npxRan = true
+        // the package self-deploys the NEW manifest with the new version stamp
+        const m: RuntimeManifest = { runtime: 'notifier', version: '0.2.0', selfConfig: hook, peers: [{ personality: 'timer', intelligence: 'absent' }] }
+        writeRuntimeManifest(m, { env: e })
+        return { ok: true }
+      },
+      npmVersion: () => '0.2.0',
+      restartPeer: restartOk(restarts),
+    })
+    expect(r.state).toBe('updated')
+    expect(npxRan).toBe(true) // FORCED re-npx despite the present manifest
+    expect(r.from).toBe('0.1.0')
+    expect(r.to).toBe('0.2.0')
+    expect(r.peers.map(p => p.personality)).toEqual(['timer']) // re-provisioned
+    expect(restarts).toEqual(['timer']) // restarted via the injected stop/start
+    expect(readRuntimeManifest('notifier', { env })?.version).toBe('0.2.0')
+  })
+
+  test('version-gate: manifest stamp equals npm latest → already-latest, NOTHING runs', async () => {
+    const env = envFor(mkTmp())
+    writeRuntimeManifest({ runtime: 'notifier', version: '0.2.0' }, { env })
+    let npxRan = false
+    const r = await updateRuntime({ runtime: 'notifier', env, runNpx: () => ((npxRan = true), { ok: true }), npmVersion: () => '0.2.0' })
+    expect(r.state).toBe('already-latest')
+    expect(npxRan).toBe(false)
+  })
+
+  test('--force overrides the gate', async () => {
+    const root = mkTmp()
+    const { dir, hook } = stubBins()
+    const env = envFor(root, dir)
+    writeRuntimeManifest({ runtime: 'notifier', version: '0.2.0', selfConfig: hook }, { env })
+    let npxRan = false
+    const r = await updateRuntime({
+      runtime: 'notifier',
+      env,
+      force: true,
+      runNpx: () => ((npxRan = true), { ok: true }),
+      npmVersion: () => '0.2.0',
+      restartPeer: restartOk([]),
+    })
+    expect(r.state).toBe('updated')
+    expect(npxRan).toBe(true)
+  })
+
+  test('no version stamp → gate skipped, idempotent re-install with an honest detail', async () => {
+    const root = mkTmp()
+    const { dir, hook } = stubBins()
+    const env = envFor(root, dir)
+    writeRuntimeManifest({ runtime: 'notifier', selfConfig: hook }, { env }) // owners have not stamped yet
+    const r = await updateRuntime({
+      runtime: 'notifier',
+      env,
+      runNpx: () => ({ ok: true }),
+      npmVersion: () => '0.2.0',
+      restartPeer: restartOk([]),
+    })
+    expect(r.state).toBe('updated')
+    expect(r.detail).toContain('no version stamp')
+  })
+
+  test('not installed → not-installed with the install-runtime recipe; npm unreachable → loud', async () => {
+    const env = envFor(mkTmp())
+    const r = await updateRuntime({ runtime: 'notifier', env, npmVersion: () => '0.2.0' })
+    expect(r.state).toBe('not-installed')
+    expect(r.detail).toContain('install-runtime notifier')
+    writeRuntimeManifest({ runtime: 'notifier', version: '0.1.0' }, { env })
+    const r2 = await updateRuntime({ runtime: 'notifier', env, npmVersion: () => null })
+    expect(r2.state).toBe('npm-unreachable')
+  })
+
+  test('failed re-npx → install-failed, no deploy, no restarts', async () => {
+    const env = envFor(mkTmp())
+    writeRuntimeManifest({ runtime: 'notifier', version: '0.1.0' }, { env })
+    const restarts: string[] = []
+    const r = await updateRuntime({
+      runtime: 'notifier',
+      env,
+      runNpx: () => ({ ok: false, detail: 'network down' }),
+      npmVersion: () => '0.2.0',
+      restartPeer: restartOk(restarts),
+    })
+    expect(r.state).toBe('install-failed')
+    expect(restarts).toEqual([])
+  })
+
+  test('mode-b runtime (telegram, no declared peers): empty re-provision, registered router restarted', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    writeRuntimeManifest({ runtime: 'telegram', version: '0.10.0' }, { env })
+    await upsertPeer({ personality: 'arthur', runtime: 'telegram', cwd: '/tmp/arthur', intelligence: 'natural' }, { env })
+    const restarts: string[] = []
+    const r = await updateRuntime({
+      runtime: 'telegram',
+      env,
+      runNpx: (_pkg, e) => {
+        writeRuntimeManifest({ runtime: 'telegram', version: '0.10.3' }, { env: e })
+        return { ok: true }
+      },
+      npmVersion: () => '0.10.3',
+      restartPeer: restartOk(restarts),
+    })
+    expect(r.state).toBe('updated')
+    expect(r.peers).toEqual([]) // operator-add runtime: nothing declared to re-provision
+    expect(restarts).toEqual(['arthur']) // the router still restarts onto the new code
+  })
+})
+
+describe('updateAllRuntimes (--all)', () => {
+  test('updates installed runtimes, reports the rest not-installed (never an error)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    writeRuntimeManifest({ runtime: 'telegram', version: '1.0.0' }, { env })
+    const results = await updateAllRuntimes({
+      env,
+      runNpx: () => ({ ok: true }),
+      npmVersion: () => '1.0.0',
+      restartPeer: restartOk([]),
+    })
+    const byRt = Object.fromEntries(results.map(r => [r.runtime, r.state]))
+    expect(byRt.telegram).toBe('already-latest')
+    expect(byRt.notifier).toBe('not-installed')
+  })
+})

package/src/runtime/update.ts

@@ -0,0 +1,185 @@
+// update-runtime — the runtime-package update story (design «Onboard костяка» §(г),
+// FINAL 10.06; owner facts: NO state migrations on either package — notifier is
+// stateless-by-design (registrations live durable in the OWNING peers' profiles),
+// telegram's bots/.env is a stable ABI, its lock is transient self-healing).
+//
+//   version-gate (npm) → re-install the package → IDEMPOTENT re-provision through
+//   the SAME path install-runtime uses (npx self-deploy + declared-set deploy:
+//   PEER_BLURB registry sync, re-self-config, manifest refresh; live peers are
+//   never clobbered — the notifier owner's point: without the re-provision a
+//   version with a new blurb/self-doc leaves stale descriptions) → restart the
+//   runtime's infra peers via the REGULAR stop/start verbs.
+//
+// The core's own `iapeer update` deliberately does NOT touch runtimes (foundation-
+// only — the standing contract; the symmetry is conscious).
+//
+// Version-gate honesty: the installed version comes from the manifest's `version`
+// stamp (the owners' self-install obligation, telegram 10.06). A manifest WITHOUT
+// the stamp cannot be gated — the update proceeds idempotently and says so.
+
+import { spawnSync } from 'child_process'
+import { type Runtime } from '../core/constants.ts'
+import { readPeersIndex } from '../registry/index.ts'
+import { readRuntimeManifest } from './index.ts'
+import {
+  deployRuntime,
+  installRuntimePackage,
+  resolveRuntimePackage,
+  RUNTIME_PACKAGES,
+  type DeployedPeer,
+  type NpxRunner,
+} from './deploy.ts'
+
+/** Injectable npm-version resolver (tests). Default: `npm view <pkg> version`. */
+export type NpmVersionFn = (pkg: string, env: NodeJS.ProcessEnv) => string | null
+
+const defaultNpmVersion: NpmVersionFn = (pkg, env) => {
+  const r = spawnSync('npm', ['view', pkg, 'version'], { encoding: 'utf8', env: env as Record<string, string>, timeout: 60_000 })
+  const v = (r.stdout ?? '').trim()
+  return r.status === 0 && v ? v : null
+}
+
+export interface RestartedPeer {
+  personality: string
+  state: 'restarted' | 'refused-foreign-launchd' | 'failed'
+  detail?: string
+}
+
+export interface UpdateRuntimeResult {
+  runtime: Runtime
+  package?: string
+  state:
+    | 'updated' // re-installed + re-provisioned + peers restarted
+    | 'already-latest' // version-gate: the manifest stamp equals npm latest
+    | 'not-installed' // no manifest — nothing to update (install-runtime first)
+    | 'npm-unreachable' // npm view failed — cannot resolve the target version
+    | 'install-failed' // the forced re-npx failed — nothing was touched further
+    | 'deploy-failed' // re-provision broke (per-peer detail in `peers`)
+  from?: string
+  to?: string
+  peers: DeployedPeer[]
+  restarted: RestartedPeer[]
+  detail?: string
+}
+
+export interface UpdateRuntimeOptions {
+  runtime: Runtime
+  /** Re-install even when the version-gate says already-latest. */
+  force?: boolean
+  env?: NodeJS.ProcessEnv
+  runNpx?: NpxRunner
+  npmVersion?: NpmVersionFn
+  /** Injectable restart (tests). Default: the regular stop→start verbs, strictly
+   *  sequential per peer. */
+  restartPeer?: (personality: string, runtime: Runtime, env: NodeJS.ProcessEnv) => RestartedPeer
+  warn?: (message: string) => void
+}
+
+/** Default per-peer restart: the REGULAR stop→start verbs (infra → launchctl
+ *  bootout/bootstrap), strictly sequential. H4 stays intact: a PP-managed peer is
+ *  refused by the verbs themselves and reported, never forced. */
+async function defaultRestartPeer(personality: string, runtime: Runtime, env: NodeJS.ProcessEnv): Promise<RestartedPeer> {
+  const { stopPeer, startPeer } = await import('../cli/index.ts')
+  try {
+    const stops = stopPeer(personality, runtime, { env })
+    if (stops.some(o => o.action === 'refused-foreign-launchd')) {
+      return { personality, state: 'refused-foreign-launchd', detail: 'persistent-peer-managed (H4) — restart it yourself' }
+    }
+    const starts = startPeer(personality, runtime, { env })
+    const bad = starts.find(o => o.action === 'bootstrap' && o.reason)
+    return bad ? { personality, state: 'failed', detail: bad.reason } : { personality, state: 'restarted' }
+  } catch (e) {
+    return { personality, state: 'failed', detail: e instanceof Error ? e.message : String(e) }
+  }
+}
+
+export async function updateRuntime(opts: UpdateRuntimeOptions): Promise<UpdateRuntimeResult> {
+  const env = opts.env ?? process.env
+  const runtime = opts.runtime
+  const manifest = readRuntimeManifest(runtime, { env })
+  if (!manifest) {
+    return {
+      runtime,
+      state: 'not-installed',
+      peers: [],
+      restarted: [],
+      detail: `no manifest for "${runtime}" — install first: iapeer install-runtime ${runtime}`,
+    }
+  }
+  const pkg = resolveRuntimePackage(runtime)
+  if (!pkg) {
+    return { runtime, state: 'not-installed', peers: [], restarted: [], detail: `no package mapping for "${runtime}"` }
+  }
+
+  // Version-gate: npm latest vs the manifest stamp. No stamp → no gate (proceed
+  // idempotently — the owners' stamp obligation closes this once shipped).
+  const latest = (opts.npmVersion ?? defaultNpmVersion)(pkg, env)
+  if (!latest) {
+    return { runtime, package: pkg, state: 'npm-unreachable', peers: [], restarted: [], detail: `npm view ${pkg} version failed — cannot resolve the target` }
+  }
+  const installed = manifest.version
+  if (installed && installed === latest && !opts.force) {
+    return { runtime, package: pkg, state: 'already-latest', from: installed, to: latest, peers: [], restarted: [] }
+  }
+
+  // Re-install (forced npx — the package self-deploys its new bin + manifest).
+  const install = installRuntimePackage({ runtime, force: true, env, runNpx: opts.runNpx })
+  if (install.state !== 'ran') {
+    return { runtime, package: pkg, state: 'install-failed', from: installed, to: latest, peers: [], restarted: [], detail: install.detail ?? install.state }
+  }
+
+  // IDEMPOTENT re-provision via the SAME deploy path install-runtime uses: blurb
+  // sync, re-self-config, no-clobber on live peers. Mode-b (telegram) declares no
+  // peers — the deploy is an empty pass, by design.
+  let peers: DeployedPeer[]
+  try {
+    const d = await deployRuntime({ runtime, env, warn: opts.warn })
+    peers = d.peers
+  } catch (e) {
+    return { runtime, package: pkg, state: 'deploy-failed', from: installed, to: latest, peers: [], restarted: [], detail: e instanceof Error ? e.message : String(e) }
+  }
+  if (peers.some(p => p.selfConfig === 'failed' || p.bootstrap === 'failed')) {
+    return { runtime, package: pkg, state: 'deploy-failed', from: installed, to: latest, peers, restarted: [], detail: 'a declared peer failed re-provision — see the per-peer lines' }
+  }
+
+  // Restart THIS runtime's registered peers so the new baked code runs (notifier
+  // semantics per the owner: cron wall-clock unaffected, @every re-anchors,
+  // watcher children relaunch, heartbeat windows reset). Strictly sequential.
+  const registered = readPeersIndex({ env }).peers.filter(
+    p => p.runtime === runtime || p.runtimes.includes(runtime),
+  )
+  const restarted: RestartedPeer[] = []
+  for (const p of registered) {
+    restarted.push(
+      opts.restartPeer
+        ? opts.restartPeer(p.personality, runtime, env)
+        : await defaultRestartPeer(p.personality, runtime, env),
+    )
+  }
+
+  return {
+    runtime,
+    package: pkg,
+    state: 'updated',
+    from: installed,
+    to: latest,
+    peers,
+    restarted,
+    detail: installed ? undefined : 'no version stamp in the old manifest — gate skipped, re-installed idempotently',
+  }
+}
+
+/** `--all`: update every KNOWN runtime that is actually installed (manifest present);
+ *  the rest are reported as not-installed, never an error. */
+export async function updateAllRuntimes(opts: Omit<UpdateRuntimeOptions, 'runtime'> = {}): Promise<UpdateRuntimeResult[]> {
+  const env = opts.env ?? process.env
+  const out: UpdateRuntimeResult[] = []
+  for (const rt of Object.keys(RUNTIME_PACKAGES) as Runtime[]) {
+    if (!readRuntimeManifest(rt, { env })) {
+      out.push({ runtime: rt, state: 'not-installed', peers: [], restarted: [], detail: 'not installed — skipped' })
+      continue
+    }
+    out.push(await updateRuntime({ ...opts, runtime: rt }))
+  }
+  return out
+}