agentp 1.13.0 → 2.0.0

package/CONTRIBUTING.md

@@ -2,9 +2,20 @@
 
 ## Introduction
 
-agentp is a collection of three zero-dependency Node.js CLI tools that extend [OpenCode](https://opencode.ai) with per-project tmux server management (`ocmux`), a stdin-to-session pipe (`agentp`), and a Telegram bot bridge (`tgagentp`).
+agentp is a collection of three **zero-dependency** Node.js CLI tools that
+extend [OpenCode](https://opencode.ai) v2:
 
-The project aims to stay **zero npm dependencies** — all tools use only the Node.js 18+ stdlib (`http`, `https`, `readline`, `url`, `child_process`, `fs`, `path`, `crypto`, `os`). PRs introducing new dependencies will not be accepted unless there is an exceptional justification.
+- **`agentp`** — pipes prompt text into a running OpenCode session and streams the answer back to stdout.
+- **`ocmux`** — manages per-project TUI windows in tmux (session picker, project switcher, create/rename/delete/annotate sessions) on top of a single **user-managed** OpenCode server.
+- **`tgagentp`** — bridges a Telegram bot chat with OpenCode (multi-chat, multi-server, file sharing). *Experimental.*
+
+The project aims to stay **zero npm dependencies** — everything uses only the
+Node.js 18+ stdlib (`http`, `https`, `readline`, `url`, `child_process`, `fs`,
+`path`, `crypto`, `os`). PRs introducing new dependencies will not be accepted
+unless there is an exceptional justification.
+
+**OpenCode v2 only.** OpenCode v1 support was removed in 2.0.0; there are no
+legacy code paths. The HTTP client lives in `lib/opencode.js`.
 
 ## Development Setup
 
@@ -12,7 +23,8 @@ The project aims to stay **zero npm dependencies** — all tools use only the No
 
 - Node.js >= 18
 - npm (ships with Node.js)
-- tmux (optional, only needed for `ocmux` and `tgagentp` features)
+- tmux (only needed for `ocmux` and `tgagentp`)
+- an OpenCode v2 server for manual testing (`opencode serve`)
 
 ### Local Install
 
@@ -21,119 +33,104 @@ git clone <your-fork>
 cd agentp
 npm link          # registers bin/agentp, bin/ocmux, bin/tgagentp globally
 # or
-npm install -g .  # alternative
+npm install -g .
 ```
 
-After linking, all three binaries are available globally. Run `tgagentp --help` or refer to `README.md`.
-
-### Code Map
+## Code Map
 
 ```
 agentp/
 ├── bin/
-│   ├── agentp        — Stdin-to-OpenCode pipe
-│   ├── ocmux         — Tmux server manager
-│   └── tgagentp      — Telegram bot bridge
+│   ├── agentp            — stdin-to-session pipe
+│   ├── ocmux             — project/TUI window manager + interactive pickers
+│   └── tgagentp          — Telegram bot bridge
 ├── lib/
-│   ├── opencode.js   — HTTP session API client (shared by agentp + tgagentp)
-│   └── ocmux.js      — Tmux management (shared by ocmux + tgagentp)
-├── tests/
-│   ├── opencode.test.js  — Unit tests for lib/opencode.js
-│   └── ocmux.test.js     — Unit tests for lib/ocmux.js
+│   ├── opencode.js       — OpenCode v2 HTTP/SSE client (shared by all three)
+│   ├── ocmux.js          — tmux helpers (shared by ocmux + tgagentp)
+│   ├── project-state.js  — `.ocmux.json` v2 schema + per-session reminders
+│   ├── tui-cmd.js        — tmux send-keys passthrough (tgagentp)
+│   ├── file-share.js     — telegram-shared directory + upload/download
+│   └── telegram-*.js     — Telegram API + formatting helpers
+├── tests/                — node:test suites (one per module)
 ├── docs/
-│   └── specification.md  — Technical architecture reference
-├── AGENTS.md             — Development notes and TODO
-├── CONTRIBUTING.md       — This file
+│   ├── specification.md     — short pointer (superseded)
+│   └── specification_v2.md  — current architecture reference
+├── AGENTS.md             — agent/dev notes
+├── CONTRIBUTING.md       — this file
 └── package.json
 ```
 
 ## Coding Standards
 
-### Style
-
-- **CommonJS** (`require` / `module.exports`) — no ES modules
-- **No semicolons** — the project uses ASI (automatic semicolon insertion)
-- **No comments** in production code — let the code speak; use descriptive variable/function names
-- **2-space indentation**
-- Single quotes for strings
-- `const` over `let`; avoid `var`
-- Arrow functions for callbacks and closures
+- **CommonJS** (`require` / `module.exports`) — no ES modules.
+- **2-space indentation**, single quotes, `const` over `let` (avoid `var`),
+  `async/await` over `.then()`.
+- **Semicolons are used** in `bin/` and `lib/` — except `lib/tui-cmd.js`, which
+  is deliberately no-semicolons. Match the file you are editing.
+- Comments are welcome and present throughout; keep them meaningful.
 
 ### Conventions
 
-- Async functions: use `async/await`, avoid raw `.then()`
-- Error handling: use try-catch at call sites; log errors via `log.error()`
-- Logging: use the `log` helper (`log.info`, `log.error`, `log.debug`) — never `console.log`
-- HTTP: use `lib/opencode.js` request helpers instead of raw `http.request`
-- Tmux: use `lib/ocmux.js` helpers instead of raw `spawnSync`
+- **HTTP:** use `lib/opencode.js` helpers — never raw `http.request`.
+- **tmux:** use `lib/ocmux.js` helpers (`_tmux` / exported wrappers) — never raw
+  `spawnSync`.
+- **State:** `.ocmux.json` I/O goes through `lib/project-state.js`
+  (`readProjectState`, `writeProjectState`, `readAnnotations`, `writeAnnotation`,
+  atomic writes). Never hand-roll reads/writes.
+- **Logging:** `tgagentp` uses `log.info`/`log.error`/`log.debug` (never bare
+  `console.log`). `agentp`/`ocmux` use `console.log` for CLI stdout (answers,
+  lists, `--version`) and `console.error` for diagnostics.
 
 ### Architecture Rules
 
-1. **Zero npm dependencies.** The `package.json` `"dependencies"` field must remain empty.
-2. **`bin/`** files are entry points — keep them thin. Business logic goes in `lib/`.
-3. **`bin/tgagentp`** is the largest file (~2000 lines). When adding new features, extract reusable logic into `lib/` when possible.
-4. **Shared state** (e.g., `chatStates`, `serverOwners`) is held in module-level variables in `bin/tgagentp` and `lib/ocmux.js`. Be mindful of mutation.
-5. **All external calls must be mockable.** `lib/opencode.js` tests mock `http.request`; `lib/ocmux.js` tests mock `child_process.spawnSync` and `fs.*`.
+1. **Zero npm dependencies.** `package.json` `"dependencies"` must remain empty.
+2. **`bin/` entry points stay thin**; business logic goes in `lib/`.
+3. **`bin/tgagentp` is the largest file (~3000 lines).** Extract reusable logic
+   into `lib/` when adding features.
+4. **Mockable externals.** All network/subprocess/filesystem access must be
+   interceptable (the existing test suites mock `http.request`,
+   `child_process.spawnSync`, and `fs.*`).
+5. **Sessions created via the API have no model** and will not execute prompts
+   until one is set — always create them with `createSessionWithModel`.
 
 ## Running Tests
 
-Tests use Node.js built-in test runner (`node:test`) — zero additional dependencies.
+Tests use the built-in `node:test` runner (no extra dependencies). Every
+external interface is mocked, so the suite runs fully in-process and is safe to
+run alongside a live OpenCode instance.
 
 ```bash
-# Run all tests
-npm test
-
-# Run a specific test file
-node --test tests/opencode.test.js
+npm test                                # all suites
+node --test tests/opencode.test.js      # one file
 node --test tests/ocmux.test.js
-
-# Run with verbose output
-node --test tests/opencode.test.js | bunyan  # or just grep for results
+node --test tests/project-state.test.js
 ```
 
-All external interfaces are mocked — tests run entirely in-process without touching the network, tmux, or the filesystem. They are safe to run alongside a live OpenCode instance.
-
-### Test Architecture
-
-Tests are structured in phases (see `AGENTS.md` for the full plan):
-
-| Phase | Module | Boundary Mocked |
-|-------|--------|----------------|
-| 1a | `lib/opencode.js` | `http.request` |
-| 1b | `lib/ocmux.js` | `child_process.spawnSync`, `child_process.execSync`, `fs.*` |
-
-Each test file uses `node:test`'s `mock` API in `before()`/`after()` hooks to install and tear down mocks. Tests within a describe block run serially (`concurrency: false`) when they share mocked state.
+Mock boundaries are installed in `before()`/`after()` (opencode) or
+`beforeEach()`/`afterEach()` (ocmux) hooks. Tests that share mocked state run
+serially (`concurrency: false`).
 
 ### Adding Tests
 
-1. Place new tests in `tests/<module>.test.js`
-2. Use `describe`, `it`, `before`, `after` from `node:test`
-3. Use `node:assert` for assertions
-4. Mock all external boundaries (network, filesystem, subprocesses)
-5. Run the full suite before submitting a PR
+1. Add them to the matching `tests/<module>.test.js`.
+2. Use `describe`/`it`/`before`/`after` from `node:test` and `node:assert`.
+3. Mock every external boundary.
+4. Run the full suite before opening a PR.
 
 ## Pull Request Process
 
-1. **Fork the repo** and create a feature branch from `main`.
-2. **Make your changes** following the coding standards above.
-3. **Run `npm test`** and ensure all tests pass.
-4. **Update documentation** if your change affects user-facing behavior:
-   - Help text in `bin/tgagentp` (the `cmdHelp` function)
-   - `docs/specification.md` for architecture changes
-   - Command table in `devto-article.md` (if adding/changing a slash command)
-   - `AGENTS.md` Done section (move items in/out as appropriate)
-5. **Commit with a descriptive message** following the existing style (e.g., `fix: ...`, `feat: ...`, `refactor: ...`, `docs: ...`).
-6. **Open a pull request** against `main`. Include a summary of the change and any testing instructions.
-
-### Review Process
-
-- Maintainers review within a few business days
-- Focus areas: mock correctness, zero-dependency rule, architectural consistency
-- Large changes may be asked to split into smaller PRs
-- All PRs must pass the test suite before merging
+1. Fork the repo and branch from `main`.
+2. Follow the coding standards above.
+3. Run `npm test` — all suites must pass.
+4. Update documentation when user-facing behavior changes:
+   - `README.md` (usage/behavior),
+   - `docs/specification_v2.md` (architecture),
+   - `AGENTS.md` (test counts / non-obvious facts),
+   - `CHANGELOG.md` (with every release).
+5. Commit with a descriptive message (`fix:`, `feat:`, `refactor:`, `docs:` …).
+6. Open a PR against `main` with a summary and testing instructions.
 
 ## Getting Help
 
-- Open an issue on GitHub for bugs or feature requests
-- Tag questions with `question` label for general help
-- For OpenCode-specific questions, refer to [opencode.ai](https://opencode.ai)
+- Open a GitHub issue for bugs or feature requests.
+- For OpenCode-specific questions, refer to [opencode.ai](https://opencode.ai).

package/README.md

@@ -8,7 +8,7 @@
 This package provides three CLI tools:
 
 - **`agentp`** — pipes prompt text into a running OpenCode server and streams the assistant final answer back to stdout
-- **`ocmux`** — manages OpenCode server + TUI sessions in tmux (create, switch, kill, list)
+- **`ocmux`** — manages project TUI windows in tmux on top of a single user-managed OpenCode server (session picker, project switcher, create/rename/delete/annotate sessions)
 - **`tgagentp`** — bridges a Telegram bot chat with all running OpenCode servers (receives messages from Telegram, routes them to the active server, sends answers back). Supports slash commands for multi-server management, session switching, agent/model listing, including file sharing from the chat.
 
 It is designed for prompt-driven workflows where you want to do things like:
@@ -41,14 +41,41 @@ npm link
 ## Requirements
 
 - Node.js 18+
-- An OpenCode server session listening locally (default port: `4096`)
+- **OpenCode v2** (`opencode serve`) — the server is user-managed; these tools only check it is reachable and complain otherwise.
+- [tmux](https://github.com/tmux/tmux) when using `ocmux` (project TUI windows).
 
-Notes:
+## Servers
+
+The OpenCode server is **user-managed**: start it yourself (e.g. `opencode serve`).
+`agentp` and `ocmux` only *check* that it is reachable and complain otherwise.
+
+- Each project records the server it uses in `.ocmux.json` (`"server"`). If that
+  server is not reachable:
+  - `agentp` exits with `Error connecting to server: …`;
+  - `ocmux` exits with `OpenCode server not reachable at <url>.`
+- **Point somewhere else for one command** (without touching any file):
+
+  ```bash
+  cat prompt.txt | agentp --server http://127.0.0.1:4097
+  # or the positional form:
+  cat prompt.txt | agentp http://127.0.0.1:4097
+  ```
 
-- `agentp` connects to the OpenCode event endpoint over HTTP.
-- In practice this means running `opencode serve` (or equivalent serve mode) so the port is open.
-- `opencode attach` is optional but useful to monitor the full conversation in another terminal/tmux pane.
-- If the OpenCode server is password-protected (`OPENCODE_SERVER_PASSWORD`), both `agentp` and `ocmux` automatically send the required HTTP Basic Auth credentials.
+- **Repoint an existing project** (e.g. the server moved to a new port/host) and
+  relaunch its TUI on the stored session:
+
+  ```bash
+  ocmux serve --server http://127.0.0.1:4097 --force
+  ```
+
+  Without `--force`, `ocmux serve` refuses when `.ocmux.json` already exists.
+
+- **Remote or containerized servers** work too: pass any host reachable over
+  HTTP, e.g. a published Docker port (`--server http://192.168.1.50:4096`) or an
+  SSH tunnel. Auth uses `OPENCODE_SERVER_PASSWORD`/`OPENCODE_SERVER_USERNAME`.
+  The client speaks **HTTP only** (no `https://`). Note that `ocmux` launches the
+  *local* `opencode --server <url>` for the TUI, so use a local OpenCode version
+  compatible with the remote server.
 
 ## Usage
 
@@ -67,6 +94,7 @@ Options:
 - `--getLast <n>`: retrieve last n assistant answers from session history
 - `--session <name>`: target a specific session by name (exact or partial match)
 - `--new`: create a new session with the given title (requires `--session`)
+- `--server <url>`: use this OpenCode server instead of the one in `.ocmux.json` (e.g. `http://host:4096`)
 - `--version`: show version
 - `--help`: show help message
 
@@ -82,8 +110,8 @@ With `--tg`, errors if tgagentp is unavailable.
 
 Arguments:
 
-- `url`: OpenCode TUI server URL or port number (defaults to `4096`). Examples: `4096`, `http://localhost:4096`, `http://192.168.1.50:4096`
-- Tip: `$(ocmux)` expands to the URL of the current project's server, so you can run `agentp $(ocmux)` from any shell.
+- `url`: OpenCode server URL or port number (defaults to `4096`). Examples: `4096`, `http://localhost:4096`, `http://192.168.1.50:4096`
+- Omit it and agentp resolves the project itself: the nearest `.ocmux.json` (upward from the working directory) supplies the server URL, the project directory, and the target session id. `agentp $(ocmux)` still works as an override, but is no longer needed.
 
 ## Examples
 
@@ -189,6 +217,7 @@ The ticket is `agentp_ticket` followed by a JSON object with these fields:
 - `sessionId` — OpenCode session ID used by the deferred job.
 - `elapsed` — seconds since `ctime`, included only when the ticket is re-printed (not on first print).
 - `defer` — the timeout requested at submission, included only when it was > 0.
+- `cancelled` — always present (defaults to `false`). Set it to `true` and pipe the ticket back to cancel the running job (see below).
 
 Tickets are printed as pretty-printed (multi-line) JSON for easier reading and
 editing; pass `--onlineTicket` to print them on a single line instead:
@@ -233,6 +262,27 @@ the ticket's own `defer` value as the timeout (default `0`):
 - If the answer is ready, it is returned and the temp file is removed.
 - If not, the ticket is re-printed with the elapsed time updated.
 
+Cancel a running deferred job by flipping `cancelled` to `true` and piping the
+ticket back (the equivalent of pressing `ESC` in the TUI window):
+
+```bash
+cat <<'EOF' | agentp --defer
+agentp_ticket {
+  "ctime": "2026-08-03T14:30:00.000Z",
+  "path": "/tmp/agentp_deferred_...tmp",
+  "server": "http://localhost:4096",
+  "sessionId": "ses_abc123",
+  "cancelled": true
+}
+EOF
+# 🚫 Prompt cancelled.
+```
+
+`agentp` interrupts the session's execution (`POST /api/session/:id/interrupt`),
+discards the ticket and its queued follow-ups, and prints
+`🚫 Prompt cancelled` (with `(or already finished)` when there was nothing left
+to interrupt).
+
 Works as a Vim/Neovim filter with deferred execution:
 
 ```vim
@@ -265,67 +315,89 @@ Useful to grab recent answers without sending a new prompt.
 
 ## ocmux
 
-Manage OpenCode server + TUI in tmux for project directories.
+Manage **project TUI windows** in tmux on top of a single user-managed OpenCode
+server. A project is a directory holding a `.ocmux.json` state file recording
+the target session; an `Opencode` tmux session holds one window per project
+(TUI only, pane 0).
 
 ```bash
 ocmux [-l] [<subcommand>] [<directory>]
 ```
 
-Without arguments, searches upward from `<directory>` (default: `$PWD`) for `.ocmux.json` and switches to that server's tmux window.
+Without arguments (and with a TTY), opens an **interactive session picker** for
+the project found upward from `<directory>` (default: `$PWD`):
 
-Subcommands:
+- sessions are listed most-recently-viewed first
+- `Enter`/`Space` switches (menu stays open) · `n` create (name input) ·
+  `r` rename (edit in place) · `R` set a reminder · `d` delete (confirm) ·
+  `a` switch agent · `m` switch model · `p` project switcher · `h` help ·
+  `q`/`Ctrl+C` quit
+- switching updates `.ocmux.json` and relaunches the TUI on the chosen session
+  (`opencode --server <url> --session <id>`); silent on success
+- new sessions inherit the model of the previously selected session (v2
+  sessions created via the API have no model and won't run a prompt until set)
 
-- **`serve [--git|--GIT] [--print-logs] [dir]`** — Create a server in `dir` (default: `$PWD`) and attach a TUI pane. Aliased as `new` for backwards compatibility (to be removed in 1.0). Errors if one already exists there. Warns if a parent directory already has a server.
-  - `--git` resolves `dir` to the nearest parent with a `.git` entry (file or dir); errors if none is found.
-  - `--GIT` resolves `dir` to the nearest parent with a `.git` directory only; errors if none is found.
-  - `--print-logs` passes `--print-logs` to `opencode serve`, which prints server logs to stderr in the server tmux pane.
-- **`kill [dir]`** — Kill the server found upward from `dir`. Removes its tmux window and state file.
-- **`resurrect [--print-logs] [dir]`** — Recover a dead/crashed server: reads `.ocmux.json`, kills old tmux window, removes state file, then creates a fresh server + TUI in the same directory. Works even if no tmux window exists (stale state file).
-- **`switch`** — Interactive session picker: an interactive menu of all running servers (columns: dirname, status, url, full path). Arrow keys or `j`/`k` move the selection; `Enter`/`Space` switches to the selected server's tmux window (the menu stays open, so you can hop between servers); `q` or `Ctrl+C` exits. The currently active server (queried live from tmux on every redraw) is highlighted across the full line width. Prints the URL of the last selected server on exit. Requires a TTY.
-- **`list`** — List all running servers with their directories, URLs, and status.
+Reminders (`R`) are stored in the `.ocmux.json` `annotations` map; `agentp`
+prepends a session's reminder to every prompt sent to it.
 
-Options:
+Subcommands:
 
-- `-l`: long output for default/serve commands (append `→ <dir>` after the URL)
-- `--version`: show version
-- `-h`: show help message
-- `--`: treat the next argument as a directory even if it matches a subcommand name
+- **`serve [--server <url>] [--git|--GIT] [dir]`** — create a project TUI window
+  (checks the server is reachable first). Aliased as `new` for backwards
+  compatibility. `--git`/`--GIT` resolve `dir` to the nearest parent with a
+  `.git` entry / directory.
+- **`session <id|title> [dir]`** — non-interactive session switch.
+- **`list [-l]`** — list project windows (with `-l`, their server URL).
+- **`model [ref]`** — switch the model of the selected session.
+- **`kill [dir]`** — close the project's TUI window. **Keeps `.ocmux.json`**
+  (session memory; marks it `stopped`).
+- **`resurrect [dir]`** — recreate the project window from its state file.
+- **`migrate`** — rewrite legacy (v1-style) `.ocmux.json` files to the v2 schema.
+
+The old `switch` subcommand is gone: press **`p`** inside the session picker to
+open the (read-only) project switcher instead. `ocmux` never starts or stops the
+OpenCode server — run `opencode serve` yourself (see [Versioning](#versioning)
+for the pairing policy).
+
+Options: `-l` · `--version` · `-h` · `--` (treat the next argument as a directory).
 
 Notes:
 
-- If `<directory>` is not a valid path, `ocmux` tries to match it against the basenames of existing sessions (exact unique match).
-- When using `--git`/`--GIT`, `ocmux` refuses to create a new server above an existing `.ocmux.json` found while searching for the git root.
-- In default mode, if no server is found, the primary error line is printed to stdout. This intentionally makes `agentp $(ocmux)` fail instead of silently falling back to `agentp`'s default `localhost:4096` server.
-
-### Requirements
-
-- Node.js 18+
-- [tmux](https://github.com/tmux/tmux) — session multiplexer
-- `opencode` binary in PATH (the OpenCode CLI)
+- If `<directory>` is not a valid path, `ocmux` matches it against the basenames
+  of existing project windows (exact unique match).
+- If the server is password-protected (`OPENCODE_SERVER_PASSWORD`), both
+  `agentp` and `ocmux` send the required HTTP Basic Auth credentials.
 
 ### State file
 
-`ocmux` stores per-project state in `.ocmux.json` (contains URL, log path, window index). It searches upward from the target directory, similar to git.
+`.ocmux.json` (in the project directory) stores `version`, `directory`,
+`session`, and `server`. It is found by searching upward, like git. It is
+gitignored — never commit it.
 
 ## How agentp Works
 
 1. Reads all stdin into a single prompt string.
-2. Finds the most recently updated session, or creates one named `agentp`.
-3. Sends the prompt via the session API (`POST /session/:id/message`).
-4. Prints the assistant answer to stdout.
-5. With `--tg` (or by default when `--qa` is given), forwards the answer to Telegram
-   via the agentp gateway. The answer appears in your Telegram chat as if tgagentp
-   itself had processed the request.
-6. If tgagentp's [/record](#tgagentp) feature was active, the gateway response includes
-   the recorded conversation buffer. In `--qa` mode, agentp prepends this buffer (with
-   rulers) to its stdout so OpenCode receives the full Telegram context. Use `--flush`
-   to clear the buffer without prepending.
-
-The session API ensures the request is processed even when no TUI is attached, and returns the full answer in a single HTTP response.
+2. Resolves the target from the nearest `.ocmux.json`: server URL, project
+   directory, and the stored session id (falls back to the most recently viewed
+   session in that directory, or creates one pinned to the directory).
+3. Focuses the project's TUI window, prepends the session annotation (if any),
+   and sends the prompt via the v2 session API (`POST /api/session/:id/prompt`,
+   delivering to that session regardless of what the TUI shows).
+4. Attaches to the SSE stream first so no events are missed, and streams text
+   until the session is quiescent after its terminal signal.
+5. Prints the assistant answer to stdout (with `--qa`, a header with the project
+   path and session id/title before the prompt/answer rulers).
+6. With `--tg` (or by default when `--qa` is given), forwards the answer to
+   Telegram via the agentp gateway. If tgagentp's [/record](#tgagentp) feature
+   was active, the gateway response includes the recorded conversation buffer,
+   which `--qa` prepends to stdout (use `--flush` to clear it).
 
 Operational hint:
 
-- You can keep a separate `opencode attach` view open to see the full run context while `agentp` is used from shell scripts or editor buffers.
+- You can keep a separate TUI view open to see the full run context while
+  `agentp` is used from shell scripts or editor buffers:
+  `opencode --server '<url>' --session '<id>'` (or `--continue` for the last
+  session). `ocmux` manages these windows per project.
 
 ## tgagentp
 
@@ -446,6 +518,21 @@ Chat-to-server directory mappings are saved to `/tmp/tgagentp-connections.json`
 | `TGAGENTP_DEBOUNCE_MS` | Optional. Debounce interval for queued-message notifications (default: `5000`). |
 | `TGAGENTP_ROOT` | Optional. Root directory for `/serve` and `/new` commands (must be writable). |
 
+## Versioning
+
+The 1.x line was born with some internal inconsistency: early releases bumped
+middle digits for small fixes, and `agentp`/`ocmux` were versioned independently
+of the OpenCode they talked to. `2.0.0` marks a cleanup of that history — and a
+single policy from now on:
+
+> **agentp/ocmux/tgagentp share one version, and its major number is paired with
+> the OpenCode major version they target.** OpenCode 2.x ⇒ this project lands in
+> 2.x; if OpenCode ever ships a 3.0, a 3.x here targets it (the minor tracks
+> features, the patch tracks fixes).
+
+OpenCode v1 support was dropped in 2.0.0; the HTTP client (`lib/opencode.js`)
+is v2-only and the tools assume `opencode serve` is user-managed.
+
 ## License
 
 MIT