docs(T697): update OpenCode wake and eviction guidance

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- **OpenCode wake documentation matches the shipped adapters (T697).** README and portability guidance describe standalone `resume: true` wakes, one shared service per machine for long-lived agents, and standalone/service-hosted recovery after MCP eviction (T659/T688).
+
 ## 0.5.47 (2026-10-16)
 
 - **Service-hosted OpenCode sessions stay wakeable after MCP eviction (T688).** OpenCode stops an idle session's MCP about hourly, which releases its lease. T659 kept standalone sessions wakeable through their plugin's poll; a session hosted by the shared `opencode serve --service` is now a wake target too while that service process (same pid and birth) lives, and the wake posts to the service with `resume: true` and a verified receipt. A lease held by another session of the agent still blocks it. docs/OPENCODE.md recommends plain `opencode` (one service per machine, every project) for long-lived agents.

README.md

@@ -148,13 +148,20 @@ AgentMBX gives every agent the same small set of mailbox tools. It delivers mess
   | CLI | Wake path | Status |
   |---|---|---|
   | Codex | `codex app-server` experimental `thread/queue/add`, `thread/queue/list`, and `thread/queue/delete`; AgentMBX tracks its owned notice and withdraws it after read/ack, release, or handover while still queued, preserving unowned items | requires a Codex build with the experimental queue API; historical live receipts |
-  | OpenCode | service-hosted session: the local service's session API (`/synthetic`). `--standalone` session: the plugin inside that session's own serve, over a loopback queue (see [OPENCODE.md](docs/OPENCODE.md)) | historical service-path live receipts; standalone wakes are admitted in-process, whether one starts a turn on an idle session is unproven (T544) |
+  | OpenCode | service-hosted session: the local service's session API (`/synthetic`, `resume: true`). `--standalone` session: its own plugin/loopback queue, also `resume: true` (T544; see [OPENCODE.md](docs/OPENCODE.md)) | recorded service-path live receipts and an idle standalone turn (T544); admission alone does not prove model execution |
   | Claude Code | pushed by the session's own mbx MCP server through Claude Code's per-session inbox socket (`CLAUDE_CODE_MESSAGING_SOCKET`), so a plainly started `claude` wakes on mail with no flag, setting or cron; `agentmbx claude [args]` adds the research-preview mbx channel instead | historical macOS/Fedora live receipts |
   | Kimi | desktop app: its local control socket (setup installs an AgentMBX plugin into the app). `kimi web`: the local server's prompts API. Terminal: a background `agentmbx watch` task the session keeps running (Kimi starts a turn when it exits) | historical terminal/desktop/web live receipts |
   | Hermes | one background `agentmbx watch` task with completion notification; shell hooks bind the session and add inbox context before model calls | watcher requires re-arming after each wake; shared gateway hosts aren't covered |
   | Grok | a background `agentmbx watch --cli grok --session <id>` task; exact session hooks | watcher requires re-arming after each wake |
   | anything else | desktop notification | no automatic model turn implied |
 
+  For long-lived OpenCode agents, run plain `opencode` against the shared service, started once with
+  `opencode service start`: one service per machine, with each session keeping its own project folder.
+  After OpenCode evicts an idle session's MCP, standalone wakes remain available while that serve's plugin
+  polls the local daemon (T659); service-hosted wakes remain available while the recorded service process
+  is alive (T688). Both paths require the recorded PID and process birth, and a lease held by a different
+  session blocks the old binding. See [the run-mode and eviction guide](docs/OPENCODE.md#after-opencode-evicts-the-sessions-mcp).
+
 - **Across machines:** a small daemon per host. Hosts pair with one command each: `agentmbx pair` prints a one-time token, `agentmbx join <host> <token>` on the other machine finishes it (or compare a 6-digit code instead). Hosts find each other on the LAN over mDNS. Every hop is signed. Messages to a sleeping machine wait in an outbox and retry for 72 h, and each is stored exactly once.
 - **Wake batching:** one atomic 30-second window per agent, plus explicit wake mute. Status messages never wake anyone. The published runtime has no hourly per-thread or daily per-agent hard cap; loop detection is observational, so batching alone doesn't bound an automated conversation's token use.
 - **Full-text search** (SQLite FTS5) and an audit log. `mbx:<id>@<host>` references can be cited from tickets and notes.

docs/PORTABILITY.md

@@ -43,13 +43,20 @@ detection/wiring remains a separate boundary. An arbitrary MCP client can wire
 |---|---|---|---|
 | Claude Code | MCP; SessionStart, UserPromptSubmit, PermissionRequest, Stop, PostToolUse, SessionEnd | Its own MCP server sends a no-body hint through the per-session messaging socket; optional `agentmbx claude` channel launcher | Socket/channel support and exact-session binding; historical macOS/Linux receipts aren't proof of every current frontend |
 | Codex | MCP; SessionStart, UserPromptSubmit, PermissionRequest, Stop | `codex app-server` experimental `thread/queue/add`, `thread/queue/list`, and `thread/queue/delete`; tracks owned notices and withdraws them after read/ack, release, or handover while still queued; unowned items are preserved | Requires a Codex build with the experimental queue API and hooks. Consumed notices cannot be recalled. Startup, same-thread resume, and new-thread isolation are separate live gates |
-| OpenCode | MCP; plugin session-created, post-tool, and idle hooks; sidebar plugin | Service sessions use their API; standalone sessions use their own plugin/loopback queue | Standalone in-process admission doesn't prove an idle model turn. Shared-service permission coverage doesn't establish standalone coverage |
+| OpenCode | MCP; plugin session-created, post-tool, and idle hooks; sidebar plugin | Service sessions use their API; standalone sessions use their own plugin/loopback queue. Both daemon wake paths use `resume: true` (T544) | An idle standalone turn was observed with T544; a receipt alone still doesn't prove model execution. Shared-service permission coverage doesn't establish standalone coverage |
 | Kimi terminal | MCP, skill, SessionStart/UserPromptSubmit/PermissionRequest/Stop hooks | One background `agentmbx watch` task exits with a hint and starts the next turn | Re-arm the watcher after handling mail. `MBX_SELF_WATCH` opts into a periodic self-check. Terminal permission hooks can't approve prompts |
 | Kimi web/rc/desktop | MCP and hosted-session hooks; one-time conversation bind ticket | Web prompts API or desktop control socket | Restart a hosted server started before setup; verify the current exact conversation. Approval API coverage applies to hosted sessions |
 | Hermes terminal/TUI | MCP; `on_session_start` and `pre_llm_call` shell hooks with exact hook approvals | Background `agentmbx watch` task with completion notifications | Re-arm after each wake. Hooks load at session start; a shared gateway/desktop host isn't covered. No Hermes permission-approval adapter is claimed |
 | Grok | MCP, status line, SessionStart/UserPromptSubmit/PostToolUse/Stop hooks | Background `agentmbx watch --cli grok --session <id>` | Re-arm each completion; verify exact session ID and provider background-task notification |
 | Other MCP clients | Manual MCP configuration | Desktop notification fallback | No automatic model turn or permission adapter implied |
 
+For long-lived OpenCode agents, prefer plain `opencode` against the shared service, started once with
+`opencode service start`: one service per machine, not per project. After MCP eviction, standalone
+bindings remain wakeable while their plugin polls the local daemon (T659); service-hosted bindings
+remain wakeable while their recorded service process lives (T688). Both paths verify the recorded PID
+and process birth, and refuse an old binding when a different session holds the mailbox lease.
+See [OpenCode run modes and eviction recovery](OPENCODE.md#after-opencode-evicts-the-sessions-mcp).
+
 Setup preserves other tools' hook groups, backs up files before editing, and
 uninstall removes AgentMBX-owned entries. Modified/foreign configuration can
 require manual review. See [the wake reference](SPEC.md#waking-recipients).