@agfpd/iapeer 0.4.0 → 0.4.2

package/src/init/index.ts

@@ -21,6 +21,7 @@ import { IapError } from '../core/errors.ts'
 import {
   ensureLocalIapScaffold,
   pluginStateDir,
+  resolveGlobalRoot,
   writeFileAtomic,
   type StorageOptions,
 } from '../storage/index.ts'
@@ -245,6 +246,36 @@ export function ensureDoctrineTemplate(cwd: string): { path: string; created: bo
   return { path, created: true }
 }
 
+/**
+ * Create the GLOBAL host-doctrine template `~/.iapeer/IAPEER.md` if absent — the
+ * host-wide owner doctrine (Layer-2 GLOBAL in composeSystemPrompt, shared by EVERY
+ * peer; the general layer ABOVE each peer's own `.iapeer/IAPEER.md`). It is consumed at
+ * launch but was never scaffolded, so a fresh install left no host-doctrine file for the
+ * owner to find — asymmetric with the per-peer stub (ensureDoctrineTemplate). This
+ * mirrors that stub at host scope (discoverability + consistency). NEVER overwrites an
+ * existing host doctrine. Returns {path, created}.
+ */
+export function ensureGlobalDoctrineTemplate(env: NodeJS.ProcessEnv = process.env): { path: string; created: boolean } {
+  const root = resolveGlobalRoot(env)
+  const path = join(root, IAPEER_DOCTRINE_FILE)
+  if (existsSync(path)) return { path, created: false }
+  mkdirSync(root, { recursive: true })
+  writeFileSync(
+    path,
+    [
+      '# Host doctrine',
+      '',
+      '<!-- Host-wide rules shared by EVERY peer on this machine — the general layer,',
+      "     merged into every peer's system prompt at launch ABOVE that peer's own",
+      '     .iapeer/IAPEER.md. Replace this with your host-wide conventions. An empty',
+      '     file contributes nothing. -->',
+      '',
+    ].join('\n'),
+    { mode: 0o644 },
+  )
+  return { path, created: true }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // initPeer — orchestrate: provision (identity + registry + infra plist) + per-peer
 // ecosystem wiring (MCP transport per agentic runtime + doctrine template)

package/src/install/index.ts

@@ -13,10 +13,11 @@
 // signInstalledBinary (signing.ts) re-signs each install with the
 // stable local identity so the designated requirement — and the grants — survive.
 
-import { copyFileSync, existsSync, mkdirSync, renameSync, statSync } from 'fs'
+import { copyFileSync, cpSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
 import { homedir } from 'os'
-import { join } from 'path'
+import { basename, join, relative, sep } from 'path'
 import { spawnSync } from 'child_process'
+import { resolveGlobalRoot } from '../storage/index.ts'
 import { signInstalledBinary, type SigningOutcome } from './signing.ts'
 
 /** The stable host-wide install path of the `iapeer` binary. Standard user-bin (no
@@ -95,6 +96,64 @@ export function installIapeer(cliEntrypoint: string, env: NodeJS.ProcessEnv = pr
   return { binPath, prevPath, size, signing }
 }
 
+/**
+ * Scaffold an ecosystem package's docs to the STABLE, versioned, per-package host
+ * path `~/.iapeer/docs/<pkg>/` so an agent can read the contract OFFLINE (a compiled
+ * binary embeds no docs; the npm tarball's docs/ is discarded after install — proven:
+ * `iapeer update` extracts to a temp dir it rm's in a `finally`, and the bunx cache
+ * does not retain the package findably). This is the FOUNDATION-OWNED CONVENTION every
+ * ecosystem package follows: each copies its OWN docs on its OWN install/update, so a
+ * package's on-host docs always match its installed version.
+ *
+ * Mechanics: copy <docsSource> → ~/.iapeer/docs/<pkg> EXCLUDING internals/ (mirroring
+ * the npm `files` exclusion), via an atomic temp-dir swap so a reader never sees a
+ * half-copied tree. BEST-EFFORT — a missing source or copy hiccup NEVER fails the
+ * install (the binary works without on-host docs); the caller logs the outcome.
+ */
+export function scaffoldHostDocs(
+  pkg: string,
+  docsSource: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { copied: boolean; dest: string; reason?: string } {
+  const root = resolveGlobalRoot(env)
+  const dest = join(root, 'docs', pkg)
+  // Fail-closed sandbox guard (in spirit with assertInstallSandboxIsolated): never write
+  // the REAL machine ~/.iapeer under a sandboxed test that forgot to set IAPEER_ROOT.
+  // Compared against the ACTUAL OS home (homedir()), not env.HOME — the root IS the docs
+  // isolation, so an env.HOME-based check would false-trip when a test legitimately
+  // points IAPEER_ROOT at <tmp>/.iapeer (with env.HOME also <tmp>).
+  if (env.IAPEER_TEST_SANDBOX === '1' && root === join(homedir(), '.iapeer')) {
+    throw new Error(`refusing to scaffold docs into the REAL ${join(root, 'docs')} under IAPEER_TEST_SANDBOX=1 — set IAPEER_ROOT`)
+  }
+  if (!existsSync(docsSource)) return { copied: false, dest, reason: `docs source not found: ${docsSource}` }
+  const tmp = `${dest}.tmp-${process.pid}`
+  try {
+    rmSync(tmp, { recursive: true, force: true })
+    mkdirSync(join(dest, '..'), { recursive: true })
+    cpSync(docsSource, tmp, {
+      recursive: true,
+      // Skip the internals/ subtree (matches package.json files: "!docs/internals";
+      // returning false for a directory skips its whole subtree) and macOS .DS_Store
+      // cruft (the foundation is macOS-targeted, so every dev/host tree carries it).
+      filter: src => {
+        if (basename(src) === '.DS_Store') return false
+        const rel = relative(docsSource, src)
+        return rel !== 'internals' && !rel.startsWith(`internals${sep}`)
+      },
+    })
+    rmSync(dest, { recursive: true, force: true })
+    renameSync(tmp, dest)
+    return { copied: true, dest }
+  } catch (e) {
+    try {
+      rmSync(tmp, { recursive: true, force: true })
+    } catch {
+      /* best-effort cleanup */
+    }
+    return { copied: false, dest, reason: e instanceof Error ? e.message : String(e) }
+  }
+}
+
 /** The previous-binary path kept by the last install for one-step rollback. */
 export function iapeerPrevBinPath(env: NodeJS.ProcessEnv = process.env): string {
   return `${iapeerBinPath(env)}.prev`

package/src/launch/composeSystemPrompt.ts

@@ -103,6 +103,14 @@ export function composeSystemPrompt(input: ComposePromptInput): string {
   // The YAML identity block is the only Layer-1 section (synthesized, no marker).
   const sections: string[] = [yaml]
 
+  // Host-context pointer to the on-host ecosystem docs (FU6). Each package's install
+  // scaffolds its own contract docs to the stable, versioned, per-package path
+  // ~/.iapeer/docs/<package>/, so an agent can read "how does iapeer do X" offline
+  // instead of guessing. Synthesized Layer-1 fact (no marker). Wording: owner-approved.
+  sections.push(
+    'iapeer reference docs are on this host at ~/.iapeer/docs/ — one folder per package (start at iapeer/README.md). Consult them for how iapeer works instead of guessing.',
+  )
+
   // Layer 2 — IAPEER.md doctrine, GLOBAL then LOCAL (general → specific), each its
   // OWN marked file-section. The bash existence-gate (present-but-empty global → a
   // bare "\n") is dropped deliberately: an empty doctrine file now contributes no

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/tui/ansi.ts

@@ -0,0 +1,71 @@
+// ANSI palette for plain-text CLI output that runs OUTSIDE Ink — chiefly the
+// post-Ink onboard summary (run.tsx), which prints after the wizard unmounts and
+// would otherwise read as a flat, colorless tail to a styled flow.
+//
+// It mirrors the Ink wizard's palette one-for-one (see app.tsx color()/glyph()):
+//   ok → green ✓ · warn → yellow ! · fail → red ✗ · pending → gray · ·
+//   headers → bold (cyan for emphasis) · secondary detail/paths → dim
+// so the seam between the React-rendered part and the printed part is invisible.
+//
+// Color is GATED (colorEnabled): on by default only on a real TTY, force-on with
+// FORCE_COLOR (covers inherited-pipe passthrough by a child process), and hard-off
+// with NO_COLOR (https://no-color.org — presence disables, any value) so piped /
+// redirected / CI captures stay byte-clean. This is the team-wide convention we
+// hand to peer providers (e.g. iapeer-memory) whose stdout we surface verbatim.
+
+const ESC = '\x1b['
+const RESET = `${ESC}0m`
+
+const CODE = {
+  bold: '1',
+  dim: '2',
+  red: '31',
+  green: '32',
+  yellow: '33',
+  cyan: '36',
+  gray: '90',
+} as const
+
+export type AnsiPaint = (s: string) => string
+
+export interface Ansi {
+  bold: AnsiPaint
+  dim: AnsiPaint
+  red: AnsiPaint
+  green: AnsiPaint
+  yellow: AnsiPaint
+  cyan: AnsiPaint
+  gray: AnsiPaint
+}
+
+/** Whether to emit ANSI color for `stream`. NO_COLOR (any value) hard-disables;
+ *  FORCE_COLOR (truthy, not "0"/"false") forces on; otherwise gated on a real TTY. */
+export function colorEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+  stream: { isTTY?: boolean } = process.stdout,
+): boolean {
+  if (env.NO_COLOR != null) return false
+  const fc = env.FORCE_COLOR
+  if (fc != null && fc !== '0' && fc !== 'false' && fc !== '') return true
+  return stream.isTTY === true
+}
+
+/** Build a palette. When `enabled` is false every paint fn is identity (no codes),
+ *  so the same call sites produce clean text for pipes/CI. Codes compose: an inner
+ *  paint applies before the outer, both before the run resets — `a.bold(a.cyan(s))`
+ *  renders bold+cyan. */
+export function makeAnsi(enabled: boolean): Ansi {
+  const wrap =
+    (code: string): AnsiPaint =>
+    (s: string) =>
+      enabled ? `${ESC}${code}m${s}${RESET}` : s
+  return {
+    bold: wrap(CODE.bold),
+    dim: wrap(CODE.dim),
+    red: wrap(CODE.red),
+    green: wrap(CODE.green),
+    yellow: wrap(CODE.yellow),
+    cyan: wrap(CODE.cyan),
+    gray: wrap(CODE.gray),
+  }
+}

package/src/tui/onboard/app.tsx

@@ -219,8 +219,11 @@ export function OnboardApp({
       if (installed.length === 0) {
         set('auth', { status: 'warn', detail: 'no runtime installed' })
         adv.push(
-          '⚠ SETUP INCOMPLETE — no agent runtime found. iapeer needs Claude Code or Codex CLI\n' +
-            '  to run peers. Install one, sign in, then re-run `iapeer onboard`.',
+          '⚠ SETUP INCOMPLETE — no agent runtime found. iapeer needs an agent runtime: Claude Code OR Codex (either works).\n' +
+            '  Install EITHER (commands verified against the official docs), sign in, then re-run `iapeer onboard`:\n' +
+            '    Claude Code:  curl -fsSL https://claude.ai/install.sh | bash   (or: brew install --cask claude-code)\n' +
+            '    Codex:        npm install -g @openai/codex                     (or: brew install --cask codex)\n' +
+            '  If a download is blocked in your region, try the brew form or the other runtime.',
         )
       } else {
         const notes = installed.map(rt => runtimeAuthNote(rt, env)).filter((n): n is string => n != null)

package/src/tui/onboard/run.tsx

@@ -19,6 +19,7 @@
 import React from 'react'
 import { render } from 'ink'
 import { OnboardApp, type WizardResult } from './app.tsx'
+import { type Ansi, colorEnabled, makeAnsi } from '../ansi.ts'
 
 /** Sentinel: the environment is not a real interactive TTY — caller should fall
  *  back to the linear non-interactive onboard path (never render raw + hang). */
@@ -28,6 +29,36 @@ export interface OnboardWizardOptions {
   env?: NodeJS.ProcessEnv
 }
 
+/** Style one post-Ink summary line to match the Ink wizard exactly: the headline
+ *  (no leading glyph) bold — red when it announces errors; each item line keeps its
+ *  glyph colored by status (✓ green / ! yellow / ✗ red / · gray) and dims the
+ *  trailing " — detail", just as the in-wizard render does. */
+function paintSummaryLine(line: string, a: Ansi): string {
+  const m = line.match(/^(\s*)([✓!✗·]) (.*)$/)
+  if (!m) return /error/i.test(line) ? a.bold(a.red(line)) : a.bold(line)
+  const [, indent, mark, rest] = m
+  const paintMark = mark === '✓' ? a.green : mark === '!' ? a.yellow : mark === '✗' ? a.red : a.gray
+  const i = rest.indexOf(' — ')
+  const label = i >= 0 ? rest.slice(0, i) : rest
+  const detail = i >= 0 ? rest.slice(i) : ''
+  return `${indent}${paintMark(mark)} ${label}${detail ? a.dim(detail) : ''}`
+}
+
+/** Color a `prefix: state[ rest]` progress line by the state's semantics, matching
+ *  the wizard palette + the cross-CLI convention agreed with iapeer-memory: red for
+ *  failure, GRAY for a neutral skip/decline (· semantics — yellow is reserved for
+ *  warn/attention, not "user chose not to"), yellow for warn, green otherwise. */
+function paintResult(prefix: string, state: string, rest: string, a: Ansi): string {
+  const paint = /(fail|error|refus)/i.test(state)
+    ? a.red
+    : /(skip|declin)/i.test(state)
+      ? a.gray
+      : /(warn|missing|incomplete)/i.test(state)
+        ? a.yellow
+        : a.green
+  return `${a.bold(`${prefix}:`)} ${paint(state)}${rest}`
+}
+
 /** Render the interactive onboard wizard. Resolves with the process exit code, or
  *  WIZARD_NOT_INTERACTIVE when there is no real TTY to drive it. */
 export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise<number> {
@@ -35,6 +66,10 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
   if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
     return WIZARD_NOT_INTERACTIVE
   }
+  // Post-Ink lines are plain stdout (Ink has unmounted), so they carry their own
+  // ANSI to stay visually continuous with the wizard. Gated: real TTY here (the
+  // wizard only runs on one), off under NO_COLOR.
+  const a = makeAnsi(colorEnabled(env, process.stdout))
 
   let result: WizardResult = { code: 0, memoryConsent: false, telegramConsent: false, advisories: [], summary: [] }
   try {
@@ -57,54 +92,79 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
   try {
     if (result.telegramConsent) {
       const { onboardTelegramStep } = await import('../../onboard/steps.ts')
-      process.stdout.write('\nSetting up Telegram… (Ctrl-C to skip — add later: `iapeer create <you> --runtime telegram`)\n')
+      process.stdout.write(
+        '\n' +
+          a.bold('Setting up Telegram…') +
+          a.dim(' (Ctrl-C to skip — add later: `iapeer create <you> --runtime telegram`)') +
+          '\n',
+      )
       try {
         const ts = await onboardTelegramStep({ env })
-        process.stdout.write(`telegram: ${ts.state}${ts.detail ? ` — ${ts.detail}` : ''}\n`)
+        process.stdout.write(paintResult('telegram', ts.state, ts.detail ? ` — ${ts.detail}` : '', a) + '\n')
       } catch (e) {
-        process.stdout.write(`telegram: step skipped — ${e instanceof Error ? e.message : String(e)}\n`)
+        process.stdout.write(paintResult('telegram', 'step skipped', ` — ${e instanceof Error ? e.message : String(e)}`, a) + '\n')
       }
     } else {
-      process.stdout.write('\ntelegram: skipped — add later with `iapeer create <you> --runtime telegram`\n')
+      process.stdout.write(
+        '\n' + paintResult('telegram', 'skipped', ' — add later with `iapeer create <you> --runtime telegram`', a) + '\n',
+      )
     }
 
     if (result.memoryConsent) {
       const { onboardMemoryProvider } = await import('../../onboard/memory.ts')
       process.stdout.write(
-        '\nInstalling the shared-memory provider (@agfpd/iapeer-memory)…\n' +
-          'This can take a few minutes — it builds a native module. Memory is OPTIONAL:\n' +
-          'press Ctrl-C to skip it (set it up later with `npx @agfpd/iapeer-memory init`).\n\n',
+        '\n' +
+          a.bold('Installing the shared-memory provider (@agfpd/iapeer-memory)…') +
+          '\n' +
+          a.dim(
+            'This can take a few minutes — it builds a native module. Memory is OPTIONAL:\n' +
+              'press Ctrl-C to skip it (set it up later with `npx @agfpd/iapeer-memory init`).',
+          ) +
+          '\n\n',
       )
       try {
         const mem = await onboardMemoryProvider({ env, runtime: result.hostRuntime, timeoutMs: 12 * 60_000 })
         const label = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
-        process.stdout.write(`\nmemory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${label})\n`)
+        const rest = `${mem.detail ? ` — ${mem.detail}` : ''} ${a.dim(`(slot: ${label})`)}`
+        process.stdout.write('\n' + paintResult('memory', mem.state, rest, a) + '\n')
       } catch (e) {
-        process.stdout.write(
-          `\nmemory: step skipped — ${e instanceof Error ? e.message : String(e)} (set up later: \`npx @agfpd/iapeer-memory init\`)\n`,
-        )
+        const rest = ` — ${e instanceof Error ? e.message : String(e)} ${a.dim('(set up later: `npx @agfpd/iapeer-memory init`)')}`
+        process.stdout.write('\n' + paintResult('memory', 'step skipped', rest, a) + '\n')
       }
     } else {
-      process.stdout.write('\nmemory: skipped — set it up later with `npx @agfpd/iapeer-memory init`\n')
+      process.stdout.write(
+        '\n' + paintResult('memory', 'skipped', ' — set it up later with `npx @agfpd/iapeer-memory init`', a) + '\n',
+      )
     }
   } finally {
     process.removeListener('SIGINT', ignore)
     for (const h of prevInt) process.on('SIGINT', h as NodeJS.SignalsListener)
   }
 
-  // Final summary (plain text, post-Ink).
+  // Final summary (post-Ink, ANSI-styled to match the wizard's palette).
   process.stdout.write('\n')
-  for (const line of result.summary) process.stdout.write(line + '\n')
+  for (const line of result.summary) process.stdout.write(paintSummaryLine(line, a) + '\n')
   if (result.advisories.length > 0) {
     process.stdout.write('\n')
-    for (const a of result.advisories) process.stdout.write(a + '\n')
+    // Advisories mirror the wizard's yellow box (a multi-line entry stays yellow
+    // line-to-line until the trailing reset).
+    for (const adv of result.advisories) process.stdout.write(a.yellow(adv) + '\n')
   }
-  process.stdout.write('\nNext steps:\n')
-  process.stdout.write('  • Create your first agent:  iapeer create <name> --runtime claude\n')
+
+  // Next steps — an aligned 2-column block (label padded, command highlighted), the
+  // bot-token left as its own explicit step (no surprise / don't-make-them-guess).
+  const next: Array<{ label: string; cmd: string; note?: string }> = [
+    { label: 'Create your first agent', cmd: 'iapeer create <name> --runtime claude' },
+  ]
   if (result.telegramConsent) {
-    // The wizard set up the human peer (name + user_id) but NOT the bot itself —
-    // the bot token is a separate, explicit step (no surprise / don't-make-them-guess).
-    process.stdout.write('  • Activate Telegram:        iapeer connect telegram   (paste a bot token from @BotFather)\n')
+    next.push({ label: 'Activate Telegram', cmd: 'iapeer connect telegram', note: 'paste a bot token from @BotFather' })
+  }
+  const w = Math.max(...next.map(n => n.label.length))
+  process.stdout.write('\n' + a.bold('Next steps:') + '\n')
+  for (const n of next) {
+    process.stdout.write(
+      `  ${a.cyan('•')} ${n.label.padEnd(w)}   ${a.cyan(n.cmd)}${n.note ? '  ' + a.dim(`(${n.note})`) : ''}\n`,
+    )
   }
   return result.code
 }

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 }
+}