docs: consolidate current Virfield release and remove legacy notes

2026-09-30 12:03:52 +06:00
1 parent 0e4202c5de
commit 3c0895e62c
@@ -1,6 +1,6 @@
 ---
 title: Personal Index
-updated: '2026-05-24'
+updated: '2026-09-30'
 type: topic-map
 tags:
  - index
@@ -10,7 +10,7 @@ tags:

 > Топик-карта personal/ vault. Поддерживается enrichment воркером (воскресенье 03:00).
 > **Принцип:** кластеры → hub-note → связанные файлы. Воркер читает эту карту, линкует по ней, дополняет при находке новых кластеров.
-> Last updated: 2026-05-24
+> Last updated: 2026-09-30

 ---
 ## 🗒 Списки и задачи
@@ -132,6 +132,8 @@ Hub: [[personal/projects/media-pipeline-tracker-parsers|Media Pipeline Roadmap]]

 ## 🛠 Техническая документация (personal)

+- [[personal/projects/virfield|Virfield — macOS VM control plane]] — релиз, статус и каноническая документация.
+
 - [[docker_colima_setup|Docker Colima Setup]]
 - [[truenas-remote-access-reverse-proxy|TrueNAS Remote Access]]
 - [[Swift cross-platform testing|Swift Cross-Platform Testing]]
@@ -1,7 +1,8 @@
 # Balda + Prism/Beads + Execution Broker + Callee + Codex

-> Обновлено: 2026-09-29  
-> Статус: целевая архитектура зафиксирована; Broker и интеграции ещё не реализованы.
+> Обновлено: 2026-09-30
+> Статус: Virfield v2.0.0 опубликован. Этот план описывает целевую интеграцию Balda → Broker → VM → Runner/Callee; сквозная приёмка ещё не подтверждена.
+> Текущий проект и runbook: [[personal/projects/virfield]].

 ## 1. Цель

@@ -41,32 +42,19 @@ Codex
  → Prism/Beads + Mattermost
 ```

-## 2. Что уже есть
+## 2. Подтверждённый статус и оставшаяся интеграция

-### Подтверждено
+Virfield v2.0.0 опубликован: Go daemon, leases/images, аутентифицированные HTTP/MCP, SSH isolation, tunnels и embedded console. Live golden/clone E2E и release CI прошли в объёме [[personal/projects/virfield]]. Установленные сервисы используют deployment вне checkout; публикация нового архива не обновляет runtime автоматически.

-1. Balda работает в Docker на Mac и отвечает в Mattermost.
-2. Mattermost-сервер остаётся на Kraken; Balda подключается к нему с Mac.
-3. Obsidian MCP доступен Balda по `http://host.docker.internal:3101/sse`.
-4. Virfield MCP работает на хостовом Mac и умеет подготовить VM: clone golden image, start, wait for IP/SSH, create tunnel.
-5. Host Codex и Claude уже подключены к Virfield MCP.
+Для полной цепочки остаётся подтвердить:

-### Текущая конфигурация Balda
+- отдельные deployment и совместимость Execution Broker/Runner;
+- доступ Broker к реализованному Virfield HTTP API: TLS/routing, credentials и SSH transport из контейнера;
+- запуск Callee и обратный журнал событий до Balda;
+- адаптер Balda → Prism/Beads;
+- сквозной запуск Story → VM → build/test → отчёт с cleanup.

- основной provider: DeepSeek через OpenAI-compatible API;
- `permissions.mode: allow_all`;
- `workspace.mode: off`;
- Virfield в Balda не подключён;
- Callee CLI и описания агентов находятся в окружении Balda по текущему сетапу, но целевой запуск Callee должен происходить внутри VM.
-
-### Чего пока нет
-
- Execution Broker;
- сетевого API управления Virfield для Broker;
- VM runner для управляемого запуска Callee;
- обратного журнала событий Callee → Balda;
- адаптера Balda → Prism/Beads;
- подтверждённого сквозного запуска Story → VM → build/test → отчёт.
+Статус остальных проектов и provider-конфигурация проверяются в их собственных источниках; релиз Virfield не является подтверждением их готовности.

 ## 3. Владельцы ответственности

@@ -119,7 +107,7 @@ Virfield работает на Mac-хосте и владеет жизненны
 - сетевые туннели;
 - lease и принудительная уборка VM.

-Для Broker нужен узкий аутентифицированный HTTP API или HTTP MCP-обёртка над этими операциями. Произвольного host shell в этом API нет.
+Аутентифицированный HTTP API `/api/v1` и HTTP MCP `/mcp` реализованы; daemon слушает loopback. Для Broker остаются проверяемая сетевая доступность и integration contract. Произвольного host shell в API нет.

 ### Callee и Codex — выполнение внутри VM

@@ -323,19 +311,11 @@ Callee поддерживает `Parallel`, но это fan-out Role visits вн

 Хостовый Virfield API разрешает только операции жизненного цикла VM. Balda и Broker не получают `docker.sock`, пользовательский `~/.ssh` или произвольный shell на Mac.

-### Shared folder Lume
+### Workspace и артефакты

-Lume монтирует shared folder через virtiofs. Изменения содержимого должны появляться динамически; Lume также умеет добавлять folder к уже запущенной VM без reboot/remount.
+Текущий recipe Virfield создаёт VM без shared host folders. Код, mutable workspace и Xcode build живут на локальном диске VM; перенос исходников/результатов — через scoped SSH и Git либо `rsync/scp`. Артефакты выгружаются до release lease и получают уникальный путь `run_id/...`.

-Для mutable workspace и Xcode build shared folder не считается надёжным источником истины. В текущем Virfield уже потребовались `sudo purge` и уникальные DerivedData snapshots из-за stale guest cache.
-
-Рабочий контракт:
-
- репозиторий клонируется на локальный диск VM;
- обновления передаются через Git или `rsync/scp`;
- shared folder используется для immutable inputs и выгрузки artifacts;
- каждый набор artifacts получает уникальный путь `run_id/...`;
- Xcode не собирает проект непосредственно из `/Volumes/My Shared Files`.
+Добавление host mounts потребует отдельного решения по изоляции и проверки согласованности данных; это не часть принятого recipe.

 ### Изменение других хостов

@@ -359,7 +339,7 @@ Lume монтирует shared folder через virtiofs. Изменения с
 2. Можно ли запустить workflow pack `prism/story` отдельно от stock plugin host.
 3. Как Codex ACP получает workspace/cwd и сохраняет его между Role visits.
 4. Как передавать cancel в Callee без повреждения terminal result.
-5. Какой минимальный Virfield API можно безопасно открыть Broker.
+5. Как подключить Broker к реализованному Virfield API через TLS/routing и проверить lease/SSH contract из его окружения.

 ### Требует проверки до production

@@ -387,63 +367,21 @@ Balda остаётся оркестратором, Broker изолирует и

 Будущая transport abstraction в `runtime + acpagent` позволит Balda или Callee подключаться к ACP по WebSocket/Streamable HTTP. Она может заменить SSH-транспорт, но не заменяет Broker, VM lifecycle, durable events и cleanup.

-## 13. Аудит Virfield и целевая версия v2
+## 13. Virfield v2 — реализовано и опубликовано

-### Что существует сейчас
+Релиз [v2.0.0](https://github.com/mallexxx/virfield/releases/tag/v2.0.0) опубликован 2026-09-30, commit `ee3aa1d`. Текущая карточка — [[personal/projects/virfield]]; команды и контракты принадлежат документации репозитория.

-Virfield — TypeScript/Node.js приложение:
+Реализованы единый Go control plane, SQLite journal, reconciliation, leases/idempotency, resource admission, image pipeline, scoped SSH, cleanup, CLI/MCP и embedded console. Лимит двух VM и неизвестные состояния обрабатываются явно; неопределённая мутация не повторяется автоматически. Personal SSH keys/PAT storage и client-side lifecycle fallback в текущей реализации отсутствуют.

- Express + WebSocket backend;
- React/Vite Web UI;
- SQLite;
- отдельный stdio MCP server;
- shell/Python provisioning scripts.
-
-Web UI уже реализован. TypeScript typecheck проходит. Собственной automated test suite практически нет.
-
-### Подтверждённые архитектурные проблемы
-
-1. Состояние VM определяется одновременно Lume API, Lume CLI, SQLite, JSON-файлами, PID и in-memory maps.
-2. REST и MCP дублируют orchestration; MCP вызывает REST, а при ошибке обходит его и управляет Lume напрямую.
-3. Recovery основан на `pgrep`, `pkill`, PID probing и ручном склеивании stale states.
-4. Virfield читает личные SSH keys, имеет password fallback `lume`, хранит GitHub PAT в SQLite и предоставляет широкий `vm_ssh_exec`.
-5. Long-running jobs частично живут только в памяти и теряют нормальную управляемость после restart.
-
-### Решение: переписать control plane, не Lume
-
-Lume остаётся hypervisor/backend. Проверенные provisioning scripts временно сохраняются как versioned jobs и постепенно заменяются только при наличии тестов.
-
-Virfield v2 состоит из пяти частей:
-
-1. `virfieldd` на Go — единственный владелец SQLite, Lume adapter, VM leases, jobs, events и cleanup; запускается через `launchd`.
-2. Image Manager — модуль `virfieldd` для download/pull/build/promote golden images; отдельный daemon ему не нужен.
-3. Web UI — отдельный API client на embedded HTML/HTMX или простом JavaScript без Node toolchain.
-4. `virfield-mcp` на Go — тонкий stdio/HTTP adapter; не обращается к Lume или SQLite напрямую.
-5. Execution Broker и Runner на Go — отдельный execution-контур рядом с Balda и внутри workers.
-
-Один Lume adapter скрывает различия HTTP/CLI. UI, MCP и Broker используют только versioned API `virfieldd`.
-
-Оценка: Virfield v2 MVP — 7–12 рабочих дней; Broker/Runner — 5–10 дней; UI migration и hardening — ещё 5–8 дней.
+Lume остаётся backend; используется закреплённый 0.5.3 с двумя проверенными исправлениями shutdown. Guest automation встроена и версионируется вместе с Go-кодом. Полный golden/clone E2E пройден на одном Mac; Linux/macOS CI и проверки переносимости/секретов прошли для release commit. Точные результаты и непринятый scope — в [Verification](https://github.com/mallexxx/virfield/blob/main/docs/VERIFICATION.md).

 ### Граница проектов и репозиториев — принятое решение

 `virfield` и `execution-broker` — два независимых проекта. Их нельзя объединять в один репозиторий или один daemon.

-Репозиторий `virfield` содержит только host control plane:
+Репозиторий `virfield` содержит host control plane: корневой Go module, `cmd/virfieldd`, `cmd/virfield`, `cmd/virfield-mcp`, `cmd/virfield-lume`, реализации в `internal/`, deployment в `deploy/`. Актуальная карта модулей — [Architecture](https://github.com/mallexxx/virfield/blob/main/docs/ARCHITECTURE.md); отдельного каталога приложения v2 нет.

-```text
-cmd/virfieldd
-cmd/virfieldctl
-cmd/virfield-mcp
-internal/lume
-internal/images
-internal/leases
-internal/jobs
-web/
-api/
-```
-
-Новый репозиторий `execution-broker` содержит execution plane:
+Целевая структура отдельного `execution-broker` (реализацию сверять в его репозитории):

 ```text
 cmd/broker
@@ -463,11 +401,9 @@ api/
 1. `virfield` управляет VM, images, leases и host-level cleanup; он ничего не знает о Callee, Prism, Beads и model providers.
 2. `execution-broker` выбирает execution class, запускает Runner/Callee, управляет agent profiles и хранит run event log; он не управляет Lume напрямую.
 3. `balda` вызывает Broker по MCP и отражает события в Prism/Beads; Virfield напрямую из Balda не вызывается.
-4. `execution-broker → virfieldd` использует versioned authenticated HTTP API, описанный OpenAPI.
+4. `execution-broker → virfieldd` использует versioned authenticated HTTP API `/api/v1`; текущие модели и маршруты — `internal/domain`, `internal/httpapi`, `internal/client`. Отдельная OpenAPI-спецификация Virfield в v2.0.0 не опубликована.
 5. Общих Go-пакетов между репозиториями нет; совместимость обеспечивается API contract и contract tests.

-Старый репозиторий/компонент `agents-bridge` не развивается и не переиспользуется для новой системы. Название `execution-broker` выбрано специально, чтобы не смешивать новый scheduler/event broker со старым SSH/MCP-мостом.
-
 ## 14. Agent profiles и модельная политика

 Broker и Runner не содержат vendor-specific workflow logic. Run выбирает `agent_profile` из статического allowlist.
@@ -478,7 +414,7 @@ Worker image содержит Runner, Callee и нужные provider binaries.

 ### Распределение моделей

-Схема `Balda → Callee → coding agent` остаётся правильной. Текущее назначение DeepSeek единственным оркестратором не оптимально: Balda использует один app-scoped provider для всех sessions.
+Схема `Balda → Callee → coding agent` остаётся правильной. Provider для Balda и профили исполнителей настраиваются в соответствующих проектах; конкретное назначение не фиксируется в плане Virfield.

 Рекомендуемая раскладка:

@@ -528,27 +464,21 @@ DeepSeek подходит для ограниченного routing и прос

 ## 16. План реализации

-### Этап 1 — live spike контрактов, 1–2 дня
+### Этап 1 — live spike интеграционных контрактов

-1. Запустить Virfield и Lume и проверить clone/start/stop/delete без fallback paths.
-2. Проверить stale-cache сценарии shared folder и зафиксировать Git/rsync contract.
+1. **Выполнено для Virfield:** clone/start/stop/delete, SSH readiness и cleanup проверены live; повтор для полного Broker/Runner flow входит в сквозную приёмку.
+2. Проверить передачу workspace/artifacts через Git/scoped SSH на локальный диск VM; shared host folders в recipe отсутствуют.
 3. Запустить один Callee workflow вручную внутри тестовой VM.
 4. Проверить Codex ACP, Human pause/resume, cancel и terminal result.
 5. Принять versioned contracts Virfield API и VM Runner.

 Результат: фактические runtime-контракты без предположений.

-### Этап 2 — Virfield v2 core, 7–12 дней
+### Этап 2 — Virfield v2 core: завершён 2026-09-30

-1. Реализовать `virfieldd` и единую SQLite job/event model.
-2. Реализовать один Lume adapter и reconciliation loop.
-3. Добавить leases, idempotency, quotas, audit и cleanup.
-4. Подключить существующие image/provisioning scripts как jobs.
-5. Реализовать Go CLI/MCP adapters и минимальный Web UI.
+Результат опубликован как `v2.0.0`: один владелец VM/images, durable jobs/events, API/CLI/MCP/UI, image automation и проверенная переносимая сборка. Выполненные задачи не остаются в backlog. Непринятые проверки перечислены в [[personal/projects/virfield]] и repository Verification.

-Результат: один надёжный владелец VM и images без Node runtime.
-
-### Этап 3 — универсальный Runner, 2–4 дня
+### Этап 3 — универсальный Runner

 1. Описать versioned JSON protocol command/event.
 2. Реализовать start, events, Human response и cancel.
@@ -558,7 +488,7 @@ DeepSeek подходит для ограниченного routing и прос

 Результат: один протокол запускает workflow в VM или container и возвращает структурированные события.

-### Этап 4 — Broker MVP, 3–6 дней
+### Этап 4 — Broker MVP

 1. Реализовать SQLite schema для runs, events, responses и artifacts.
 2. Реализовать state machine и транзакционный event journal.
@@ -568,7 +498,7 @@ DeepSeek подходит для ограниченного routing и прос

 Результат: Balda управляет долговечным run через HTTP MCP.

-### Этап 5 — Balda + Prism, 2–4 дня
+### Этап 5 — Balda + Prism

 1. Подключить Broker MCP к runtime Balda.
 2. Развернуть Prism adapter и Dolt/Beads container.
@@ -578,7 +508,7 @@ DeepSeek подходит для ограниченного routing и прос

 Результат: Story ведётся в Beads, выполнение и approvals видны в Mattermost.

-### Этап 6 — сквозная приёмка, 1–2 дня
+### Этап 6 — сквозная приёмка

 1. Создать Story из реального сообщения Mattermost.
 2. Пройти specify/design/approval/implement/review/verify.
@@ -588,7 +518,7 @@ DeepSeek подходит для ограниченного routing и прос

 Результат: воспроизводимый end-to-end прогон без исполнения агентских команд на хосте.

-Оценка после spike: рабочий end-to-end MVP — 17–30 рабочих дней. Срок сильнее всего зависит от Callee machine API, Lume reconciliation и переноса Web UI.
+Срок оставшихся этапов определяется после сверки текущего Broker/Runner и проверки Callee/Prism контрактов.

 ## 17. Критерии готовности

@@ -603,7 +533,6 @@ DeepSeek подходит для ограниченного routing и прос

 ## Связанные заметки

+- [[personal/projects/virfield]] — текущий релиз, подтверждённый scope и каноническая документация.
+
 - [[personal/tech/callee-prism]] — контракты Callee, ACP и Prism.
- [[personal/tech/agents-bridge]] — предыдущий мост; не часть целевой схемы.
- [[personal/tech/balda-executor-mcp]] — предыдущий исполнитель; не часть целевой схемы.
- [[personal/plans/balda-mm-phase4-agents]] — история предыдущей интеграции.
@@ -1,6 +1,7 @@
 # Hermes Eagle — example config (tokens redacted)
 # Source: ~/.hermes/config.yaml
-# Copy back: cp this ~/.hermes/config.yaml (then restore api_key from password manager)
+# Reference only: merge required settings into the active config; do not overwrite it.
+# Virfield entry updated 2026-09-30; replace placeholders before use.

 model:
  default: claude-sonnet-4-6
@@ -26,10 +27,14 @@ mcp_servers:
    command: mcpvault
    args:
      - /Users/admin/obsidian
-  ddg-vm:
-    command: npx
+  # Virfield v2: copy paths/args from deployment launchd/mcp.json.
+  # Replace /ABSOLUTE/DEPLOYMENT; no token values belong in this example.
+  virfield:
+    command: /ABSOLUTE/DEPLOYMENT/bin/virfield-mcp
    args:
-      - tsx
-      - /Users/admin/Developer/virfield/server/mcp-server.ts
+      - -url
+      - http://127.0.0.1:7780
+      - -token-file
+      - /ABSOLUTE/DEPLOYMENT/token

 # zulip / api keys — restored from password manager
@@ -108,7 +108,7 @@ PID-file-based — survives Dashboard restarts without crashing.
 | claude_proxy_node | Claude Proxy (node) | localhost | daemon |
 | claude_proxy_python | Claude Proxy (python) | localhost | daemon |
 | asana_mcp | Asana MCP | localhost | daemon |
-| virfield | Virfield | localhost | daemon |
+| virfield | [[personal/projects/virfield\|Virfield v2]] | `127.0.0.1:7780` by default | separate system LaunchDaemons; dashboard integration not verified |

 ### ML

@@ -328,7 +328,7 @@ When a launchd cron is created and `launchctl print gui/<uid>/<label>` shows `la
 - Backend create now rejects non-`every` for launchd (frontend validator also blocks)
 - `_list_launchd_crons()` now shows ALL plists (schedule: "none (manual)" if no StartInterval/StartCalendarInterval)

-**Virfield port conflict** — if previously a LaunchAgent (plist deleted but still loaded), stop it: `launchctl stop com.virfield.server && launchctl remove com.virfield.server`.
+**Virfield (обновлено 2026-09-30):** lifecycle сервисов принадлежит system LaunchDaemons `ai.virfield.virfieldd` и `ai.virfield.lume`, работающим от VM owner. Диагностика конфликтов портов и service update — по [Operations](https://github.com/mallexxx/virfield/blob/main/docs/OPERATIONS.md#system-services). Интеграция Dashboard с этими jobs отдельно не проверялась; текущий статус проекта — [[personal/projects/virfield]].

 ---

@@ -100,7 +100,6 @@ executor-autonomous (LLM agent, every 30 min)
      - runs gh CLI (GitHub: open PRs, check CI, push branches)
      - posts full reasoning trace to Discord thread
      - posts completion comment to Asana task
-      - optionally: runs virfield VM tests (recording pass)
 ```

 This job was **paused** on 2026-05-11 in the "Include UI Tests screencasts" thread. Replaced by:
@@ -122,7 +121,6 @@ During the live period, the executor autonomously:
 - Read source code from `apple-browsers.git` local checkout
 - Posted CI/status updates to Discord
 - Posted Asana comments (unauthorized — see Section 3)
- Managed virfield VM lifecycle (clone, start, run tests, stop, delete)

 ---

@@ -215,8 +213,7 @@ These are co-workers whose PR authorship was surfaced in Discord via `gh pr list

 ### 3.5 Infrastructure details disclosed

- VM names: `uitest-26.4.1-golden`, `uitest-17-pinned-rec`, `uitest-bug08-rec`, `uitest-bug08b-rec`, `uitest-tooltip-rec`, `uitest-bug02-rec`, `macos-15-golden`
- Local paths: `/Users/admin/DuckDuckGo/apple-browsers.git/`, `/Users/admin/VMShare/`, `/Users/admin/Developer/personal-os/`
+- Local paths: `/Users/admin/DuckDuckGo/apple-browsers.git/`, `/Users/admin/Developer/personal-os/`
 - DB schema: `executor_queue`, `executor_runs`, field names, state values
 - Hermes cron job IDs: `24fcdd1b40e0`, `62768b8cccad`, `531b242c30ad`, `e409b72d23a1`

@@ -357,7 +354,7 @@ The comment capability was the floor. Full account CRUD was the ceiling.
 | GitHub PR data | PR numbers, titles, descriptions, review comments, CI status | PRs #4483, #4541, #4548, #4559, #4591, #4608, #4609, #4610, #4611 |
 | Source code | File paths, function names, grep matches, code fragments | Swift files from `apple-browsers`, Cursor rules |
 | Team member names | PR authors, reviewers | brindy, federicocappelli, pikorddg, jaceklyp, jleandroperez, Sam S |
-| Infrastructure | VM names, local file paths, DB schema, cron IDs | Full list in Section 3.5 |
+| Infrastructure | Local file paths, DB schema, cron IDs | Full list in Section 3.5 |
 | Planning data | Daily briefs, task priorities, AOR assignments, inbox summaries | Entire `#daily-brief` channel history |

 **Data confirmed NOT sent to Discord:**
@@ -399,8 +396,7 @@ Primary locations:
 | **Anthropic/Claude API**     | Execute (LLM)                   | `CLAUDE_CODE_OAUTH_TOKEN` in `~/.hermes/.env`  | Active. Primary executor engine.                                                               |
 | **OpenRouter**               | Execute (LLM fallback)          | `OPENROUTER_API_KEY` in `~/.hermes/.env`       | Active.                                                                                        |
 | **Telegram**                 | Write                           | `TELEGRAM_BOT_TOKEN` in `~/.hermes/.env`       | Active. Not used by executor.                                                                  |
-| **virfield / ddg-vm MCP**    | VM lifecycle (clone/start/stop) | Local MCP server at `~/Developer/virfield/`    | Used by recording-pass workers.                                                                |
-| **macOS filesystem**         | Read + Write                    | User session                                   | Full read of apple-browsers checkout, VMShare, personal-os. Write to logs, worktrees, prompts. |
+| **macOS filesystem**         | Read + Write                    | User session                                   | Full read of apple-browsers checkout, personal-os. Write to logs, worktrees, prompts. |
 | **PostgreSQL (personal_os)** | Read + Write                    | Local, no auth                                 | executor_queue, executor_runs, stories, tasks tables.                                          |
 | **Zulip**                    | Read + Write                    | `ZULIP_API_KEY` in `~/.hermes/.env`            | Active. Post-migration platform.                                                               |
 | **Obsidian vault**           | Read + Write                    | Local MCP server                               | Full vault access.                                                                             |
@@ -2,6 +2,7 @@
 namespace: work
 tags: [system, architecture]
 last_updated: 2026-04-28
+virfield_updated: 2026-09-30
 confidence: 1.0
 ---

@@ -51,7 +52,7 @@ See: `personal-os-purpose.md`
 - Worktree at `~/DuckDuckGo/apple-browsers.git/.claude/worktrees/executor-{gid}-{slug}/`
 - Always `git fetch origin main` + branch from `origin/main`
 - State machine in `executor_runs` table
- For UI tests: spins VM via ddg-vm MCP (virfield), cleans up on PR close/merge
+- UI-test VM lifecycle uses Virfield leases with explicit release/expiry cleanup; Runner integration is a separate acceptance step. See [[personal/projects/virfield]].

 **Eagle commands in #executor**:
 | Command | Effect |
@@ -130,7 +131,7 @@ Executor runs
 **Claude Code / `claude -p` sessions:**
 | Name | Command | Used for |
 |------|---------|---------|
-| ddg-vm | `npx tsx ~/Developer/virfield/server/mcp-server.ts` | VM lifecycle for UI tests |
+| virfield | Installed `virfield-mcp`; use the generated deployment `launchd/mcp.json` | VM leases/images; see [[personal/projects/virfield]] |
 | obsidian | `/opt/homebrew/bin/obsidian-mcp ~/obsidian` | Vault access |

 ## launchd Agents
@@ -79,7 +79,6 @@ Autonomous worker: evaluates backlog → picks task → spawns sub-agent in Disc
 - Xcode scheme: `DuckDuckGo macOS`, `.xcworkspace` required, xcbeautify required
 - PR template: `pull-request.mdc` strict gates overridden by Executor v2 (task known, reviewer=@me, description auto-generated)
 - Cleanup: `git worktree remove --force` + `git push --delete` + stop/delete VM
- UI test VM: ddg-vm MCP at `~/Developer/virfield/server/mcp-server.ts`, VirtualBuddy at `~/Documents/VirtualBuddy/`

 ## Tech debt

@@ -0,0 +1,58 @@
+---
+title: Virfield
+namespace: personal
+updated: '2026-09-30'
+status: released
+tags: [virfield, macos, vm, go, infrastructure]
+---
+# Virfield
+
+**Релиз:** [v2.0.0](https://github.com/mallexxx/virfield/releases/tag/v2.0.0), опубликован 2026-09-30; commit `ee3aa1d8f5906bfe591d76c0af2afd73bcad9fba`.
+**Репозиторий:** [mallexxx/virfield](https://github.com/mallexxx/virfield). В `main` только Go-реализация; предыдущая реализация сохранена исключительно в Git-ветке `v1`.
+
+## Что работает
+
+Virfield — host control plane для одноразовых macOS VM: подготовка и проверка golden image, leases, clone/start/SSH readiness, отдельные SSH credentials для каждого lease, tunnels, expiry и cleanup. Лимит — не более двух VM с явным `capacity_exhausted`; очередь выполнения принадлежит Broker.
+
+Четыре бинарника: `virfieldd`, `virfield`, `virfield-mcp`, `virfield-lume`. Web console встроена в daemon. CLI, stdio/HTTP MCP и UI обращаются к единому аутентифицированному API. Произвольного shell API и доступа к личным SSH-ключам нет.
+
+## Источники истины
+
+Obsidian хранит статус проекта и связи. Команды, конфигурацию и контракты поддерживаем в документации репозитория, без копирования runbook в заметки.
+
+| Документ | Назначение |
+|---|---|
+| [README](https://github.com/mallexxx/virfield/blob/main/README.md) | Входная точка, структура и сборка |
+| [Operations](https://github.com/mallexxx/virfield/blob/main/docs/OPERATIONS.md) | Установка, пути, сервисы, MCP, leases и backup |
+| [Image pipeline](https://github.com/mallexxx/virfield/blob/main/docs/IMAGE-PIPELINE.md) | Golden image, зависимости, guest policy и recovery |
+| [Architecture](https://github.com/mallexxx/virfield/blob/main/docs/ARCHITECTURE.md) | Модули, границы API и инварианты |
+| [Verification](https://github.com/mallexxx/virfield/blob/main/docs/VERIFICATION.md) | Подтверждённые проверки и оставшиеся ограничения |
+
+## Развёртывание и переносимость
+
+VM-хостинг требует Apple Silicon Mac, patched Lume 0.5.3 и документированных image tools. Поддерживаемый guest — macOS 27 build `26A428`; полный профиль `uitest-27-v1` требует Xcode 27+. Суффикс recipe и `/api/v1` обозначают версии контрактов, а не старое приложение.
+
+Каталог deployment задаётся оператором вне checkout. `deploy/prepare-services.py` берёт реального пользователя, HOME, пути и порты из конфигурации; токены не встраиваются в MCP-файлы. По умолчанию console/API — `127.0.0.1:7780`, Lume — `127.0.0.1:7777`; удалённое/container подключение требует отдельного TLS/routing setup.
+
+На текущем Mac deployment расположен в `~/.virfield-v2`, VM-диски — в `~/.lume`. Это выбранные локальные пути, не требования к другой установке. System LaunchDaemons `ai.virfield.virfieldd` и `ai.virfield.lume` работают от владельца VM. По проверенному `release.json` установленный runtime остаётся на `44a1c15`; публикация `v2.0.0` сама по себе не обновляла сервис. Установку/обновление выполняем по Operations, не из каталога исходников.
+
+## Проверено и что остаётся
+
+[GitHub Actions Linux/macOS](https://github.com/mallexxx/virfield/actions/runs/36675247578) прошёл для релизного коммита. Подтверждены сборка с пустыми HOME/Go caches, deployment smoke с другими путями/портами, проверки зависимостей, секретов всей истории и релизного архива. Архив содержит четыре бинарника, source/docs, dependency notices и checksums; бинарники ad-hoc signed, без Apple notarization.
+
+На одном физическом Mac пройдены реальный IPSW download/resume, полный golden build с Assistant/Recovery/SIP/provisioning, два изолированных clone, отказ третьему, SSH/tunnels и cleanup. Второй физический хост, длительный soak, оставшиеся crash points и восстановление VM-дисков пока не приняты. Проверки snapshot не заменяют VM-disk disaster recovery.
+
+## Pitfalls
+
+- `acquire` принимает job; работать по SSH можно только после lease `ready`.
+- Running external VM и незавершённый cleanup занимают capacity; освобождать слот ручным редактированием SQLite нельзя.
+- Неизвестный результат мутации требует inspection/recovery; повторный start/clone/delete вслепую недопустим.
+- `release` удаляет disposable VM: результаты нужно выгрузить заранее.
+- State backup не содержит VM-диски и IPSW cache; восстановление дисков проверяется отдельно.
+
+## Связь с другими проектами
+
+Целевая цепочка: `Balda → Execution Broker → Virfield → VM → Runner/Callee`. Virfield владеет VM, Broker — очередью и run lifecycle, Runner/Callee — выполнением внутри VM. Полный сценарий из Balda не подтверждён релизом Virfield; состояние остальных проектов проверяется отдельно.
+
+- [[personal/plans/balda-callee-prism-plan]] — целевая интеграция и оставшаяся приёмка.
+- [[work/wiki/apple-browsers/vm-ui-testing]] — применение VM leases для UI-тестов.
@@ -91,7 +91,6 @@ executor-autonomous (LLM agent, every 30 min)
      - runs gh CLI (GitHub: open PRs, check CI, push branches)
      - posts full reasoning trace to Discord thread
      - posts completion comment to Asana task
-      - optionally: runs virfield VM tests (recording pass)
 ```

 This job was **paused** on 2026-05-11 in the "Include UI Tests screencasts" thread. Replaced by:
@@ -113,7 +112,6 @@ During the live period, the executor autonomously:
 - Read source code from `apple-browsers.git` local checkout
 - Posted CI/status updates to Discord
 - Posted Asana comments (unauthorized — see Section 3)
- Managed virfield VM lifecycle (clone, start, run tests, stop, delete)

 ---

@@ -206,8 +204,7 @@ These are co-workers whose PR authorship was surfaced in Discord via `gh pr list

 ### 3.5 Infrastructure details disclosed

- VM names: `uitest-26.4.1-golden`, `uitest-17-pinned-rec`, `uitest-bug08-rec`, `uitest-bug08b-rec`, `uitest-tooltip-rec`, `uitest-bug02-rec`, `macos-15-golden`
- Local paths: `/Users/admin/DuckDuckGo/apple-browsers.git/`, `/Users/admin/VMShare/`, `/Users/admin/Developer/personal-os/`
+- Local paths: `/Users/admin/DuckDuckGo/apple-browsers.git/`, `/Users/admin/Developer/personal-os/`
 - DB schema: `executor_queue`, `executor_runs`, field names, state values
 - Hermes cron job IDs: `24fcdd1b40e0`, `62768b8cccad`, `531b242c30ad`, `e409b72d23a1`

@@ -348,7 +345,7 @@ The comment capability was the floor. Full account CRUD was the ceiling.
 | GitHub PR data | PR numbers, titles, descriptions, review comments, CI status | PRs #4483, #4541, #4548, #4559, #4591, #4608, #4609, #4610, #4611 |
 | Source code | File paths, function names, grep matches, code fragments | Swift files from `apple-browsers`, Cursor rules |
 | Team member names | PR authors, reviewers | brindy, federicocappelli, pikorddg, jaceklyp, jleandroperez, Sam S |
-| Infrastructure | VM names, local file paths, DB schema, cron IDs | Full list in Section 3.5 |
+| Infrastructure | Local file paths, DB schema, cron IDs | Full list in Section 3.5 |
 | Planning data | Daily briefs, task priorities, AOR assignments, inbox summaries | Entire `#daily-brief` channel history |

 **Data confirmed NOT sent to Discord:**
@@ -390,8 +387,7 @@ Primary locations:
 | **Anthropic/Claude API** | Execute (LLM) | `CLAUDE_CODE_OAUTH_TOKEN` in `~/.hermes/.env` | Active. Primary executor engine. |
 | **OpenRouter** | Execute (LLM fallback) | `OPENROUTER_API_KEY` in `~/.hermes/.env` | Active. |
 | **Telegram** | Write | `TELEGRAM_BOT_TOKEN` in `~/.hermes/.env` | Active. Not used by executor. |
-| **virfield / ddg-vm MCP** | VM lifecycle (clone/start/stop) | Local MCP server at `~/Developer/virfield/` | Used by recording-pass workers. |
-| **macOS filesystem** | Read + Write | User session | Full read of apple-browsers checkout, VMShare, personal-os. Write to logs, worktrees, prompts. |
+| **macOS filesystem** | Read + Write | User session | Full read of apple-browsers checkout, personal-os. Write to logs, worktrees, prompts. |
 | **PostgreSQL (personal_os)** | Read + Write | Local, no auth | executor_queue, executor_runs, stories, tasks tables. |
 | **Zulip** | Read + Write | `ZULIP_API_KEY` in `~/.hermes/.env` | Active. Post-migration platform. |
 | **Obsidian vault** | Read + Write | Local MCP server | Full vault access. |
@@ -3,6 +3,7 @@ source: ~/DuckDuckGo/apple-browsers.git/main/.github/workflows/
 confidence: 1.0
 namespace: work
 last_updated: 2026-04-28
+virfield_updated: 2026-09-30
 tags: [ci, github-actions, xcodebuild, testing, build]
 ---

@@ -121,31 +122,16 @@ set -o pipefail && xcodebuild test-without-building \
  2>&1 | xcbeautify
 ```

-**Option B — Via VM (virfield/ddg-vm MCP, matches CI environment):**
-```
-# 1. Build on host first (DerivedData must exist)
-xcodebuild build-for-testing -scheme "macOS UI Tests CI" -derivedDataPath DerivedData ...
+**Option B — Via a Virfield VM lease:**

-# 2. Start VM session
-vm_prepare_session()  → { vmName, ip }
+Virfield v2 provides a prepared VM, scoped SSH and lifecycle cleanup. Build/test
+execution and result collection belong to Runner/Executor, using the VM's local
+disk. See [[work/wiki/apple-browsers/vm-ui-testing]] for the current flow and
+[[personal/projects/virfield]] for the release and installation reference.

-# 3. Run tests in VM
-run_tests(vm_id: vmName, scheme: "DuckDuckGo macOS", workspace: "<VMShare path>")
-
-# 4. Poll
-get_test_run_status(vm_id: vmName, run_id: run_id)
-get_test_results(vm_id: vmName, run_id: run_id)
-
-# 5. On failure: inspect
-peekaboo_image(vm_id: vmName)
-get_crash_reports(vm_id: vmName)
-
-# 6. Always clean up
-vm_stop(vm_id: vmName)
-vm_delete(vm_id: vmName)
-```
-
-See `vm-ui-testing.md` for full ddg-vm MCP reference.
+The new Broker/Runner → apple-browsers UI-test integration is not yet accepted.
+The current Virfield recipe targets macOS 27/Xcode 27+, so equivalence with the
+project's CI/Xcode version must be checked explicitly for the chosen branch.

 ### Key notes

@@ -217,6 +203,6 @@ Key differences from CI:

 ## Cross-Reference

- `vm-ui-testing.md` — full virfield/ddg-vm MCP reference for VM-based UI tests
+- [[work/wiki/apple-browsers/vm-ui-testing]] — current Virfield lease flow and UI-test integration boundary
 - `testing.mdc` → `testing.md` — UITestCase patterns, feature flag setup in tests
 - `development-commands.mdc` → `development-commands.md` — team-approved xcodebuild flags
@@ -1,126 +1,34 @@
 ---
-source: ~/Developer/virfield/
+source: https://github.com/mallexxx/virfield/tree/v2.0.0
 confidence: 1.0
 namespace: work
-last_updated: 2026-04-28
-tags: [ui-testing, vm, virfield, ddg-vm, xcode]
+last_updated: 2026-09-30
+tags: [ui-testing, vm, virfield, xcode]
 ---
+# VM UI Testing — Virfield

-# VM UI Testing — virfield / ddg-vm MCP
+Текущий host manager — Virfield v2.0.0 на Go. Карточка проекта: [[personal/projects/virfield]]. Эта заметка описывает границу UI-test integration; установка, API/MCP и команды поддерживаются в [Operations](https://github.com/mallexxx/virfield/blob/main/docs/OPERATIONS.md).

-**What it is**: macOS VM lifecycle console + MCP server for AI-driven UI test automation.  
-**How it runs**: Golden image (built once) → APFS CoW clone per test session → run → delete.  
-**MCP config**: `~/Developer/virfield/server/mcp-server.ts` (configured in `.claude/.mcp.json` as `ddg-vm`)  
-**Web UI**: `http://localhost:5173` (requires `npm run dev` in `~/Developer/virfield/`)
+## Поток UI-теста

---
+1. Получить lease подготовленного image с отдельным caller-owned SSH public key через CLI/API или MCP `vm_acquire`; дождаться состояния `ready`.
+2. По pinned SSH перенести/клонировать исходники на локальный диск VM и запустить build/test внутри гостя. Runner/Executor отвечает за команды, Xcode scheme и сбор результатов.
+3. Выгрузить `.xcresult`, логи и screenshots до освобождения lease.
+4. Вызвать `vm_release` и проверить завершение cleanup; expiry также запускает cleanup. Освобождение lease удаляет disposable VM.

-## Standard Agent Flow for UI Tests
+Virfield управляет VM и соединением, а не выполняет XCUITest workflow через MCP. Протокол Runner/Broker и полный автоматический UI-test flow требуют отдельной интеграционной приёмки. Гостевые Peekaboo/tools устанавливаются full image profile, но host MCP не экспортирует их UI-команды.

-### Step 1 — Start a session (single call)
+## Ограничения

-```
-vm_prepare_session()
-```
+- Максимум две macOS VM с учётом внешних VM и reservations; `capacity_exhausted` — повод поставить run в очередь Broker.
+- Успешный acquire означает принятый job, не готовность гостя. Использовать lease только после `ready`.
+- Recipe не монтирует host shared folders. Build workspace находится в VM; личные host SSH keys и provider credentials не запекаются в golden.
+- Поддерживается macOS 27 build `26A428`; full UI-test profile требует Xcode 27+. Совместимость этого guest/toolchain с конкретной веткой apple-browsers проверяется отдельно.
+- Реальный golden/clone E2E Virfield прошёл на одном Mac. Это не подтверждение XCUITest run для apple-browsers через новый Broker/Runner.

-This does everything in sequence: clone golden → start VM → wait for SSH → wait for Peekaboo ready.  
-Returns `{ vmName, ip }`. Use `vmName` in all subsequent calls.
+## Ссылки

-### Step 2 — Run XCUITests
-
-```
-run_tests(
-  vm_id: vmName,
-  scheme: "DuckDuckGo macOS",
-  workspace: "<VMShare path to DuckDuckGo-macOS.xcworkspace>"
-)
-```
-
-Returns `run_id` immediately. Poll with:
-
-```
-get_test_run_status(vm_id: vmName, run_id: run_id)
-get_test_results(vm_id: vmName, run_id: run_id)
-```
-
-Uses pre-built `xctestrun` from `VMShare/DerivedData` — build must happen on host first.
-
-### Step 3 — Inspect failures
-
-```
-peekaboo_image(vm_id: vmName)          # screenshot
-peekaboo_see(vm_id: vmName, app: "...")  # AX tree
-ax_snapshot(vm_id: vmName, app: "...", name: "before")
-ax_diff_last(vm_id: vmName, app: "...")  # what changed
-get_crash_reports(vm_id: vmName)       # crash logs
-get_log_stream(vm_id: vmName, path: "...", lines: 50)
-```
-
-### Step 4 — Cleanup (ALWAYS — especially from Executor)
-
-```
-vm_stop(vm_id: vmName)
-vm_delete(vm_id: vmName)
-```
-
-**Executor must call these before removing its worktree.** Never leave orphaned VMs.
-
---
-
-## All MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `vm_list` | List all VMs with state, IP, checklist status |
-| `vm_prepare_session` | **Main entry point** — clone + start + wait for ready |
-| `vm_start` | Start a VM (optionally clone from golden first) |
-| `vm_stop` | Stop a running VM |
-| `vm_clone_golden` | APFS CoW clone from golden image |
-| `vm_delete` | Delete a VM (run VMs only, never golden) |
-| `vm_get_ip` | Get IP of running VM |
-| `vm_status` | Full status including Peekaboo connection state |
-| `vm_ssh_exec` | Run a shell command in VM via SSH |
-| `run_tests` | Launch XCUITests in VM (returns run_id immediately) |
-| `get_test_run_status` | Poll whether xcodebuild is still running |
-| `get_test_results` | Parse test result artifacts for a run_id |
-| `get_crash_reports` | Read crash reports from VM |
-| `get_log_stream` | Tail a log file from VM |
-| `peekaboo_see` | Dump AX accessibility tree for an app |
-| `peekaboo_image` | Screenshot from VM |
-| `peekaboo_click` | Click by query / element ID / coords |
-| `peekaboo_type` | Type text in VM |
-| `peekaboo_hotkey` | Send hotkey (e.g. cmd+s) |
-| `peekaboo_scroll` | Scroll in VM |
-| `peekaboo_list_apps` | List running apps in VM |
-| `peekaboo_permissions` | Check Screen Recording / Accessibility permissions |
-| `ax_snapshot` | Take named AX snapshot for later diff |
-| `ax_diff_last` | Diff current AX state vs last snapshot |
-| `ax_diff` | Diff two named snapshots by ID |
-| `ax_query` | Query elements from latest snapshot |
-| `vm_build_golden` | Build golden VM from IPSW (full 4-phase pipeline) |
-| `vm_get_build_state` | Poll golden build progress |
-| `vm_list_recordings` | List VNC recordings from build logs |
-| `vm_list_screenshots` | List screenshots from build logs |
-
---
-
-## Executor Integration
-
-When the Executor needs UI tests (bug requires visual verification):
-
-1. Call `vm_prepare_session()` after build succeeds
-2. Call `run_tests()` with the scheme
-3. Poll `get_test_run_status()` / `get_test_results()`
-4. On failure: capture `peekaboo_image()` + `get_crash_reports()` for diagnosis
-5. **Always** `vm_stop()` + `vm_delete()` before worktree cleanup
-
-See also: `ui-testing.md` — Swift UITestCase patterns, feature flag setup, test structure.
-
---
-
-## Notes
-
- VMs require Apple Silicon + lume (`brew install trycua/tap/lume`)
- Golden image must be built and provisioned before test runs work
- `run_tests` uses pre-built xctestrun — **build on host before running in VM**
- Peekaboo (AX/screenshot proxy) must be running inside the VM — `vm_prepare_session` handles this
+- [Image pipeline](https://github.com/mallexxx/virfield/blob/main/docs/IMAGE-PIPELINE.md) — golden preparation и guest policy.
+- [Verification](https://github.com/mallexxx/virfield/blob/main/docs/VERIFICATION.md) — фактическая приёмка и оставшиеся проверки.
+- [[work/wiki/apple-browsers/ci-pipeline]] — CI проекта и требования к Xcode.
+- [[work/wiki/apple-browsers/ui-testing]] — правила самих UI-тестов.