feat(dispatcher): add opencode CLI support (#89)

## Summary

Add first-class opencode (`anomalyco/opencode`) support to the
dispatcher's agent abstraction layer. opencode is a provider-agnostic
open-source coding agent CLI that, like codex, mints its own session id
per invocation. Mirrors the pattern established in #88: capture the
CLI-minted id from the JSON stream into a sidecar, feed it back on
resume.

## Why

After #88 fixed the codex branch with a session-id-capture pattern,
opencode's identical wrinkle (CLI mints the id; caller can't pre-mint)
became cheap to address with the same approach. README #87 already lists
opencode as the next CLI to integrate; this closes that follow-up.

## Design

opencode JSON shape (verified against `opencode run --format json --pure
"test"` on v1.14.46):

```json
{"type":"step_start","timestamp":1778415469963,"sessionID":"ses_1ee2d8d...","part":...}
```

Every event carries `"sessionID":"ses_<base62>"` — not gated on a
specific event type. The capture filter records the first occurrence
(which arrives in the very first event), validates the format with
`^ses_[A-Za-z0-9]+$`, and writes it to
`${pid_dir}/opencode-session-${dispatcher_session_id}`.

- `run_agent` opencode case: `opencode run --format json [--title
<session_name>] [PROMPT]` piped through `_opencode_capture_session`.
- `resume_agent` opencode case: reads the captured id via
`_opencode_session_id` and calls `opencode run --session <id> --format
json [PROMPT]`. Falls back to `run_agent` when the sidecar is missing or
malformed (defense-in-depth: even though pid_dir is mode 0700, a
malformed sidecar value would otherwise be passed to `opencode run
--session ...` as raw shell input).

## Test Plan

- [x] **Live verification**: installed opencode v1.14.46 locally, ran
`opencode run --format json --pure "test"`, confirmed JSON shape; ran
resume with the captured id, confirmed it works.
- [x] 31 new cases in `tests/unit/test-lib-agent-opencode.sh`:
- Source-of-truth grep (opencode case present, uses `run --format json`,
resume uses `--session`)
- run_agent argv shape + sessionID capture (stub emits the actual
opencode JSON shape)
   - resume_agent uses captured sessionID
- Fallback when sidecar missing (logs diagnostic, calls run_agent shape,
creates fresh sidecar)
- Crash path (opencode exits before any JSON event → no sidecar, exit
code surfaced)
- **Malformed-sidecar regression** (manually planted
`ses_with;injection\`hazard` → regex rejects, fallback triggers, garbage
never reaches `opencode run --session`)
- [x] Codex tests still pass (27/27)
- [x] Full unit suite: 37/37 test files pass
- [x] `bash -n` clean on `lib-agent.sh`
- [x] shellcheck: only SC1091-info for `lib-config.sh` source
- [x] Code-reviewer agent run: zero findings ≥ 80 confidence
- [ ] CI checks pass

## Backwards Compatibility

- `AGENT_CMD=opencode` was previously routed to the generic `<cli> -p
<prompt>` fallback. With this PR it's routed to a first-class branch —
the new behavior is strictly more correct (no `-p` flag misuse).
- `claude` / `codex` / `kiro` branches unchanged.
- Sidecar paths are new files under an already-existing per-user dir
(mode 0700).

## Open follow-ups (not in scope)

- `--dangerously-skip-permissions` flag wiring when
`AGENT_PERMISSION_MODE=bypassPermissions`. The codex branch has the same
gap; would prefer a single PR that addresses both consistently rather
than per-CLI ad-hoc fixes.

## Checklist

- [x] Design described in commit message + this PR body
- [x] Test cases documented (31 cases with thorough behavioral +
regression coverage)
- [x] Build/tests pass
- [x] Code review passed (zero blocking findings)

Author: zxkane

README.md

@@ -2,7 +2,7 @@
 
 A fully automated development pipeline that turns GitHub issues into merged pull requests — no human intervention required. It scans for issues labeled `autonomous`, dispatches a **Dev Agent** to implement the feature with tests in an isolated worktree, and hands off to a **Review Agent** for code review with optional E2E verification. The entire cycle runs unattended on a cron schedule.
 
-Supports multiple coding agent CLIs — Claude Code, Codex CLI, Kiro CLI, Cursor Agent, Gemini CLI, and most CLIs with a `-p <prompt>` non-interactive flag — via a pluggable agent abstraction layer.
+Supports multiple coding agent CLIs — Claude Code, Codex CLI, Kiro CLI, opencode, Cursor Agent, Gemini CLI, and most CLIs with a `-p <prompt>` non-interactive flag — via a pluggable agent abstraction layer.
 
 ## Getting Started
 
@@ -168,7 +168,7 @@ The file is a bash script that's `source`d at every dispatcher tick and wrapper
 | `REPO` | Yes | `owner/repo-name` | The GitHub repo the pipeline watches. |
 | `REPO_OWNER`, `REPO_NAME` | Yes | Split form of `REPO` | Used for App-token scoping. |
 | `PROJECT_DIR` | Yes | Absolute path to the project root on the dispatcher box | Where the agent runs. |
-| `AGENT_CMD` | No (default `claude`) | `claude`, `codex`, or `kiro` | The CLI used to spawn dev/review agents. Other CLIs work via the generic `<cli> -p <prompt>` fallback. See the Supported Agent CLIs table for resume semantics per CLI. |
+| `AGENT_CMD` | No (default `claude`) | `claude`, `codex`, `kiro`, or `opencode` | The CLI used to spawn dev/review agents. Other CLIs work via the generic `<cli> -p <prompt>` fallback. See the Supported Agent CLIs table for resume semantics per CLI. |
 | `AGENT_DEV_MODEL`, `AGENT_REVIEW_MODEL` | No (default empty / `sonnet`) | Model name passed to the agent CLI | Empty = let the CLI pick. The review model defaults to `sonnet` to keep review costs predictable. |
 | `AGENT_PERMISSION_MODE` | No (default `auto`) | `auto`, `plan`, or `bypassPermissions` | `bypassPermissions` grants the agent unrestricted shell access — only use in a trusted sandbox. |
 | `AGENT_TIMEOUT` | No (default `4h`) | coreutils `timeout` units (e.g. `30m`, `2h`, `1d`) | Wall-clock cap on each agent invocation. Prevents hung CLI processes (stale `--resume`, MCP stdio deadlock) from monopolizing wrapper PID slots. |
@@ -373,9 +373,9 @@ The dispatcher is an [OpenClaw](https://github.com/OpenClaw/OpenClaw) skill that
 | Kiro CLI | `kiro-cli` | `chat --no-interactive [--agent <name>]` | (falls back to new) | Basic support |
 | Cursor Agent | `agent` | `-p "<prompt>"` | `--resume=<chat-id>` | Generic fallback (untested explicit branch) |
 | Gemini CLI | `gemini` | `-p "<prompt>"` | (no documented resume flag) | Generic fallback (untested explicit branch) |
-| opencode (`anomalyco/opencode`) | `opencode` | `run "<prompt>"` (positional) | `run --session <id>` — but **caller cannot pre-mint the session id**; opencode mints its own. Needs an explicit `lib-agent.sh` adapter (capture session id from `--format json` stdout, persist sidecar) before resume works. | Generic fallback only (currently); explicit branch tracked as a follow-up |
+| opencode | `opencode` | `run --format json [PROMPT]` | `run --session <sessionID>` (captured from JSON stream) | Full support |
 
-Configure via `AGENT_CMD` in `scripts/autonomous.conf`. The `claude`, `codex`, and `kiro` rows have explicit branches in `scripts/lib-agent.sh`; the others run through the generic `<cli> -p <prompt>` fallback. Any CLI not listed should still work if it accepts a `-p <prompt>` non-interactive flag — the abstraction layer is intentionally permissive.
+Configure via `AGENT_CMD` in `scripts/autonomous.conf`. The `claude`, `codex`, `kiro`, and `opencode` rows have explicit branches in `scripts/lib-agent.sh`; the others run through the generic `<cli> -p <prompt>` fallback. Any CLI not listed should still work if it accepts a `-p <prompt>` non-interactive flag — the abstraction layer is intentionally permissive.
 
 ## Development Workflow (Hook System)
 

skills/autonomous-dispatcher/scripts/autonomous.conf.example

@@ -11,6 +11,10 @@ REPO_NAME="repo-name"
 PROJECT_DIR="/path/to/project"
 
 # === Agent Configuration ===
+# AGENT_CMD: which coding-agent CLI to spawn for dev/review wrappers.
+# First-class support: claude, codex, kiro, opencode. Other CLIs work via
+# the generic `<cli> -p <prompt>` fallback. See README "Supported Agent
+# CLIs" for resume semantics per CLI.
 AGENT_CMD="claude"
 AGENT_DEV_MODEL=""
 AGENT_REVIEW_MODEL="sonnet"

skills/autonomous-dispatcher/scripts/lib-agent.sh

@@ -1,20 +1,27 @@
 #!/bin/bash
 # lib-agent.sh — Agent CLI abstraction layer.
 #
-# Supports: claude (default), codex, kiro, and generic fallback.
+# Supports: claude (default), codex, kiro, opencode, and generic fallback.
 # Source this file in autonomous-dev.sh and autonomous-review.sh.
 #
 # Session-id semantics differ across CLIs:
-#   claude — caller pre-mints `--session-id <UUID>`; same id used for both
-#            run and resume. Cleanest fit for the dispatcher's session_id.
-#   codex  — CLI mints its own thread_id per `codex exec` invocation. We
-#            capture it from `--json` stdout via _codex_capture_thread and
-#            persist a sidecar under pid_dir_for_project() keyed by the
-#            dispatcher's session_id, then feed it back to
-#            `codex exec resume <thread_id>` on resume.
-#   kiro   — no session model; every invocation is a fresh conversation.
-#            resume_agent falls back to run_agent.
-#   *      — generic <cli> -p <prompt> fallback; resume falls back to new.
+#   claude   — caller pre-mints `--session-id <UUID>`; same id used for
+#              both run and resume. Cleanest fit for the dispatcher's
+#              session_id.
+#   codex    — CLI mints its own thread_id per `codex exec` invocation.
+#              We capture it from `--json` stdout via
+#              _codex_capture_thread and persist a sidecar under
+#              pid_dir_for_project() keyed by the dispatcher's
+#              session_id, then feed it back to
+#              `codex exec resume <thread_id>` on resume.
+#   kiro     — no session model; every invocation is a fresh conversation.
+#              resume_agent falls back to run_agent.
+#   opencode — same CLI-minted-session-id wrinkle as codex but with a
+#              `sessionID` field on every JSON event. Captured the same
+#              way (_opencode_capture_session) and fed back to
+#              `opencode run --session <id>` on resume.
+#   *        — generic <cli> -p <prompt> fallback; resume falls back to
+#              a fresh run.
 
 # Load project config via the shared helper (closes #58).
 # Note: ${BASH_SOURCE[0]:-$0} (NOT readlink -f) so the symlink-vendor
@@ -149,6 +156,74 @@ _codex_thread_id() {
   printf '%s\n' "$tid"
 }
 
+# Opencode session-id capture/recall.
+#
+# opencode `run` mints its own session id (`ses_<base62>`) per invocation
+# and accepts `--session <id>` only for resuming an existing one — same
+# CLI-minted-id wrinkle as codex. Mirror the codex helpers, with two
+# differences:
+#   - Field name is `sessionID` (camelCase, capital ID), not `thread_id`.
+#   - The id is on EVERY event in the JSON stream, not gated on a single
+#     event type. We still capture the first occurrence, which arrives in
+#     the very first event.
+
+_opencode_session_file() {
+  local session_id="$1"
+  local pid_dir
+  pid_dir=$(pid_dir_for_project) || return 1
+  printf '%s/opencode-session-%s\n' "$pid_dir" "$session_id"
+}
+
+# _opencode_capture_session <dispatcher_session_id>
+#
+# Pipeline filter: pass-through awk filter that streams stdin → stdout
+# unchanged and writes the first observed sessionID to a sidecar. Same
+# pattern + safety properties as _codex_capture_thread.
+#
+# opencode emits one JSON event per line with a `"sessionID":"ses_..."`
+# field on every event. Format verified against opencode v1.14.46 output.
+_opencode_capture_session() {
+  local session_id="$1"
+  local sess_file
+  sess_file=$(_opencode_session_file "$session_id") || { cat; return 0; }
+  awk -v out="$sess_file" '
+    BEGIN {
+      # opencode session ids look like `ses_<base62>` (e.g. ses_1ee2d8d...).
+      # Tracked together with the regex below so the math stays in sync.
+      prefix = "\"sessionID\":\""
+    }
+    {
+      print
+      fflush()
+      if (!captured) {
+        if (match($0, /"sessionID":"ses_[A-Za-z0-9]+"/)) {
+          sid = substr($0, RSTART + length(prefix), RLENGTH - length(prefix) - 1)
+          # Same CWE-59 defense as _codex_capture_thread.
+          cmd = "test -L \"" out "\" && exit 0; printf \"%s\\n\" \"" sid "\" > \"" out "\""
+          system(cmd)
+          captured = 1
+        }
+      }
+    }'
+}
+
+# _opencode_session_id <dispatcher_session_id>
+#
+# Read the captured opencode sessionID from the sidecar. Echo + rc=0 on
+# hit, echo nothing + rc=1 on miss/malformed. The `^ses_[A-Za-z0-9]+$`
+# regex matches the documented opencode format and protects the
+# downstream `opencode run --session <id>` invocation from injection.
+_opencode_session_id() {
+  local session_id="$1"
+  local sess_file sid
+  sess_file=$(_opencode_session_file "$session_id") || return 1
+  [[ -L "$sess_file" ]] && return 1
+  [[ -f "$sess_file" ]] || return 1
+  sid=$(head -n1 "$sess_file" 2>/dev/null)
+  [[ "$sid" =~ ^ses_[A-Za-z0-9]+$ ]] || return 1
+  printf '%s\n' "$sid"
+}
+
 # Acquire PID guard: prevent duplicate instances for the same issue.
 # Checks for symlink attacks, running processes, then writes current PID.
 # Args: $1=pid_file, $2=label (e.g. "autonomous-dev"), $3=issue_number
@@ -214,6 +289,21 @@ run_agent() {
         ${model:+--model "$model"} \
         "$prompt"
       ;;
+    opencode)
+      # opencode `run [message..]` is the headless invocation. opencode
+      # mints its own session id and emits it on every event in the JSON
+      # event stream, so we capture it the same way as codex.
+      #
+      # The session_name we got from the dispatcher is passed to --title
+      # so opencode's session list shows a human-readable handle alongside
+      # the ses_<base62> id.
+      _run_with_timeout "$AGENT_CMD" run --format json \
+        ${model:+--model "$model"} \
+        ${session_name:+--title "$session_name"} \
+        "$prompt" \
+        | _opencode_capture_session "$session_id"
+      return "${PIPESTATUS[0]}"
+      ;;
     *)
       _run_with_timeout "$AGENT_CMD" -p "$prompt"
       ;;
@@ -271,6 +361,23 @@ resume_agent() {
       # is treated as fresh instructions.
       run_agent "$session_id" "$prompt" "$model" "$session_name"
       ;;
+    opencode)
+      # `opencode run --session <id> [PROMPT]` resumes the conversation.
+      # Same pattern as the codex branch: read the captured opencode
+      # session id from the sidecar, fall back to a new run if missing
+      # (run_agent crashed before the first JSON event reached us).
+      local _opencode_sid
+      if _opencode_sid=$(_opencode_session_id "$session_id"); then
+        _run_with_timeout "$AGENT_CMD" run --format json --session "$_opencode_sid" \
+          ${model:+--model "$model"} \
+          "$prompt" \
+          | _opencode_capture_session "$session_id"
+        return "${PIPESTATUS[0]}"
+      else
+        echo "[lib-agent] no captured opencode sessionID for session $session_id; starting a new opencode session" >&2
+        run_agent "$session_id" "$prompt" "$model" "$session_name"
+      fi
+      ;;
     *)
       # Agents without resume support start a new session
       run_agent "$session_id" "$prompt" "$model" "$session_name"