@agfpd/iapeer 0.1.0

package/src/registry/registry.test.ts

@@ -0,0 +1,400 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  findPeer,
+  readPeersIndex,
+  removePeer,
+  upsertPeer,
+  withPeersLock,
+  type PeerRecord,
+} from './index.ts'
+import { defaultIntelligenceForRuntime, type Intelligence } from '../core/constants.ts'
+import { writeFileAtomic, resolvePeersPaths } from '../storage/index.ts'
+
+let root: string
+const opts = () => ({ rootDir: root })
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'iapeer-registry-'))
+})
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true })
+})
+
+// The live arthur record (from ~/.iapeer/peers-profiles.json): a human peer
+// primarily on telegram, also present on claude, with a telegram interface.
+async function seedArthur(): Promise<void> {
+  await upsertPeer(
+    {
+      personality: 'arthur',
+      runtime: 'telegram',
+      runtimes: ['telegram', 'claude'],
+      description: 'Артур — владелец хоста и команды агентов.',
+      intelligence: 'natural',
+      interfaces: { telegram: { user_id: '409502965' } },
+      cwd: '/Users/macmini/Peers/arthur',
+    },
+    opts(),
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// WITNESS: the OLD upsertPeer record-builder (peers.ts:342-358, full-replace).
+// Pure reproduction so each H1 test shows a real delta — the witness produces
+// the clobbered record, the new upsertPeer preserves the existing fields.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function oldUpsertRecord(
+  args: {
+    personality: string
+    runtime: string
+    runtimes?: readonly string[]
+    description?: string
+    intelligence?: Intelligence
+    interfaces?: Record<string, unknown>
+    cwd: string
+  },
+): PeerRecord {
+  const runtime = args.runtime
+  const runtimes = [runtime, ...(args.runtimes ?? [])].filter((v, i, a) => a.indexOf(v) === i)
+  const description = args.description ?? '' // empty wipes existing
+  const intelligence =
+    args.intelligence !== undefined ? args.intelligence : defaultIntelligenceForRuntime(runtime) // default, not existing
+  return {
+    personality: args.personality,
+    runtime,
+    runtimes,
+    description,
+    intelligence,
+    cwd: args.cwd,
+    ...(args.interfaces ? { interfaces: args.interfaces } : {}),
+  }
+}
+
+// The claude-boot upsert (server.ts:266 path): no intelligence, empty
+// description, single runtime claude, no interfaces.
+const bootUpsertArgs = {
+  personality: 'arthur',
+  runtime: 'claude',
+  runtimes: ['claude'],
+  description: '',
+  cwd: '/Users/macmini/Peers/arthur',
+} as const
+
+// ─────────────────────────────────────────────────────────────────────────────
+// H1: merge-with-existing
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('upsertPeer H1 merge-with-existing', () => {
+  test('claude-boot upsert WITHOUT intelligence does NOT downgrade a natural peer', async () => {
+    await seedArthur()
+
+    // WITNESS (before fix): old builder overwrites with the claude default (artificial)
+    expect(oldUpsertRecord(bootUpsertArgs).intelligence).toBe('artificial')
+
+    // NEW (after fix): registry preserves natural
+    await upsertPeer(bootUpsertArgs, opts())
+    const arthur = findPeer(readPeersIndex(opts()), 'arthur')!
+    expect(arthur.intelligence).toBe('natural')
+  })
+
+  test('runtimes are unioned, not replaced (telegram not dropped on claude boot)', async () => {
+    await seedArthur()
+
+    // WITNESS: old builder drops telegram, leaving only claude
+    expect(oldUpsertRecord(bootUpsertArgs).runtimes).toEqual(['claude'])
+
+    // NEW: union → telegram + claude both present
+    await upsertPeer(bootUpsertArgs, opts())
+    const arthur = findPeer(readPeersIndex(opts()), 'arthur')!
+    expect(arthur.runtimes).toContain('telegram')
+    expect(arthur.runtimes).toContain('claude')
+  })
+
+  test('empty description does NOT wipe a meaningful existing description', async () => {
+    await seedArthur()
+
+    // WITNESS: old builder wipes it to ''
+    expect(oldUpsertRecord(bootUpsertArgs).description).toBe('')
+
+    // NEW: existing description preserved
+    await upsertPeer(bootUpsertArgs, opts())
+    const arthur = findPeer(readPeersIndex(opts()), 'arthur')!
+    expect(arthur.description).toBe('Артур — владелец хоста и команды агентов.')
+  })
+
+  test('interfaces preserved when absent from args', async () => {
+    await seedArthur()
+
+    // WITNESS: old builder drops interfaces (not in args)
+    expect(oldUpsertRecord(bootUpsertArgs).interfaces).toBeUndefined()
+
+    // NEW: telegram interface preserved
+    await upsertPeer(bootUpsertArgs, opts())
+    const arthur = findPeer(readPeersIndex(opts()), 'arthur')!
+    expect(arthur.interfaces).toEqual({ telegram: { user_id: '409502965' } })
+  })
+
+  test('explicit intelligence in args DOES override existing', async () => {
+    await seedArthur()
+    await upsertPeer({ ...bootUpsertArgs, intelligence: 'artificial' }, opts())
+    const arthur = findPeer(readPeersIndex(opts()), 'arthur')!
+    expect(arthur.intelligence).toBe('artificial')
+  })
+
+  test('explicit non-empty description in args DOES override', async () => {
+    await seedArthur()
+    await upsertPeer({ ...bootUpsertArgs, description: 'new desc' }, opts())
+    expect(findPeer(readPeersIndex(opts()), 'arthur')!.description).toBe('new desc')
+  })
+})
+
+// Regression — the audit's CRITICAL finding: the only production caller (provisionPeer
+// from `iapeer init`) forwards the READ-NORMALIZED contract value (profile.intelligence
+// = 'natural' for a legacy 'human' peer) as an explicit upsert intelligence. The write
+// boundary must treat that as a re-assertion of the SAME nature and keep the legacy raw
+// — NOT migrate the on-disk vocab the live legacy-IAP fleet reads.
+describe('upsertPeer vocab-preservation (registry self-defends the legacy raw)', () => {
+  const arthurCwd = '/Users/macmini/Peers/arthur'
+  async function seedLegacyHuman(): Promise<void> {
+    await upsertPeer({ personality: 'arthur', runtime: 'telegram', runtimes: ['telegram', 'claude'], intelligence: 'human' as never, cwd: arthurCwd }, opts())
+  }
+  test('seeding a legacy human value persists the raw verbatim; read normalizes', async () => {
+    await seedLegacyHuman()
+    const p = findPeer(readPeersIndex(opts()), 'arthur')!
+    expect(p.intelligence).toBe('natural') // READ-normalized contract value
+    expect(p.intelligenceRaw).toBe('human') // RAW on disk preserved
+  })
+  test('re-asserting the SAME nature (read-normalized natural) does NOT migrate human→natural', async () => {
+    await seedLegacyHuman()
+    // exactly what provisionPeer emits on a routine re-init (no explicit --intelligence):
+    await upsertPeer({ personality: 'arthur', runtime: 'telegram', intelligence: 'natural', cwd: arthurCwd }, opts())
+    expect(findPeer(readPeersIndex(opts()), 'arthur')!.intelligenceRaw).toBe('human') // STILL human
+  })
+  test('a GENUINE nature change DOES adopt the new value as the raw', async () => {
+    await seedLegacyHuman()
+    await upsertPeer({ personality: 'arthur', runtime: 'telegram', intelligence: 'artificial', cwd: arthurCwd }, opts())
+    expect(findPeer(readPeersIndex(opts()), 'arthur')!.intelligenceRaw).toBe('artificial')
+  })
+  test('legacy vocab accepted by the write path (read-path symmetry); garbage rejected', async () => {
+    await upsertPeer({ personality: 'srv', runtime: 'notifier', intelligence: 'scripted' as never, cwd: '/tmp/srv' }, opts())
+    const s = findPeer(readPeersIndex(opts()), 'srv')!
+    expect(s.intelligence).toBe('absent') // scripted → absent (normalized)
+    expect(s.intelligenceRaw).toBe('scripted') // raw preserved
+    await expect(upsertPeer({ personality: 'bad', runtime: 'claude', intelligence: 'sentient' as never, cwd: '/tmp/bad' }, opts())).rejects.toThrow(/artificial\|natural\|absent/)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// New peer: runtime default DOES apply when there is no existing
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('upsertPeer new peer (no existing) — defaults apply', () => {
+  test('new claude peer without intelligence → artificial (runtime default)', async () => {
+    await upsertPeer({ personality: 'fresh', runtime: 'claude', cwd: '/tmp/fresh' }, opts())
+    expect(findPeer(readPeersIndex(opts()), 'fresh')!.intelligence).toBe('artificial')
+  })
+
+  test('new telegram peer without intelligence → natural (runtime default)', async () => {
+    await upsertPeer({ personality: 'someone', runtime: 'telegram', cwd: '/tmp/someone' }, opts())
+    expect(findPeer(readPeersIndex(opts()), 'someone')!.intelligence).toBe('natural')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Concurrency: single locked writer — no lost update
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('registry locked writer — concurrent upsert does not clobber', () => {
+  test('two parallel upserts of the same personality both survive (runtimes union)', async () => {
+    await upsertPeer({ personality: 'p', runtime: 'claude', cwd: '/tmp/p' }, opts())
+
+    // Both add a distinct runtime concurrently. Under the lock each reads the
+    // other's write; an unlocked read-modify-write would lose one.
+    await Promise.all([
+      upsertPeer({ personality: 'p', runtime: 'claude', runtimes: ['codex'], cwd: '/tmp/p' }, opts()),
+      upsertPeer({ personality: 'p', runtime: 'claude', runtimes: ['telegram'], cwd: '/tmp/p' }, opts()),
+    ])
+
+    const p = findPeer(readPeersIndex(opts()), 'p')!
+    expect(p.runtimes).toContain('claude')
+    expect(p.runtimes).toContain('codex')
+    expect(p.runtimes).toContain('telegram')
+
+    // exactly one record for the personality (no duplicate / no clobber)
+    expect(readPeersIndex(opts()).peers.filter(x => x.personality === 'p')).toHaveLength(1)
+  })
+
+  test('many parallel upserts of distinct peers all land', async () => {
+    const names = Array.from({ length: 12 }, (_, i) => `peer-${i}`)
+    await Promise.all(
+      names.map(n => upsertPeer({ personality: n, runtime: 'claude', cwd: `/tmp/${n}` }, opts())),
+    )
+    const index = readPeersIndex(opts())
+    for (const n of names) expect(findPeer(index, n)).not.toBeNull()
+    expect(index.peers).toHaveLength(12)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Structural invariant #3: peers file is unreachable past the locked API
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('registry single-writer is structural (#3)', () => {
+  test('storage.writeFileAtomic REFUSES the peers-profiles.json path', () => {
+    const { peersFile } = resolvePeersPaths(opts())
+    expect(() => writeFileAtomic(peersFile, '{"version":2,"peers":[]}')).toThrow(/registry/)
+  })
+
+  test('after a refused bypass, the registry file written by upsert is intact JSON', async () => {
+    await seedArthur()
+    const { peersFile } = resolvePeersPaths(opts())
+    expect(() => writeFileAtomic(peersFile, 'CLOBBER')).toThrow()
+    const parsed = JSON.parse(readFileSync(peersFile, 'utf8'))
+    expect(parsed.version).toBe(2)
+    expect(parsed.peers[0].personality).toBe('arthur')
+  })
+
+  test('removePeer also goes through the locked writer', async () => {
+    await seedArthur()
+    await removePeer('arthur', opts())
+    expect(findPeer(readPeersIndex(opts()), 'arthur')).toBeNull()
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// VOCAB read-compat: legacy human/scripted on disk → contract natural/absent
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('registry read-compat (legacy intelligence vocab)', () => {
+  test('legacy registry file (human/scripted) reads as natural/absent, does not crash', () => {
+    const { peersFile } = resolvePeersPaths(opts())
+    // a legacy file as it exists on the live host today (pre-migration)
+    writeFileSync(
+      peersFile,
+      JSON.stringify({
+        version: 2,
+        peers: [
+          { personality: 'arthur', runtime: 'telegram', runtimes: ['telegram', 'claude'], description: 'Артур', intelligence: 'human', cwd: '/Users/macmini/Peers/arthur' },
+          { personality: 'cronjob', runtime: 'cron', runtimes: ['cron'], description: '', intelligence: 'scripted', cwd: '/tmp/cronjob' },
+          { personality: 'boris', runtime: 'claude', runtimes: ['claude'], description: 'b', intelligence: 'artificial', cwd: '/tmp/boris' },
+        ],
+      }),
+    )
+    const index = readPeersIndex(opts())
+    expect(findPeer(index, 'arthur')!.intelligence).toBe('natural') // human → natural
+    expect(findPeer(index, 'cronjob')!.intelligence).toBe('absent') // scripted → absent
+    expect(findPeer(index, 'boris')!.intelligence).toBe('artificial') // pass-through
+  })
+
+  test('genuinely unknown intelligence value still throws', () => {
+    const { peersFile } = resolvePeersPaths(opts())
+    writeFileSync(
+      peersFile,
+      JSON.stringify({
+        version: 2,
+        peers: [{ personality: 'x', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'bogus', cwd: '/tmp/x' }],
+      }),
+    )
+    expect(() => readPeersIndex(opts())).toThrow(/intelligence/)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fix A — GOLDEN round-trip: a registry write PRESERVES every peer's RAW vocab
+// verbatim (legacy-safe). The incident: removePeer rewrote the live registry,
+// persisting the IN-MEMORY normalization (arthur human→natural) → the legacy IAP
+// (human/artificial/scripted only) read "natural" as corrupted → fleet transport
+// down. The fix persists the raw on-disk vocab; normalization is in-memory only.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('Fix A — registry write preserves raw intelligence vocab (legacy-safe)', () => {
+  const seedFullVocab = () => {
+    const { peersFile } = resolvePeersPaths(opts())
+    writeFileSync(
+      peersFile,
+      JSON.stringify({
+        version: 2,
+        peers: [
+          { personality: 'phuman', runtime: 'telegram', runtimes: ['telegram'], description: '', intelligence: 'human', cwd: '/a' },
+          { personality: 'pscripted', runtime: 'notifier', runtimes: ['notifier'], description: '', intelligence: 'scripted', cwd: '/b' },
+          { personality: 'partificial', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'artificial', cwd: '/c' },
+          { personality: 'pnatural', runtime: 'telegram', runtimes: ['telegram'], description: '', intelligence: 'natural', cwd: '/d' },
+          { personality: 'pabsent', runtime: 'notifier', runtimes: ['notifier'], description: '', intelligence: 'absent', cwd: '/e' },
+        ],
+      }),
+    )
+  }
+  const onDiskVocab = () => {
+    const disk = JSON.parse(readFileSync(resolvePeersPaths(opts()).peersFile, 'utf8'))
+    return Object.fromEntries((disk.peers as { personality: string; intelligence: string }[]).map(p => [p.personality, p.intelligence]))
+  }
+
+  test('in-memory read NORMALIZES (human→natural, scripted→absent) for foundation logic', () => {
+    seedFullVocab()
+    const idx = readPeersIndex(opts())
+    expect(findPeer(idx, 'phuman')!.intelligence).toBe('natural')
+    expect(findPeer(idx, 'pscripted')!.intelligence).toBe('absent')
+    expect(findPeer(idx, 'partificial')!.intelligence).toBe('artificial')
+  })
+
+  test('GOLDEN: an upsert write preserves EVERY peer raw vocab (human→human, scripted→scripted, …)', async () => {
+    seedFullVocab()
+    await upsertPeer({ personality: 'trigger', runtime: 'claude', cwd: '/t', intelligence: 'artificial' }, opts())
+    const v = onDiskVocab()
+    expect(v.phuman).toBe('human') // NOT 'natural' — preserved
+    expect(v.pscripted).toBe('scripted') // NOT 'absent' — preserved
+    expect(v.partificial).toBe('artificial')
+    expect(v.pnatural).toBe('natural')
+    expect(v.pabsent).toBe('absent')
+    expect(v.trigger).toBe('artificial')
+    // the intelligenceRaw shadow field never leaks to disk
+    const disk = JSON.parse(readFileSync(resolvePeersPaths(opts()).peersFile, 'utf8'))
+    expect((disk.peers as Record<string, unknown>[]).every(p => p.intelligenceRaw === undefined)).toBe(true)
+  })
+
+  test('INCIDENT scenario: removePeer of one peer preserves the legacy vocab of the others', async () => {
+    seedFullVocab()
+    await removePeer('partificial', opts()) // the exact op that broke the live registry
+    const v = onDiskVocab()
+    expect(v.partificial).toBeUndefined() // removed
+    expect(v.phuman).toBe('human') // arthur-like human peer: vocab INTACT (the fix)
+    expect(v.pscripted).toBe('scripted')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Companion fix — test/sandbox isolation is FAIL-CLOSED. The incident root cause
+// (#1): a sandbox run resolved the registry to the REAL ~/.iapeer and rewrote it.
+// Under IAPEER_TEST_SANDBOX=1, withPeersLock REFUSES to write the HOME-default
+// root — a test/sandbox MUST divert via IAPEER_ROOT. (The whole `bun test` run is
+// marked via package.json, so every locked write during tests is guarded.)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('Companion fix — withPeersLock fail-closed sandbox isolation', () => {
+  test('THROWS when IAPEER_TEST_SANDBOX=1 and the root falls through to HOME/.iapeer', async () => {
+    // fake HOME, NO IAPEER_ROOT override → resolves to <fakeHome>/.iapeer (the
+    // "forgot to divert" case the incident hit). Guard fires BEFORE any FS write.
+    const fakeHome = mkdtempSync(join(tmpdir(), 'iapeer-guard-home-'))
+    const env = { HOME: fakeHome, IAPEER_TEST_SANDBOX: '1' } as NodeJS.ProcessEnv
+    await expect(withPeersLock({ env }, () => 'wrote')).rejects.toThrow(/refusing to write the REAL registry/i)
+    rmSync(fakeHome, { recursive: true, force: true })
+  })
+
+  test('ALLOWS the same run when IAPEER_ROOT diverts the root away from HOME/.iapeer', async () => {
+    const fakeHome = mkdtempSync(join(tmpdir(), 'iapeer-guard-home-'))
+    const env = { HOME: fakeHome, IAPEER_ROOT: join(fakeHome, 'sbx'), IAPEER_TEST_SANDBOX: '1' } as NodeJS.ProcessEnv
+    const out = await withPeersLock({ env }, () => 'ok')
+    expect(out).toBe('ok')
+    rmSync(fakeHome, { recursive: true, force: true })
+  })
+
+  test('NO guard when the sandbox flag is absent (rootDir-isolated tests are unaffected)', async () => {
+    // opts() = { rootDir: <mkdtemp> }, env defaults to process.env (no flag in the
+    // passed env object) → guard short-circuits, the normal locked write proceeds.
+    const out = await withPeersLock({ rootDir: root, env: {} as NodeJS.ProcessEnv }, () => 'ok')
+    expect(out).toBe('ok')
+  })
+})

package/src/runtime/deploy.ts

@@ -0,0 +1,230 @@
+// deployRuntime — the onboard INFRA-DEPLOY orchestration (contract Установка §2 /
+// Фаза §4). The foundation ORCHESTRATES; the package self-configures. This covers
+// provision MODE (a) "declared-set": read the runtime package's manifest and provision
+// the WHOLE declared peer-set (notifier → timer + watcher), each via `createPeer` —
+// so each peer gets profile + registry + plist (installAlwaysOnPlist + H4 guard) +
+// per-peer self-config hook + auto-bootstrap, uniformly.
+//
+// MODE (b) "operator-add" (telegram human) does NOT come through here — it is a direct
+// `iapeer create maria --runtime telegram`. Both modes share the SAME per-peer
+// self-config hook (invoked inside createPeer→initPeer); deployRuntime is just the
+// enumeration of the declared set. "1 always-on infra peer = 1 plist", idempotent
+// (re-deploy of an existing peer does not duplicate or clobber).
+//
+// The package's host-wide self-INSTALL (npx — puts the `<runtime>-runtime` bin on PATH
+// and writes the manifest) is the package's job (self-deploy). The foundation invokes
+// that installer (onboard delegates) and THEN calls deployRuntime; this module owns the
+// second half (read manifest → provision the declared set).
+
+import { spawnSync } from 'child_process'
+import { homedir } from 'os'
+import { type Runtime } from '../core/constants.ts'
+import { IapError } from '../core/errors.ts'
+import { createPeer, type CreatePeerResult } from '../create/index.ts'
+import { readRuntimeManifest, type RuntimeManifest, type RuntimePeerDecl } from './index.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Built-in runtime → npm package registry (§6, Артур 08.06): onboard AUTO-resolves
+// the package for a known infra runtime and `npx`-installs it (the package self-
+// deploys its bin + manifest). The operator overrides per-runtime with --package.
+// FROZEN map; a runtime absent here needs an explicit --package.
+// ─────────────────────────────────────────────────────────────────────────────
+export const RUNTIME_PACKAGES: Readonly<Record<string, string>> = {
+  telegram: '@agfpd/telegram-runtime',
+  notifier: '@agfpd/notifier-runtime',
+}
+
+/** Resolve the npm package for a runtime: explicit override wins, else the built-in
+ *  registry, else undefined (no mapping → caller must pass --package). */
+export function resolveRuntimePackage(runtime: Runtime, override?: string): string | undefined {
+  return override?.trim() || RUNTIME_PACKAGES[runtime]
+}
+
+export interface DeployRuntimeOptions {
+  runtime: Runtime
+  /** Override the on-disk manifest (tests / a package handing it in directly). */
+  manifest?: RuntimeManifest
+  /** Override the peer-set to provision (default: manifest.peers). */
+  peers?: RuntimePeerDecl[]
+  /** Auto-bootstrap each provisioned plist (default true; per-peer, infra). */
+  bootstrap?: boolean
+  env?: NodeJS.ProcessEnv
+  warn?: (message: string) => void
+}
+
+export interface DeployedPeer {
+  personality: string
+  location: string
+  /** self-config hook state for this peer (configured / failed / absent). */
+  selfConfig?: string
+  /** bootstrap state for this peer (loaded / already-loaded / skipped-sandbox / …). */
+  bootstrap?: string
+  result: CreatePeerResult
+}
+
+export interface DeployRuntimeResult {
+  runtime: Runtime
+  /** The peers provisioned (the declared set, or the explicit override). */
+  peers: DeployedPeer[]
+  /** True when the runtime declares no fixed set (mode b — operator-add only). */
+  operatorAddOnly: boolean
+}
+
+/**
+ * Deploy a runtime's DECLARED peer-set (mode a). Reads the package's manifest from
+ * ~/.iapeer/runtimes/<runtime>/runtime.json (unless one is handed in), then provisions
+ * each declared peer via createPeer (provision + per-peer self-config + auto-bootstrap).
+ * A runtime with no declared peers (mode b — telegram) is `operatorAddOnly` (nothing
+ * to deploy here; humans are added with `iapeer create`). Throws when no manifest is
+ * found at all (the package is not installed — `npx <package>` runs first).
+ */
+export async function deployRuntime(opts: DeployRuntimeOptions): Promise<DeployRuntimeResult> {
+  const env = opts.env ?? process.env
+  const manifest = opts.manifest ?? readRuntimeManifest(opts.runtime, { env })
+  if (!manifest) {
+    throw new IapError(
+      `no runtime manifest for "${opts.runtime}" at ~/.iapeer/runtimes/${opts.runtime}/runtime.json — ` +
+        `install the runtime package first (npx <package> self-deploys it)`,
+    )
+  }
+  const declared = opts.peers ?? manifest.peers ?? []
+  const peers: DeployedPeer[] = []
+  for (const decl of declared) {
+    const result = await createPeer({
+      personality: decl.personality,
+      runtime: opts.runtime,
+      intelligence: decl.intelligence,
+      description: decl.description,
+      path: decl.path,
+      runtimeBin: decl.runtimeBin,
+      bootstrap: opts.bootstrap,
+      env,
+      warn: opts.warn,
+    })
+    peers.push({
+      personality: result.personality,
+      location: result.location,
+      selfConfig: result.selfConfig?.state,
+      bootstrap: result.bootstrapped?.state,
+      result,
+    })
+  }
+  return { runtime: opts.runtime, peers, operatorAddOnly: declared.length === 0 }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §6 — package self-install (npx) + onboardRuntime (npx → deploy)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type NpxState =
+  | 'ran' // npx <package> ran and exited 0 (the package self-deployed)
+  | 'skipped' // a manifest is already present → package installed, no re-npx
+  | 'failed' // npx exited non-zero
+  | 'no-package' // no built-in mapping and no --package, AND no manifest present
+
+export interface InstallRuntimePackageResult {
+  runtime: Runtime
+  package?: string
+  state: NpxState
+  detail?: string
+}
+
+/** Injectable npx runner (so tests / a sandbox proof can simulate the package's
+ *  self-deploy without a published npm package). Default: `npx -y <package>`. */
+export type NpxRunner = (pkg: string, env: NodeJS.ProcessEnv) => { ok: boolean; detail?: string }
+
+const defaultNpxRunner: NpxRunner = (pkg, env) => {
+  // The package self-deploys on `npx` (puts its `<runtime>-runtime` bin on PATH and
+  // writes ~/.iapeer/runtimes/<r>/runtime.json). IAPEER_ROOT in env steers it to the
+  // right root (incl. a sandbox). cwd = HOME (the package is host-wide, cwd-agnostic).
+  const r = spawnSync('npx', ['-y', pkg], {
+    cwd: env.HOME?.trim() || homedir(),
+    encoding: 'utf8',
+    env: env as Record<string, string>,
+  })
+  if (r.error || (r.status ?? 1) !== 0) {
+    return { ok: false, detail: (r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim() }
+  }
+  return { ok: true }
+}
+
+export interface InstallRuntimePackageOptions {
+  runtime: Runtime
+  /** Override the built-in package mapping (--package). */
+  package?: string
+  /** Re-run npx even when a manifest is already present (force a package update). */
+  force?: boolean
+  env?: NodeJS.ProcessEnv
+  /** Injected npx runner (tests / sandbox proof). */
+  runNpx?: NpxRunner
+}
+
+/**
+ * Ensure a runtime PACKAGE is installed (the package self-deploys its bin + manifest
+ * via `npx`). IDEMPOTENT: when a manifest is already present (package installed) and
+ * not forced, it is a no-op (`skipped`). Otherwise resolves the package (override →
+ * built-in registry) and runs npx. No mapping + no --package + no manifest → `no-package`.
+ */
+export function installRuntimePackage(opts: InstallRuntimePackageOptions): InstallRuntimePackageResult {
+  const env = opts.env ?? process.env
+  const pkg = resolveRuntimePackage(opts.runtime, opts.package)
+  const manifestPresent = readRuntimeManifest(opts.runtime, { env }) !== null
+  if (manifestPresent && !opts.force) {
+    return { runtime: opts.runtime, package: pkg, state: 'skipped' }
+  }
+  if (!pkg) {
+    return { runtime: opts.runtime, state: 'no-package' }
+  }
+  const run = opts.runNpx ?? defaultNpxRunner
+  const r = run(pkg, env)
+  return { runtime: opts.runtime, package: pkg, state: r.ok ? 'ran' : 'failed', detail: r.detail }
+}
+
+export interface OnboardRuntimeOptions extends DeployRuntimeOptions {
+  /** Override the built-in package mapping (--package). */
+  package?: string
+  /** Re-run npx even when the manifest is already present. */
+  npx?: boolean
+  /** Injected npx runner (tests / sandbox proof). */
+  runNpx?: NpxRunner
+}
+
+export interface OnboardRuntimeResult {
+  install: InstallRuntimePackageResult
+  deploy?: DeployRuntimeResult
+}
+
+/**
+ * §6 onboard a runtime END-TO-END: (1) ensure the package is installed (npx self-
+ * deploy — auto-resolved from the built-in registry, or --package), THEN (2) deploy
+ * its declared peer-set. FAIL-CLOSED: a failed npx (or no package AND no manifest)
+ * aborts before deploy — never provision against a missing package. A telegram-style
+ * runtime (manifest with no declared peers) installs the package and is then
+ * operator-add (`iapeer create <human> --runtime telegram`).
+ */
+export async function onboardRuntime(opts: OnboardRuntimeOptions): Promise<OnboardRuntimeResult> {
+  const env = opts.env ?? process.env
+  const install = installRuntimePackage({
+    runtime: opts.runtime,
+    package: opts.package,
+    force: opts.npx,
+    env,
+    runNpx: opts.runNpx,
+  })
+  if (install.state === 'failed') {
+    throw new IapError(`npx install of runtime "${opts.runtime}" package ${install.package} failed: ${install.detail ?? ''}`)
+  }
+  if (install.state === 'no-package') {
+    throw new IapError(
+      `no package for runtime "${opts.runtime}" (no built-in mapping, no --package) and no manifest present — ` +
+        `pass --package <npm-package>`,
+    )
+  }
+  const deploy = await deployRuntime({
+    runtime: opts.runtime,
+    bootstrap: opts.bootstrap,
+    env,
+    warn: opts.warn,
+  })
+  return { install, deploy }
+}