@agfpd/iapeer 0.2.97 → 0.2.99

package/docs/ru/13-/320/260/321/200/321/205/320/270/321/202/320/265/320/272/321/202/321/203/321/200/320/260-/320/270-/320/272/320/276/320/275/321/202/321/200/320/260/320/272/321/202.md

@@ -0,0 +1,190 @@
+# 13 — Архитектура и контракт
+
+**Русский** · [English](../13-architecture-and-contract.md)
+
+Раздел для тех, кто разрабатывает под iapeer: рантайм-пакеты, capability-плагины, провайдеры памяти.
+
+## Инварианты
+
+На них держится поведение системы:
+
+- **Один роутер.** В системе ровно один постоянно работающий демон. Все сообщения идут через него; второго маршрутизатора нет.
+- **Идентичность на каждый запрос.** Демон не хранит сессию клиента — он определяет, кто к нему обратился, из заголовка `X-IAPeer-Identity` каждого MCP-запроса. Один слушатель обслуживает всех пиров.
+- **Единственный писатель реестра.** `peers-profiles.json` пишется только через одного писателя под файловой блокировкой. Прямая запись файла запрещена на уровне ядра — это исключает гонки.
+- **Живость определяется live-сессией пира.** Пир жив тогда и только тогда, когда у него есть живая сессия под супервизором. Это не отдельный флаг в состоянии, который можно рассинхронизировать, а наблюдаемый факт.
+- **`доставлено` ⟺ легло в живую сессию.** Успех доставки означает, что сообщение принято живой сессией (демон дождался подтверждения). Не подтвердила — демон считает сессию мёртвой, а не лжёт об успехе.
+- **Источник истины — локальный профиль.** Реестр — пересобираемая проекция профилей пиров. При расхождении прав профиль.
+- **Бинарь установлен на хост.** Демон работает с установленного `~/.local/bin/iapeer`, а не из рабочего дерева исходников. Обновление — это замена бинаря и перезапуск демона на него.
+
+## Рантайм-адаптеры на стороне ядра
+
+Адаптер — слой ядра, который умеет запускать сессию рантайма. Все адаптеры реализуют единый интерфейс; различия рантаймов спрятаны за ним.
+
+Ключевые свойства адаптера:
+
+- **`kind`** — `tui` (интерактивная сессия, принимает ввод: claude, codex) или `router` (долгоживущий процесс без ввода: telegram, notifier).
+- **`usesDoctrine`** — потребляет ли рантайм собранный системный промпт. Для TUI-агентов — да, для роутеров — нет (это не языковые модели).
+- **`requiresIntelligence`** — гейт по природе пира. У `telegram` это `natural`: попытка завести Telegram-присутствие у не-человека отклоняется с явной ошибкой.
+- **`buildArgv`** — как собрать команду запуска: для роутеров это `<рантайм>-runtime run` плюс дополнительные аргументы из `launch.env`.
+
+Роутеры пропускают все TUI-фазы: у них нет загрузочных диалогов, маркеров готовности, подтверждения доставки и контрольных команд. Их живость держит launchd, а не пробуждение демоном.
+
+Продакшен-механизм хостинга TUI-сессий — **pty-супервизор**: супервизор-демон владеет pty сессии и её pane-логом, через его сокет идёт доставка на ввод. tmux остаётся только внутренней dev-ветвью (shadow-branch), на пользовательском уровне не фигурирует.
+
+## Контракт рантайм-пакета
+
+Рантайм-пакет (`*-runtime`) — npm-пакет, добавляющий инфраструктурный рантайм. Примеры: `@agfpd/notifier-runtime`, `@agfpd/telegram-runtime`.
+
+### Манифест runtime.json
+
+Пакет при self-install пишет манифест в `~/.iapeer/runtimes/<рантайм>/runtime.json`. Ядро его читает.
+
+```json
+{
+  "runtime": "notifier",
+  "version": "0.2.0",
+  "selfConfig": { "command": "notifier-runtime", "args": ["self-config"] },
+  "peers": [
+    { "personality": "timer",   "intelligence": "absent", "description": "Планировщик по расписанию" },
+    { "personality": "watcher", "intelligence": "absent", "description": "Наблюдатель за событиями" }
+  ]
+}
+```
+
+| Поле | Тип | Обязательность | Назначение |
+|---|---|---|---|
+| `runtime` | строка | обязательно | ID рантайма, совпадает с именем папки; шаблон `^[a-z][a-z0-9]{0,31}$` |
+| `version` | строка | опционально | Версия пакета. Используется для гейта при `update-runtime`; без неё обновление просто переустанавливает |
+| `selfConfig` | дескриптор | опционально | Хук персональной настройки, вызывается ядром на каждого пира при провижне |
+| `peers` | массив | опционально | Объявленный набор пиров. Есть — режим declared-set; нет — operator-add |
+
+Элемент `peers[]`: `personality` (обязательно), `intelligence`, `description`, `path` (явная папка), `runtimeBin` (путь лаунчера) — последние четыре опциональны.
+
+**Дескриптор** (`selfConfig` и подобные) — это `{ "command": "...", "args": [...] }` или просто строка-команда.
+
+### Два режима развёртывания
+
+- **declared-set** — манифест содержит `peers[]`. `iapeer install-runtime <рантайм>` разворачивает весь набор сразу (notifier разворачивает `timer` и `watcher`).
+- **operator-add** — `peers[]` пуст или отсутствует. Пиров заводит оператор по одному: `iapeer create <имя> --runtime <рантайм>` (так подключают людей в telegram).
+
+### Что ядро вызывает у пакета
+
+Контракт минимален — ядро обращается к пакету ровно тремя способами:
+
+1. **`npx <пакет>`** — при установке. Пакет идемпотентно раскладывает свой бинарь на `PATH` и пишет `runtime.json`.
+2. **`<рантайм>-runtime run`** — при запуске сессии (через launchd-плист или launch). В окружении — `PEER_PERSONALITY`, `PEER_RUNTIME`, `PEER_IDENTITY`.
+3. **Хук `selfConfig`** — при провижне каждого пира. Вызывается в рабочей папке пира; в окружении — `IAPEER_PEER_PERSONALITY`, `IAPEER_PEER_CWD`, `IAPEER_PEER_RUNTIME`, `IAPEER_PEER_INTELLIGENCE`. Код возврата 0 — настроено (идемпотентно), иначе — ошибка (плист пишется, но не загружается).
+
+Команды вроде `prepare`, `interface`, `bot`, `doctor` — это внутренние команды самого пакета для оператора, а не контракт с ядром: ядро их не вызывает.
+
+### Установка и обновление
+
+- **`install-runtime <рантайм>`** определяет npm-пакет (по встроенному реестру или флагу `--package`), ставит его через `npx`, затем разворачивает объявленный набор пиров.
+- **`update-runtime <рантайм>`** сверяет версию манифеста с npm; при отставании переустанавливает, заново провизионирует и перезапускает пиров рантайма штатными `stop`/`start`.
+
+## Стандарт capability-плагина
+
+Capability-плагин добавляет пиру способность, не будучи рантаймом. Отличие чёткое: рантайм — способ присутствия пира, плагин — способность поверх рантайма.
+
+### Манифест iapeer.json
+
+Плагин может (но не обязан) положить в свой корень `iapeer.json`:
+
+| Поле | Тип | Назначение |
+|---|---|---|
+| `setup` | дескриптор | Шаг установки плагина. Вызывается при `enable`, если объявлен и установка прошла |
+| `requires` | — | Зависимости (рантаймы, другие плагины). Ядро их не разрешает — плагин проверяет их сам и отказывает, если зависимости нет |
+
+Плагин без `iapeer.json` или без `setup` — это простой класс: ставится и включается, дополнительной инициализации нет.
+
+### enable
+
+`iapeer enable <плагин> [пир]` по шагам:
+
+1. Находит пир (по имени или по текущей папке); отказывает, если у пира нет агентского рантайма.
+2. На каждом агентском рантайме пира ставит плагин: для Claude — в область проекта внутри папки пира (`plugin install … --scope project`), для Codex — в общий конфиг хоста. Установка попутно включает плагин.
+3. Если объявлен `setup` и установка удалась — вызывает его. В окружении: `IAPEER_PEER_PERSONALITY`, `IAPEER_PEER_CWD`; рабочая папка — корень плагина. Шаг best-effort: его сбой не откатывает уже сделанные установку и включение.
+
+Идемпотентность: для Claude привязка идёт по реальному пути папки пира, поэтому повторный `enable` не задевает другие пиры и не дублирует установку.
+
+### Критерии iapeer-совместимости
+
+Плагин считается совместимым, если он:
+
+1. полезен сам по себе;
+2. объявляет, что предоставляет и что требует;
+3. не владеет чужой ответственностью;
+4. имеет идемпотентную подготовку;
+5. имеет самодиагностику (`doctor`/`status`);
+6. использует общий ABI идентичности (`PEER_*`), когда тот доступен;
+7. не требует от пользователя вручную синхронизировать идентичность между плагинами;
+8. одинаково понимает имя, рантайм и идентичность под Claude, Codex и будущими рантаймами.
+
+## Контракт слота памяти
+
+Память даёт провайдер, занимающий единственный на хост слот. Слот занят ровно одним провайдером или пуст.
+
+### Манифест провайдера
+
+Провайдер атомарно пишет `~/.iapeer/memory-provider.json`; ядро только читает. Удаляет файл — освобождает слот. Ядро слот никогда не пишет.
+
+```json
+{
+  "provider": "iapeer-memory",
+  "package": "@agfpd/iapeer-memory",
+  "version": "0.2.7",
+  "registeredAt": "2026-06-11T17:46:41.449Z",
+  "heartbeat": "/Users/me/.iapeer/state/iapeer-memory/memoryd.heartbeat",
+  "provision": {
+    "command": "/Users/me/.local/bin/iapeer-memory",
+    "args": ["provision-peer", "--cwd", "{cwd}", "--runtime", "{runtime}",
+             "--personality", "{personality}", "--occasion", "{occasion}"]
+  },
+  "unprovision": {
+    "command": "/Users/me/.local/bin/iapeer-memory",
+    "args": ["unprovision-peer", "--cwd", "{cwd}", "--runtime", "{runtime}",
+             "--occasion", "{occasion}"]
+  }
+}
+```
+
+| Поле | Тип | Обязательность | Назначение |
+|---|---|---|---|
+| `provider` | строка | обязательно | Имя провайдера |
+| `package` | строка | обязательно | npm-пакет |
+| `version` | строка | обязательно | Версия пакета |
+| `registeredAt` | ISO-дата | обязательно | Когда занят слот |
+| `heartbeat` | путь | опционально | Файл сердцебиения демона провайдера; `iapeer status` показывает его свежесть |
+| `provision` | дескриптор | опционально | Команда настройки памяти пира при рождении |
+| `unprovision` | дескриптор | опционально | Команда сворачивания при удалении пира |
+
+`command` обязан быть абсолютным путём; `args` — массив строк. Невалидный блок ядро трактует как отсутствующий, пустой слот — как нормальное состояние.
+
+### Команды provision/unprovision
+
+В аргументах подставляются четыре плейсхолдера (подстановка пер-аргумент, на уровне подстроки):
+
+| Плейсхолдер | Значение |
+|---|---|
+| `{cwd}` | рабочая папка пира |
+| `{runtime}` | конкретный агентский рантайм (`claude` / `codex`) |
+| `{personality}` | имя пира — обязан совпадать с `normalize(basename({cwd}))` (имя пира и папка соотносятся 1:1); несовпадение → `ensurePeerProfile` завершается ошибкой |
+| `{occasion}` | момент вызова (см. ниже) |
+
+**Моменты вызова, которые эмитит ядро:**
+
+- **`birth`** — при рождении пира, по одной команде на каждый агентский рантайм. Идёт после предварительного доверия codex к папке, чтобы поверхности провайдера легли в уже доверенную папку.
+- **`remove`** — при удалении пира, по команде на агентский рантайм. Идёт до очистки состояния пира — провайдер видит его в последнем согласованном виде.
+
+**Окружение:** команда наследует всё окружение ядра; специальные `IAPEER_PEER_*` сюда ядро **не** добавляет — провайдер опирается на плейсхолдеры в аргументах. stdin игнорируется, stdout/stderr захватываются.
+
+**Семантика выполнения:** код возврата 0 — успех; иначе — ошибка; превышение 120 секунд — таймаут; недоступный бинарь — отдельный исход. Всё best-effort: сбой команды не валит ни рождение, ни удаление пира, но громко логируется. Провайдер обязан быть идемпотентным — ядро может вызвать одну команду повторно.
+
+### Рычаг родной памяти
+
+Когда слот занят, держать параллельно родную память рантайма вредно. Ядро при рождении пира с занятым слотом отключает её:
+
+- **Claude** — в `<папка>/.claude/settings.json` дописывает `"autoMemoryEnabled": false`;
+- **Codex** — в `<папка>/.codex/config.toml` дописывает `[features] memories = false`.
+
+Включить обратно — удалить ключ (восстановить умолчание рантайма). Вручную: `iapeer native-memory off|on`. Для Codex ядро при рождении заодно прописывает доверие к папке (`[projects."<реальный-путь>"] trust_level = "trusted"`), чтобы проектный конфиг читался с первой сессии; при удалении пира эта запись снимается.

package/docs/ru/14-/320/272/320/276/320/275/321/204/320/270/320/263/321/203/321/200/320/260/321/206/320/270/321/217-/320/270-/320/266/321/203/321/200/320/275/320/260/320/273/321/213.md

@@ -0,0 +1,91 @@
+# 14 — Конфигурация и журналы
+
+**Русский** · [English](../14-configuration-and-logs.md)
+
+Ядро работает на разумных значениях по умолчанию — отдельная настройка для запуска не нужна. Поведение тонко настраивается переменными окружения; журналы дают материал для разбора, когда что-то пошло не так.
+
+## Переменные окружения
+
+Все значения ниже — дефолты из текущего кода. Переменную задают в окружении демона или конкретного пира (через `launch.env`, см. [06 — Хранение](06-хранение.md)).
+
+### Жизненный цикл
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_IDLE_SECS` | `3600` | Через сколько секунд простоя демон закрывает сессию агента (усыпление). |
+| `IAPEER_BOOT_DEADLINE_SECS` | `240` | Сколько ждать загрузки сессии при подъёме, прежде чем считать запуск неудачным. |
+| `IAPEER_READY_GATE_SECS` | `120` | Сколько ждать готовности агента к вводу после загрузки. |
+| `IAPEER_CRASHLOOP_MAX` | `3` | Сколько смертей в окне допускается, прежде чем демон перестанет поднимать пир. |
+| `IAPEER_CRASHLOOP_WINDOW_SECS` | `300` | Окно (секунды), на котором считаются смерти для защиты от цикла перезапусков. |
+| `IAPEER_EPHEMERAL_QUIET_SECS` | `20` | Окно тишины, после которого свернётся эфемерный воркер, уже отправивший ответ. |
+| `IAPEER_EPHEMERAL_UNARMED_IDLE_SECS` | `600` | Страховочный предел для эфемерного воркера, который молчит и не отправил ответ. |
+
+Надзорный тик демона фиксирован — раз в минуту, не настраивается.
+
+### Демон
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_PORT` | `8765` | TCP-порт роутера на `127.0.0.1`. |
+| `IAPEER_DAEMON_SOCKET` | `~/.iapeer/state/iapeer/router.sock` | Путь локального сокета демона. |
+| `IAPEER_BEARER_TOKEN` | — | Если задан, демон требует этот bearer-токен на входе; иначе проверка токена выключена. |
+
+### Доставка сообщений
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAP_HOST_LIVENESS_GRACE_MS` | `4000` | Сколько ждать подтверждения, что сессия приняла сообщение, прежде чем считать её мёртвой. |
+| `IAP_LIVENESS_GRACE_MS` | `3000` | Окно проверки живости занятой сессии (по сдвигу истории диалога). |
+| `IAPEER_COMPOSER_QUEUE_TIMEOUT_MS` | `120000` | Сколько очередь композера ждёт, пока освободится поле ввода, прежде чем досылать принудительно. |
+| `IAPEER_COMPOSER_QUEUE_POLL_MS` | `500` | Частота опроса поля ввода в очереди композера. |
+
+### Пути и бинарники
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_ROOT` | `~/.iapeer` | Корень хранилища. Смена влечёт изоляцию сокетов в `<корень>/socks` (полезно для изолированных тестовых хостов). |
+| `IAPEER_SOCK_DIR` | `/tmp` | Каталог сокетов host-wide. Переопределяет расположение host-wide. |
+| `IAPEER_BIN_DIR` | `~/.local/bin` | Куда ставится бинарь `iapeer`. |
+| `IAPEER_LAUNCHAGENTS_DIR` | `~/Library/LaunchAgents` | Каталог плистов launchd. |
+| `IAPEER_CLAUDE_BIN` | `~/.local/bin/claude` | Путь к бинарю Claude. |
+| `IAPEER_CODEX_BIN` | `codex` (из `PATH`) | Путь к бинарю Codex. |
+| `NOTIFIER_RUNTIME_BIN` | `notifier-runtime` (из `PATH`) | Путь к лаунчеру notifier (для launchd с его минимальным `PATH`). |
+| `TELEGRAM_RUNTIME_BIN` | `telegram-runtime` (из `PATH`) | Путь к лаунчеру Telegram. |
+| `CODEX_HOME` | `~/.codex` | Переопределение каталога глобального конфига Codex. |
+
+### Журналы
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_LIFECYCLE_LOG_MAX_BYTES` | `5 МиБ` | Размер `lifecycle.log`, при котором происходит ротация. |
+| `IAPEER_LIFECYCLE_LOG_KEEP` | `5` | Сколько ротаций `lifecycle.log` хранить. |
+| `IAPEER_DELIVERY_LOG_MAX_BYTES` | `5 МиБ` | Размер `delivery.log` для ротации. |
+| `IAPEER_DELIVERY_LOG_KEEP` | `5` | Сколько ротаций `delivery.log` хранить. |
+| `IAPEER_SUPERVISE_LOG_VERBOSE` | выкл. | Подробный лог надзорных тиков (по умолчанию пишутся только решения, не рутинные «ничего не делаю»). |
+| `IAPEER_DAEMON_LOG` | выкл. | Расширенный лог демона. |
+
+### Внутренние, dev и тестовые
+
+`IAPEER_TEST_SANDBOX=1` включает защиту от записи в реальные пути: установка откажется писать в настоящий `~/.local/bin/iapeer` и потребует задать `IAPEER_BIN_DIR` на изолированный путь. Для разработки и автотестов, не для обычной работы.
+
+Ещё несколько переменных система читает, но в обычной эксплуатации их не задают:
+
+- `NOTIFIER_FALLBACK_TARGET` — запасной адресат для сигналов notifier; ядро резолвит его в плист пира при онбординге (без хардкода), вручную оператор его не выставляет.
+- `IAP_TMUX_PASTE_SETTLE_MS`, `IAP_TMUX_SUBMIT_TIMEOUT_MS` — тайминги доставки во внутренней tmux dev-ветви; на проде используется pty-супервизор ([13 — Архитектура и контракт](13-архитектура-и-контракт.md)), вне разработки не нужны.
+- `IAPEER_SHADOW_PATH` — `PATH` для shadow-fidelity прогона (внутренний инструмент разработки).
+
+## Журналы и диагностика
+
+Демон ведёт три долговременных журнала в `~/.iapeer/logs/iapeer/`:
+
+- **`lifecycle.log`** — решения жизненного цикла: пробуждения, усыпления, перезапуски, итоги надзорных тиков. Первое место, куда смотреть, если пир ведёт себя не так.
+- **`delivery.log`** — исход каждой доставки: кто, кому, в какой рантайм, результат, размеры, тема. Только метаданные — **тело сообщения не пишется**.
+- **`exits.log`** — смерти сессий с посмертными данными: супервизор фиксирует причину (код выхода / сигнал) в момент смерти сессии.
+
+### Посмертная диагностика
+
+Причину смерти сессии (код выхода / сигнал) супервизор фиксирует в момент смерти — это то, что обычная проверка «жив ли процесс» не ловит. Отдельный сторож (canary) держит соединение с супервизором и при смерти сессии записывает в `exits.log` обстоятельства: память, swap, процессы по потреблению, системные отчёты диагностики. Это материал для ответа на вопрос «почему агент умер».
+
+### Full Disk Access
+
+Чтобы читать системные отчёты диагностики, бинарю `iapeer` нужен Full Disk Access (FDA) — разрешение macOS. `iapeer status` показывает, выдан ли FDA, и подсказывает, что делать, если нет. Без FDA пиры будут натыкаться на запросы TCC при доступе к защищённым папкам и контейнерам сторонних приложений.

package/docs/ru/README.md

@@ -0,0 +1,97 @@
+# iapeer
+
+**Русский** · [English](../README.md)
+
+iapeer — ядро мультиагентной системы на одном хосте. Он держит реестр участников, единый демон-роутер для обмена сообщениями между ними и набор команд, которыми участниками управляют: создают, запускают, усыпляют, перезапускают, подключают к внешним каналам.
+
+Участник системы называется **пиром**. Пиром может быть AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс (планировщик, наблюдатель). iapeer не различает их по природе на уровне транспорта — все они адресуются одинаково и обмениваются сообщениями через один протокол.
+
+```text
+   send_to_peer (от любого пира)
+        │
+        ▼
+   ┌────────────────────────┐
+   │      демон-роутер        │   работает постоянно
+   │   поиск · доставка       │   читает peers-profiles.json (реестр)
+   └────────────────────────┘
+        │
+        ▼
+   пир-получатель  (если спит — поднимет)
+```
+
+## Что это решает
+
+Когда на машине живёт не один агент, а команда — у каждого своя роль, своя рабочая папка, свой рантайм, — возникают задачи, которых у одиночного агента нет:
+
+- **Адресация.** Как агенту A отправить сообщение агенту B, не зная, запущен ли тот прямо сейчас.
+- **Присутствие.** Держать ли каждого агента в памяти постоянно (дорого) или поднимать по требованию (нужен кто-то, кто поднимет).
+- **Идентичность.** Один и тот же логический агент может присутствовать в разных рантаймах (сегодня Claude, завтра Codex) — система должна понимать, что это один и тот же пир.
+- **Жизненный цикл.** Кто усыпит простаивающего агента, кто перезапустит зависшего, кто не даст упавшему агенту войти в цикл перезапусков.
+
+iapeer берёт это на себя. Агенту достаточно вызвать `send_to_peer(<имя>, <текст>)` — остальное делает демон: найдёт получателя в реестре, проверит, жив ли он, доставит сообщение в живую сессию или поднимет спящего и доставит после пробуждения.
+
+## Быстрый старт
+
+Требования: **macOS** (управление процессами идёт через launchd), **[bun](https://bun.sh)** на `PATH` и хотя бы один агентский рантайм — Claude Code или Codex CLI.
+
+```bash
+# 1. Установите ядро — бинарь, раскладку ~/.iapeer и плист демона
+npx @agfpd/iapeer
+
+# 2. Подготовьте хост — onboard стартует демон, регистрирует marketplace,
+#    ставит notifier, Telegram и память
+iapeer onboard
+
+# 3. Создайте первого агента
+iapeer create assistant --runtime claude
+
+# 4. Отправьте сообщение — демон поднимет сессию, если её нет
+iapeer send assistant --message "привет, ты на связи?"
+```
+
+Подробный разбор каждого шага — в [02 — Быстрый старт](02-быстрый-старт.md).
+
+## Документация
+
+Разделы выстроены слоями: от «поставить и пользоваться» к «понять архитектуру и расширять».
+
+**Введение**
+- [01 — Обзор](01-обзор.md) — что такое iapeer и из чего он состоит
+- [02 — Быстрый старт](02-быстрый-старт.md) — установка, онбординг, первый пир, первое сообщение
+
+**Концепции**
+- [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md)
+- [04 — Жизненный цикл и демон](04-жизненный-цикл-и-демон.md)
+- [05 — Идентичность и системный промпт](05-системный-промпт.md)
+- [06 — Хранение](06-хранение.md)
+
+**Руководства**
+- [07 — Установка и обновление](07-установка-и-обновление.md)
+- [08 — Управление пирами](08-управление-пирами.md)
+- [09 — Рантаймы](09-рантаймы.md)
+- [10 — Обмен сообщениями](10-обмен-сообщениями.md)
+- [11 — Расширения и память](11-расширения-и-память.md)
+
+**Справочник**
+- [12 — CLI](12-cli-reference.md) — все команды с флагами
+- [13 — Архитектура и контракт](13-архитектура-и-контракт.md) — для разработчиков плагинов и рантайм-пакетов
+- [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md) — переменные окружения, журналы, диагностика
+
+## Статус
+
+Построено и работает: единый демон-роутер, протокол обмена сообщениями (IAP), реестр пиров, идентичность и её ABI, жизненный цикл (пробуждение, усыпление, перезапуск, надзор), рантайм-адаптеры для Claude, Codex, Telegram и notifier, установка и онбординг хоста, подключение Telegram, слот памяти и capability-плагины.
+
+Запланировано поверх ядра: граф совместимости пакетов, доктор здоровья всей команды и интерактивный интерфейс координации. Пока этих надстроек нет, координационные операции живут в CLI `iapeer`.
+
+## Планы
+
+Более крупные направления, запланированы и ещё не сделаны:
+
+- **Веб-интерфейс** — работа с командой через браузер.
+- **Поддержка Linux** — сегодня iapeer работает на macOS; Linux в планах.
+- **Дополнительные агентские рантаймы** — `opencode` и `antigravity`, два новых CLI-рантайма наряду с Claude Code и Codex.
+- **Рантайм Discord** — рантайм присутствия человека для Discord, наряду с Telegram.
+- **Гейт разрешений** — более тонкий контроль над тем, что агенту позволено делать.
+- **Апрув разрешений через Telegram** — подтверждать запросы разрешений агента прямо из чата; сегодня разрешения выданы автоматически флагами.
+
+Платформа сейчас — только macOS/launchd. Поддержка Linux (systemd) и Windows не реализована.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.97",
+  "version": "0.2.99",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",
@@ -27,8 +27,10 @@
   "files": [
     "src",
     "bin",
+    "docs",
     "tsconfig.json",
-    "!src/**/*.test.ts"
+    "!src/**/*.test.ts",
+    "!docs/internals/**"
   ],
   "exports": {
     ".": "./src/index.ts",

package/src/cli/index.ts

@@ -63,8 +63,8 @@ import {
 } from '../identity/profileStandard.ts'
 import { runAlwaysOn } from '../launch/launchdRun.ts'
 import { ensureDaemonStarted, installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
-import { MARKETPLACE_NAME, onboardHost, tccFullDiskAccessNote } from '../onboard/index.ts'
-import { readMemoryProvider } from '../status/index.ts'
+import { MARKETPLACE_NAME, onboardHost, runtimeAuthNote, tccFullDiskAccessNote } from '../onboard/index.ts'
+import { probeFullDiskAccess, readMemoryProvider } from '../status/index.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { pluginLogsDir } from '../storage/index.ts'
 
@@ -1096,9 +1096,22 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         })
         const memLabel = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
         out(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${memLabel})\n`)
-        // macOS TCC advisory (manual grant — no flag/setting can): gated on a memory provider, since a
-        // vault (often an iCloud Obsidian dir) is the TCC-protected resource. Base ~/.iapeer needs none.
-        const tcc = tccFullDiskAccessNote({ memoryActive: mem.provider != null })
+        // Runtime auth readiness (clean-host prerequisite): a peer runs the runtime's
+        // interactive TUI; the launcher auto-clears first-run modals (theme/trust) but
+        // CANNOT complete a login OAuth flow. Warn for every INSTALLED runtime (marketplace
+        // state != runtime-missing) that has no positive auth evidence — before it ships a
+        // peer that would fail to wake on the login screen.
+        for (const m of r.marketplaces) {
+          if (m.state === 'runtime-missing') continue
+          const authNote = runtimeAuthNote(m.runtime, env)
+          if (authNote) errOut(authNote + '\n')
+        }
+        // macOS TCC advisory (manual grant — no flag/setting/script can): PROBE-DRIVEN, not
+        // memory-gated — a missing grant silently breaks file I/O (EPERM, no prompt/hang) on
+        // any TCC-protected path (iCloud vault, Documents/Desktop/Downloads peer cwd). Silent
+        // when granted / non-macOS / undeterminable.
+        const { iapeerBinPath } = await import('../install/index.ts')
+        const tcc = tccFullDiskAccessNote({ fda: probeFullDiskAccess(env), binPath: iapeerBinPath(env) })
         if (tcc) out(tcc)
         return daemonFailed || r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
       }

package/src/launch/adapters/claude.ts

@@ -49,6 +49,12 @@ const CLAUDE_BOOT_DIALOG_MARKERS = [
   'I am using this for local development',
   '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.)
+  'Choose the text style',
 ] as const
 
 function anyBootDialog(pane: string): boolean {
@@ -185,7 +191,16 @@ export const claudeAdapter: RuntimeAdapter = {
     if (
       pane.includes('trust this folder') ||
       pane.includes('Allow external CLAUDE.md file imports?') ||
-      pane.includes('I am using this for local development')
+      pane.includes('I am using this for local development') ||
+      // 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.
+      // NOTE: the LOGIN method picker that can follow on an UNAUTHENTICATED host is
+      // deliberately NOT auto-answered — selecting subscription opens a browser OAuth
+      // flow no headless peer can complete. Login is an onboard PREREQUISITE
+      // (ANTHROPIC_API_KEY or a one-time `claude login`); a never-authed host fails
+      // the wake LOUD at the boot deadline rather than auto-entering a dead OAuth.
+      pane.includes('Choose the text style')
     ) {
       return ['Enter']
     }

package/src/onboard/index.ts

@@ -12,7 +12,7 @@
 import { spawnSync } from 'child_process'
 import { homedir } from 'os'
 import { join } from 'path'
-import { accessSync, constants as FS } from 'fs'
+import { accessSync, constants as FS, existsSync, readFileSync } from 'fs'
 
 /** OUR marketplace — GitHub owner/repo, the source both runtimes' `marketplace add`
  *  takes; and the registered NAME both runtimes' `marketplace list` shows. */
@@ -216,23 +216,120 @@ export function onboardHost(opts: OnboardOptions = {}): OnboardResult {
 /**
  * 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
- * RUNTIME allows; macOS TCC is a SEPARATE OS layer that NO flag or settings key can grant — it is
- * user-granted in System Settings, by design. `~/.iapeer` lives under $HOME and is NOT TCC-protected,
- * so a BASE install needs nothing. The trigger that warrants the grant is a memory vault — commonly an
- * iCloud Obsidian dir, and iCloud Drive / Desktop / Documents / Downloads ARE TCC-protected — so the
- * note is GATED on a memory provider being present; a base ~/.iapeer-only host is never nagged.
- * Returns null when not applicable (caller prints nothing). Pure (no I/O) — unit-testable.
+ * RUNTIME allows; macOS TCC is a SEPARATE OS layer that NO flag, settings key, config, env var or
+ * script can grant — it is user-granted in System Settings, by design (the TCC db is SIP-protected).
+ *
+ * PROBE-DRIVEN, not memory-gated (was: gated on a memory provider). The advisory now fires off the
+ * REAL FDA state (`fda` from probeFullDiskAccess), because a missing grant is a latent fault no proxy
+ * captures: the DEFAULT memory vault is an iCloud Obsidian dir AND a peer work dir can itself sit in a
+ * protected location (Documents/Desktop/Downloads) with NO memory provider at all. So: grant present
+ * → silent; grant ABSENT on macOS → warn, every time.
+ *
+ * Failure mode is SILENT, not a hang: per Apple (DTS/Quinn, devforums 678819) a launchd-spawned CLI
+ * with no GUI front gets NO TCC dialog — the access is denied with EPERM. A peer therefore does NOT
+ * block; its file I/O on a protected path just silently fails. `~/.iapeer` (under $HOME) is NOT
+ * TCC-protected and needs nothing.
+ *
+ * Returns null when granted / undeterminable / non-macOS (`fda` true or null). Pure (no I/O) —
+ * the FDA probe and binPath are injected by the caller, so this stays unit-testable.
  */
-export function tccFullDiskAccessNote(opts: { memoryActive: boolean }): string | null {
-  if (!opts.memoryActive) return null
+export function tccFullDiskAccessNote(opts: { fda: boolean | null; binPath: string }): string | null {
+  if (opts.fda !== false) return null // granted, non-macOS, or undeterminable → nothing to nag
   return (
     [
-      'macOS Full Disk Access (manual — TCC cannot be set by any flag or settings key):',
-      '  ~/.iapeer needs none (it is under $HOME). BUT a memory vault or a peer work dir in a',
-      '  TCC-protected location (iCloud Drive, Desktop, Documents, Downloads — e.g. an iCloud',
-      '  Obsidian vault) does, or file tools silently fail to read/write there.',
-      '  Grant it to ~/.local/bin/iapeer (and to Terminal too, if you attach) in:',
+      'macOS Full Disk Access NOT granted (manual — TCC cannot be set by any flag, settings key or script):',
+      '  Without it, file I/O on TCC-protected paths SILENTLY FAILS with EPERM (no prompt, no hang) —',
+      '  a peer reading/writing an iCloud Obsidian vault (iCloud Drive / Desktop / Documents / Downloads)',
+      '  just gets denied. `~/.iapeer` itself is under $HOME and needs nothing.',
+      `  Grant it to ${opts.binPath} (and to Terminal too, if you attach) in:`,
       '    System Settings → Privacy & Security → Full Disk Access',
     ].join('\n') + '\n'
   )
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runtime auth readiness — the one CLEAN-HOST modal a launcher CANNOT auto-clear
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// A headless peer runs the runtime's INTERACTIVE TUI (a pty), not `-p`. On a clean
+// host the first-run flow blocks on modals; the launcher auto-answers the ones it
+// recognizes (theme picker, folder-trust, …) — but the LOGIN screen cannot be
+// auto-answered (selecting subscription opens a browser OAuth flow no headless peer
+// can complete). So login is a PREREQUISITE: the host must be authenticated BEFORE
+// the first peer launches, or that peer's wake fails loud at the boot deadline.
+//
+// These probes are CONSERVATIVE: they return ready ONLY on positive evidence, so a
+// missing signal nags (one harmless advisory line) rather than letting an
+// unauthenticated host silently ship a peer that will fail to wake.
+
+/** Resolve claude's config dir (CLAUDE_CONFIG_DIR override, else ~/.claude). */
+function claudeConfigDir(env: NodeJS.ProcessEnv): string {
+  const override = env.CLAUDE_CONFIG_DIR?.trim()
+  if (override) return override
+  return join(env.HOME?.trim() || homedir(), '.claude')
+}
+
+/**
+ * True when claude is authenticated for a headless launch (won't block on the login
+ * picker). Positive evidence, in order: an auth env var; a completed onboarding +
+ * account in `~/.claude.json` (the subscription `claude login` path); or an
+ * `apiKeyHelper` in settings.json. Anything else → not ready (nag). Reads are
+ * env-rooted (HOME/CLAUDE_CONFIG_DIR) so a hermetic test isolates them.
+ */
+export function claudeAuthReady(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.ANTHROPIC_API_KEY?.trim() || env.ANTHROPIC_AUTH_TOKEN?.trim() || env.CLAUDE_CODE_OAUTH_TOKEN?.trim()) {
+    return true
+  }
+  // `~/.claude.json` lives at HOME root (not inside the config dir) in the default
+  // layout the fleet uses; hasCompletedOnboarding + an account/key marker proves the
+  // first-run flow (theme + login) is done.
+  const statePath = join(env.HOME?.trim() || homedir(), '.claude.json')
+  try {
+    const j = JSON.parse(readFileSync(statePath, 'utf8')) as Record<string, unknown>
+    if (j.hasCompletedOnboarding === true && (j.oauthAccount != null || j.customApiKeyResponses != null)) return true
+  } catch {
+    /* absent/unreadable → fall through to settings */
+  }
+  try {
+    const s = JSON.parse(readFileSync(join(claudeConfigDir(env), 'settings.json'), 'utf8')) as Record<string, unknown>
+    if (typeof s.apiKeyHelper === 'string' && s.apiKeyHelper.trim()) return true
+  } catch {
+    /* no settings / no helper */
+  }
+  return false
+}
+
+/**
+ * True when codex is authenticated (won't block / error at startup). Positive
+ * evidence: `OPENAI_API_KEY` env, or an `auth.json` under $CODEX_HOME/~/.codex.
+ * Env-rooted for hermetic tests.
+ */
+export function codexAuthReady(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.OPENAI_API_KEY?.trim()) return true
+  const codexHome = env.CODEX_HOME?.trim()
+  const authPath = codexHome
+    ? join(codexHome, 'auth.json')
+    : join(env.HOME?.trim() || homedir(), '.codex', 'auth.json')
+  return existsSync(authPath)
+}
+
+/**
+ * Advisory line for a runtime that is NOT authenticated (so the operator fixes it
+ * BEFORE launching peers). Returns null when the runtime is ready. Pure dispatch
+ * over the per-runtime probes above.
+ */
+export function runtimeAuthNote(runtime: OnboardRuntime, env: NodeJS.ProcessEnv = process.env): string | null {
+  if (runtime === 'claude') {
+    if (claudeAuthReady(env)) return null
+    return (
+      'claude: NOT authenticated — the first peer would block on the login screen (a launcher cannot\n' +
+      '  complete the browser OAuth flow). Before launching peers, either run `claude` once in your\n' +
+      '  terminal to sign in (subscription), or set ANTHROPIC_API_KEY in the daemon environment.'
+    )
+  }
+  if (codexAuthReady(env)) return null
+  return (
+    'codex: NOT authenticated — the first codex peer cannot reach the model. Before launching codex\n' +
+    '  peers, run `codex login` once (or set OPENAI_API_KEY in the daemon environment).'
+  )
+}