bug: opencode-aidevops plugin missing @bufbuild/protobuf + headless-runtime-helper does not attach to running opencode server

[superdav42]

Description

Two related bugs in the framework cause opencode run to fail with Error: Session not found, blocking ALL headless worker dispatch on machines where an opencode serve process is running. Both bugs were diagnosed during a 60-minute pulse session that was unable to launch any workers until the deployed scripts were manually patched.

This is distinct from #16978 (closed Apr 4 in v3.6.20). That issue handled "Session not found" caused by stale persisted session IDs. The bugs reported here trigger even when no --session flag is passed and no persisted session exists.

---

Bug 1: opencode-aidevops plugin missing @bufbuild/protobuf dependency

~/.aidevops/agents/plugins/opencode-aidevops/cursor/models.js imports @bufbuild/protobuf:

import { create, fromBinary, toBinary } from "@bufbuild/protobuf";

But the plugin's package.json has no dependencies section, so the module is not installed. Loading the plugin fails:

ERROR service=plugin error={"name":"ResolveMessage","message":"Cannot find module '@bufbuild/protobuf' from '/home/dave/.aidevops/agents/plugins/opencode-aidevops/cursor/models.js'"} plugin config hook failed

This causes the embedded opencode server inside opencode run to fail to start, surfacing as Error: Session not found.

Fix: Add @bufbuild/protobuf to the plugin's package.json dependencies and have setup.sh run npm install in the plugin directory after aidevops update.

---

Bug 2: headless-runtime-helper.sh does not attach to running opencode server

When the user has opencode serve running on port 4096 (e.g., for the TUI or web client), the environment has OPENCODE_PID and OPENCODE_SERVER_PASSWORD set. In this state:

• opencode run "..." -m anthropic/claude-haiku-4-5 --dir /tmp → fails with Error: Session not found
• opencode run "..." -m anthropic/claude-haiku-4-5 --dir /tmp --attach http://localhost:4096 --password "$OPENCODE_SERVER_PASSWORD" → succeeds

The canary test in headless-runtime-helper.sh (_run_canary_test, ~line 2548) and the worker dispatch command builder (_build_run_cmd, ~line 1349) do not detect OPENCODE_PID and do not pass --attach/--password. Every canary fails, blocking dispatch entirely.

Fix: When OPENCODE_PID and OPENCODE_SERVER_PASSWORD are set, append --attach http://localhost:4096 --password "$OPENCODE_SERVER_PASSWORD" to both the canary and the worker opencode run invocation. Verified locally:

# _build_run_cmd patch (line ~1359)
if [[ -n "${OPENCODE_PID:-}" && -n "${OPENCODE_SERVER_PASSWORD:-}" ]]; then
    printf '%s\0' --attach "http://localhost:4096" --password "${OPENCODE_SERVER_PASSWORD}"
fi

# _run_canary_test patch (line ~2558)
local -a canary_attach_args=()
if [[ -n "${OPENCODE_PID:-}" && -n "${OPENCODE_SERVER_PASSWORD:-}" ]]; then
    canary_attach_args=(--attach "http://localhost:4096" --password "${OPENCODE_SERVER_PASSWORD}")
fi
perl -e "alarm $CANARY_TIMEOUT_SECONDS; exec @ARGV" -- \
    "$OPENCODE_BIN_DEFAULT" run "Reply with exactly: CANARY_OK" \
    -m "$canary_model" --dir "${HOME}" \
    "${canary_attach_args[@]+"${canary_attach_args[@]}"}" \
    >"$canary_output" 2>&1 || canary_exit=$?

Both workers dispatched successfully after the patch. Note: port 4096 is the opencode default — a more robust fix would discover the actual port from the running process.

---

Expected Behavior

1. opencode-aidevops plugin loads cleanly without missing-module errors after aidevops update.
2. headless-runtime-helper.sh run succeeds when called from a session with OPENCODE_PID set, without manual patching.
3. The pulse can dispatch workers regardless of whether the user is also running opencode serve for interactive use.

Steps to Reproduce

1. Have opencode serve running on port 4096 (any opencode TUI/web session does this — OPENCODE_PID and OPENCODE_SERVER_PASSWORD will be set in the environment).
2. Trigger any pulse cycle or run the canary manually:

   opencode run "Reply with exactly: CANARY_OK" -m anthropic/claude-haiku-4-5 --dir "$HOME"

3. Observe: Error: Session not found — no worker spawns.
4. Run with --attach http://localhost:4096 --password "$OPENCODE_SERVER_PASSWORD" → succeeds.

Worker logs show:

[aidevops] OAuth pool: ...
Error: Session not found
[INFO] [fast-fail] count=1 backoff=600s reason=local_error

Environment

• aidevops version: 3.6.167
• Latest version: 3.6.170
• AI Assistant: OpenCode
• OS: Ubuntu 24.04.4 LTS
• Shell: bash 5.2.21(1)-release
• gh CLI: gh version 2.45.0
• OpenCode version: 1.3.16 (pinned)
• OpenCode serve: running on 0.0.0.0:4096

Additional Context

• During the pulse session, four failed worker PIDs (2604559, 2629009, 3372716, 3703540) accumulated before the root cause was diagnosed. Each posted a DISPATCH_CLAIM comment and died without spawning, leaving stale claims that blocked re-dispatch for ~30 min via the dispatch-comment TTL.
• After patching both functions, workers for issues feat: add OpenCode GitHub/GitLab integration support #5 and feat: add parallel session workflow with branch-synced session naming #6 in Ultimate-Multisite/ultimate-ai-connector-webllm dispatched successfully. Issue feat: add OpenCode GitHub/GitLab integration support #5 was fully completed (PR feat: Ralph Loop iterative AI development workflows #14 merged) in the same pulse session.
• The deployed-copy patch will be overwritten by the next aidevops update, so this fix needs to land upstream.
• The previous "Session not found" fix in v3.6.20 (bug: pulse DISPATCH_CLAIM loop — workers never spawn due to dedup self-blocking and headless runtime errors #16978) added stale-session detection on retry, but does not handle this case because the canary fails before any retry logic runs.

Worker Guidance

Files to modify:

• EDIT: .agents/scripts/headless-runtime-helper.sh — _build_run_cmd (~line 1349) and _run_canary_test (~line 2548). When OPENCODE_PID and OPENCODE_SERVER_PASSWORD are set, append --attach <url> --password <password> to the opencode command. Discover the URL from the running process if possible (e.g., parse ss -tlnp | grep opencode), otherwise fall back to http://localhost:4096.
• EDIT: .agents/plugins/opencode-aidevops/package.json — add @bufbuild/protobuf to dependencies.
• EDIT: setup.sh (or the relevant plugin install step) — ensure npm install runs in the plugin directory after aidevops update.

Reference pattern: Model the OPENCODE_PID guard on the existing OPENCODE_PID passthrough at headless-runtime-helper.sh:151-154 (the env-passthrough block that already knows about this variable).

Verification:

# Bug 1
ls ~/.aidevops/agents/plugins/opencode-aidevops/node_modules/@bufbuild/protobuf

# Bug 2 (with opencode serve running)
opencode run "Reply with exactly: CANARY_OK" -m anthropic/claude-haiku-4-5 --dir "$HOME"
# Must succeed without --attach flag after fix

# End-to-end
~/.aidevops/agents/scripts/pulse-wrapper.sh
ps aux | grep -i opencode | grep -v "serve\|watchdog"  # should show worker processes

[github-actions]

Thanks for the report, @superdav42.

This issue has been queued for maintainer review. A maintainer will review it and either:

• Approve it using: sudo aidevops approve issue 17829
• Ask for more information if the report needs clarification
• Close it if it's a duplicate or out of scope

Tip: For faster, higher-quality issue reporting, use /log-issue-aidevops in your AI assistant session. It gathers diagnostics automatically and checks for duplicates.

[marcusquinn]

Maintainer Approval (cryptographically signed)

APPROVE:issue:marcusquinn/aidevops:17829:2026-04-08T14:17:38Z

-----BEGIN SSH SIGNATURE-----
U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgeu2Ii1FVuPun+49v51FONnIskf
TinwsexuL1MNgCwJ8AAAAQYWlkZXZvcHMtYXBwcm92ZQAAAAAAAAAGc2hhNTEyAAAAUwAA
AAtzc2gtZWQyNTUxOQAAAEApKxV5BQg2FppvhF8TOZ+MZa5dFCrkOBUHM7Nu5F1Hkvatu9
dpHMDRbVSxZPsvyBVHChC/sNl4eeUtBcwVQ4gE
-----END SSH SIGNATURE-----

This approval was signed with a root-protected SSH key. It cannot be forged by automation.