chore: seed repo with spec, plan, and design

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-09 19:50:15 +07:00
commit 83f1c1f57d
6 changed files with 12502 additions and 0 deletions
@@ -0,0 +1,437 @@
+# spacesh — техническая спецификация
+
+> Терминал-воркспейс под AI-агентов. macOS-first. Tauri 2 + Rust + React/TypeScript.
+> Версия документа: v0.1 (handoff-ready). Назначение: спецификация для реализации.
+
+---
+
+## 0. Допущения и зафиксированный скоуп
+
+Документ фиксирует решения, принятые на этапе проектирования. Несколько вещей сознательно **вынесены за рамки v1**:
+
+- **Учёт токенов и остатков лимитов — НЕ входит в v1.** Решено убрать из уравнения; провайдерские API для остатков грязные/против ToS, а ценность размыта существующими menu-bar трекерами. Может вернуться позже как отдельный подписчик на шину.
+- **Юридический слой (авторизация пользователей, хранение чужих токенов, ToS-обвязка) — НЕ входит в v1.** Инструмент в первую очередь делается под себя. Вопрос продажи откладывается.
+- **Встроенный браузер — выкинут.** Большая поверхность поддержки, нулевая ценность для агентского флоу.
+- **Полноценный редактор (Monaco-класс) — отложен.** В v1 — дерево файлов + diff-просмотр изменений агента (CodeMirror 6), не IDE.
+
+**Фича «модификации» уточнена как внешние нотификации.** В v1 это рассылка уведомлений о событиях агентов во внешние каналы — **в первую очередь Telegram и MAX**. Реализуется как подписчик внутри демона на события шины (см. §9.2). Guardrails (перехват команд) — не входит в v1.
+
+---
+
+## 1. Идея проекта
+
+### 1.1. Проблема
+
+Один AI-агент в терминале — управляем глазами. Пять-восемь агентов параллельно в разных проектах — нет: непонятно, кто закончил, кто упал, кто ждёт ввода, к кому возвращаться. Обычный терминал/tmux не сообщает статус сам, раскладки не переживают перезапуск удобно, а единого способа дёрнуть нужную панель из скрипта нет.
+
+### 1.2. Что такое spacesh
+
+Терминал-воркспейс, где **бэкенд-демон владеет живыми сессиями**, а GUI и CLI — тонкие клиенты к нему. Воркспейс на проект, реальные PTY со сплитами, видимый статус каждого агента (детерминированный, через хуки агентов), единый CLI поверх той же командной шины. Всё с клавиатуры, macOS-native.
+
+### 1.3. Ключевые отличия от аналогов (pilotry и пр.)
+
+1. **Демон переживает GUI.** Краш/обновление приложения не убивает агента в середине задачи. Прямая дорога к remote/SSH-воркспейсам (демон на ноде — GUI на макбуке).
+2. **macOS-native.** Аналоги Windows-first; spacesh строится сразу под WKWebView, launchd, нативные хоткеи и уведомления.
+3. **Детерминированный статус** через хуки агентов вместо угадывания по выводу.
+4. **Единая командная шина** — GUI и CLI идут через один socket, CLI получается почти бесплатно.
+
+### 1.4. Чем spacesh НЕ является
+
+Не IDE, не браузер, не замена tmux в смысле мультиплексора для серверов (хотя архитектурно к remote готов), не агент сам по себе — spacesh запускает чужие официальные CLI (Claude Code, Codex, Gemini, opencode, shell) в PTY и не подменяет их логику.
+
+### 1.5. Целевой пользователь (v1)
+
+Senior-инфраструктурщик/разработчик, гоняющий несколько агентов параллельно на macOS, скриптующий своё окружение, ценящий клавиатурный флоу и переживаемость сессий.
+
+---
+
+## 2. Принципы и нефункциональные требования
+
+| Принцип | Следствие в реализации |
+|---|---|
+| Демон — единственный источник истины | GUI и CLI не хранят состояние; только шлют команды и слушают события |
+| Keyboard-first | Весь рабочий цикл закрывается с клавиатуры; мышь — только ресайз |
+| macOS-native | launchd user-agent для демона, нативные уведомления с actions, WKWebView-aware фронт |
+| Лёгкость | Системный webview (Tauri), без встроенного Chromium |
+| Переживаемость | Сессии живут в демоне между перезапусками GUI |
+| Расширяемость через шину | Новые фичи = новые команды/события/подписчики, спина не двигается |
+
+**Бюджеты производительности:**
+
+- Латентность ввода (keypress → echo в панели): < 16 мс при нормальной нагрузке.
+- Батчинг вывода PTY: коалесцировать ~4–8 мс **или** до ~16 КБ, что раньше; не эмитить событие `output` по байту.
+- Backpressure: при отставании рендера демон не должен расти в памяти неограниченно — кольцевой лимит на неподтверждённый поток к клиенту.
+- Repaint при reattach: снапшот экрана панели < 100 мс на типовой грид.
+
+---
+
+## 3. Архитектура — топология
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ spacesh-daemon (spaceshd)                                 │
+│   владеет:                                                │
+│     • PTY-процессы (по surface)                           │
+│     • терминальный грид каждой панели (alacritty_terminal)│
+│     • модель воркспейсов / дерево сплитов / раскладки      │
+│     • движок статусов                                     │
+│     • подписчики (нотификации Telegram/MAX)              │
+│                                                           │
+│   хостит: Unix-domain socket  ~/.spacesh/sock             │
+└───────────────┬───────────────────────┬──────────────────┘
+                │                        │
+        attach/команды/события     команды/события (--json)
+                │                        │
+     ┌──────────┴─────────┐     ┌────────┴───────────┐
+     │ GUI-клиент (Tauri) │     │ CLI-клиент (spacesh)│
+     │  рендер xterm.js   │     │  тонкий бинарь      │
+     │  ввод, attach/det. │     │  shell-completions  │
+     └────────────────────┘     └─────────────────────┘
+```
+
+Один socket, один протокол. И клик в GUI, и `spacesh focus s_8f3` из скрипта — это одна и та же команда `focus`. Никакой дубликации операционной логики.
+
+---
+
+## 4. Процессная модель (вариант B — демон)
+
+### 4.1. Жизненный цикл демона
+
+- Демон стартует лениво: первый клиент (GUI или CLI), не найдя socket, поднимает `spaceshd` и ждёт готовности.
+- Под macOS оборачивается в **launchd user-agent** (`~/Library/LaunchAgents/xyz.spacesh.daemon.plist`) с `KeepAlive` — автоперезапуск при краше, автостарт при логине (опционально, по настройке).
+- Демон single-instance: лок-файл `~/.spacesh/daemon.lock` + проверка живости socket.
+- Graceful shutdown по команде `shutdown` или при отсутствии сессий и клиентов дольше TTL (настраиваемо; по умолчанию демон живёт, пока живы сессии).
+
+### 4.2. Переживаемость сессий
+
+PTY-процессы принадлежат демону, а не GUI. Закрытие/краш/обновление GUI **не убивает** агентов. При следующем запуске GUI выполняет `attach` к живым панелям и репейнтит их из снапшота грида (см. §6.4).
+
+Раскладка (определение воркспейсов, дерево сплитов, привязка агентов к панелям) персистится на диск отдельно от живых процессов (§8.4) — так что даже полная перезагрузка демона восстанавливает структуру (с перезапуском агентов), а краш GUI восстанавливает и структуру, и живые процессы.
+
+### 4.3. Эволюция к remote (вне v1, но заложено)
+
+Socket абстрагирован за трейтом транспорта. UDS локально сегодня → проброс через SSH (`ssh -L` к UDS на ноде) завтра → нативный TCP+mTLS позже. Демон не знает, локальный клиент или удалённый.
+
+---
+
+## 5. Протокол командной шины
+
+### 5.1. Транспорт и кадрирование
+
+- Транспорт: Unix-domain socket, асинхронный (tokio).
+- Кадрирование: **length-prefixed** (`u32` BE длина + payload).
+- Сериализация: **JSON** в v1 (читаемость, отладка, `--json` для CLI). Возможна замена на MessagePack при упоре в объём вывода — изолировано в `spacesh-proto`.
+- Мультиплексирование: один socket на клиента; внутри — корреляция запрос/ответ по `id`, плюс независимый поток push-событий.
+
+### 5.2. Конверт сообщения
+
+```jsonc
+// Запрос (клиент → демон)
+{ "id": 42, "kind": "req", "cmd": "focus", "args": { "surface_id": "s_8f3" } }
+
+// Ответ (демон → клиент), коррелируется по id
+{ "id": 42, "kind": "res", "ok": true, "data": { /* ... */ } }
+{ "id": 42, "kind": "res", "ok": false, "error": { "code": "NOT_FOUND", "msg": "..." } }
+
+// Событие (демон → подписчики), без id запроса
+{ "kind": "evt", "evt": "state", "data": { "surface_id": "s_8f3", "state": "done" } }
+```
+
+### 5.3. Команды (request/response)
+
+| Команда | Аргументы | Ответ | Назначение |
+|---|---|---|---|
+| `open` | `{ path }` | `{ workspace_id }` | Открыть директорию воркспейсом; повторный вызов не плодит дубль |
+| `close_workspace` | `{ workspace_id }` | `{}` | Закрыть воркспейс (с подтверждением при живых панелях) |
+| `new_surface` | `{ workspace_id, agent, split? }` | `{ surface_id }` | Поднять панель с агентом; `split: right\|down` — сразу сплитом |
+| `close` | `{ surface_id }` | `{}` | Закрыть панель |
+| `focus` | `{ surface_id }` | `{}` | Сфокусировать панель и поднять окно |
+| `input` | `{ surface_id, bytes }` | `{}` | Ввод с клавиатуры (base64 в JSON) |
+| `resize` | `{ surface_id, cols, rows }` | `{}` | Ресайз PTY (→ SIGWINCH) |
+| `attach` | `{ surface_id }` | `{ snapshot, cols, rows, cursor }` | Подписаться на панель + получить снапшот для репейнта |
+| `detach` | `{ surface_id }` | `{}` | Отписаться от потока панели |
+| `status` | `{ json? }` | `{ workspaces[] }` | Список воркспейсов и панелей с состояниями |
+| `set_state` | `{ surface_id, state }` | `{}` | Внешний сигнал статуса (от хуков агента, см. §7) |
+| `move_surface` | `{ surface_id, target }` | `{}` | Перетаскивание/переупорядочивание |
+| `apply_preset` | `{ workspace_id, preset_id }` | `{ surface_ids[] }` | Развернуть пресет раскладки |
+| `shutdown` | `{}` | `{}` | Остановить демон |
+
+### 5.4. События (push)
+
+| Событие | Данные | Назначение |
+|---|---|---|
+| `output` | `{ surface_id, bytes }` | Живой поток вывода PTY для рендера (батчированный) |
+| `state` | `{ surface_id, state }` | Смена статуса: `done\|wait\|work\|error\|idle` |
+| `exit` | `{ surface_id, code }` | Процесс панели завершился |
+| `surface_created` | `{ surface_id, workspace_id, agent }` | Появилась панель |
+| `surface_closed` | `{ surface_id }` | Панель закрыта |
+
+### 5.5. Жизненный цикл attach/detach (сердце варианта B)
+
+```
+GUI стартует
+  → status                 // получить структуру
+  → для каждой видимой панели: attach { surface_id }
+      ← res { snapshot, cursor }   // репейнт xterm.js из снапшота
+      ← evt output ...             // дальше живой поток
+GUI сворачивается/закрывается
+  → detach (или просто рвёт соединение — демон чистит подписку по closed-socket)
+GUI возвращается
+  → attach снова → новый снапшот → живой поток
+```
+
+Снапшот собирается демоном из Rust-грида (`alacritty_terminal`) и сериализуется в ANSI-дамп, который xterm.js скармливает себе для мгновенного репейнта. Это закрывает главную боль демон-архитектуры — восстановление экрана панели после reattach — без отдельного ring-buffer.
+
+---
+
+## 6. Терминальный слой
+
+### 6.1. PTY
+
+- Крейт: **`portable-pty`** (спавн, master/slave, resize). Кроссплатформенно — пригодится, даже если v1 только macOS.
+- На surface: один PTY + дочерний процесс (агентский CLI или shell), рабочая директория = папка воркспейса, прокинутый env.
+
+### 6.2. Reader-loop, батчинг, backpressure
+
+- Отдельная async-задача на PTY читает в буфер.
+- **Коалесцирование:** накапливать вывод и эмитить `output` раз в ~4–8 мс или по достижении ~16 КБ. Билд-лог на 50k строк не должен порождать 50k событий.
+- **Backpressure:** на каждого подписчика — ограниченный канал. При переполнении (рендер не успевает) — дропать/сжимать промежуточные кадры, но грид в демоне (§6.3) обновлять всегда — он авторитетный.
+
+### 6.3. Гибрид-парсинг (xterm.js рендер / Rust-грид семантика)
+
+Один байтовый поток PTY раздаётся в **три** места:
+
+1. **GUI** (событие `output`) → **xterm.js** парсит ANSI и рисует. Аддоны: `webgl` (рендер), `search`, `serialize`, `web-links`.
+2. **Rust-грид** (`alacritty_terminal`) в демоне → авторитетная модель экрана/скроллбэка. Используется для:
+   - детекции статуса (fallback-паттерны, §7.3),
+   - поиска по скроллбэку на стороне демона,
+   - извлечения вывода последней команды (по маркерам OSC 133),
+   - снапшота при reattach (§6.4).
+3. Тот же грид служит источником снапшота — отдельный буфер не нужен.
+
+Развод **отображения** (xterm.js) и **анализа** (alacritty-грид) снимает ложный выбор «или рендер, или умная модель». Два парсера на один stream дёшево.
+
+> Выбор `alacritty_terminal` (а не голого `vte`): он держит полноценный грид с курсором и скроллбэком из коробки, что нужно и для семантики, и для снапшота. `vte` дал бы только парсинг esc-последовательностей без модели экрана.
+
+### 6.4. Снапшот и репейнт
+
+При `attach` демон сериализует текущий грид панели → ANSI-дамп (видимая область + позиция курсора + при необходимости часть скроллбэка) → GUI пишет его в свежий инстанс xterm.js. Дальше едет живой `output`. Бюджет — см. §2.
+
+---
+
+## 7. Детекция статуса (инверсия)
+
+Статус не угадывается из вывода, а **приходит в демон как команда** `set_state`. Источники, по убыванию надёжности:
+
+### 7.1. Хуки агентов (основной путь)
+
+- **Claude Code** поддерживает хуки (Stop / Notification и родственные). Вешаем на них вызов CLI:
+  ```
+  spacesh notify --surface $SPACESH_SURFACE_ID --state done   # на завершение
+  spacesh notify --surface $SPACESH_SURFACE_ID --state wait   # на запрос ввода
+  ```
+  CLI шлёт `set_state` в socket → демон ставит статус → событие `state` → кольцо панели меняет цвет. Детерминированно.
+- `$SPACESH_SURFACE_ID` инжектируется в env панели при спавне — так хук знает, про какую панель сообщает.
+
+> **Внимание при реализации:** точные имена хуков и формат payload у Claude Code меняются между версиями. Слой интеграции с хуками изолировать в адаптер и версионировать; не зашивать имена в ядро.
+
+### 7.2. OSC 133 для shell
+
+Для обычных shell-панелей инжектировать shell-integration с **OSC 133** (semantic prompt marking): чёткие маркеры «команда началась / закончилась + exit code». Даёт статус (`work` между A/C-маркерами, `done`/`error` по exit code), а заодно навигацию по промптам и извлечение вывода последней команды.
+
+### 7.3. Fallback — паттерны вывода
+
+Для агентов без хуков — эвристики поверх alacritty-грида (спиннеры, промпт-паттерны, запросы подтверждения). Изолировано в один модуль, считается best-effort. Меньшинство кейсов.
+
+### 7.4. Состояния
+
+`work` (работает) · `wait` (ждёт ввода) · `done` (готов) · `error` (ошибка) · `idle` (простаивает). Маппятся на цвет кольца панели и бейдж в сайдбаре.
+
+---
+
+## 8. Модель воркспейсов и раскладки
+
+### 8.1. Сущности
+
+- **Workspace** — папка проекта + дерево сплитов + метаданные (имя, цвет, группа, флаг «не забыть»).
+- **Surface (панель)** — лист дерева сплитов; PTY + агент + состояние.
+- **Split node** — внутренний узел: ориентация (`h`/`v`) + дети + пропорции.
+- **Group** — именованная цветная коллекция воркспейсов с порядком.
+
+### 8.2. Дерево сплитов
+
+Рекурсивное бинарное (или n-арное) дерево. Ресайз — изменение пропорций узла. 10 пресет-раскладок: `1`, `2↔`, `2↕`, `2+1`, `1+2`, `3`, `2×2`, `4`, `2×3`, `2×4`.
+
+### 8.3. Пресеты
+
+Пресет = (раскладка панелей) + (привязка агента к каждой панели). Сохранённый пресет → запуск в один клик (`apply_preset`). Хранится в конфиге пользователя.
+
+### 8.4. Персистентность
+
+- Раскладка и метаданные — на диск (`~/.spacesh/state.json` или SQLite, если вырастет), отдельно от живых процессов.
+- Сохранение по изменению (debounce), атомарная запись (temp + rename).
+- При старте демона без живых сессий — структура восстанавливается, агенты перезапускаются по запросу/настройке.
+
+### 8.5. UX-метаданные (дёшево, эффект большой)
+
+- **Цветные группы** воркспейсов.
+- **Метка «не забыть»** — unread-модель как в почте: кружок на воркспейсе, пока к нему не вернулись.
+- **Свой порядок** — перетаскивание, раскладка сохраняется.
+- **Центр событий** — лента уведомлений (готов/ждёт/ошибка) с «отметить прочитанным».
+
+---
+
+## 9. Фичи поверх ядра (v1)
+
+### 9.1. Зум-панели
+
+Временный фуллскрин одной панели поверх раскладки. Чисто **UI-состояние GUI** — дерево сплитов не трогается, демона не касается. Хоткей-тоггл, по выходу возврат к прежней раскладке.
+
+### 9.2. Внешние нотификации (Telegram, MAX)
+
+Когда окно свёрнуто или ты не за макбуком, событие агента должно догнать снаружи. Реализуется как **подписчик внутри `spaceshd`** на события шины — спине это ничего не двигает, чистое расширение.
+
+**Механика:**
+
+- Подписчик слушает события `state` (по умолчанию реагирует на `done`, `wait`, `error`; набор настраивается) и `exit`.
+- На совпадении формирует сообщение (`воркспейс · агент · состояние`, время, опционально хвост вывода) и диспетчит во включённые каналы.
+- Каждый канал — отдельный **адаптер** за общим трейтом `NotificationChannel { async fn send(&self, msg) }`. Добавить новый канал = новый адаптер, ядро не трогается.
+
+**Адаптеры v1:**
+
+| Канал | Транспорт | Конфиг | Заметки |
+|---|---|---|---|
+| **Telegram** | Bot API, HTTPS `sendMessage` | `bot_token`, `chat_id` | Бот создаётся через @BotFather. Только исходящие — webhook/long-poll не нужны |
+| **MAX** | MAX Bot API (`dev.max.ru`), HTTPS, JSON | `bot_token`, `chat_id` | Токен от Master Bot. Авторизация заголовком `Authorization: <token>` (query-параметр устарел). Только исходящие |
+
+> MAX Bot API построен по тем же принципам, что Telegram (токен → HTTPS-запросы → JSON), но детали отличаются: тип апдейтов в явном поле `update_type`, свой набор методов и формат сообщений. Для нотификаций нам нужен только метод отправки сообщения — приём апдейтов/webhook не требуется. Есть официальный TS-клиент `@maxhub/max-bot-api` и python-клиенты, если не захочется бить по HTTP напрямую.
+
+**Поведение:**
+
+- **Анти-спам / дедуп:** не слать повторное уведомление об одном и том же состоянии панели; коалесцировать всплески (несколько `done` подряд → одно сводное). Окно дедупа настраивается.
+- **Rate limits:** соблюдать лимиты каналов (у MAX базово ~30 msg/s на бота; Telegram ~30 msg/s глобально, ~1 msg/s на чат). Для персонального инструмента не критично, но очередь с троттлингом заложить.
+- **Фильтр по воркспейсу/группе:** опционально слать только по помеченным воркспейсам (увязывается с меткой «не забыть», §8.5).
+- **Доставка best-effort:** сбой канала логируется, ретраится ограниченно, не блокирует работу демона.
+
+**Конфиг (пример, `~/.spacesh/config.toml`):**
+
+```toml
+[notifications]
+on_states = ["done", "wait", "error"]
+dedup_window_secs = 30
+
+[notifications.telegram]
+enabled = true
+bot_token = "env:SPACESH_TG_TOKEN"
+chat_id = "123456789"
+
+[notifications.max]
+enabled = true
+bot_token = "env:SPACESH_MAX_TOKEN"
+chat_id = "..."
+```
+
+> Токены — через ссылку на env-переменную, не хранить в открытом виде в конфиге.
+
+---
+
+## 10. Структура кода
+
+### 10.1. Rust workspace (cargo)
+
+```
+spacesh/
+├── crates/
+│   ├── spacesh-proto/     # типы команд/событий, serde, кадрирование. Шарится всеми.
+│   ├── spacesh-core/      # модель воркспейсов/сплитов, грид (alacritty_terminal),
+│   │                      #   движок статусов. Без I/O — юнит-тестируемо.
+│   ├── spacesh-pty/       # спавн/io PTY (portable-pty), reader-loop, батчинг, resize.
+│   ├── spaceshd/          # демон: владеет сессиями, хостит socket, fan-out событий,
+│   │                      #   персист раскладки, launchd-обвязка, подписчики.
+│   └── spacesh-cli/       # тонкий бинарь-клиент к socket.
+└── app/                   # Tauri-приложение
+    ├── src-tauri/         # Rust-сторона: клиент к socket + мост в webview
+    └── src/               # React/TS фронт
+```
+
+| Крейт | Ответственность | Ключевые зависимости |
+|---|---|---|
+| `spacesh-proto` | Протокол: типы, serde, length-prefix framing | `serde`, `serde_json` |
+| `spacesh-core` | Доменная модель, грид, статусы | `alacritty_terminal` |
+| `spacesh-pty` | PTY io, батчинг, backpressure | `portable-pty`, `tokio` |
+| `spaceshd` | Демон, socket-сервер, fan-out, персист, подписчики-нотификации (Telegram/MAX) | `tokio`, `reqwest`, `spacesh-*` |
+| `spacesh-cli` | CLI-клиент | `clap`, `tokio` |
+| `app/src-tauri` | Мост socket ↔ webview | `tauri` 2, `tokio` |
+
+### 10.2. React/TS фронт
+
+| Компонент | Ответственность |
+|---|---|
+| `TerminalView` | xterm.js + аддоны (webgl/search/serialize/links) на панель; ввод → `input`, репейнт из снапшота |
+| `LayoutEngine` | рекурсивное дерево сплитов, ресайз мышью, **зум-панели** |
+| `Sidebar` | воркспейсы/группы, цвета, метка «не забыть», бейджи статуса |
+| `EventCenter` | лента уведомлений, «отметить прочитанным» |
+| `Wizard` | новый воркспейс (папка+раскладка→агент в панель), пресеты |
+| `Settings` | конфиг нотификаций (Telegram/MAX), хоткеи, правила; редактирование `config.toml` |
+| `socketBridge` | подписка на события демона через Tauri IPC, отправка команд |
+
+---
+
+## 11. Хоткеи (черновой набор)
+
+| Действие | Хоткей |
+|---|---|
+| Новый воркспейс | `Cmd + N` |
+| Переключить воркспейс | `Cmd + 1…9` |
+| Сплит панели | `Cmd + Shift + T` |
+| К свежему агенту | `Cmd + Shift + U` |
+| Соседняя панель | `Cmd + Opt + ← ↑ → ↓` |
+| Зум панели (тоггл) | `Cmd + Shift + Z` |
+| Поиск по скроллбэку | `Cmd + F` |
+| Настройки | `Cmd + ,` |
+
+> macOS-маппинг (Cmd вместо Ctrl). Сверить конфликты с системными/агентскими хоткеями; вынести в настраиваемую схему.
+
+---
+
+## 12. Порядок реализации (milestones)
+
+**M0 — живой терминал через socket (вертикальный срез).**
+`spacesh-proto` + `spaceshd` с командами `open` / `new_surface` / `input` / `output` + реальный PTY (`spacesh-pty`). Цель: байты летают GUI ↔ демон ↔ PTY. Минимальный фронт с одним `TerminalView`.
+
+**M1 — переживаемость и reattach.**
+Грид в демоне (`spacesh-core` + alacritty), `attach`/`detach` со снапшотом, репейнт xterm.js. launchd-обвязка. Цель: убил GUI — агент жив, открыл — экран восстановился.
+
+**M2 — раскладки и воркспейсы.**
+`LayoutEngine`, дерево сплитов, ресайз, персист (`state.json`), сайдбар с воркспейсами. Пресеты + `apply_preset`. Wizard.
+
+**M3 — статусы.**
+`set_state`, интеграция хуков Claude Code, OSC 133 для shell, fallback-паттерны. Кольца + бейджи + центр событий + нативные уведомления.
+
+**M4 — CLI.**
+`spacesh-cli` поверх готовой шины: `open`/`status`/`focus`/`close`/`new-surface`/`notify`, `--json`, shell-completions.
+
+**M5 — фичи поверх.**
+Зум-панели, внешние нотификации (Telegram + MAX, §9.2), поиск по скроллбэку, diff-просмотр изменений агента (CodeMirror 6).
+
+**M6 (post-v1) — remote.**
+Транспорт-трейт → проброс socket через SSH → демон на ноде, GUI на макбуке.
+
+---
+
+## 13. Открытые вопросы и риски
+
+| # | Вопрос/риск | Заметка |
+|---|---|---|
+| 1 | Имена/формат хуков Claude Code дрейфуют по версиям | Изолировать в версионируемый адаптер; не зашивать в ядро |
+| 2 | Нотификации: блокировка бота за массовые рассылки/спам (особенно MAX) | Только исходящие, низкий объём, дедуп + троттлинг; не использовать для рассылок |
+| 3 | WKWebView ≠ WebView2: IME (рус/англ), фокус, DnD, перехват клавиш | Отлаживать на macOS с нуля, не переносить допущения с Windows-аналогов |
+| 4 | Производительность xterm.js при шквальном выводе | webgl-аддон обязателен; батчинг §6.2; профилировать на реальных билд-логах |
+| 5 | Подпись/нотаризация для раздачи (Developer ID, stapling) | Заложить в CI заранее, иначе Gatekeeper ломает «скачал и запустил» |
+| 6 | Автообновление вне App Store | Tauri updater / Sparkle; решить на M1 |
+| 7 | Single-instance демона и гонки при старте | Лок-файл + проверка живости socket; обработать «socket есть, демон мёртв» |
+| 8 | Объём `output` по JSON-socket | Если упрёмся — MessagePack, изменение локализовано в `spacesh-proto` |
+
+---
+
+*Конец спецификации v0.1.*