From 6cd3c93b84df58d8d12b15079a7fc96c6e0697f7 Mon Sep 17 00:00:00 2001
From: 4 Bytes Robby <robby@4bytes.de>
Date: Mon, 8 Jun 2026 22:55:07 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20update=20ROADMAP=20=E2=80=94=20embed=20?=
 =?UTF-8?q?sidecar=20now=20In=20Progress,=20EPIC=20#117=20with=20wave=20su?=
 =?UTF-8?q?b-issues=20#118=20#119=20#120?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ROADMAP.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 89a98a7..fdadca4 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -311,7 +311,20 @@ Per P48 — Open Source Github Review Automation: CI, linters, and tests are alr
 
 ## Wave: Embedding Sidecar Architecture
 
-> Status: **Planned**. Replaces node-llama-cpp (in-process) with llama.cpp server as a separate sidecar process.
+> Status: **🔄 In Progress** (EPIC #117). Replaces node-llama-cpp (in-process) with a Go sidecar binary that manages `llama-server` as a separate HTTP process. Split into 3 waves:
+> - Wave 1 (#118): Go embed-sidecar binary
+> - Wave 2 (#119): Plugin integration
+> - Wave 3 (#120): Remove node-llama-cpp
+
+### Design Decisions (v1.7.1+)
+- **Two modes only**: hash-based (default) / Go sidecar (opt-in via `BRAIN_EMBED_SIDECAR`). No in-process node-llama-cpp.
+- **Non-blocking**: `embed()` returns hash result immediately; sidecar loads async.
+- **Go binary**: Bundled via GitHub Releases prebuilt, extracted by `build.ts` (same pattern as `vec0.so`).
+- **Self-bootstrapping**: Go binary downloads `llama-server` + GGUF model on first run (cached in `~/.cache/four-opencode-brain/`).
+- **Port**: 8666, configurable via `opencode.json` and `BRAIN_EMBED_SIDECAR_PORT`.
+- **Single-instance**: Port bind detection — 2nd instance connects to existing sidecar.
+- **Idle timeout**: 30min without requests → auto-shutdown.
+- **Rich `/status`**: `{phase, progress, queue_depth}` — always responsive even during model loading.
 
 ### Goal
 OpenCode communicates with a local llama.cpp server via HTTP (OpenAI-compatible `/v1/embeddings`) instead of embedding node-llama-cpp in the main process. This eliminates init-race conditions, separates CPU-heavy embedding from the main event loop, and allows the sidecar to outlive individual OpenCode sessions.