@agfpd/iapeer 0.4.62 → 0.4.63

package/docs/15-fleet-api.md

@@ -0,0 +1,142 @@
+# 15 — Fleet API
+
+The daemon's HTTP surface for **operator clients**: dashboards, menu-bar apps, scripts, future web gateways. It serves three things: a **snapshot** of the fleet state, a **live event stream**, and **commands** over the existing management verbs. Everything an `iapeer list`-style client needs — without parsing CLI output.
+
+This is a **normative contract**: fleet clients (SwiftBar plugins, native apps, web pages) are written against this document, not against the daemon source. The MUST/MUST NOT rules in «Client obligations» below are load-bearing — a client that skips them will break on a future daemon update.
+
+## Surface and transport
+
+- Base path: **`/fleet/v1`**, plain HTTP + JSON (+ SSE for events). This is *not* MCP: MCP (`/mcp`) is the agent surface and deliberately carries a single tool; fleet clients are GUIs and scripts that consume HTTP natively.
+- Served on **both** daemon listeners:
+  - the unix socket `~/.iapeer/state/iapeer/router.sock` — `curl --unix-socket ~/.iapeer/state/iapeer/router.sock http://iapeer/fleet/v1/snapshot`
+  - TCP loopback — `http://127.0.0.1:8765/fleet/v1/snapshot`
+- **Discovery:** read `~/.iapeer/state/iapeer/router.json`. A daemon that serves this API advertises `"fleet": 1` there, next to the active `sock`/`tcp` addresses and the daemon `version`. Absent `fleet` key ⇒ pre-fleet daemon ⇒ the client must degrade (hide, or fall back to CLI).
+- **Auth:** when the daemon is configured with a bearer token (`IAPEER_BEARER_TOKEN`), every fleet request must carry `Authorization: Bearer <token>` — the same gate as MCP, checked before dispatch. Without a configured token, the surface is open to the local user (same trust class as the CLI: loopback + same-uid socket).
+- **No CORS headers, deliberately.** A browser page must not be able to drive loopback fleet commands cross-origin. A web gateway is a separate future decision with mandatory auth.
+
+## Client obligations (normative)
+
+1. **Unknown event kinds MUST be ignored.** The `ev` vocabulary grows without a version bump (e.g. future `approval-request` / `approval-resolved`). A client that throws on an unknown `ev` is broken by design.
+2. **Unknown JSON fields MUST be ignored.** The snapshot and every response evolve **additively** within `/fleet/v1`: new fields appear, existing fields keep their meaning and type. Removals or type changes would be a `/fleet/v2`.
+3. **Events are at-least-once.** After an SSE reconnect (and around log rotation) a client may see an event twice. The SSE `id:` is the event's epoch-ms timestamp — use it (plus field equality) for display-level dedup. There is no exactly-once replay cursor; on reconnect, re-fetch the snapshot and resume from live events.
+4. **The snapshot is the state; events are change hints.** The intended loop: fetch `/snapshot` once, subscribe to `/events`, re-fetch `/snapshot` when an event arrives (cheap, coalesce bursts). Do not reconstruct fleet state from events alone.
+5. **Ages are client-rendered.** `last_active_ms` is an epoch timestamp; render the ticking «4m ago» yourself instead of polling the snapshot per second.
+
+## GET /fleet/v1/snapshot
+
+The full fleet state. The peer rows are produced by the **same in-process function that renders `iapeer list`** — agreement with the CLI is by construction.
+
+```json
+{
+  "api": 1,
+  "version": "0.4.63",
+  "ts": "2026-07-05T18:00:00.000Z",
+  "host": {
+    "version": "0.4.63",
+    "pid": 12345,
+    "startedAt": "2026-07-05T09:00:00.000Z",
+    "uptimeSecs": 32400,
+    "memory": { "provider": "iapeer-memory", "version": "1.2.3", "heartbeatAgeSecs": 12 },
+    "voice":  { "provider": "voice-connect", "version": "0.3.1", "heartbeatAgeSecs": null },
+    "fda": true
+  },
+  "peers": [
+    {
+      "personality": "boris",
+      "description": "Напарник Артура по мультиагентной системе",
+      "intelligence": "artificial",
+      "default_runtime": "claude",
+      "cwd": "/Users/me/.iapeer/peers/boris",
+      "runtimes": [
+        { "runtime": "claude", "status": "live", "attached": true },
+        { "runtime": "codex",  "status": "asleep" }
+      ],
+      "last_active_runtime": "claude",
+      "last_active_ms": 1751731100000,
+      "attached": true,
+      "launchd_managed": false,
+      "wake_policy": "warm"
+    }
+  ]
+}
+```
+
+Field notes:
+
+- `runtimes[].status` — `live` (session up) · `asleep` (wakeable on demand) · `stopped` (operator stop flag; the daemon won't wake it). Same glyph semantics as the CLI: `●` / `○` / `✕`.
+- `runtimes[].attached` — present (`true`) only when a **human operator** is attached to that live hosted session.
+- `attached` — any runtime attached (peer-level convenience).
+- `launchd_managed` — launchd owns this peer's lifecycle (H4): the daemon never wakes/reaps it, and wake/stop/start commands are guarded accordingly.
+- `wake_policy` — `warm` (default: wake-on-message, idle-reap, resume) or `ephemeral` (stateless worker: serial task queue, die-after-reply).
+- `queue_depth` — ephemeral peers only: pending tasks across the peer's serial queues.
+- `host.memory` / `host.voice` — the provider slots (`null` = empty slot); `heartbeatAgeSecs: null` with a non-null slot = provider declared but its daemon isn't heartbeating.
+- `host.fda` — Full Disk Access of the binary: `true` / `false` / `null` (undeterminable).
+- The daemon answering **is** the health signal: there is no `healthy` boolean. A dashboard that cannot reach any advertised address should render the daemon as down (this is also why a purely API-fed dashboard is insufficient when the daemon itself is broken — the built-in TUI keeps its direct in-process read path for exactly that case).
+- The peer's **LLM model is deliberately absent**: the effective model of a live session is not an observable registry fact (static launch pins exist, but reporting a pin as «the model» would lie under runtime auto-switching). If it ever becomes observable, it will appear as an additive field.
+
+## GET /fleet/v1/peers/&lt;personality&gt;
+
+One peer's card: the same object as the snapshot row, plus its recent history.
+
+```json
+{ "api": 1, "version": "0.4.63", "ts": "…", "peer": { …snapshot row… },
+  "events": [ { "src": "lifecycle", "ev": "wake", "ts": "…", "personality": "boris", "mode": "resume" } ] }
+```
+
+`events` — the newest ≤50 events concerning this peer (matched on personality / `<runtime>-<personality>` identity fields), merged across the logs by timestamp, oldest first. `404` for an unregistered peer.
+
+## GET /fleet/v1/events — SSE stream
+
+`text/event-stream` of fleet events, sourced by tail-following the daemon's **durable logs** (`lifecycle.log`, `delivery.log`, `exits.log`). Those files are written by *every* participating process — the daemon, CLI verbs (attach/stop/wake), the pty supervisors — so the stream covers events an in-daemon bus would miss.
+
+```
+GET /fleet/v1/events?replay=50
+```
+
+- `replay=N` (0…500, default 0) — emit the newest N historical events before going live.
+- Each event:
+
+  ```
+  event: wake
+  id: 1751731100123
+  data: {"src":"lifecycle","ev":"wake","ts":"2026-07-05T18:00:00.123Z","personality":"boris","mode":"resume"}
+  ```
+
+  `data` is the full parsed log line: `src` (`lifecycle` | `delivery` | `exits`) + `ev` + every logfmt field with quoted values decoded. `id` = epoch-ms of the event.
+- A comment `: connected` marks the transition from replay to live; `: hb` comments every ~15 s keep the connection alive.
+- Latency: live events surface within ~0.5 s (log-tail poll).
+
+Current `ev` vocabulary (grows over time — see obligation 1): `wake`, `supervise` (with `action`: `reaped-idle` = parked, `reaped-ephemeral`, `dead`→fresh/resume classification, `eager-orphan-fresh`, `skipped-error`…), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (from `exits.log`, with `dead_status`/`dead_signal`).
+
+What the headline states look like on the stream: a peer **waking** is `ev=wake`; a peer **parked to sleep** is `ev=supervise action=reaped-idle`; a **death** is `ev=session-exit` (immediately, from the supervisor) followed by the daemon's classification on its next pass.
+
+## Commands
+
+`POST /fleet/v1/peers/<personality>/<command>` with an optional JSON body `{ "runtime": "claude", "topic": "…" }` (both optional; `topic` is used by `wake` only). The commands are the **existing management verbs called in-process** — every guard (H4 launchd read-only, the foreign-plist fleet guard, the crash-loop guard, wake serialization) lives inside those verbs and cannot be bypassed via the API.
+
+| Command | Verb semantics | Success |
+|---|---|---|
+| `wake` | bring the peer up (no message; fresh-vs-resume decided by the daemon) | `200` + wake outcome, `502` + `status:"FAILED"` |
+| `stop` | set the stop flag / bootout an always-on peer | `200` + `outcomes[]`, `502` if a bootout failed or a foreign plist was refused |
+| `start` | clear the stop flag (warm peers become wakeable; no session is launched) / bootstrap always-on | `200` / `502` mirror of `stop` |
+| `new` | **unconditional** fresh restart (the emergency lever) | `200` + `action:"fresh"` |
+| `refresh` | lazy soft-reload: fresh on next natural wake, no kill | `200` + `outcomes[]` |
+| `interrupt` | interrupt a stuck/raving turn (Escape into the live session) | `200` / `502` |
+| `compact` | compact the resumable dialogue (honest failure when none) | `200` + `action:"compacted"` / `502` |
+
+`POST /fleet/v1/send` — deliver a message through the same routing path as the `send_to_peer` tool (wake-on-miss, queueing, delivery log — identical semantics):
+
+```json
+{ "personality": "boris", "message": "…", "runtime": "claude", "topic": "…", "from": "nova" }
+```
+
+`from` is optional: a full `<runtime>-<personality>`, or a bare personality (its default runtime). Default: the **single natural-intelligence peer** of the registry — a GUI-originated message is the human's. With zero or several natural peers the request is refused (`400`) with an instruction to pass `from`.
+
+Not part of the API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them), **approve** (no approval broker exists yet; it will arrive as new endpoints + `ev` kinds under this same contract).
+
+Errors are always `{"error": "…"}` with an honest status: `400` malformed request, `401` bearer required, `404` unknown peer/endpoint, `405` wrong method, `502` the verb itself failed, `500` internal.
+
+## Compatibility
+
+- `/fleet/v1` evolves **additively**; `api: 1` in every snapshot. Breaking changes mean `/fleet/v2` served alongside.
+- The capability marker in `router.json` (`fleet: 1`) is the feature-detect: clients must treat its absence as «no fleet API» rather than probing endpoints.

package/docs/README.md

@@ -76,6 +76,7 @@ The sections are layered: from "install and use" to "understand the architecture
 - [12 — CLI](12-cli-reference.md) — all commands with flags
 - [13 — Architecture and contract](13-architecture-and-contract.md) — for plugin and runtime-package developers
 - [14 — Configuration and logs](14-configuration-and-logs.md) — environment variables, logs, diagnostics
+- [15 — Fleet API](15-fleet-api.md) — the daemon's HTTP surface for operator clients (dashboards, tray apps, scripts): snapshot, event stream, commands
 
 ## Status
 

package/docs/ru/15-fleet-api.md

@@ -0,0 +1,142 @@
+# 15 — Fleet API
+
+HTTP-поверхность демона для **операторских клиентов**: дашбордов, menu-bar-приложений, скриптов, будущих веб-гейтвеев. Отдаёт три вещи: **снапшот** состояния флота, **живой поток событий** и **команды** поверх существующих управляющих verb'ов. Всё, что нужно клиенту класса `iapeer list`, — без парсинга CLI-вывода.
+
+Это **нормативный контракт**: клиенты fleet API (SwiftBar-плагины, нативные приложения, веб-страницы) пишутся по этому документу, а не по исходникам демона. Правила «Обязанности клиента» ниже — несущие: клиент, который их пропустит, сломается на будущем обновлении демона.
+
+## Поверхность и транспорт
+
+- Базовый путь: **`/fleet/v1`**, обычный HTTP + JSON (+ SSE для событий). Это *не* MCP: MCP (`/mcp`) — агентская поверхность и намеренно несёт единственный инструмент; fleet-клиенты — GUI и скрипты, потребляющие HTTP нативно.
+- Обслуживается на **обоих** слушателях демона:
+  - unix-сокет `~/.iapeer/state/iapeer/router.sock` — `curl --unix-socket ~/.iapeer/state/iapeer/router.sock http://iapeer/fleet/v1/snapshot`
+  - TCP loopback — `http://127.0.0.1:8765/fleet/v1/snapshot`
+- **Обнаружение:** читайте `~/.iapeer/state/iapeer/router.json`. Демон, отдающий этот API, объявляет там `"fleet": 1` — рядом с активными адресами `sock`/`tcp` и версией демона. Нет ключа `fleet` ⇒ демон без fleet API ⇒ клиент обязан деградировать (скрыться или уйти на CLI).
+- **Аутентификация:** если демон настроен с bearer-токеном (`IAPEER_BEARER_TOKEN`), каждый fleet-запрос обязан нести `Authorization: Bearer <токен>` — тот же гейт, что у MCP, проверяется до диспатча. Без настроенного токена поверхность открыта локальному пользователю (тот же класс доверия, что CLI: loopback + same-uid сокет).
+- **Без CORS-заголовков, намеренно.** Страница в браузере не должна уметь дёргать loopback-команды флота кросс-доменно. Веб-гейтвей — отдельное будущее решение с обязательной аутентификацией.
+
+## Обязанности клиента (нормативно)
+
+1. **Неизвестные виды событий ОБЯЗАНЫ игнорироваться.** Словарь `ev` растёт без смены версии (например, будущие `approval-request` / `approval-resolved`). Клиент, падающий на неизвестном `ev`, сломан по построению.
+2. **Неизвестные JSON-поля ОБЯЗАНЫ игнорироваться.** Снапшот и каждый ответ развиваются **аддитивно** внутри `/fleet/v1`: новые поля появляются, существующие сохраняют смысл и тип. Удаление или смена типа означали бы `/fleet/v2`.
+3. **События — at-least-once.** После SSE-переподключения (и вокруг ротации логов) клиент может увидеть событие дважды. SSE `id:` — epoch-ms события; используйте его (плюс равенство полей) для дедупликации на уровне отображения. Точного replay-курсора нет; после reconnect перечитайте снапшот и продолжайте с живых событий.
+4. **Снапшот — состояние; события — сигналы изменений.** Целевой цикл: получить `/snapshot` один раз, подписаться на `/events`, перечитывать `/snapshot` по приходу события (дёшево; всплески коалесцируйте). Не восстанавливайте состояние флота из одних событий.
+5. **Возрасты рендерит клиент.** `last_active_ms` — epoch-метка; тикающее «4m ago» рисуйте сами, а не поллингом снапшота каждую секунду.
+
+## GET /fleet/v1/snapshot
+
+Полное состояние флота. Строки пиров производит **та же in-process функция, что рендерит `iapeer list`** — совпадение с CLI обеспечено по построению.
+
+```json
+{
+  "api": 1,
+  "version": "0.4.63",
+  "ts": "2026-07-05T18:00:00.000Z",
+  "host": {
+    "version": "0.4.63",
+    "pid": 12345,
+    "startedAt": "2026-07-05T09:00:00.000Z",
+    "uptimeSecs": 32400,
+    "memory": { "provider": "iapeer-memory", "version": "1.2.3", "heartbeatAgeSecs": 12 },
+    "voice":  { "provider": "voice-connect", "version": "0.3.1", "heartbeatAgeSecs": null },
+    "fda": true
+  },
+  "peers": [
+    {
+      "personality": "boris",
+      "description": "Напарник Артура по мультиагентной системе",
+      "intelligence": "artificial",
+      "default_runtime": "claude",
+      "cwd": "/Users/me/.iapeer/peers/boris",
+      "runtimes": [
+        { "runtime": "claude", "status": "live", "attached": true },
+        { "runtime": "codex",  "status": "asleep" }
+      ],
+      "last_active_runtime": "claude",
+      "last_active_ms": 1751731100000,
+      "attached": true,
+      "launchd_managed": false,
+      "wake_policy": "warm"
+    }
+  ]
+}
+```
+
+Заметки по полям:
+
+- `runtimes[].status` — `live` (сессия поднята) · `asleep` (разбудится по требованию) · `stopped` (операторский стоп-флаг; демон будить не станет). Та же семантика глифов, что в CLI: `●` / `○` / `✕`.
+- `runtimes[].attached` — присутствует (`true`) только когда к этой живой hosted-сессии подключён **человек-оператор**.
+- `attached` — любой рантайм с подключённым человеком (удобство уровня пира).
+- `launchd_managed` — жизненным циклом пира владеет launchd (H4): демон его не будит/не усыпляет, а команды wake/stop/start соответствующе защищены.
+- `wake_policy` — `warm` (по умолчанию: пробуждение по сообщению, idle-reap, resume) или `ephemeral` (stateless-воркер: серийная очередь задач, die-after-reply).
+- `queue_depth` — только у ephemeral-пиров: ожидающие задачи в серийных очередях пира.
+- `host.memory` / `host.voice` — провайдерские слоты (`null` = слот пуст); `heartbeatAgeSecs: null` при непустом слоте = провайдер объявлен, но его демон не шлёт heartbeat.
+- `host.fda` — Full Disk Access бинаря: `true` / `false` / `null` (неопределимо).
+- Сам факт ответа демона **и есть** сигнал здоровья: булева `healthy` нет. Дашборд, не достучавшийся ни до одного объявленного адреса, обязан рисовать демона лежачим (поэтому же дашборд, питающийся только API, недостаточен, когда сломан сам демон — встроенный TUI сохраняет прямой in-process путь чтения ровно на этот случай).
+- **LLM-модель пира отсутствует намеренно**: эффективная модель живой сессии — не наблюдаемый факт реестра (статические пины запуска существуют, но выдавать пин за «модель» — врать при рантаймном автопереключении). Станет наблюдаемой — появится аддитивным полем.
+
+## GET /fleet/v1/peers/&lt;personality&gt;
+
+Карточка одного пира: тот же объект, что строка снапшота, плюс его недавняя история.
+
+```json
+{ "api": 1, "version": "0.4.63", "ts": "…", "peer": { …строка снапшота… },
+  "events": [ { "src": "lifecycle", "ev": "wake", "ts": "…", "personality": "boris", "mode": "resume" } ] }
+```
+
+`events` — новейшие ≤50 событий, касающихся пира (матч по personality / полям идентичности `<runtime>-<personality>`), слитые по времени из всех логов, старые первыми. `404` для незарегистрированного пира.
+
+## GET /fleet/v1/events — SSE-поток
+
+`text/event-stream` событий флота, источник — tail-follow **долговременных логов** демона (`lifecycle.log`, `delivery.log`, `exits.log`). Эти файлы пишут *все* участвующие процессы — демон, CLI-verb'ы (attach/stop/wake), pty-супервизоры, — поэтому поток покрывает события, которые внутридемонная шина бы пропустила.
+
+```
+GET /fleet/v1/events?replay=50
+```
+
+- `replay=N` (0…500, по умолчанию 0) — выдать новейшие N исторических событий перед переходом в live.
+- Каждое событие:
+
+  ```
+  event: wake
+  id: 1751731100123
+  data: {"src":"lifecycle","ev":"wake","ts":"2026-07-05T18:00:00.123Z","personality":"boris","mode":"resume"}
+  ```
+
+  `data` — полностью разобранная строка лога: `src` (`lifecycle` | `delivery` | `exits`) + `ev` + все logfmt-поля с раскодированными кавычками. `id` = epoch-ms события.
+- Комментарий `: connected` отмечает переход от replay к live; комментарии `: hb` каждые ~15 с держат соединение.
+- Латентность: живые события всплывают в пределах ~0.5 с (поллинг хвоста лога).
+
+Текущий словарь `ev` (растёт со временем — см. обязанность 1): `wake`, `supervise` (с `action`: `reaped-idle` = парковка, `reaped-ephemeral`, классификация `dead`→fresh/resume, `eager-orphan-fresh`, `skipped-error`…), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (из `exits.log`, с `dead_status`/`dead_signal`).
+
+Как выглядят главные состояния на потоке: **пробуждение** пира — `ev=wake`; **парковка в сон** — `ev=supervise action=reaped-idle`; **смерть** — `ev=session-exit` (немедленно, от супервизора), затем классификация демона на его следующем проходе.
+
+## Команды
+
+`POST /fleet/v1/peers/<personality>/<команда>` с необязательным JSON-телом `{ "runtime": "claude", "topic": "…" }` (оба опциональны; `topic` использует только `wake`). Команды — это **существующие управляющие verb'ы, вызванные in-process**: каждый гвард (H4 read-only для launchd-пиров, fleet-guard чужих плистов, защита от crash-loop, сериализация пробуждений) живёт внутри самих verb'ов и через API не обходится.
+
+| Команда | Семантика verb'а | Успех |
+|---|---|---|
+| `wake` | поднять пира (без сообщения; fresh-vs-resume решает демон) | `200` + исход, `502` + `status:"FAILED"` |
+| `stop` | поставить стоп-флаг / bootout always-on пира | `200` + `outcomes[]`, `502` при неудачном bootout или отказе на чужом плисте |
+| `start` | снять стоп-флаг (warm-пиры становятся пробуждаемыми; сессия не запускается) / bootstrap always-on | `200` / `502`, зеркально `stop` |
+| `new` | **безусловный** свежий рестарт (аварийный рычаг) | `200` + `action:"fresh"` |
+| `refresh` | ленивая мягкая перезагрузка: fresh на следующем естественном пробуждении, без kill | `200` + `outcomes[]` |
+| `interrupt` | прервать зависший/зациклившийся turn (Escape в живую сессию) | `200` / `502` |
+| `compact` | компактифицировать резюмируемый диалог (честный отказ, когда его нет) | `200` + `action:"compacted"` / `502` |
+
+`POST /fleet/v1/send` — доставить сообщение тем же маршрутом, что инструмент `send_to_peer` (wake-on-miss, очереди, delivery-лог — семантика идентична):
+
+```json
+{ "personality": "boris", "message": "…", "runtime": "claude", "topic": "…", "from": "nova" }
+```
+
+`from` опционален: полный `<runtime>-<personality>` или голая personality (её default-рантайм). По умолчанию — **единственный natural-intelligence пир** реестра: сообщение из GUI принадлежит человеку. При нуле или нескольких natural-пирах запрос отклоняется (`400`) с указанием передать `from`.
+
+Не входит в API, намеренно: **attach** (передача терминала — клиент открывает системный терминал с `iapeer attach <peer>`), реестровые/хостовые **admin-verb'ы** (`create`/`remove`/`update`/`uninstall` — добавятся, когда появится клиент с реальной потребностью), **approve** (брокера подтверждений ещё не существует; он придёт новыми эндпоинтами + видами `ev` в рамках этого же контракта).
+
+Ошибки — всегда `{"error": "…"}` с честным статусом: `400` некорректный запрос, `401` требуется bearer, `404` неизвестный пир/эндпоинт, `405` не тот метод, `502` сам verb упал, `500` внутренняя.
+
+## Совместимость
+
+- `/fleet/v1` развивается **аддитивно**; `api: 1` в каждом снапшоте. Ломающие изменения означают `/fleet/v2`, поднятый рядом.
+- Маркер capability в `router.json` (`fleet: 1`) — способ feature-detect: его отсутствие клиент обязан трактовать как «fleet API нет», а не прощупывать эндпоинты.

package/docs/ru/README.md

@@ -76,6 +76,7 @@ iapeer send assistant --message "привет, ты на связи?"
 - [12 — CLI](12-cli-reference.md) — все команды с флагами
 - [13 — Архитектура и контракт](13-архитектура-и-контракт.md) — для разработчиков плагинов и рантайм-пакетов
 - [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md) — переменные окружения, журналы, диагностика
+- [15 — Fleet API](15-fleet-api.md) — HTTP-поверхность демона для операторских клиентов (дашборды, tray-приложения, скрипты): снапшот, поток событий, команды
 
 ## Статус
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.62",
+  "version": "0.4.63",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/daemon/fleet.ts

@@ -0,0 +1,654 @@
+// Fleet-API — the daemon's OPERATOR-CLIENT HTTP surface (Ф0 of iapeer-tray: one
+// fleet-API in the daemon, many thin faces on top — SwiftBar / native tray / web
+// gateway / telegram approval buttons). Plain HTTP+JSON + SSE, DELIBERATELY NOT an
+// MCP tool: MCP is the AGENT surface and the contract keeps it minimal
+// (send_to_peer only — an extra tool occupies every session's context window);
+// fleet clients are GUIs/scripts that consume HTTP natively.
+//
+// Design pillars (spec accepted by the PM 05.07.2026; normative client contract in
+// docs/15-fleet-api.md):
+//   • SNAPSHOT truth = the SAME in-process primitives `iapeer list` uses
+//     (cli.listPeers) — agreement with the CLI is by construction, not by parsing.
+//   • EVENTS = tail-follow of the THREE durable logs (lifecycle.log / delivery.log /
+//     exits.log under cfg.eventLogDir). Those logs are written by EVERY process
+//     (daemon + CLI attach/stop/wake + supervisor deaths) — an in-memory daemon bus
+//     would silently miss the CLI-originated events. At-least-once semantics;
+//     clients MUST ignore unknown `ev` kinds (the approval-request growth seam).
+//   • COMMANDS = the EXISTING verb functions called in-process (stopPeer/startPeer/
+//     newPeer/refreshPeer/compactPeer/wakeOrSpawn/routeControl) — H4, the fleet
+//     guard and the crash-loop guard all live INSIDE those functions, so the API
+//     cannot bypass them. send routes through daemon.callTool — the SAME path as
+//     the MCP tool (delivery.log line + all post-delivery hooks included).
+//
+// Security class: unchanged. The endpoints listen on the SAME two listeners
+// (0600 unix socket + TCP loopback) behind the SAME optional H8 bearer gate
+// (checked in daemon/index.ts BEFORE dispatch); command power ≤ what the same-uid
+// CLI already has. NO CORS headers — a browser page must NOT be able to drive
+// loopback fleet commands cross-origin; the future web gateway is its own decision
+// with bearer mandatory (see the frozen TCP open-auth decision + its triggers).
+//
+// Layering: this module is a COMPOSITION-SIDE sibling of daemon/main.ts (wired via
+// StartDaemonOptions.fleet — the same injected-seam pattern as wake/supervise), so
+// the daemon library stays lifecycle-free. The CLI verb functions are loaded via a
+// LAZY dynamic import: cli/index.ts statically imports daemon/main.ts, so a static
+// import back would create the repo's first import cycle.
+
+import type { IncomingMessage, ServerResponse } from 'http'
+import { closeSync, openSync, readSync, statSync } from 'fs'
+import { buildProcessAddress } from '../core/socket.ts'
+import { IAPEER_VERSION } from '../core/version.ts'
+import {
+  ephemeralQueueDepth,
+  isEphemeralPeer,
+  isLaunchdManaged,
+  loadLifecycleConfig,
+  wakeOrSpawn,
+  type LifecycleConfig,
+} from '../lifecycle/index.ts'
+import { lifecycleLogPath } from '../lifecycle/eventlog.ts'
+import { exitLogPath } from '../launch/index.ts'
+import { hasAttachedSupervisorClient } from '../launch/ptyHost.ts'
+import { readPeersIndex } from '../registry/index.ts'
+import { resolveCallerIdentity, type ResolvedCaller } from '../identity/index.ts'
+import { routeControl } from '../transport/index.ts'
+import {
+  eventConcernsPeer,
+  parseEventLine,
+  readLogTail,
+  type ParsedEventLine,
+} from '../storage/rotatelog.ts'
+import { heartbeatAgeSecs, probeFullDiskAccess, readMemoryProvider, readVoiceProvider } from '../status/index.ts'
+import { deliveryLogPath } from './deliverylog.ts'
+import { callTool, type CallToolDeps } from './index.ts'
+
+/** The API generation baked into every snapshot (additive evolution within v1 —
+ *  see docs/15-fleet-api.md «Compatibility»). */
+export const FLEET_API_VERSION = 1
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Snapshot
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FleetRuntimeStatus {
+  runtime: string
+  status: 'live' | 'asleep' | 'stopped'
+  /** Present (true) iff a HUMAN operator is attached to this live hosted session. */
+  attached?: boolean
+}
+
+export interface FleetPeer {
+  personality: string
+  description: string
+  intelligence: string
+  default_runtime: string
+  cwd: string
+  runtimes: FleetRuntimeStatus[]
+  last_active_runtime?: string
+  last_active_ms?: number
+  /** Any runtime session with a human attached. */
+  attached: boolean
+  /** H4 — launchd owns this peer's lifecycle; the daemon (and the wake/stop/start
+   *  commands) treat it read-only / guarded. */
+  launchd_managed: boolean
+  wake_policy: 'warm' | 'ephemeral'
+  /** Ephemeral peers only: pending serial-queue tasks across declared runtimes. */
+  queue_depth?: number
+}
+
+export interface FleetHost {
+  version: string
+  pid: number
+  startedAt: string
+  uptimeSecs: number
+  memory: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
+  voice: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
+  fda: boolean | null
+}
+
+export interface FleetSnapshot {
+  api: typeof FLEET_API_VERSION
+  version: string
+  ts: string
+  host: FleetHost
+  peers: FleetPeer[]
+}
+
+// The CLI op functions, injectable for tests. Defaults LAZY-load cli/index.ts at
+// call time (see the layering note in the module header).
+export interface FleetOps {
+  listPeers: (opts: { env?: NodeJS.ProcessEnv }) => import('../cli/index.ts').PeerListing[]
+  stopPeer: typeof import('../cli/index.ts').stopPeer
+  startPeer: typeof import('../cli/index.ts').startPeer
+  refreshPeer: typeof import('../cli/index.ts').refreshPeer
+  newPeer: typeof import('../cli/index.ts').newPeer
+  compactPeer: typeof import('../cli/index.ts').compactPeer
+}
+
+async function defaultOps(): Promise<FleetOps> {
+  const cli = await import('../cli/index.ts')
+  return {
+    listPeers: cli.listPeers,
+    stopPeer: cli.stopPeer,
+    startPeer: cli.startPeer,
+    refreshPeer: cli.refreshPeer,
+    newPeer: cli.newPeer,
+    compactPeer: cli.compactPeer,
+  }
+}
+
+/** Assemble the full fleet snapshot. Peer rows come from the SAME listPeers the CLI
+ *  `list` verb renders — agreement with `iapeer list` is by construction. On top:
+ *  the occupancy/ownership facts the registry row alone does not carry (attached
+ *  human, H4 launchd ownership, wake_policy, ephemeral queue depth). */
+export function buildFleetSnapshot(
+  env: NodeJS.ProcessEnv,
+  cfg: LifecycleConfig,
+  ops: Pick<FleetOps, 'listPeers'>,
+  startedAtMs: number,
+  nowMs: number = Date.now(),
+): FleetSnapshot {
+  const peers: FleetPeer[] = ops.listPeers({ env }).map(r => {
+    const runtimes: FleetRuntimeStatus[] = r.runtimes.map(s => {
+      const attached =
+        s.status === 'live' && hasAttachedSupervisorClient(buildProcessAddress(s.runtime, r.personality), env)
+      return { runtime: s.runtime, status: s.status, ...(attached ? { attached: true } : {}) }
+    })
+    let ephemeral = false
+    try {
+      ephemeral = isEphemeralPeer(r.cwd)
+    } catch {
+      /* unreadable profile → treated as warm */
+    }
+    let queueDepth = 0
+    if (ephemeral) {
+      for (const s of r.runtimes) queueDepth += ephemeralQueueDepth(cfg, buildProcessAddress(s.runtime, r.personality))
+    }
+    return {
+      personality: r.personality,
+      description: r.description,
+      intelligence: r.intelligence,
+      default_runtime: r.default_runtime,
+      cwd: r.cwd,
+      runtimes,
+      ...(r.last_active_runtime ? { last_active_runtime: r.last_active_runtime } : {}),
+      ...(r.last_active_ms !== undefined ? { last_active_ms: r.last_active_ms } : {}),
+      attached: runtimes.some(s => s.attached === true),
+      launchd_managed: isLaunchdManaged(r.personality, env),
+      wake_policy: ephemeral ? ('ephemeral' as const) : ('warm' as const),
+      ...(ephemeral ? { queue_depth: queueDepth } : {}),
+    }
+  })
+  const mem = readMemoryProvider(env)
+  const voice = readVoiceProvider(env)
+  return {
+    api: FLEET_API_VERSION,
+    version: IAPEER_VERSION,
+    ts: new Date(nowMs).toISOString(),
+    host: {
+      version: IAPEER_VERSION,
+      pid: process.pid,
+      startedAt: new Date(startedAtMs).toISOString(),
+      uptimeSecs: Math.max(0, Math.floor((nowMs - startedAtMs) / 1000)),
+      memory: mem
+        ? { provider: mem.provider, version: mem.version, heartbeatAgeSecs: heartbeatAgeSecs(mem, nowMs) }
+        : null,
+      voice: voice
+        ? { provider: voice.provider, version: voice.version, heartbeatAgeSecs: heartbeatAgeSecs(voice, nowMs) }
+        : null,
+      fda: probeFullDiskAccess(env),
+    },
+    peers,
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Events — tail-follow of the durable logs → SSE
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FleetEvent extends ParsedEventLine {
+  /** Which log the event came from: lifecycle | delivery | exits. */
+  src: string
+}
+
+/** The three durable event logs under cfg.eventLogDir (exits.log shares the dir —
+ *  lifecycle/index.ts passes exitLogDir: cfg.eventLogDir). */
+export function fleetEventFiles(cfg: LifecycleConfig): Array<{ path: string; src: string }> {
+  return [
+    { path: lifecycleLogPath(cfg.eventLogDir), src: 'lifecycle' },
+    { path: deliveryLogPath(cfg.eventLogDir), src: 'delivery' },
+    { path: exitLogPath(cfg.eventLogDir), src: 'exits' },
+  ]
+}
+
+/** The newest `limit` events across the given logs (merged by timestamp) — the SSE
+ *  `replay=N` primer and the peer-detail recent-events reader. Reads only the last
+ *  64 KiB of each file. */
+export function readRecentEvents(
+  files: Array<{ path: string; src: string }>,
+  limit: number,
+  concerning?: string,
+): FleetEvent[] {
+  const events: FleetEvent[] = []
+  for (const f of files) {
+    for (const line of readLogTail(f.path).split('\n')) {
+      const e = parseEventLine(line)
+      if (!e) continue
+      if (concerning && !eventConcernsPeer(e, concerning)) continue
+      events.push({ ...e, src: f.src })
+    }
+  }
+  events.sort((a, b) => a.tsMs - b.tsMs)
+  return events.slice(-limit)
+}
+
+interface TailState {
+  path: string
+  src: string
+  offset: number
+  partial: string
+}
+
+/**
+ * Shared poll-based tail-follower over the durable logs: ONE timer regardless of
+ * how many SSE subscribers are connected (starts with the first, stops with the
+ * last). Rotation-aware: a size SMALLER than the held offset means the base file
+ * was rotated away (base → .1) — reading restarts at 0 on the fresh file. Poll is
+ * deliberately chosen over fs.watch: rotation-robust, no platform edge cases, and
+ * a few-hundred-ms latency is invisible on a dashboard.
+ */
+export class FleetEventTailer {
+  private readonly files: TailState[]
+  private readonly subs = new Set<(e: FleetEvent) => void>()
+  private timer: ReturnType<typeof setInterval> | undefined
+  constructor(
+    files: Array<{ path: string; src: string }>,
+    private readonly pollMs = 400,
+    private readonly statSize: (path: string) => number | null = defaultStatSize,
+    private readonly readFrom: (path: string, offset: number, length: number) => string | null = defaultReadFrom,
+  ) {
+    this.files = files.map(f => ({ ...f, offset: -1, partial: '' }))
+  }
+
+  /** Subscribe to live events; returns the unsubscribe function. The FIRST
+   *  subscriber primes every offset to the current EOF (history is the replay
+   *  reader's job) and starts the poll timer; the last unsubscribe stops it. */
+  subscribe(fn: (e: FleetEvent) => void): () => void {
+    if (this.subs.size === 0) {
+      for (const f of this.files) {
+        f.offset = this.statSize(f.path) ?? 0
+        f.partial = ''
+      }
+      this.timer = setInterval(() => this.tick(), this.pollMs)
+      this.timer.unref?.()
+    }
+    this.subs.add(fn)
+    return () => {
+      this.subs.delete(fn)
+      if (this.subs.size === 0 && this.timer) {
+        clearInterval(this.timer)
+        this.timer = undefined
+      }
+    }
+  }
+
+  /** One poll pass over every file — exposed for tests (deterministic, no timer). */
+  tick(): void {
+    for (const f of this.files) {
+      const size = this.statSize(f.path)
+      if (size === null) {
+        // file gone (rotation window / never created yet) — restart at 0 when it appears
+        f.offset = 0
+        f.partial = ''
+        continue
+      }
+      if (size < f.offset) {
+        // rotated: base moved to .1, a fresh base is being written — restart
+        f.offset = 0
+        f.partial = ''
+      }
+      if (size === f.offset) continue
+      const chunk = this.readFrom(f.path, f.offset, size - f.offset)
+      if (chunk === null) continue // transient read failure — retry next tick
+      f.offset = size
+      const text = f.partial + chunk
+      const lines = text.split('\n')
+      f.partial = lines.pop() ?? '' // the trailing piece before the next newline
+      for (const line of lines) {
+        const e = parseEventLine(line)
+        if (!e) continue
+        for (const s of [...this.subs]) {
+          try {
+            s({ ...e, src: f.src })
+          } catch {
+            /* a subscriber must never break the tailer */
+          }
+        }
+      }
+    }
+  }
+}
+
+function defaultStatSize(path: string): number | null {
+  try {
+    return statSync(path).size
+  } catch {
+    return null
+  }
+}
+
+function defaultReadFrom(path: string, offset: number, length: number): string | null {
+  try {
+    const fd = openSync(path, 'r')
+    try {
+      const buf = Buffer.alloc(length)
+      const n = readSync(fd, buf, 0, length, offset)
+      return buf.subarray(0, n).toString('utf8')
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return null
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP handler
+// ─────────────────────────────────────────────────────────────────────────────
+
+const JSON_HEADERS = { 'content-type': 'application/json' }
+const MAX_BODY_BYTES = 64 * 1024
+const SSE_HEARTBEAT_MS = 15_000
+const MAX_REPLAY = 500
+
+function sendJson(res: ServerResponse, status: number, value: unknown): void {
+  res.writeHead(status, JSON_HEADERS)
+  res.end(`${JSON.stringify(value)}\n`)
+}
+
+function readBody(req: IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    req.on('data', (c: Buffer) => {
+      size += c.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`))
+        req.destroy()
+        return
+      }
+      chunks.push(c)
+    })
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8').trim()
+      if (!raw) {
+        resolve({})
+        return
+      }
+      try {
+        const parsed = JSON.parse(raw) as unknown
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+          reject(new Error('request body must be a JSON object'))
+          return
+        }
+        resolve(parsed as Record<string, unknown>)
+      } catch (e) {
+        reject(new Error(`invalid JSON body: ${e instanceof Error ? e.message : String(e)}`))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+/** Resolve the SENDER identity for POST /fleet/v1/send. Explicit `from` (either a
+ *  full `<runtime>-<personality>` or a bare personality → its default runtime) wins;
+ *  otherwise the SINGLE natural-intelligence peer of the registry (the host owner —
+ *  a GUI-originated message is the human's). Ambiguity → an instructive error. */
+export function resolveSendCaller(from: string | undefined, env: NodeJS.ProcessEnv): ResolvedCaller {
+  const index = readPeersIndex({ env })
+  if (from?.trim()) {
+    const raw = from.trim()
+    const byName = index.peers.find(p => p.personality === raw)
+    if (byName) return resolveCallerIdentity({ personality: byName.personality, runtime: byName.runtime }, index)
+    const dash = raw.indexOf('-')
+    if (dash > 0) {
+      return resolveCallerIdentity({ runtime: raw.slice(0, dash), personality: raw.slice(dash + 1) }, index)
+    }
+    throw new Error(`unknown from peer "${raw}"`)
+  }
+  const natural = index.peers.filter(p => p.intelligence === 'natural')
+  if (natural.length === 1) {
+    return resolveCallerIdentity({ personality: natural[0]!.personality, runtime: natural[0]!.runtime }, index)
+  }
+  throw new Error(
+    natural.length === 0
+      ? 'no natural-intelligence peer registered — pass "from" explicitly'
+      : `ambiguous default sender (${natural.length} natural peers) — pass "from" explicitly`,
+  )
+}
+
+export interface FleetHandlerOptions {
+  env?: NodeJS.ProcessEnv
+  /** Injectable CLI ops (tests). Default: lazy dynamic import of cli/index.ts. */
+  ops?: FleetOps
+  /** Injectable tailer poll interval (tests). */
+  pollMs?: number
+}
+
+export type FleetHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: { deps: CallToolDeps },
+) => Promise<void>
+
+/**
+ * Build the /fleet/v1 request handler the composition point injects into
+ * startDaemon (StartDaemonOptions.fleet). One handler instance per daemon —
+ * it owns the shared event tailer and the daemon start timestamp.
+ */
+export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler {
+  const env = opts.env ?? process.env
+  const cfg = loadLifecycleConfig(env)
+  const startedAtMs = Date.now()
+  const files = fleetEventFiles(cfg)
+  const tailer = new FleetEventTailer(files, opts.pollMs)
+  let opsPromise: Promise<FleetOps> | undefined
+  const getOps = (): Promise<FleetOps> => {
+    if (opts.ops) return Promise.resolve(opts.ops)
+    opsPromise ??= defaultOps()
+    return opsPromise
+  }
+
+  return async (req, res, ctx) => {
+    const url = new URL(req.url ?? '/', 'http://fleet.local')
+    const path = url.pathname
+    const method = (req.method ?? 'GET').toUpperCase()
+    try {
+      // ── reads ────────────────────────────────────────────────────────────
+      if (path === '/fleet/v1/snapshot') {
+        if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/snapshot' })
+        return sendJson(res, 200, buildFleetSnapshot(env, cfg, await getOps(), startedAtMs))
+      }
+      if (path === '/fleet/v1/events') {
+        if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/events' })
+        serveEvents(req, res, url, tailer, files)
+        return
+      }
+      const peerMatch = /^\/fleet\/v1\/peers\/([^/]+)$/.exec(path)
+      if (peerMatch) {
+        if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/peers/<peer>' })
+        const personality = decodeURIComponent(peerMatch[1]!)
+        const snapshot = buildFleetSnapshot(env, cfg, await getOps(), startedAtMs)
+        const peer = snapshot.peers.find(p => p.personality === personality)
+        if (!peer) return sendJson(res, 404, { error: `unknown peer "${personality}"` })
+        const events = readRecentEvents(files, 50, personality)
+        return sendJson(res, 200, { api: FLEET_API_VERSION, version: IAPEER_VERSION, ts: snapshot.ts, peer, events })
+      }
+      // ── commands ─────────────────────────────────────────────────────────
+      const cmdMatch = /^\/fleet\/v1\/peers\/([^/]+)\/(wake|stop|start|new|refresh|interrupt|compact)$/.exec(path)
+      if (cmdMatch) {
+        if (method !== 'POST') return sendJson(res, 405, { error: 'method not allowed — POST' })
+        const personality = decodeURIComponent(cmdMatch[1]!)
+        const command = cmdMatch[2]!
+        let body: Record<string, unknown>
+        try {
+          body = await readBody(req)
+        } catch (e) {
+          return sendJson(res, 400, { error: e instanceof Error ? e.message : String(e) })
+        }
+        const runtime = typeof body.runtime === 'string' ? body.runtime : undefined
+        const topic = typeof body.topic === 'string' ? body.topic : undefined
+        return await runCommand(res, command, { personality, runtime, topic }, cfg, env, await getOps())
+      }
+      if (path === '/fleet/v1/send') {
+        if (method !== 'POST') return sendJson(res, 405, { error: 'method not allowed — POST /fleet/v1/send' })
+        let body: Record<string, unknown>
+        try {
+          body = await readBody(req)
+        } catch (e) {
+          return sendJson(res, 400, { error: e instanceof Error ? e.message : String(e) })
+        }
+        if (typeof body.personality !== 'string' || !body.personality || typeof body.message !== 'string' || !body.message) {
+          return sendJson(res, 400, { error: 'send needs {personality, message} (+ optional runtime/topic/from)' })
+        }
+        let caller: ResolvedCaller
+        try {
+          caller = resolveSendCaller(typeof body.from === 'string' ? body.from : undefined, env)
+        } catch (e) {
+          return sendJson(res, 400, { error: e instanceof Error ? e.message : String(e) })
+        }
+        // The SAME path the MCP tool takes (routeSend + delivery.log + post-delivery
+        // hooks) — ctx.deps is the daemon's own wired CallToolDeps.
+        const result = await callTool(
+          caller,
+          'send_to_peer',
+          {
+            personality: body.personality,
+            runtime: typeof body.runtime === 'string' ? body.runtime : undefined,
+            message: body.message,
+            topic: typeof body.topic === 'string' ? body.topic : undefined,
+          },
+          ctx.deps,
+        )
+        const text = result.content[0]?.text ?? ''
+        if (result.isError) return sendJson(res, 502, { error: text })
+        return sendJson(res, 200, { from: caller.address, result: safeParse(text) })
+      }
+      return sendJson(res, 404, {
+        error: `unknown fleet endpoint ${method} ${path}`,
+        endpoints: [
+          'GET /fleet/v1/snapshot',
+          'GET /fleet/v1/peers/<peer>',
+          'GET /fleet/v1/events?replay=N',
+          'POST /fleet/v1/peers/<peer>/(wake|stop|start|new|refresh|interrupt|compact)',
+          'POST /fleet/v1/send',
+        ],
+      })
+    } catch (e) {
+      if (!res.headersSent) {
+        sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) })
+      } else {
+        try {
+          res.end()
+        } catch {
+          /* connection already gone */
+        }
+      }
+    }
+  }
+}
+
+function safeParse(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+async function runCommand(
+  res: ServerResponse,
+  command: string,
+  args: { personality: string; runtime?: string; topic?: string },
+  cfg: LifecycleConfig,
+  env: NodeJS.ProcessEnv,
+  ops: FleetOps,
+): Promise<void> {
+  const { personality, runtime, topic } = args
+  switch (command) {
+    case 'wake': {
+      // Same H4 / crash-loop / wake-lock semantics as a message wake — wakeOrSpawn
+      // owns them. task:'' = bare bring-up (the seed/initial prompt is the first turn).
+      const r = await wakeOrSpawn({ personality, runtime, topic, task: '' }, { cfg, env })
+      return sendJson(res, r.status === 'FAILED' ? 502 : 200, { command, ...r })
+    }
+    case 'stop': {
+      const outcomes = ops.stopPeer(personality, runtime, { env })
+      const failed = outcomes.some(o => o.action === 'refused-foreign-launchd' || (o.action === 'bootout' && o.reason !== undefined))
+      return sendJson(res, failed ? 502 : 200, { command, outcomes })
+    }
+    case 'start': {
+      const outcomes = ops.startPeer(personality, runtime, { env })
+      const failed = outcomes.some(o => o.action === 'refused-foreign-launchd' || (o.action === 'bootstrap' && o.reason !== undefined))
+      return sendJson(res, failed ? 502 : 200, { command, outcomes })
+    }
+    case 'new': {
+      const o = await ops.newPeer(personality, runtime, { env })
+      return sendJson(res, o.action === 'fresh' ? 200 : 502, { command, ...o })
+    }
+    case 'refresh': {
+      const outcomes = ops.refreshPeer(personality, runtime, { env })
+      return sendJson(res, 200, { command, outcomes })
+    }
+    case 'interrupt': {
+      const r = await routeControl(personality, runtime, { name: 'interrupt' })
+      if (!r.ok) return sendJson(res, 502, { command, error: r.error.message })
+      return sendJson(res, 200, { ...r.value, command }) // routeControl echoes its own `command` — ours (the endpoint name) wins
+    }
+    case 'compact': {
+      const o = await ops.compactPeer(personality, runtime, { env })
+      return sendJson(res, o.action === 'compacted' ? 200 : 502, { command, ...o })
+    }
+    default:
+      return sendJson(res, 404, { error: `unknown command "${command}"` })
+  }
+}
+
+/** Serve the SSE event stream: optional replay of the newest N historical events,
+ *  then live tail. At-least-once semantics (a reconnect may re-see events — `id`
+ *  is the event's epoch-ms for client-side dedup); heartbeat comment every 15 s. */
+function serveEvents(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  tailer: FleetEventTailer,
+  files: Array<{ path: string; src: string }>,
+): void {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+  })
+  const writeEvent = (e: FleetEvent): void => {
+    const data = JSON.stringify({ src: e.src, ev: e.ev, ...e.fields })
+    res.write(`event: ${e.ev}\nid: ${e.tsMs}\ndata: ${data}\n\n`)
+  }
+  const replayRaw = parseInt(url.searchParams.get('replay') ?? '', 10)
+  const replay = Number.isFinite(replayRaw) ? Math.max(0, Math.min(MAX_REPLAY, replayRaw)) : 0
+  if (replay > 0) for (const e of readRecentEvents(files, replay)) writeEvent(e)
+  res.write(`: connected\n\n`)
+  const unsubscribe = tailer.subscribe(writeEvent)
+  const heartbeat = setInterval(() => {
+    try {
+      res.write(`: hb\n\n`)
+    } catch {
+      /* torn connection — close handler cleans up */
+    }
+  }, SSE_HEARTBEAT_MS)
+  heartbeat.unref?.()
+  const cleanup = (): void => {
+    clearInterval(heartbeat)
+    unsubscribe()
+  }
+  res.on('close', cleanup)
+  req.on('close', cleanup)
+}

package/src/daemon/index.ts

@@ -359,6 +359,23 @@ export interface DaemonHandle {
   close: () => Promise<void>
 }
 
+/**
+ * The fleet-API request handler seam (Ф0 iapeer-tray) — the OPERATOR-CLIENT HTTP
+ * surface (/fleet/v1/*: snapshot + SSE events + commands), served on the SAME
+ * listeners behind the SAME bearer gate as the MCP path. Injected by the
+ * composition point (daemon/main.ts wires daemon/fleet.ts's buildFleetHandler) so
+ * the daemon library never imports lifecycle/CLI — the same seam pattern as
+ * wake/supervise. `ctx.deps` is the daemon's wired CallToolDeps: the fleet send
+ * command routes through the SAME callTool path as the MCP tool (delivery.log +
+ * post-delivery hooks included). OFF by default (library/tests): without the seam,
+ * /fleet/* URLs fall through to the MCP handler like any other request.
+ */
+export type FleetRequestHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: { deps: CallToolDeps },
+) => Promise<void>
+
 export interface StartDaemonOptions extends StorageOptions {
   /**
    * Unix-socket path (H8 base: 0600, same-uid local callers — CLI / pane /
@@ -439,6 +456,12 @@ export interface StartDaemonOptions extends StorageOptions {
   /** H4 launchd-managed detector — see CallToolDeps.isLaunchdManaged / the launchd-revive
    *  delivery retry. OFF by default (library/tests); production main wires the real one. */
   isLaunchdManaged?: (personality: string) => boolean
+  /**
+   * Fleet-API handler (see FleetRequestHandler) — serves /fleet/v1/* on both
+   * listeners, behind the bearer gate. OFF by default; the production main wires
+   * daemon/fleet.ts's buildFleetHandler. Advertised in router.json as `fleet: 1`.
+   */
+  fleet?: FleetRequestHandler
   /**
    * Write the discovery file (router.json) at <root>/state/iapeer/router.json with
    * the active addresses `{sock, tcp}` — atomically on listen, removed on close.
@@ -456,27 +479,51 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
   const host = opts.host ?? '127.0.0.1'
   const bearer = opts.bearerToken?.trim() || undefined
 
-  // ONE MCP request handler, shared by EVERY listener (socket + TCP). Stateless:
+  // The ONE wired CallToolDeps object — shared by the per-request MCP servers AND
+  // the fleet-API handler (its send command routes through the SAME callTool path,
+  // so a fleet-originated send gets the identical delivery.log line + hooks).
+  const callDeps: CallToolDeps = {
+    env: opts.env, // Б7 — thread the daemon's storage env into the request path (registry read + routeSend)
+    wake: opts.wake,
+    deliveryLogDir: opts.deliveryLogDir,
+    onDelivered: opts.onDelivered,
+    ephemeral: opts.ephemeral,
+    noteLiveTopic: opts.noteLiveTopic,
+    noteDelivered: opts.noteDelivered,
+    composerQueue: opts.composerQueue,
+    isLaunchdManaged: opts.isLaunchdManaged,
+  }
+
+  // ONE HTTP request handler, shared by EVERY listener (socket + TCP): the bearer
+  // gate first, then the fleet-API branch (when wired), then stateless MCP —
   // a fresh Server + transport per request, fully isolated.
   const handle = (req: IncomingMessage, res: ServerResponse): void => {
-    // H8 bearer layer (FIRST, before any MCP work): when a token is configured,
+    // H8 bearer layer (FIRST, before any MCP/fleet work): when a token is configured,
     // reject anything not carrying `Authorization: Bearer <token>`. Off when unset.
     if (bearer && req.headers.authorization !== `Bearer ${bearer}`) {
       res.writeHead(401, { 'content-type': 'application/json', 'www-authenticate': 'Bearer' })
       res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32001, message: 'unauthorized' } }))
       return
     }
-    const server = createMcpServer({
-      env: opts.env, // Б7 — thread the daemon's storage env into the request path (registry read + routeSend)
-      wake: opts.wake,
-      deliveryLogDir: opts.deliveryLogDir,
-      onDelivered: opts.onDelivered,
-      ephemeral: opts.ephemeral,
-      noteLiveTopic: opts.noteLiveTopic,
-      noteDelivered: opts.noteDelivered,
-      composerQueue: opts.composerQueue,
-      isLaunchdManaged: opts.isLaunchdManaged,
-    })
+    // Fleet-API branch (Ф0 iapeer-tray): /fleet/* is the operator-client surface.
+    // Deliberately AFTER the bearer gate and BEFORE MCP — the two surfaces share
+    // listeners but never overlap in URL space.
+    if (opts.fleet && req.url && (req.url === '/fleet' || req.url.startsWith('/fleet/'))) {
+      void opts.fleet(req, res, { deps: callDeps }).catch(() => {
+        if (!res.headersSent) {
+          res.writeHead(500, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ error: 'internal error' }))
+        } else {
+          try {
+            res.end()
+          } catch {
+            /* connection already gone */
+          }
+        }
+      })
+      return
+    }
+    const server = createMcpServer(callDeps)
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
     res.on('close', () => {
       transport.close()
@@ -568,7 +615,12 @@ export async function startDaemon(opts: StartDaemonOptions = {}): Promise<Daemon
     // `version` (В53): the RUNNING daemon's baked version — lets `iapeer update`
     // detect an interrupted update (binary already at latest, live daemon still on
     // the old code) and heal it with a restart instead of a false "already-latest".
-    writeFileAtomic(discoveryPath, `${JSON.stringify({ sock: socketPath ?? null, tcp: url ?? null, version: IAPEER_VERSION })}\n`)
+    // `fleet` (Ф0 iapeer-tray): the fleet-API capability marker — a client reads it
+    // to know this daemon serves /fleet/v1/* (absent on pre-fleet daemons).
+    writeFileAtomic(
+      discoveryPath,
+      `${JSON.stringify({ sock: socketPath ?? null, tcp: url ?? null, version: IAPEER_VERSION, ...(opts.fleet ? { fleet: 1 } : {}) })}\n`,
+    )
   }
 
   const removeArtifacts = (): void => {

package/src/daemon/main.ts

@@ -66,6 +66,7 @@ import {
 } from '../transport/index.ts'
 import { iapeerBinPath } from '../install/index.ts'
 import { appendDeliveryEvent } from './deliverylog.ts'
+import { buildFleetHandler } from './fleet.ts'
 import { defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
 
 /** Default TCP loopback port for the always-on router. Real http MCP clients
@@ -362,6 +363,11 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     // launchd-managed target (the daemon can't wake it, but KeepAlive revives it) → retry-
     // resolve for a bounded window instead of failing in ~16ms — bridges a router restart.
     isLaunchdManaged: (personality: string) => isLaunchdManaged(personality, env),
+    // Fleet-API (Ф0 iapeer-tray): the operator-client surface /fleet/v1/* — snapshot
+    // (the same listPeers truth as `iapeer list`), SSE events (tail of the durable
+    // logs), commands over the existing verb functions. Same listeners, same bearer
+    // gate; advertised in router.json as fleet:1. Contract: docs/15-fleet-api.md.
+    fleet: buildFleetHandler({ env }),
     supervise: {
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
       // idle-reap / zombie-sweep, THEN the eager fresh re-launch for any peer whose

package/src/tui/dashboard/data.ts

@@ -6,12 +6,12 @@
 // All paths resolve through the injected env → the same IAPEER_ROOT isolation as
 // every other side-effect (sandbox rule). Reads only — the dashboard mutates nothing.
 
-import { closeSync, openSync, readSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { listPeers, type PeerListing } from '../../cli/index.ts'
 import { loadLifecycleConfig } from '../../lifecycle/index.ts'
 import { deliveryLogPath } from '../../daemon/deliverylog.ts'
 import { lifecycleLogPath } from '../../lifecycle/eventlog.ts'
+import { readLogTail } from '../../storage/rotatelog.ts'
 import { assemblePeerLog } from './model.ts'
 
 /** One peers snapshot (the poll unit). listPeers is synchronous and cheap: registry
@@ -42,26 +42,10 @@ export async function takeHostHeader(env: NodeJS.ProcessEnv): Promise<HostHeader
   }
 }
 
-/** Read the last `bytes` of a file without loading the whole log (delivery.log can
- *  be MBs before rotation). Missing/unreadable file → ''. */
-export function readTail(path: string, bytes = 64 * 1024): string {
-  try {
-    const size = statSync(path).size
-    const fd = openSync(path, 'r')
-    try {
-      const start = Math.max(0, size - bytes)
-      const buf = Buffer.alloc(size - start)
-      readSync(fd, buf, 0, buf.length, start)
-      // drop the leading partial line when we started mid-file
-      const s = buf.toString('utf8')
-      return start > 0 ? s.slice(s.indexOf('\n') + 1) : s
-    } finally {
-      closeSync(fd)
-    }
-  } catch {
-    return ''
-  }
-}
+/** Read the last `bytes` of a file without loading the whole log. Promoted to the
+ *  storage layer (readLogTail — the fleet-API replay reader shares it); kept as a
+ *  re-export so dashboard call sites/tests are untouched. */
+export const readTail: (path: string, bytes?: number) => string = readLogTail
 
 /** The per-peer log panel content: newest `limit` events concerning the peer from
  *  delivery.log + lifecycle.log (merged by timestamp). */

package/src/tui/dashboard/model.ts

@@ -8,6 +8,7 @@
 // under `bun test` with zero terminal plumbing.
 
 import type { PeerListing } from '../../cli/index.ts'
+import { eventConcernsPeer as concernsPeer, parseEventLine as parseLogfmtLine } from '../../storage/rotatelog.ts'
 
 // ─── row filtering ───────────────────────────────────────────────────────────
 
@@ -55,36 +56,22 @@ export interface LogEvent {
   fields: Record<string, string>
 }
 
-/** Parse one `ts=<iso> ev=<kind> k=v …` line; null for anything else (corrupt tail). */
+/** Parse one `ts=<iso> ev=<kind> k=v …` line; null for anything else (corrupt tail).
+ *  Delegates to the storage-layer QUOTE-AWARE parser (the writer's symmetric read
+ *  half) and adds the display time — the earlier display-only tokenizer split quoted
+ *  multi-word values (reason="idle 3700s") mid-value. */
 export function parseEventLine(line: string): LogEvent | null {
-  if (!line.startsWith('ts=')) return null
-  const fields: Record<string, string> = {}
-  // k=v tokens; values are token-atomic in our append format (no embedded spaces).
-  for (const tok of line.split(' ')) {
-    const i = tok.indexOf('=')
-    if (i > 0) fields[tok.slice(0, i)] = tok.slice(i + 1)
-  }
-  const ts = fields.ts
-  const ev = fields.ev
-  if (!ts || !ev) return null
-  const tsMs = Date.parse(ts)
-  if (!Number.isFinite(tsMs)) return null
-  const d = new Date(tsMs)
+  const p = parseLogfmtLine(line)
+  if (!p) return null
+  const d = new Date(p.tsMs)
   const pad = (n: number): string => String(n).padStart(2, '0')
-  return { tsMs, time: `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`, ev, fields }
+  return { tsMs: p.tsMs, time: `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`, ev: p.ev, fields: p.fields }
 }
 
 /** Does this event concern the peer? Matches bare personality and any `<rt>-<personality>`
- *  identity in the fields the two logs actually carry (to/caller/via/personality/identity). */
-export function eventConcernsPeer(e: LogEvent, personality: string): boolean {
-  const idSuffix = `-${personality}`
-  for (const key of ['to', 'caller', 'via', 'personality', 'identity', 'from', 'peer'] as const) {
-    const v = e.fields[key]
-    if (!v) continue
-    if (v === personality || v.endsWith(idSuffix)) return true
-  }
-  return false
-}
+ *  identity in the fields the two logs actually carry (to/caller/via/personality/identity).
+ *  Re-exported from the storage layer (the fleet peer-detail endpoint shares it). */
+export const eventConcernsPeer: (e: LogEvent, personality: string) => boolean = concernsPeer
 
 /** One display line per event — compact, the interesting fields only. */
 export function formatEvent(e: LogEvent): { text: string; tone: 'ok' | 'fail' | 'info' } {