@agfpd/iapeer 0.4.1 → 0.4.3

package/docs/07-install-and-update.md

@@ -47,25 +47,34 @@ You'll see the core version, the daemon's health, and the memory-slot state. The
 
 A breakdown of each onboard step is in [02 — Quick start](02-quickstart.md); runtimes and memory in detail — in [09](09-runtimes.md) and [11](11-extensions-and-memory.md).
 
-## Updating the core
+## Updating
 
 ```bash
-iapeer update            # to the latest version
-iapeer update 0.2.80     # to a specific version
-iapeer update --force    # reinstall even if the version is already in place
+iapeer update                   # cascade-update the WHOLE stack: core + runtimes + memory
+iapeer update --foundation-only # update just the core
+iapeer update 0.2.80            # pin the CORE to a specific version (core only)
+iapeer update --force           # reinstall even if the version is already in place
 ```
 
-An update pulls the core version from npm and restarts the daemon onto it. Step by step:
+A bare `iapeer update` updates the **whole host stack** in one command — the core (foundation), every installed runtime, and the memory provider — so "updated" means the whole machine, not just the core. The core goes first; the runtimes and memory follow only if the core came up healthy.
+
+**1. Core (foundation)** — and it ABORTS the cascade on a hard failure (never update runtimes onto a broken core):
 
 1. Learns the target version from npm. If the installed one already matches and there's no `--force` — it does nothing.
-2. Downloads and builds the new binary. This is done via `npm pack`, not `npx`: the binary doesn't rebuild itself.
+2. Downloads and builds the new binary via `npm pack`, not `npx` (the binary doesn't rebuild itself).
 3. Restarts the daemon onto the new binary.
-4. Restarts the infrastructure launchd jobs the core owns (`com.iapeer.*` — the `timer`, `watcher`, Telegram routers), moving them onto the just-replaced binary. Their plists launch the same core binary as the daemon — without a restart a job would stay on the old code. It's the job that's restarted (booted out and back in); the runtimes' **package code** (telegram-runtime, notifier-runtime) is not updated by this — that's the separate `update-runtime` operation. The memory provider (`iapeer-memory`) and ordinary peers' plists aren't touched at all. If the daemon didn't come up in step 3, this step is skipped — no point moving jobs onto a binary the daemon didn't revive on.
-5. Verifies the daemon actually came up healthy — not by the restart command exiting successfully, but by a probe: it connects to the daemon's socket (the one the daemon opens right before the readiness signal). The daemon counts as healthy only when the socket accepts a connection **twice in a row** — a single probe would also pass for a daemon that bound the socket and immediately crashed. The check is given 15 seconds; if a run of successful probes doesn't accumulate in that time, the command says so directly and advises rolling back.
+4. Restarts the infrastructure launchd jobs the core owns (`com.iapeer.*` — the `timer`, `watcher`, Telegram routers), moving them onto the just-replaced binary. It's the JOBS that restart, not the runtimes' package code — that's the next step. If the daemon didn't come up in step 3, this is skipped.
+5. Verifies the daemon came up healthy — by a probe, not by the restart command exiting: it connects to the daemon's socket and counts it healthy only when it accepts a connection **twice in a row** (a single probe would also pass a daemon that bound the socket and immediately crashed). The check is given 15 seconds; on failure the command says so and advises rolling back.
+
+**2. Runtimes** — each installed runtime package (telegram-runtime, notifier-runtime) is version-gated, re-installed, re-provisioned, and its peers restarted (via the regular stop/start — the persistent-peer fleet is refused, never forced).
+
+**3. Memory provider** — if a provider is claimed, its own update verb runs (the provider owns its update, its slot version, and its memory-daemon restart).
+
+Runtimes and memory are **best-effort**: a component failure is reported and the rest still run; the command exits non-zero if anything failed. Agentic peers (Claude/Codex) pick up new core doctrine lazily on their next wake.
 
-An update touches **only the core**. The daemon plist and third-party packages stay as they are.
+`iapeer update --foundation-only` does just step 1 (the narrow case). A pinned `iapeer update <version>` is **core-only** by design — a version pin is core-specific (downgrade, or pin a proven version, deeper than one rollback step).
 
-Naming a specific version (`iapeer update <version>`) is useful when you need to roll back deeper than one step, or pin a proven version.
+> **Upgrading from before the cascade (< 0.4.2).** The cascade is driven by the *installed* binary, so the very first `iapeer update` from a pre-cascade version runs the OLD (foundation-only) logic: it upgrades the core to the cascade-capable binary but does not yet cascade runtimes + memory. Run `iapeer update` once more — now the new binary cascades the rest. This is a one-time bootstrap; from 0.4.2 onward it is a single command. (A fresh install lands on a cascade-capable binary directly, so it never needs the double run.)
 
 ## Rollback
 

package/docs/ru/07-/321/203/321/201/321/202/320/260/320/275/320/276/320/262/320/272/320/260-/320/270-/320/276/320/261/320/275/320/276/320/262/320/273/320/265/320/275/320/270/320/265.md

@@ -47,25 +47,34 @@ iapeer status
 
 Разбор каждого шага onboard — в [02 — Быстрый старт](02-быстрый-старт.md); рантаймы и память подробно — в [09](09-рантаймы.md) и [11](11-расширения-и-память.md).
 
-## Обновление ядра
+## Обновление
 
 ```bash
-iapeer update            # до последней версии
-iapeer update 0.2.80     # до конкретной версии
-iapeer update --force    # переустановить, даже если версия уже стоит
+iapeer update                   # каскад: обновить ВЕСЬ стек — ядро + рантаймы + память
+iapeer update --foundation-only # обновить только ядро
+iapeer update 0.2.80            # запинить ЯДРО на конкретную версию (только ядро)
+iapeer update --force           # переустановить, даже если версия уже стоит
 ```
 
-Обновление тянет версию ядра из npm и перезапускает демон на неё. По шагам:
+Голый `iapeer update` обновляет **весь хостовый стек** одной командой — ядро (фундамент), каждый установленный рантайм и провайдер памяти, — чтобы «обновлено» значило всю машину, а не только ядро. Ядро идёт первым; рантаймы и память следуют, только если ядро поднялось здоровым.
+
+**1. Ядро (фундамент)** — и оно ПРЕРЫВАЕТ каскад при жёсткой ошибке (не обновлять рантаймы на сломанное ядро):
 
 1. Узнаёт нужную версию из npm. Если установленная уже совпадает и нет `--force` — ничего не делает.
-2. Скачивает и собирает новый бинарь. Это делается через `npm pack`, а не `npx`: бинарь не пересобирает себя сам.
+2. Скачивает и собирает новый бинарь через `npm pack`, а не `npx` (бинарь не пересобирает себя сам).
 3. Перезапускает демон на новый бинарь.
-4. Перезапускает launchd-джобы инфраструктуры, которыми владеет ядро (`com.iapeer.*` — роутеры `timer`, `watcher`, Telegram), переводя их на только что заменённый бинарь. Их плисты запускают тот же бинарь ядра, что и демон, — без перезапуска джоб остался бы на старом коде. Перезапускается именно джоб (снимается и поднимается заново); **пакетный код** рантаймов (telegram-runtime, notifier-runtime) при этом не обновляется — это отдельная операция `update-runtime`. Провайдер памяти (`iapeer-memory`) и плисты обычных пиров не трогаются вовсе. Если демон на шаге 3 не поднялся, этот шаг пропускается — нет смысла переводить джобы на бинарь, на котором демон не ожил.
-5. Проверяет, что демон действительно поднялся здоровым, — не по тому, что команда перезапуска завершилась успешно, а пробой: подключается к сокету демона (тому самому, что демон открывает прямо перед сигналом готовности). Здоровым демон считается, только когда сокет принимает соединение **дважды подряд** — одиночная проба прошла бы и у демона, который привязал сокет и тут же упал. На проверку отведено 15 секунд; если за это время серия успешных проб не набралась — команда говорит об этом прямо и советует откатиться.
+4. Перезапускает launchd-джобы инфраструктуры, которыми владеет ядро (`com.iapeer.*` — роутеры `timer`, `watcher`, Telegram), переводя их на заменённый бинарь. Перезапускаются именно ДЖОБЫ, а не пакетный код рантаймов — это следующий шаг. Если демон на шаге 3 не поднялся, шаг пропускается.
+5. Проверяет, что демон поднялся здоровым, — пробой, а не кодом возврата команды перезапуска: подключается к сокету демона и считает здоровым, только когда тот принимает соединение **дважды подряд** (одиночная проба прошла бы и у демона, который привязал сокет и тут же упал). На проверку 15 секунд; при провале команда говорит и советует откатиться.
+
+**2. Рантаймы** — каждый установленный рантайм-пакет (telegram-runtime, notifier-runtime) проходит version-gate, переустановку, ре-провижн, и его пиры перезапускаются (через обычный stop/start — флот persistent-peer отклоняется, не форсится).
+
+**3. Провайдер памяти** — если слот занят, запускается его собственный update-verb (провайдер владеет своим обновлением, версией слота и перезапуском memory-демона).
+
+Рантаймы и память — **best-effort**: ошибка компонента сообщается, остальные всё равно отрабатывают; код возврата ненулевой, если что-то упало. Агентские пиры (Claude/Codex) подхватывают новую доктрину ядра лениво на следующем пробуждении.
 
-Обновление трогает **только ядро**. Плист демона и сторонние пакеты остаются как есть.
+`iapeer update --foundation-only` делает только шаг 1 (узкий случай). Запиненный `iapeer update <версия>` — **только ядро** by design: пин версии специфичен для ядра (откат глубже одного шага или фиксация проверенной версии).
 
-Указать конкретную версию (`iapeer update <версия>`) полезно, когда нужно откатиться глубже, чем на один шаг назад, или встать на проверенную версию.
+> **Обновление с версии до каскада (< 0.4.2).** Каскад исполняет *установленный* бинарь, поэтому самый первый `iapeer update` со старой версии работает по СТАРОЙ (foundation-only) логике: он поднимает ядро до каскад-способного бинаря, но рантаймы + память пока не каскадит. Запусти `iapeer update` ещё раз — теперь новый бинарь докаскадит остальное. Это разовый bootstrap; начиная с 0.4.2 — одна команда. (Свежая установка сразу ставит каскад-способный бинарь, поэтому двойной прогон ей не нужен.)
 
 ## Откат
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -21,7 +21,7 @@ import {
   type Runtime,
 } from '../core/constants.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
-import { recycleFoundationOwnedInfraJobs, updateIapeer, waitForDaemonHealthy } from '../update/index.ts'
+import { cascadeTail, recycleFoundationOwnedInfraJobs, updateIapeer, waitForDaemonHealthy } from '../update/index.ts'
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { ensureGlobalIapScaffold } from '../storage/index.ts'
 import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../registry/index.ts'
@@ -955,7 +955,10 @@ export function parseArgs(argv: string[]): { positionals: string[]; flags: Recor
  *  narrow terminal). `sig` = the invocation signature, `desc` = one prose line. */
 const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
   { sig: 'install', desc: 'build binary + global scaffold + daemon plist (one bootstrap)' },
-  { sig: 'update [version] [--force]', desc: 'pull latest (or exact) @agfpd/iapeer from npm + restart daemon + recycle owned infra jobs' },
+  {
+    sig: 'update [version] [--force] [--foundation-only]',
+    desc: 'cascade-update the WHOLE stack (foundation + installed runtimes + memory) from npm + restart; --foundation-only = core only; a pinned <version> updates the core only',
+  },
   { sig: 'rollback', desc: 'revert to the previous binary (.prev) + restart daemon + recycle owned infra jobs' },
   {
     sig: 'uninstall [--dry-run] [--yes] [--remove-codesign-identity]',
@@ -1250,9 +1253,9 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // and the memory provider's install-time sweep (`--all`). NOT slot-gated here —
         // an explicit operator/provider action; only the BIRTH-time hook is slot-gated.
         const state = positionals[0]
-        if (state !== 'off' && state !== 'on') return usage(errOut)
+        if (state !== 'off' && state !== 'on') return argErr(errOut, 'native-memory needs a state — usage: iapeer native-memory <off|on> (--peer <p> | --all)')
         const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
-        if (flags.all !== true && !peerName) return usage(errOut)
+        if (flags.all !== true && !peerName) return argErr(errOut, 'native-memory needs a target — pass --peer <p> or --all')
         const { applyNativeMemory } = await import('../launch/nativeMemory.ts')
         const index = readPeersIndex({ env })
         const targets = flags.all === true ? index.peers : index.peers.filter(p => p.personality === peerName)
@@ -1285,7 +1288,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // the read-only drift detector for verify pipelines — per-hook
         // trusted/missing/drift, exit 1 on anything but full trust.
         const target = positionals[0]
-        if (!target) return usage(errOut)
+        if (!target) return argErr(errOut, 'trust-hooks needs a hooks file — usage: iapeer trust-hooks <hooks.json> [--check]')
         const { preSeedCodexHooksTrust, checkCodexHooksTrust } = await import('../launch/codexHooksTrust.ts')
         if (flags.check === true) {
           let checks
@@ -1328,7 +1331,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // manifest), THEN deploy its declared peer-set (each → provision + per-peer
         // self-config + auto-bootstrap). A runtime whose manifest declares no peers
         // (telegram) is operator-add — use `iapeer create <human> --runtime telegram`.
-        if (!positionals[0]) return usage(errOut)
+        if (!positionals[0]) return argErr(errOut, 'install-runtime needs a runtime — usage: iapeer install-runtime <runtime> (e.g. telegram | notifier)')
         const { onboardRuntime } = await import('../runtime/deploy.ts')
         const r = await onboardRuntime({
           runtime: positionals[0] as Runtime,
@@ -1356,7 +1359,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // 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)
+        if (!all && !positionals[0]) return argErr(errOut, 'update-runtime needs a runtime or --all — usage: iapeer update-runtime <runtime> | --all')
         const { updateRuntime, updateAllRuntimes } = await import('../runtime/update.ts')
         const results = all
           ? await updateAllRuntimes({ force: flags.force === true, env, warn: m => errOut(`warn: ${m}\n`) })
@@ -1403,7 +1406,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // cwd-INDEPENDENT: resolve a location (default ~/.iapeer/peers/<p> or --path),
         // scaffold the folder (no-clobber), then init it. Operator-add for an infra
         // human (telegram) or any agentic peer; provisions + auto-bootstraps infra.
-        if (!positionals[0]) return usage(errOut)
+        if (!positionals[0]) return argErr(errOut, 'create needs a peer name — usage: iapeer create <personality> [--runtime r] [--path dir]')
         const explicitRuntime = typeof flags.runtime === 'string' ? (flags.runtime as Runtime) : undefined
         // FU5 — never SILENTLY default to claude when both agentic runtimes are
         // installed. `--runtime` selects the DEFAULT (not the sole runtime); the
@@ -1567,7 +1570,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           : positionals[0]
             ? [positionals[0]]
             : null
-        if (!peers) return usage(errOut)
+        if (!peers) return argErr(errOut, 'stop needs a peer or --all — usage: iapeer stop <peer> [runtime] | --all')
         const outcomes = peers.flatMap(p => stopPeer(p, flags.all === true ? undefined : positionals[1], { env }))
         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
@@ -1576,9 +1579,9 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Fleet-switch enabler (codex-parity audit): add an agentic runtime to
         // existing peer(s) — full codex birth chain per target, idempotent.
         const rt = positionals[0]
-        if (!rt) return usage(errOut)
+        if (!rt) return argErr(errOut, 'add-runtime needs a runtime — usage: iapeer add-runtime <runtime> (--peer <p> | --all)')
         const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
-        if (flags.all !== true && !peerName) return usage(errOut)
+        if (flags.all !== true && !peerName) return argErr(errOut, 'add-runtime needs a target — pass --peer <p> or --all')
         const outcomes = await addRuntime(rt, { peer: peerName, all: flags.all === true, env })
         for (const o of outcomes) out(`${o.personality}: ${o.action}${o.detail ? ` — ${o.detail}` : ''}\n`)
         return outcomes.some(o => o.action === 'failed') ? 1 : 0
@@ -1586,9 +1589,9 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
       case 'default-runtime': {
         // The PRIMARY flip (routing/wake default) — the fleet-switch moment itself.
         const rt = positionals[0]
-        if (!rt) return usage(errOut)
+        if (!rt) return argErr(errOut, 'default-runtime needs a runtime — usage: iapeer default-runtime <runtime> (--peer <p> | --all)')
         const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
-        if (flags.all !== true && !peerName) return usage(errOut)
+        if (flags.all !== true && !peerName) return argErr(errOut, 'default-runtime needs a target — pass --peer <p> or --all')
         const outcomes = await defaultRuntime(rt, { peer: peerName, all: flags.all === true, env })
         for (const o of outcomes) out(`${o.personality}: ${o.action}${o.detail ? ` — ${o.detail}` : ''}\n`)
         return outcomes.some(o => o.action === 'failed') ? 1 : 0
@@ -1598,7 +1601,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // §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)
+        if (!positionals[0]) return argErr(errOut, 'new needs a peer name — usage: iapeer new <peer> [runtime]')
         const o = await newPeer(positionals[0], positionals[1], { env })
         if (o.action === 'fresh') {
           out(`new: ${o.runtime}-${o.personality} fresh session up\n`)
@@ -1619,7 +1622,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           : positionals[0]
             ? [positionals[0]]
             : null
-        if (!peers) return usage(errOut)
+        if (!peers) return argErr(errOut, 'start needs a peer or --all — usage: iapeer start <peer> [runtime] | --all')
         const outcomes = peers.flatMap(p => startPeer(p, flags.all === true ? undefined : positionals[1], { env }))
         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
@@ -1633,7 +1636,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           : positionals[0]
             ? [positionals[0]]
             : null
-        if (!peers) return usage(errOut)
+        if (!peers) return argErr(errOut, 'refresh needs a peer or --all — usage: iapeer refresh <peer> [runtime] | --all')
         const outcomes = peers.flatMap(p => refreshPeer(p, flags.all === true ? undefined : positionals[1], { env }))
         for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}\n`)
         return 0
@@ -1642,7 +1645,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Reap a registry record through the locked writer (the operator path over
         // registry.removePeer). Idempotent on an absent peer (exit 0). Refuses a LIVE
         // peer unless --force (orphaning a running session from routing is the risk).
-        if (!positionals[0]) return usage(errOut)
+        if (!positionals[0]) return argErr(errOut, 'remove needs a peer name — usage: iapeer remove <peer> [--force]')
         const o = await removePeerCli(positionals[0], { force: flags.force === true, env })
         if (o.action === 'removed') {
           out(`removed "${o.personality}" from the registry\n`)
@@ -1684,7 +1687,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           const mf = flags['message-file']
           message = mf === '-' ? readFileSync(0, 'utf8') : readFileSync(mf, 'utf8')
         }
-        if (!positionals[0] || message === null) return usage(errOut)
+        if (!positionals[0] || message === null) return argErr(errOut, 'send needs a target and a message — usage: iapeer send <target> --message <text> (or --message-file <f|->)')
         // --attachment is REPEATABLE; parseArgs collapses repeats (last-wins), so
         // re-scan the raw rest argv to collect every attachment path (else files
         // silently drop — a text-only smoke test would not catch it).
@@ -1716,49 +1719,72 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return 0
       }
       case 'update': {
-        // The single deploy path: pull a version of the foundation from npm and restart
-        // the daemon onto it (cloud-only — never a working-tree build). No arg → latest;
-        // an explicit `update <version>` pins to that exact version (downgrade / recover
-        // deeper than the single .prev). Foundation ONLY; the plist and other host packages
-        // are untouched. --force reinstalls even when already at the desired version. (Run
-        // from the installed binary; the first-ever install is `npx @agfpd/iapeer`.)
-        const r = updateIapeer({ env, force: flags.force === true, targetVersion: positionals[0] })
+        // CASCADE deploy (FU12): a bare `iapeer update` updates the WHOLE host stack —
+        // foundation → every installed runtime → the memory provider — in one command.
+        // Foundation goes FIRST and ABORTS the cascade on a hard failure (never update
+        // runtimes onto a broken core). Runtimes + memory are BEST-EFFORT (reported, not
+        // fatal). Two narrowings stay foundation-ONLY: `--foundation-only` (explicit) and
+        // a pinned `update <version>` (a version pin is foundation-specific — downgrade /
+        // recover). H4 holds throughout (foreign persistent-peer fleet is refused, never
+        // forced — the runtime restart goes via the guarded stop/start). Cloud-only; the
+        // first-ever install is `npx @agfpd/iapeer`.
+        const pinned = positionals[0]
+        const foundationOnly = flags['foundation-only'] === true
+        const cascading = !foundationOnly && !pinned
+        if (cascading) {
+          // no-surprise heads-up: this restarts peers and can run minutes.
+          out(
+            'iapeer update — updating the WHOLE stack: foundation + installed runtimes + memory provider.\n' +
+              'This rebuilds the daemon, restarts the telegram/notifier services and the memory daemon,\n' +
+              'and can take a few minutes; agentic peers pick up the new code on their next wake.\n' +
+              '(`iapeer update --foundation-only` updates just the core.)\n\n',
+          )
+        }
+
+        // ── Foundation (the core; a hard failure aborts the cascade) ──
+        const r = updateIapeer({ env, force: flags.force === true, targetVersion: pinned })
+        let foundationHardFail = false
         if (r.status === 'failed') {
           errOut(`update failed: ${r.reason}\n`)
-          return 1
-        }
-        if (r.status === 'already-latest') {
-          out(`already at version ${r.from}\n`)
-          return 0
-        }
-        // 'updated': the binary is swapped. If the daemon was restarted, VERIFY it
-        // actually came back up before declaring success — a new binary that fails to
-        // boot must not read as a healthy deploy (it's the cue to roll back).
-        if (r.daemon === 'restarted') {
+          foundationHardFail = true
+        } else if (r.status === 'already-latest') {
+          out(`foundation: already at version ${r.from}\n`)
+        } else if (r.daemon === 'restarted') {
+          // 'updated' + daemon restarted: VERIFY it actually came back up (a binary that
+          // fails to boot must not read as a healthy deploy — it's the cue to roll back).
           const h = await waitForDaemonHealthy({ env })
           if (!h.healthy) {
-            errOut(`updated ${r.from} → ${r.to} but the daemon is NOT healthy after restart (${h.detail}).\n` +
-              `roll back now: iapeer rollback\n`)
-            return 1
+            errOut(`foundation: updated ${r.from} → ${r.to} but the daemon is NOT healthy after restart (${h.detail}).\nroll back now: iapeer rollback\n`)
+            foundationHardFail = true
+          } else {
+            const note = infraRecycleNote(r.infra)
+            ;(infraRecycleFailed(r.infra) ? errOut : out)(`foundation: updated ${r.from} → ${r.to}; daemon restarted and healthy${note}\n`)
           }
+        } else {
+          const daemonNote =
+            r.daemon === 'not-loaded'
+              ? 'daemon not loaded — new binary will be used on next start'
+              : r.daemon === 'failed'
+                ? `WARNING — ${r.reason}; roll back with: iapeer rollback`
+                : String(r.daemon)
+          if (r.daemon === 'failed') foundationHardFail = true
           const note = infraRecycleNote(r.infra)
-          if (infraRecycleFailed(r.infra)) {
-            errOut(`updated ${r.from} → ${r.to}; daemon restarted and healthy${note}\n`)
-            return 1
-          }
-          out(`updated ${r.from} → ${r.to}; daemon restarted and healthy${note}\n`)
-          return 0
+          ;(r.daemon === 'failed' || infraRecycleFailed(r.infra) ? errOut : out)(`foundation: updated ${r.from} → ${r.to}; ${daemonNote}${note}\n`)
         }
-        const daemonNote =
-          r.daemon === 'not-loaded'
-            ? 'daemon not loaded — new binary will be used on next start'
-            : r.daemon === 'failed'
-              ? `WARNING — ${r.reason}; roll back with: iapeer rollback`
-              : String(r.daemon)
-        const note = infraRecycleNote(r.infra)
-        const failed = r.daemon === 'failed' || infraRecycleFailed(r.infra)
-        ;(failed ? errOut : out)(`updated ${r.from} → ${r.to}; ${daemonNote}${note}\n`)
-        return failed ? 1 : 0
+        const foundationExit = foundationHardFail || infraRecycleFailed(r.infra) ? 1 : 0
+
+        // foundation-only / pinned / hard-fail → stop here (don't cascade onto a broken core).
+        if (!cascading || foundationHardFail) return foundationExit
+
+        // ── Cascade tail: runtimes + memory provider (best-effort) ──
+        const { updateAllRuntimes } = await import('../runtime/update.ts')
+        const { updateMemoryProvider } = await import('../onboard/memory.ts')
+        const tail = await cascadeTail({
+          runtimes: () => updateAllRuntimes({ force: flags.force === true, env, warn: m => errOut(`warn: ${m}\n`) }),
+          memory: () => updateMemoryProvider({ env }),
+          out,
+        })
+        return foundationExit === 0 && !tail.failed ? 0 : 1
       }
       case 'rollback': {
         // Recovery: restore the .prev binary kept by the last install, restart the
@@ -1909,7 +1935,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Ф-F: the always-on infra entrypoint (telegram/notifier), held by launchd.
         // The infra plist runs `iapeer run-infra <personality> <runtime>` (installed
         // binary) instead of `bun launchdRun.ts`. cwd = the launchd WorkingDirectory.
-        if (!positionals[0] || !positionals[1]) return usage(errOut)
+        if (!positionals[0] || !positionals[1]) return argErr(errOut, 'run-infra needs a runtime and a personality — usage: iapeer run-infra <runtime> <personality> (internal launchd entrypoint)')
         return await runAlwaysOn(positionals[0], positionals[1], process.cwd())
       }
       case 'self-done': {
@@ -1983,7 +2009,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
       case 'interrupt': {
         // In-session control (Ф-E, clean-slash namespace): interrupt a stuck/raving
         // turn (Escape). UNCONDITIONAL — acts on the live session.
-        if (!positionals[0]) return usage(errOut)
+        if (!positionals[0]) return argErr(errOut, 'interrupt needs a peer name — usage: iapeer interrupt <peer> [runtime]')
         const r = await routeControl(positionals[0], positionals[1], { name: verb })
         if (!r.ok) {
           errOut(`${verb}: ${r.error.message}\n`)
@@ -1996,7 +2022,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Dialogue control: if the session is merely asleep
         // after a clean idle-reap, resume the same dialogue and compact it; if there
         // is no resumable dialogue, fail honestly instead of compacting a fresh one.
-        if (!positionals[0]) return usage(errOut)
+        if (!positionals[0]) return argErr(errOut, 'compact needs a peer name — usage: iapeer compact <peer> [runtime]')
         const o = await compactPeer(positionals[0], positionals[1], { env })
         if (o.action === 'compacted') {
           out(`compact → ${o.personality} (${o.runtime})${o.woke ? ' after resume' : ''}\n`)
@@ -2010,7 +2036,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // `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)
+        if (positionals[0] !== 'telegram' || !positionals[1]) return argErr(errOut, 'connect needs "telegram <peer>" — usage: iapeer connect telegram <peer> [--token <t>] (e.g. iapeer connect telegram boris)')
         const { connectTelegram } = await import('../connect/index.ts')
         const r = await connectTelegram({
           peer: positionals[1],
@@ -2040,7 +2066,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // per-runtime (claude project-scope IN the peer cwd / codex global) + enable +
         // call the plugin's `setup` ONLY if its iapeer.json declares it. Idempotent and
         // fleet-safe — claude is keyed by the peer's projectPath. `enable <plugin> [peer]`.
-        if (!positionals[0]) return usage(errOut)
+        if (!positionals[0]) return argErr(errOut, 'enable needs a capability/plugin — usage: iapeer enable <plugin> [peer]')
         const { enableCapability } = await import('../enable/index.ts')
         const r = enableCapability({
           plugin: positionals[0],
@@ -2055,7 +2081,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return r.runtimes.some(rt => rt.state === 'failed') || r.setup === 'failed' ? 1 : 0
       }
       case 'attach': {
-        if (!positionals[0]) return usage(errOut)
+        if (!positionals[0]) return argErr(errOut, 'attach needs a peer name — usage: iapeer attach <peer> [runtime]')
         const r = await attachPeer({ personality: positionals[0], runtime: positionals[1], env })
         if (!r.ok) {
           errOut(`attach: ${r.reason}\n`)
@@ -2131,7 +2157,14 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           const id = resolveIdentity({ env })
           const r = await folderLaunch({ cwd: process.cwd(), runtime: verb, env, cfg })
           if (r.status === 'FAILED') {
-            errOut(`launch: ${r.reason}\n`)
+            // A bare token format-matches a runtime, so it dispatched here as `iapeer
+            // <runtime>` (launch the cwd peer on that runtime). When that fails, the user
+            // most often just MISTYPED a command — surface BOTH readings so the message is
+            // actionable instead of a bare "runtime not declared" (FU13).
+            errOut(
+              `iapeer: "${verb}" — ${r.reason}\n` +
+                '  If you meant a command, run `iapeer help`. `iapeer <runtime>` launches a runtime declared for the current peer.\n',
+            )
             return 1
           }
           const identity = r.process_address ?? buildProcessAddress(verb, id.personality)
@@ -2143,6 +2176,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           out(`launched ${identity} (fresh)\n`)
           return 0
         }
+        errOut(`iapeer: unknown verb "${verb ?? ''}"\n`)
         return usage(errOut)
       }
     }
@@ -2157,6 +2191,15 @@ function usage(errOut: (s: string) => void): number {
   return 2
 }
 
+/** A TARGETED argument error (FU13): a one-line, addressed, actionable reason for THIS
+ *  verb — never the generic top-level help wall (which reads as "nothing happened" to a
+ *  user who just mistyped one verb). `message` should name what's missing + the verb's
+ *  own form, e.g. "connect telegram needs a peer — usage: iapeer connect telegram <peer>". */
+function argErr(errOut: (s: string) => void, message: string): number {
+  errOut(`iapeer: ${message}\n`)
+  return 2
+}
+
 /** Interactive default-runtime picker (FU5) — only called on a real TTY when more
  *  than one agentic runtime is installed and no `--runtime` was given. Accepts a
  *  number or the runtime name; empty input takes the first (the listed default). */

package/src/onboard/index.ts

@@ -46,6 +46,14 @@ export interface OnboardOptions {
   /** Restrict to these runtimes (default both). */
   runtimes?: OnboardRuntime[]
   env?: NodeJS.ProcessEnv
+  /** Injectable (tests). Default registerMarketplace. */
+  register?: (runtime: OnboardRuntime, env: NodeJS.ProcessEnv) => { ok: boolean; detail?: string }
+  /** Injectable (tests). Default isMarketplaceRegistered. */
+  isRegistered?: (runtime: OnboardRuntime, env: NodeJS.ProcessEnv) => boolean
+  /** Injectable (tests). Default Bun.sleepSync — the pause before the one transient retry. */
+  sleep?: (ms: number) => void
+  /** Delay (ms) before the single non-timeout retry. Default 2000. */
+  retryDelayMs?: number
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -192,13 +200,17 @@ export function refreshMarketplace(
 export function onboardHost(opts: OnboardOptions = {}): OnboardResult {
   const env = opts.env ?? process.env
   const runtimes = opts.runtimes ?? (['claude', 'codex'] as OnboardRuntime[])
+  const isRegistered = opts.isRegistered ?? isMarketplaceRegistered
+  const register = opts.register ?? registerMarketplace
+  const sleep = opts.sleep ?? ((ms: number) => Bun.sleepSync(ms))
+  const retryDelayMs = opts.retryDelayMs ?? 2000
   const marketplaces: OnboardRuntimeResult[] = []
   for (const runtime of runtimes) {
     if (!isExecutable(runtimeBin(runtime, env), env)) {
       marketplaces.push({ runtime, state: 'runtime-missing' })
       continue
     }
-    if (isMarketplaceRegistered(runtime, env)) {
+    if (isRegistered(runtime, env)) {
       marketplaces.push({ runtime, state: 'already-registered' })
       continue
     }
@@ -206,13 +218,59 @@ export function onboardHost(opts: OnboardOptions = {}): OnboardResult {
       marketplaces.push({ runtime, state: 'would-register' })
       continue
     }
-    const r = registerMarketplace(runtime, env)
-    marketplaces.push({ runtime, state: r.ok ? 'registered' : 'failed', detail: r.detail })
+    marketplaces.push(resolveMarketplaceAdd(runtime, env, register, isRegistered, sleep, retryDelayMs))
   }
   const noop = marketplaces.every(m => m.state !== 'registered')
   return { marketplaces, noop }
 }
 
+/**
+ * One `marketplace add` with first-run-transient resilience (Arthur's fresh-run found a
+ * scary red "failed" on a step that actually self-heals — the failure is transient, the
+ * marketplace ends up registered). Layered:
+ *   (a) SELF-HEAL: if the add reports failure but a re-check shows the marketplace IS
+ *       present (it landed despite a non-zero tail / a race), report `registered`.
+ *   (c) ONE retry after a short delay — only for a NON-timeout transient (a network/git
+ *       blip on the GitHub clone). NEVER on a timeout: a wedged / macOS-launch-approval-
+ *       parked binary would just re-wedge, doubling the wait.
+ *   (b) on a timeout signature, report `failed` with the macOS-approval advisory; on any
+ *       other persistent failure, a transient-retry hint. The marketplace is OPTIONAL for
+ *       core function, so a clear actionable line beats a bare "failed".
+ */
+function resolveMarketplaceAdd(
+  runtime: OnboardRuntime,
+  env: NodeJS.ProcessEnv,
+  register: (r: OnboardRuntime, e: NodeJS.ProcessEnv) => { ok: boolean; detail?: string },
+  isRegistered: (r: OnboardRuntime, e: NodeJS.ProcessEnv) => boolean,
+  sleep: (ms: number) => void,
+  retryDelayMs: number,
+): OnboardRuntimeResult {
+  const first = register(runtime, env)
+  if (first.ok) return { runtime, state: 'registered' }
+  // (a) self-heal — present despite the reported error?
+  if (isRegistered(runtime, env)) {
+    return { runtime, state: 'registered', detail: 'add reported an error, but the marketplace is present' }
+  }
+  const timedOut = /timed out/i.test(first.detail ?? '')
+  if (!timedOut) {
+    // (c) one retry for a non-timeout transient.
+    sleep(retryDelayMs)
+    const second = register(runtime, env)
+    if (second.ok || isRegistered(runtime, env)) return { runtime, state: 'registered', detail: 'succeeded on retry' }
+    return {
+      runtime,
+      state: 'failed',
+      detail: `${second.detail ?? first.detail} — transient (network/git)? re-run \`iapeer onboard\`; the marketplace is optional for core function`,
+    }
+  }
+  // (b) timeout signature → the known macOS launch-approval park.
+  return {
+    runtime,
+    state: 'failed',
+    detail: `${first.detail} — macOS may be verifying the runtime binary; approve it in System Settings → Privacy & Security, then re-run \`iapeer onboard\``,
+  }
+}
+
 /**
  * macOS Full Disk Access (TCC) advisory printed at the END of onboard. The runtime permission layer
  * (`--add-dir` / `additionalDirectories` for claude, the sandbox flags for codex) governs what the

package/src/onboard/memory.ts

@@ -144,3 +144,74 @@ export async function onboardMemoryProvider(opts: MemoryOnboardOptions = {}): Pr
   }
   return { state: 'installed', provider: after }
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// updateMemoryProvider — the memory leg of the cascade `iapeer update` (FU12)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface MemoryUpdateResult {
+  state:
+    | 'updated' // provider update ran and the slot version advanced
+    | 'already-latest' // ran but the slot version is unchanged
+    | 'no-slot' // no provider claimed — nothing to update
+    | 'skipped-unavailable' // package not published / no network — soft skip
+    | 'failed' // provider update exited non-zero
+  package?: string
+  from?: string
+  to?: string
+  detail?: string
+}
+
+/** The provider's CLI bin name = the unscoped package name (`@agfpd/iapeer-memory` →
+ *  `iapeer-memory`). */
+function memoryBinName(pkg: string): string {
+  return pkg.replace(/^@[^/]+\//, '')
+}
+
+function defaultRunMemoryUpdate(pkg: string, env: NodeJS.ProcessEnv): { status: number | null; unavailable: boolean } {
+  // Availability probe FIRST (cheap, bounded): unpublished / no network → soft-skip.
+  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env, timeout: 60_000 })
+  if (probe.status !== 0) return { status: probe.status, unavailable: true }
+  // The provider ships a COMPILED bin on PATH (~/.local/bin/<bin>), NOT an npm package,
+  // so a bare `npx <bin>` / `npx <pkg>@latest` re-runs the STALE installed binary —
+  // verified by the provider: it reports the OLD version, "running FROM the installed
+  // binary", a SILENT non-update (fatal for the upgrade case). `npm exec
+  // --package=<pkg>@latest -- <bin> update` fetches latest + rebuilds, bypassing the PATH
+  // name-shadow. The provider OWNS update + slot-write + its own daemon (memoryd) restart.
+  const r = spawnSync(
+    'npm',
+    ['exec', '--yes', `--package=${pkg}@latest`, '--', memoryBinName(pkg), 'update'],
+    { stdio: 'inherit', env },
+  )
+  return { status: r.status, unavailable: false }
+}
+
+/**
+ * Update the CLAIMED memory provider via ITS OWN npx update verb (slot contract: the
+ * provider owns install/update + slot-write + peer restart; the core only invokes +
+ * reads the slot). No slot → nothing to update. Reports from→to by reading the slot
+ * version before/after. BEST-EFFORT by the caller (the cascade never aborts on it).
+ */
+export function updateMemoryProvider(opts: {
+  env?: NodeJS.ProcessEnv
+  dryRun?: boolean
+  runUpdate?: (pkg: string, env: NodeJS.ProcessEnv) => { status: number | null; unavailable: boolean }
+} = {}): MemoryUpdateResult {
+  const env = opts.env ?? process.env
+  const slot = readMemoryProvider(env)
+  if (!slot) return { state: 'no-slot', detail: 'no memory provider claimed — nothing to update' }
+  const pkg = slot.package
+  const from = slot.version
+  if (opts.dryRun) {
+    return { state: 'updated', package: pkg, from, detail: `would run: npm exec --package=${pkg}@latest -- ${memoryBinName(pkg)} update` }
+  }
+  const run = opts.runUpdate ?? defaultRunMemoryUpdate
+  const r = run(pkg, env)
+  if (r.unavailable) {
+    return { state: 'skipped-unavailable', package: pkg, from, detail: `${pkg}@latest not reachable (no network / unpublished)` }
+  }
+  if (r.status !== 0) return { state: 'failed', package: pkg, from, detail: `provider update exited ${r.status ?? 'null'}` }
+  const to = readMemoryProvider(env)?.version
+  if (from && to && from === to) return { state: 'already-latest', package: pkg, from, to }
+  return { state: 'updated', package: pkg, from, to }
+}

package/src/update/index.ts

@@ -1,8 +1,13 @@
-// `iapeer update` — the SINGLE deploy path: pull the latest published foundation
-// from npm (the cloud) and restart the daemon onto it. There is deliberately NO
-// "deploy from a working tree" — every host, including the dev host, activates a
+// `updateIapeer` — the FOUNDATION leg of the deploy: pull the latest published
+// foundation from npm (the cloud) and restart the daemon onto it. There is deliberately
+// NO "deploy from a working tree" — every host, including the dev host, activates a
 // release the same way: `npm run release` (publish) → `iapeer update` (pull + restart).
 //
+// NB the `iapeer update` VERB cascades the whole stack (FU12): it runs this foundation
+// leg FIRST (aborting on a hard failure), then `updateAllRuntimes` + the memory provider
+// (best-effort) via cascadeTail (below). updateIapeer itself stays foundation-scoped —
+// the cascade is composed in the CLI verb.
+//
 // Flow:
 //   1. latest = `npm view @agfpd/iapeer version`           (the cloud's truth)
 //   2. installed == latest && !--force → "already latest"  (no needless rebuild/restart)
@@ -43,6 +48,10 @@ import {
 } from '../launch/launchd.ts'
 import { cycleShadowJob, SHADOW_PERSONALITY, SHADOW_PLIST_LABEL } from '../shadow/install.ts'
 import { defaultDaemonSocketPath } from '../daemon/index.ts'
+// Type-only (erased at runtime → no import cycle): the cascade tail renders these
+// shapes but receives the component-updaters as injected deps.
+import type { UpdateRuntimeResult } from '../runtime/update.ts'
+import type { MemoryUpdateResult } from '../onboard/memory.ts'
 
 /** The npm package the foundation publishes / updates from. */
 export const IAPEER_PACKAGE = '@agfpd/iapeer'
@@ -316,3 +325,42 @@ export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
     reason: d.state === 'failed' ? `binary updated but daemon restart failed: ${d.detail ?? ''}`.trim() : undefined,
   }
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// cascadeTail — the runtimes + memory legs of the cascade `iapeer update` (FU12).
+// Runs AFTER a healthy foundation update (the CLI owns that, abort-on-hard-fail);
+// here we update every installed runtime then the memory provider, BEST-EFFORT — a
+// component failure is reported, never aborts the rest. Pure orchestration over
+// injected component-updaters (no value-import of runtime/onboard → no cycle), so it
+// is hermetically testable. Returns whether anything failed (→ exit≠0).
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CascadeTailDeps {
+  /** = updateAllRuntimes (runtime/update.ts). */
+  runtimes: () => Promise<UpdateRuntimeResult[]>
+  /** = updateMemoryProvider (onboard/memory.ts). */
+  memory: () => MemoryUpdateResult | Promise<MemoryUpdateResult>
+  out: (s: string) => void
+}
+
+export async function cascadeTail(deps: CascadeTailDeps): Promise<{ failed: boolean }> {
+  let failed = false
+
+  deps.out('runtimes:\n')
+  const rs = await deps.runtimes()
+  if (rs.length === 0) deps.out('  (none installed)\n')
+  for (const r of rs) {
+    const ver = r.from || r.to ? ` ${r.from ?? '?'} → ${r.to ?? '?'}` : ''
+    deps.out(`  ${r.runtime}: ${r.state}${ver}${r.detail ? ` — ${r.detail}` : ''}\n`)
+    for (const p of r.restarted) deps.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
+  }
+
+  const m = await deps.memory()
+  const mver = m.from || m.to ? ` ${m.from ?? '?'} → ${m.to ?? '?'}` : ''
+  deps.out(`memory: ${m.state}${m.package ? ` (${m.package}${mver})` : ''}${m.detail ? ` — ${m.detail}` : ''}\n`)
+  if (m.state === 'failed') failed = true
+
+  return { failed }
+}