docs: add REST API migration shaping doc, remove outdated ACP specs

Replace opencode acp (JSON-RPC/stdio) with opencode serve (HTTP REST + SSE)
as the planned backend transport. Add full shaping document with requirements,
fit check, spike results, breadboard, and implementation slices.

- Add docs/shaping/rest-api-migration.md with architecture decision
- Remove opencode-monitor-spec.md (superseded by shaping doc)
- Remove docs/plans/acp-parity-completion-spec-v2.md (ACP-specific)
- Update AGENTS.md to describe project purpose concisely
- Update docs/app-server-events.md to remove ACP mapping section
- Update docs/codebase-map.md descriptions

Author: jacobjmc

AGENTS.md

@@ -9,41 +9,37 @@ Detailed navigation/runbooks live in:
 
 - `docs/codebase-map.md` (task-oriented file map: "if you need X, edit Y")
 - `README.md` (setup, build, release, and broader project docs)
+- `docs/shaping/rest-api-migration.md` (architecture decision: ACP to REST API migration)
 
-## Project Snapshot
+## Project Purpose
 
-OpenCodeMonitor is a fork of [CodexMonitor](https://github.com/Dimillian/CodexMonitor) — a Tauri desktop app that orchestrates coding agents across local workspaces. The backend has been replaced: instead of Codex CLI, it spawns **OpenCode ACP** (`opencode acp`) as the agent process and translates between ACP's protocol and the original CodexMonitor frontend event shapes.
+OpenCodeMonitor is a fork of [CodexMonitor](https://github.com/Dimillian/CodexMonitor) — a Tauri desktop app that orchestrates coding agents across local workspaces. The fork replaces the Codex CLI backend with [OpenCode](https://opencode.ai) and translates between OpenCode's protocol and the original CodexMonitor frontend event shapes.
+
+We pull upstream CodexMonitor changes regularly (weekly/monthly). The fork's translation layer is isolated to three Rust files so frontend merges stay clean.
+
+## Architecture
 
 - Frontend: React + Vite (`src/`)
 - Backend app: Tauri Rust process (`src-tauri/src/lib.rs`)
 - Backend daemon: JSON-RPC process (`src-tauri/src/bin/codex_monitor_daemon.rs`)
 - Shared backend source of truth: `src-tauri/src/shared/*`
-- ACP event translation: `src-tauri/src/backend/event_translator.rs`
+- Protocol event translation: `src-tauri/src/backend/event_translator.rs`
 
-## Fork Architecture — ACP Translation Layer
+### Core Design Invariant
 
-The frontend thread reducer receives events in the **same shape** as original CodexMonitor. All ACP-to-CodexMonitor translation happens in Rust. This is the core design invariant.
+The frontend thread reducer receives events in the **same shape** as original CodexMonitor. All OpenCode-to-CodexMonitor translation happens in Rust, never in the frontend.
 
-Key differences from upstream CodexMonitor:
+### Backend: Migrating from ACP to REST API
 
-- **Process spawn**: `opencode acp --port <N> --cwd <path>` instead of Codex CLI. Ports allocated from `AtomicU16` starting at 14096.
-- **Protocol**: ACP uses `session/new`, `session/load`, `session/prompt`, `cancel`, `session/list`. Events arrive as `session/update` notifications.
-- **No turn concept in ACP**: Synthetic `turn/started` and `turn/completed` events are emitted around `session/prompt` calls.
-- **Permission requests**: ACP's `requestPermission` is translated to `codex/requestApproval`. Currently auto-approved by ACP — the approval UI is wired but dormant.
-- **Session creation latency**: 11-17 seconds — frontend shows loading state.
-
-Internal Rust module paths (`codex_core.rs`, `codex/mod.rs`, etc.) are **not renamed** — only user-facing strings. This minimizes merge conflicts with upstream.
+The backend is migrating from `opencode acp` (JSON-RPC over stdio) to `opencode serve` (HTTP REST + SSE). See `docs/shaping/rest-api-migration.md` for the full rationale, requirements, and implementation slices.
 
-### Key Translation Files
+The migration touches three files — the same three already diverged from upstream:
 
-- `src-tauri/src/backend/event_translator.rs` — ACP sessionUpdate → CodexMonitor event shapes
-- `src-tauri/src/shared/codex_core.rs` — All protocol methods rewritten for ACP
-- `src-tauri/src/backend/app_server.rs` — Stdout reader routes `session/update` through translator
+- `src-tauri/src/backend/event_translator.rs` — protocol events to CodexMonitor event shapes
+- `src-tauri/src/shared/codex_core.rs` — all protocol methods
+- `src-tauri/src/backend/app_server.rs` — process spawn, event routing
 
-### Stubbed Features
-
-These Codex-specific features return empty/no-op responses:
-`fork_thread`, `turn_steer`, `start_review`, `model_list`, `account_rate_limits`, `codex_login`, `skills_list`, `apps_list`, `collaboration_mode_list`, `list_mcp_server_status`, `archive_thread`, `set_thread_name`
+Internal Rust module paths (`codex_core.rs`, `codex/mod.rs`, etc.) are **not renamed** — only user-facing strings. This minimizes merge conflicts with upstream.
 
 ## Non-Negotiable Architecture Rules
 
@@ -52,7 +48,7 @@ These Codex-specific features return empty/no-op responses:
 3. Do not duplicate logic between app and daemon.
 4. Keep JSON-RPC method names and payload shapes stable unless intentionally changing contracts.
 5. Keep frontend IPC contracts in sync with backend command surfaces.
-6. All ACP protocol translation happens in Rust — never in the frontend.
+6. All OpenCode protocol translation happens in Rust — never in the frontend.
 
 ## Backend Routing Rules
 
@@ -97,12 +93,11 @@ Use project aliases for frontend imports:
 - Daemon RPC router: `src-tauri/src/bin/codex_monitor_daemon/rpc.rs`
 - Shared workspaces core: `src-tauri/src/shared/workspaces_core.rs` + `src-tauri/src/shared/workspaces_core/*`
 - Shared git UI core: `src-tauri/src/shared/git_ui_core.rs` + `src-tauri/src/shared/git_ui_core/*`
-- ACP event translator: `src-tauri/src/backend/event_translator.rs`
-- ACP protocol methods: `src-tauri/src/shared/codex_core.rs`
-- ACP process spawn: `src-tauri/src/backend/app_server.rs`
+- Protocol event translator: `src-tauri/src/backend/event_translator.rs`
+- Protocol methods: `src-tauri/src/shared/codex_core.rs`
+- Process spawn + event routing: `src-tauri/src/backend/app_server.rs`
 - Threads reducer entrypoint: `src/features/threads/hooks/useThreadsReducer.ts`
 - Threads reducer slices: `src/features/threads/hooks/threadReducer/*`
-- Spec with wire captures: `opencode-monitor-spec.md`
 
 For broader path maps, use `docs/codebase-map.md`.
 
@@ -140,8 +135,6 @@ Run validations based on touched areas:
 - Rust backend changes: `cd src-tauri && cargo check`
 - Use targeted tests for touched modules before full-suite runs when iterating.
 
-Known pre-existing failure: `tailscale::daemon_commands::tests::restart_required_for_old_version` — unrelated to the ACP port.
-
 ## Quick Runbook
 
 Core local commands (keep these inline for daily use):
@@ -185,4 +178,5 @@ Use extra care in high-churn/high-complexity files:
 
 - Task-oriented code map: `docs/codebase-map.md`
 - Setup/build/release/test commands: `README.md`
-- ACP protocol spec and wire captures: `opencode-monitor-spec.md`
+- Architecture decision (ACP to REST migration): `docs/shaping/rest-api-migration.md`
+- Frontend event contract: `docs/app-server-events.md`

docs/app-server-events.md

@@ -1,17 +1,17 @@
-# App-Server Events Reference (OpenCode ACP)
+# App-Server Events Reference
 
-This document describes the events OpenCode Monitor currently emits to the frontend after ACP-to-CodexMonitor translation.
+Events the Rust backend emits to the frontend after protocol-to-CodexMonitor translation.
 
 ## Source Of Truth
 
-- ACP process + stdout routing: `src-tauri/src/backend/app_server.rs`
-- ACP `session/update` translation: `src-tauri/src/backend/event_translator.rs`
+- Process management + event routing: `src-tauri/src/backend/app_server.rs`
+- Protocol event translation: `src-tauri/src/backend/event_translator.rs`
 - Frontend method parser: `src/utils/appServerEvents.ts`
 - Frontend event router: `src/features/app/hooks/useAppServerEvents.ts`
 
 ## Supported Event Methods
 
-These methods are currently recognized by `SUPPORTED_APP_SERVER_METHODS` and routed into thread/app state handlers:
+These methods are recognized by `SUPPORTED_APP_SERVER_METHODS` and routed into thread/app state handlers:
 
 - `app/list/updated`
 - `codex/connected`
@@ -41,21 +41,6 @@ These methods are currently recognized by `SUPPORTED_APP_SERVER_METHODS` and rou
 - `account/login/completed`
 - `error`
 
-## ACP Session Update Mapping
-
-Current `session/update` mappings in `event_translator.rs`:
-
-- `agent_message_chunk` -> `item/agentMessage/delta`
-- `agent_thought_chunk` -> `item/reasoning/textDelta`
-- `tool_call` -> `item/started`
-- `tool_call_update` -> tool deltas + `item/completed`
-- `usage_update` -> `thread/tokenUsage/updated`
-- `plan` -> `turn/plan/updated`
-- `user_message_chunk` -> `item/completed` (`userMessage`) during replay (live sends use synthetic user items)
-- dropped intentionally: `available_commands_update`
-
-Unknown ACP `sessionUpdate` values are ignored (debug builds log them to stderr).
-
 ## Background Helper Routing
 
 When translated events include a `params.threadId` that matches a registered background helper callback, the backend sends those translated events to the callback channel instead of the app event sink.
@@ -64,13 +49,14 @@ This prevents helper traffic from leaking into the visible thread stream while s
 
 ## Synthetic Turn Lifecycle
 
-ACP has no native turn lifecycle notifications. OpenCode Monitor emits:
+OpenCode has no native turn lifecycle notifications. The backend emits:
 
-- `turn/started` before `session/prompt`
-- `turn/completed` only after a successful `session/prompt` response
+- `turn/started` before sending a prompt
+- `turn/completed` after a successful prompt response
 - `error` for failed prompt paths (instead of emitting `turn/completed`)
 
 ## Notes
 
-- All ACP translation stays in Rust by design.
-- Frontend should continue consuming CodexMonitor-shaped events and avoid protocol-specific logic.
+- All protocol translation stays in Rust by design.
+- Frontend consumes CodexMonitor-shaped events and avoids protocol-specific logic.
+- For the protocol-to-CodexMonitor event mapping, see `docs/shaping/rest-api-migration.md`.

docs/codebase-map.md

@@ -109,9 +109,9 @@ When adding a new method, keep method names and payload shape aligned with `src/
 
 All cross-runtime domain behavior belongs in `src-tauri/src/shared/*`:
 
-- Codex threads/approvals/account/skills/config: `src-tauri/src/shared/codex_core.rs`
-- Codex helper commands: `src-tauri/src/shared/codex_aux_core.rs`
-- Codex update/version helpers: `src-tauri/src/shared/codex_update_core.rs`
+- OpenCode protocol methods (sessions/approvals/account/models): `src-tauri/src/shared/codex_core.rs`
+- Helper commands: `src-tauri/src/shared/codex_aux_core.rs`
+- Update/version helpers: `src-tauri/src/shared/codex_update_core.rs`
 - Workspaces/worktrees: `src-tauri/src/shared/workspaces_core.rs`, `src-tauri/src/shared/workspaces_core/*`, `src-tauri/src/shared/worktree_core.rs`
 - Settings model/update: `src-tauri/src/shared/settings_core.rs`
 - Files read/write: `src-tauri/src/shared/files_core.rs`