@agfpd/iapeer 0.4.2 → 0.4.4

package/README.md

@@ -76,6 +76,18 @@ Two ways to work with an agent locally in your terminal:
 
 Agents reach each other with `send_to_peer`; you can also message any peer over Telegram.
 
+## Bypass Permissions mode
+
+⚠️ **iapeer runs your Claude and Codex peers in bypass-permissions / no-sandbox mode — they execute tools (shell, file edits, network) without asking you to approve each action.** This is by design: a peer is a background, headless session with no human watching its terminal, so there is no one to answer a per-tool permission prompt. The launcher therefore starts Claude with `--dangerously-skip-permissions` and Codex with `--dangerously-bypass-approvals-and-sandbox`, and **auto-accepts the one-time "accept bypass mode" screen on your behalf** the first time a peer boots on a fresh machine.
+
+What this means for you, stated plainly:
+
+- A peer can run any command its runtime can run — read and write files across your home dir, install software, make network calls — with **no confirmation step**. There is no sandbox between an agent and your machine.
+- You are trusting the model's judgement (and the doctrine/instructions you give each peer) the same way you would trust a developer with a shell on your account.
+- iapeer does **not** silently weaken your own interactive `claude`/`codex` setup: the bypass acceptance is recorded per peer in the agent's own config, and the project-MCP pre-approval is written **project-locally** (under the peer's folder), never to your global user settings.
+
+Run iapeer on a host you control, give peers only the access they need, and treat a peer's instructions as security-relevant. `iapeer onboard` states this at setup; it is repeated here so the trade-off is explicit before you create your first agent. Details on every first-run dialog: [docs/07 — Install & update](docs/07-install-and-update.md#first-run-dialogs-on-a-clean-machine).
+
 ## What makes it different
 
 - **Real interactive CLI sessions, not headless one-shots.** Each AI peer is a full Claude Code or Codex CLI session, not a disposable `claude -p` / `codex exec` call (as of 2026-06-15, `claude -p` no longer counts against the subscription's main usage limits).

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

@@ -47,6 +47,24 @@ 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).
 
+## First-run dialogs on a clean machine
+
+On a fresh macOS host the first install → onboard → peer launch surfaces a handful of dialogs. iapeer auto-clears the agent runtimes' own first-run modals when it brings a peer up; **three** items are yours to do.
+
+**Auto-cleared (iapeer answers them on peer boot — you do nothing):**
+
+- **Claude** — the theme picker ("Choose the text style"), folder-trust, external-CLAUDE.md-import, and dev-channels modals (the launcher accepts the default with Enter); the **bypass-permissions accept** screen ("WARNING: Claude Code running in Bypass Permissions mode") that a *virgin* config shows the first time `--dangerously-skip-permissions` runs — its default cursor is "No, exit", so the launcher **steps the cursor to "Yes, I accept"** and confirms (never a bare Enter, which would exit); and the **project MCP-server approval** ("N new MCP servers found in this project") when the peer's cwd carries a `.mcp.json` — pre-approved at `iapeer init` via a project-local `enableAllProjectMcpServers` flag and Enter-confirmed on boot as a backstop. Claude records each accept natively, so a re-launch on the same config is dialog-free.
+- **Codex** — folder-trust ("Do you trust the contents of this directory") is pre-trusted at peer creation and also auto-accepted on boot; the self-update offer is disabled (`check_for_update_on_startup = false`) and auto-declined; hooks-review is auto-trusted.
+- **Bypass / no-sandbox is the operating mode, not a one-time prompt.** The launcher runs Claude with `--dangerously-skip-permissions` and Codex with `--dangerously-bypass-approvals-and-sandbox`, so peers execute tools without per-action approval (a headless peer has no human to approve each call). The one-time *acceptance* screen above is the only interactive gate; the mode itself then stays on for every turn. See the security note in the [README](../README.md#bypass-permissions-mode) — this is a deliberate, disclosed trade-off.
+
+**Three things you do (these cannot be automated):**
+
+1. **Log in to the runtimes — before onboard.** Sign in to Claude Code and Codex first. Their login screen is a browser OAuth flow that no headless peer can drive, so iapeer deliberately does **not** auto-answer it; a runtime that is installed but not signed in makes a peer fail its first wake loudly. `iapeer onboard` warns when it finds an unauthenticated runtime.
+2. **Login keychain password — once, during install.** The install code-signs the binary with a stable local identity so Full Disk Access survives updates; macOS asks for your login keychain password the one time that identity is created. It is expected (the installer announces it). If declined, the binary still works — TCC prompts would just recur on updates.
+3. **Full Disk Access — a manual grant, no prompt.** macOS TCC cannot be set by any flag, env var, or script. Without it, a peer reading or writing a TCC-protected path (an iCloud Obsidian vault, Desktop, Documents, Downloads) silently fails with EPERM — no prompt, no hang. Grant it in **System Settings → Privacy & Security → Full Disk Access** (`~/.iapeer` itself is under `$HOME` and needs nothing); onboard prints the reminder.
+
+Gatekeeper does not gate the locally-built CLI run from a terminal (no quarantine attribute). Verified live on a truly-virgin Claude config (claude 2.1.183): the theme picker, folder-trust, the bypass-permissions accept (cursor stepped to "Yes"), and the project MCP-server approval all auto-clear in sequence, the peer reaches its input prompt, and a second launch on the same config is dialog-free; the Codex folder-trust / update auto-clearing likewise (an owner's clean-machine install + an isolated first-boot test).
+
 ## Updating
 
 ```bash
@@ -74,6 +92,8 @@ Runtimes and memory are **best-effort**: a component failure is reported and the
 
 `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).
 
+> **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
 
 ```bash

package/docs/10-messaging.md

@@ -55,7 +55,7 @@ iapeer compact assistant       # compact the conversation
 
 `interrupt` stops a turn that's gone off-track or hung, without losing context. `compact` compacts the conversation; if the peer is asleep after a clean sleep, the daemon resumes it first, then compacts, and for an empty session it honestly answers that there's nothing to compact.
 
-Separate are **aliases** — shortcuts like `/alias-new`, `/alias-compact`, defined in the peer profile. These aren't control but text templates: the runtime expands an alias into its full text and delivers it to the peer as an ordinary message. So with one short command the operator runs a pre-written scenario (e.g. "save state to memory and restart fresh").
+Separate are **aliases** — shortcuts like `/alias_new`, `/alias_compact`, defined in the peer profile. These aren't control but text templates: the runtime expands an alias into its full text and delivers it to the peer as an ordinary message. So with one short command the operator runs a pre-written scenario (e.g. "save state to memory and restart fresh").
 
 ## Ephemeral workers
 

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,6 +47,24 @@ iapeer status
 
 Разбор каждого шага onboard — в [02 — Быстрый старт](02-быстрый-старт.md); рантаймы и память подробно — в [09](09-рантаймы.md) и [11](11-расширения-и-память.md).
 
+## Диалоги первого запуска на чистой машине
+
+На свежем macOS-хосте первый цикл install → onboard → запуск пира выводит несколько диалогов. Собственные first-run-модалки агент-рантаймов iapeer авто-снимает при поднятии пира; **три** пункта — на тебе.
+
+**Авто-снимается (iapeer отвечает на boot пира — от тебя ничего):**
+
+- **Claude** — theme-picker («Choose the text style»), folder-trust, импорт внешнего CLAUDE.md, dev-channels (лончер принимает дефолт через Enter); экран **принятия bypass-permissions** («WARNING: Claude Code running in Bypass Permissions mode»), который *виргин*-конфиг показывает при первом запуске `--dangerously-skip-permissions` — его курсор по умолчанию стоит на «No, exit», поэтому лончер **шагает курсором на «Yes, I accept»** и подтверждает (никогда не голый Enter — он бы вышел из сессии); и **аппрув проектных MCP-серверов** («N new MCP servers found in this project»), когда cwd пира несёт `.mcp.json` — пред-одобряется на `iapeer init` через проектно-локальный флаг `enableAllProjectMcpServers` и на boot подтверждается Enter'ом как страховка. Каждый accept claude записывает нативно, поэтому повторный запуск на том же конфиге уже без диалогов.
+- **Codex** — folder-trust («Do you trust the contents of this directory») пред-доверяется при создании пира и авто-принимается на boot; self-update-оффер отключён (`check_for_update_on_startup = false`) и авто-отклоняется; hooks-review авто-доверяется.
+- **Bypass / no-sandbox — это режим работы, а не разовый промпт.** Лончер запускает Claude с `--dangerously-skip-permissions`, а Codex с `--dangerously-bypass-approvals-and-sandbox`, поэтому пиры выполняют инструменты без поштучного аппрува (у headless-пира нет человека, который подтверждал бы каждый вызов). Разовый экран *принятия* выше — единственный интерактивный гейт; сам режим затем остаётся включённым на каждом ходу. См. security-заметку в [README](../../README.md#bypass-permissions-mode) — это намеренный, раскрытый компромисс.
+
+**Три пункта на тебе (автоматизировать нельзя):**
+
+1. **Залогинься в рантаймы — ДО onboard.** Войди в Claude Code и Codex заранее. Их экран логина — браузерный OAuth, который headless-пир не пройдёт, поэтому iapeer НАМЕРЕННО его не авто-отвечает; установленный, но не залогиненный рантайм роняет первый wake пира громко. `iapeer onboard` предупреждает, если найдёт неаутентифицированный рантайм.
+2. **Пароль логин-связки — один раз, при install.** Install подписывает бинарь стабильной локальной идентичностью, чтобы Full Disk Access пережил обновления; macOS один раз спросит пароль логин-связки при создании этой идентичности. Это ожидаемо (инсталлер анонсирует). При отказе бинарь всё равно работает — просто TCC-промпты будут повторяться на апдейтах.
+3. **Full Disk Access — ручной грант, без промпта.** macOS TCC нельзя выставить ни флагом, ни env, ни скриптом. Без него пир, читающий/пишущий TCC-защищённый путь (iCloud Obsidian vault, Desktop, Documents, Downloads), тихо падает с EPERM — без промпта, без зависания. Выдай в **System Settings → Privacy & Security → Full Disk Access** (`~/.iapeer` сам под `$HOME` и ничего не требует); onboard напомнит.
+
+Gatekeeper не гейтит локально собранный CLI, запускаемый из терминала (нет quarantine-атрибута). Проверено живьём на по-настоящему виргин-конфиге Claude (claude 2.1.183): theme-picker, folder-trust, принятие bypass-permissions (курсор шагнут на «Yes») и аппрув проектных MCP-серверов авто-снимаются по очереди, пир доходит до строки ввода, а повторный запуск на том же конфиге — уже без диалогов; codex folder-trust / update — аналогично (clean-install владельца + изолированный first-boot тест).
+
 ## Обновление
 
 ```bash
@@ -74,6 +92,8 @@ iapeer update --force           # переустановить, даже есл
 
 `iapeer update --foundation-only` делает только шаг 1 (узкий случай). Запиненный `iapeer update <версия>` — **только ядро** by design: пин версии специфичен для ядра (откат глубже одного шага или фиксация проверенной версии).
 
+> **Обновление с версии до каскада (< 0.4.2).** Каскад исполняет *установленный* бинарь, поэтому самый первый `iapeer update` со старой версии работает по СТАРОЙ (foundation-only) логике: он поднимает ядро до каскад-способного бинаря, но рантаймы + память пока не каскадит. Запусти `iapeer update` ещё раз — теперь новый бинарь докаскадит остальное. Это разовый bootstrap; начиная с 0.4.2 — одна команда. (Свежая установка сразу ставит каскад-способный бинарь, поэтому двойной прогон ей не нужен.)
+
 ## Откат
 
 ```bash

package/docs/ru/10-/320/276/320/261/320/274/320/265/320/275-/321/201/320/276/320/276/320/261/321/211/320/265/320/275/320/270/321/217/320/274/320/270.md

@@ -55,7 +55,7 @@ iapeer compact assistant       # сжать диалог
 
 `interrupt` останавливает зашедший не туда или зависший ход, не теряя контекст. `compact` сжимает диалог; если пир спит после чистого усыпления, демон сначала продолжит диалог, потом сожмёт, а для пустой сессии честно ответит, что сжимать нечего.
 
-Отдельно стоят **алиасы** — шорткаты вида `/alias-new`, `/alias-compact`, заданные в профиле пира. Это не контроль, а заготовки текста: рантайм разворачивает алиас в полный текст и доставляет его пиру как обычное сообщение. Так оператор одной короткой командой запускает заранее прописанный сценарий (например, «сохрани состояние в память и перезапустись свежим»).
+Отдельно стоят **алиасы** — шорткаты вида `/alias_new`, `/alias_compact`, заданные в профиле пира. Это не контроль, а заготовки текста: рантайм разворачивает алиас в полный текст и доставляет его пиру как обычное сообщение. Так оператор одной короткой командой запускает заранее прописанный сценарий (например, «сохрани состояние в память и перезапустись свежим»).
 
 ## Эфемерные воркеры
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",
@@ -44,9 +44,9 @@
     "test": "IAPEER_TEST_SANDBOX=1 bun test",
     "typecheck": "tsc --noEmit",
     "preversion": "npm run test && npm run typecheck",
-    "release": "npm version patch && npm publish && git push --follow-tags",
-    "release:minor": "npm version minor && npm publish && git push --follow-tags",
-    "release:major": "npm version major && npm publish && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push origin main --follow-tags",
+    "release:minor": "npm version minor && npm publish && git push origin main --follow-tags",
+    "release:major": "npm version major && npm publish && git push origin main --follow-tags",
     "prepublishOnly": "test -z \"$(git status --porcelain)\" || (echo 'release: working tree is dirty — commit or stash before release' >&2 && exit 1)"
   },
   "publishConfig": {

package/src/cli/index.ts

@@ -480,7 +480,7 @@ export interface NewPeerOutcome {
  * new <peer> [runtime] — the UNCONDITIONAL fresh-restart control command
  * (docs/Control-команды §new).
  *
- * The emergency lever for a HUNG or dead agent session: /alias-new covers only
+ * The emergency lever for a HUNG or dead agent session: /alias_new covers only
  * the COOPERATIVE path (a live peer reads the expanded prompt and runs
  * `iapeer self-fresh`); a stuck/raving/dead peer never reads a prompt — this
  * command restarts it MECHANICALLY, bypassing the peer entirely:
@@ -1253,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)
@@ -1288,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
@@ -1331,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,
@@ -1359,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`) })
@@ -1406,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
@@ -1570,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
@@ -1579,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
@@ -1589,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
@@ -1601,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`)
@@ -1622,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
@@ -1636,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
@@ -1645,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`)
@@ -1687,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).
@@ -1935,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': {
@@ -2009,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`)
@@ -2022,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`)
@@ -2036,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],
@@ -2066,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],
@@ -2081,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`)
@@ -2157,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)
@@ -2169,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)
       }
     }
@@ -2183,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/identity/profileStandard.ts

@@ -121,13 +121,13 @@ export function validateProfileStandard(raw: unknown, cwd: string): ProfileIssue
     issues.push({ severity: 'error', field: 'interfaces', message: 'must be a JSON object' })
   }
   // Legacy top-level aliases — contract relocates to the `expansion.aliases` plugin-
-  // config section with the /alias-* namespace (clean slash-keys are reserved for the
+  // config section with the /alias_* namespace (clean slash-keys are reserved for the
   // control layer). telegram-runtime owns that migration; flagged, not an error.
   if (obj.aliases !== undefined) {
     issues.push({
       severity: 'warn',
       field: 'aliases',
-      message: 'legacy top-level `aliases` — contract relocates to expansion.aliases (/alias-* namespace); owner migration pending',
+      message: 'legacy top-level `aliases` — contract relocates to expansion.aliases (/alias_* namespace); owner migration pending',
     })
   }
   // aliases misfiled in the PASSPORT (interfaces.telegram) — an interim home.

package/src/init/index.ts

@@ -6,16 +6,19 @@
 // THE BIG SIMPLIFICATION (install-gate, proven live): a peer gets send_to_peer
 // purely from a project-scope `.mcp.json` pointing at the host-wide HTTP-MCP daemon —
 // NO plugin install, NO /reload-plugins, NO GC version-snapshots (the whole legacy
-// persistent-peer install-gate class is gone). Verified: a cold-start claude session
-// (--dangerously-skip-permissions, as the launch primitive runs it) auto-enables the
-// `.mcp.json` http server and send_to_peer is callable on its FIRST turn, no approve.
+// persistent-peer install-gate class is gone). A cold-start claude session
+// (--dangerously-skip-permissions, as the launch primitive runs it) finds the
+// `.mcp.json` http server and send_to_peer is callable on its FIRST turn. The server's
+// project-approval is pre-granted by ensureClaudeProjectMcpEnabled (the
+// enableAllProjectMcpServers flag below); on a VIRGIN config without it the launch's
+// bootDialogKeys clears the one-time "new MCP servers found" dialog as a backstop.
 //
 // claude side here. codex side (`[mcp_servers.<name>]` in ~/.codex/config.toml +
 // default_tools_approval_mode="approve") lands with its own live codex check.
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
-import { join } from 'path'
+import { dirname, join } from 'path'
 import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER, IAPEER_DIR, isInfraRuntime, type Runtime } from '../core/constants.ts'
 import { IapError } from '../core/errors.ts'
 import {
@@ -26,6 +29,7 @@ import {
   type StorageOptions,
 } from '../storage/index.ts'
 import { provisionPeer, type ProvisionResult } from '../provision/index.ts'
+import { claudeSettingsPath } from '../launch/nativeMemory.ts'
 import { launchctlBootstrap, launchdPlistPath, type BootstrapResult } from '../launch/launchd.ts'
 import { runtimeSelfConfig, type SelfConfigResult } from '../runtime/index.ts'
 import type { Intelligence } from '../core/constants.ts'
@@ -116,6 +120,46 @@ export function writeClaudeMcpConfig(cwd: string, personality: string, daemonUrl
   return path
 }
 
+/**
+ * Idempotently enable project-scope MCP servers for a claude peer by merging
+ * `"enableAllProjectMcpServers": true` into `<cwd>/.claude/settings.json`.
+ *
+ * Why: on a VIRGIN claude config, the FIRST launch in a cwd carrying a `.mcp.json`
+ * (writeClaudeMcpConfig above) shows a BLOCKING "N new MCP servers found in this
+ * project" approval dialog BEFORE the input prompt — a headless peer has no one to
+ * approve it, so the wake stalls. This project-LOCAL flag pre-approves the cwd's MCP
+ * servers so the dialog never appears (verified live, claude 2.1.183). It is
+ * PROJECT-scoped (this peer's cwd only) — it does NOT touch the user's GLOBAL
+ * ~/.claude/settings.json, so it never alters the user's own claude environment (the
+ * same constraint that forbids a global skipDangerousModePermissionPrompt). The launch
+ * adapter's bootDialogKeys also Enter-confirms this dialog as a belt-and-suspenders
+ * backstop, so a peer whose cwd predates this flag still boots.
+ *
+ * NO-CLOBBER merge (the file may carry foreign blocks — plugin enables, statusline
+ * wrappers, the native-memory lever): parse/patch + atomic write; a non-object
+ * settings.json is REFUSED rather than overwritten. Returns the written path, or null
+ * when already set / on a refusal / on any error (best-effort, never throws — the
+ * bootDialogKeys backstop covers the dialog regardless).
+ */
+export function ensureClaudeProjectMcpEnabled(cwd: string): string | null {
+  const path = claudeSettingsPath(cwd)
+  try {
+    let obj: Record<string, unknown> = {}
+    if (existsSync(path)) {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as unknown
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null // refuse to clobber a non-object
+      obj = raw as Record<string, unknown>
+    }
+    if (obj.enableAllProjectMcpServers === true) return path // already enabled
+    obj.enableAllProjectMcpServers = true
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileAtomic(path, `${JSON.stringify(obj, null, 2)}\n`, 0o644)
+    return path
+  } catch {
+    return null // best-effort; the bootDialogKeys backstop still clears the dialog
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // codex MCP config (~/.codex/config.toml — HOST-WIDE; the token-free recipe)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -429,6 +473,10 @@ export async function initPeer(opts: InitPeerOptions): Promise<InitPeerResult> {
   // MCP client), so it gets no `.mcp.json`.
   if (provisioned.runtime === 'claude' || hasClaudeMarker(provisioned.cwd)) {
     mcpConfigPaths.push(writeClaudeMcpConfig(provisioned.cwd, provisioned.personality, daemonUrl))
+    // Pre-approve the cwd's project MCP servers so the FIRST virgin-config launch does
+    // not stall on the blocking "N new MCP servers found" dialog (project-local, never
+    // touches the user's global settings; bootDialogKeys is the backstop).
+    ensureClaudeProjectMcpEnabled(provisioned.cwd)
   }
   // codex: write the token-free host-wide config.toml block (dummy bearer flips codex's
   // auth gate; the OPEN daemon authenticates by the identity header). send_to_peer works

package/src/launch/adapters/claude.ts

@@ -50,11 +50,27 @@ const CLAUDE_BOOT_DIALOG_MARKERS = [
   'Resume from summary',
   'Resuming the full session',
   // First-run theme picker ("Let's get started. Choose the text style…") — appears
-  // on a CLEAN host (fresh config dir) BEFORE the input prompt, verified live on
-  // claude 2.1.181 in a pty. NOT removed by --dangerously-skip-permissions; if not
-  // cleared the peer never reaches ready. (There is NO separate "accept dangerous
-  // permissions" screen in 2.1.181 — verified absent.)
+  // on a CLEAN host (fresh config dir) BEFORE the input prompt. NOT removed by
+  // --dangerously-skip-permissions; if not cleared the peer never reaches ready.
   'Choose the text style',
+  // Bypass-permissions ACCEPT gate ("WARNING: Claude Code running in Bypass
+  // Permissions mode"; options "1. No, exit" / "2. Yes, I accept") — shown on a
+  // VIRGIN config the FIRST time --dangerously-skip-permissions runs, BEFORE the
+  // input prompt. (An earlier note here claimed this screen was "absent in 2.1.181";
+  // that was a NON-VIRGIN observation — the host had already accepted it once, so it
+  // was masked. On a truly virgin config it IS shown and BLOCKS the boot — verified
+  // live, claude 2.1.183 via tmux. bootDialogKeys steps the cursor to "2. Yes, I
+  // accept" and confirms; a bare Enter would hit the "1. No, exit" DEFAULT and kill
+  // the peer.) Once accepted, claude records it natively and the ready banner is the
+  // lowercase "bypass permissions on" (a DISTINCT string), so this marker vanishes —
+  // it never falsely traps isInputReady, and a re-launch is dialog-free (verified).
+  'Bypass Permissions mode',
+  // Project MCP-server approval ("N new MCP servers found in this project", servers
+  // pre-checked [✔]) — shown when cwd carries a .mcp.json the config has not yet
+  // approved. Suppressed at the source by enableAllProjectMcpServers in
+  // <cwd>/.claude/settings.json (init writes it); bootDialogKeys Enter-confirms it as
+  // a backstop. Substring matches both "1 new MCP server" and "N new MCP servers".
+  'new MCP server',
 ] as const
 
 function anyBootDialog(pane: string): boolean {
@@ -164,34 +180,43 @@ export const claudeAdapter: RuntimeAdapter = {
   /**
    * Map a visible startup dialog to the keys that clear it correctly:
    *
-   *   - RESUME COMPACT-PICKER ('Resume from summary …') → CURSOR-VERIFIED two-step.
-   *     This menu's cursor DEFAULTS to "1. Resume from summary (recommended)",
-   *     and selecting it COMPACTS the session (claude implements that choice as an
-   *     internal /compact) — but a resume must NOT trigger a compact. The original
-   *     blind ['Down','Enter'] burst (0e67e1f) put BOTH keys into one pty chunk;
-   *     under a heavy resume (a 313k-token session) the TUI dropped the Down and
-   *     the Enter confirmed the DEFAULT →
-   *     silent /compact (proven: pane log shows the picker frame with ❯ on
-   *     option 1 followed by "❯ /compact"; transcript compactMetadata
-   *     trigger=manual). Fix: ONE key per boot-iteration — Down while the cursor
-   *     is NOT yet seen on "2. Resume full session", Enter ONLY after the
-   *     captured pane PROVES it ("❯ 2."). A swallowed Down self-heals on the
-   *     next 2 s iteration; Enter can never hit the compacting default. If the
-   *     picker layout ever changes, the loop Downs until the boot deadline and
-   *     the wake fails LOUD — never a silent compact.
-   *   - OTHER MODALS (folder-trust / external-import / dev-channels) → ['Enter']:
-   *     their default-highlighted option IS the proceed path, so a bare Enter clears
-   *     each (claude-start.sh:341).
+   *   - CURSOR-VERIFIED two-step menus ('Resume from summary …' AND 'Bypass
+   *     Permissions mode') → step Down, confirm ONLY once the captured pane proves
+   *     the cursor sits on "2.". Both menus share one hazard: their DEFAULT cursor is
+   *     the WRONG option, so a blind Enter picks it.
+   *       · Resume: default "1. Resume from summary (recommended)" COMPACTS the
+   *         session (claude runs that choice as an internal /compact) — a resume must
+   *         not compact.
+   *       · Bypass: default "1. No, exit" makes the peer EXIT (die). "2. Yes, I
+   *         accept" is the proceed path. (Virgin-config gate the first time
+   *         --dangerously-skip-permissions runs; once accepted claude persists it.)
+   *     The original blind ['Down','Enter'] burst (0e67e1f) put BOTH keys in one pty
+   *     chunk; under load the TUI dropped the Down and the Enter confirmed the DEFAULT
+   *     (proven for resume: pane frame ❯ on option 1 → "❯ /compact"). Fix: ONE key
+   *     per boot-iteration — Down while the cursor is NOT yet on "2.", Enter ONLY
+   *     after the captured pane PROVES it ("❯ 2."). A swallowed Down self-heals next
+   *     iteration; Enter can never hit the bad default. If the layout ever changes the
+   *     loop Downs until the boot deadline and the wake fails LOUD.
+   *   - SINGLE-CONFIRM modals (folder-trust / external-import / dev-channels / theme /
+   *     project MCP-server approval) → ['Enter']: the default-highlighted option IS
+   *     the proceed path, so a bare Enter clears each. The MCP approval pre-checks the
+   *     servers [✔] (Enter enables them, Esc rejects all) — it is also suppressed at
+   *     the source by enableAllProjectMcpServers (init), so the Enter here is a
+   *     backstop. (claude-start.sh:341.)
    *   - anything else (incl. the post-select "Resuming…" load state) → null (wait).
    */
   bootDialogKeys(pane: string): string[] | null {
-    if (pane.includes('Resume from summary')) {
+    if (pane.includes('Resume from summary') || pane.includes('Bypass Permissions mode')) {
       return /❯\s*2\./.test(pane) ? ['Enter'] : ['Down']
     }
     if (
       pane.includes('trust this folder') ||
       pane.includes('Allow external CLAUDE.md file imports?') ||
       pane.includes('I am using this for local development') ||
+      // Project MCP-server approval (servers pre-checked [✔]; Enter confirms, Esc
+      // rejects all). enableAllProjectMcpServers normally suppresses it; this is the
+      // backstop. Matches both "1 new MCP server" and "N new MCP servers".
+      pane.includes('new MCP server') ||
       // First-run theme picker (clean host): the default-highlighted row is always a
       // valid theme (any choice is harmless for a headless peer), so a bare Enter
       // accepts it. Without this the picker blocks the boot forever on a fresh host.

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/transport/index.ts

@@ -936,7 +936,7 @@ export interface ControlResult {
  * acts on a running session — a non-live peer has nothing to interrupt) then
  * executeControlOnTarget. Without a runtime, resolves the single live runtime (2+ →
  * "specify runtime"). The clean-slash control namespace (interrupt/compact/…) is the
- * caller's; /alias-* expansions are message, not control (docs/Control §namespace).
+ * caller's; /alias_* expansions are message, not control (docs/Control §namespace).
  */
 export async function routeControl(personality: string, runtime: string | undefined, command: ControlCommand): Promise<Result<ControlResult>> {
   if (!isValidName(personality)) {