bug(agent): verify and fix built-in OpenCode ACP launcher compatibility #287

Status

EVIDENCE-BACKED BUILT-IN LAUNCHER CORRECTNESS BUG.

This is not primarily a #286 permission-policy problem.

Two independent observations now point at the built-in OpenCode ACP launcher itself:

1. real ux(agent): minimize time-to-collaboration for a temporary Agent LAN #246 dogfood on another user's machine found that the OpenCode adapter path did not work at all;
2. the ux/security(agent): Room-native ACP approval for resident Harnesses #286 Phase 0 spike reproduced a lower-level failure locally with native OpenCode 1.18.18: the exact current Free4Chat launcher did not answer the Runtime-compatible nd-JSON initialize request within 30 seconds.

Current Free4Chat launcher:

opencode acp --hostname 127.0.0.1 --port 0 --mdns=false --pure

Current OpenCode documentation describes the ACP subprocess contract simply as:

opencode acp
→ JSON-RPC over stdio / nd-JSON

Before #286 can truthfully reason about OpenCode allow / ask / deny behavior, Free4Chat must first prove that its built-in launcher recipe still matches the OpenCode version it claims to support.

Goal

Determine whether the current built-in OpenCode launcher recipe is stale/incompatible and restore one verified, minimal ACP subprocess launch if necessary.

Do not mix permission-policy UX, Room approval UI, or #286 implementation into this bug.

Reproduction matrix

Run against the exact local/pinned OpenCode version used for verification.

Compare at minimum:

A. opencode acp

B. opencode acp --pure

C. current Free4Chat recipe:
   opencode acp --hostname 127.0.0.1 --port 0 --mdns=false --pure

For each:

• send the same ACP v1 initialize frame Free4Chat uses;
• record whether a valid response arrives;
• if not, capture bounded stderr/exit behavior without leaking secrets;
• continue through session/new only after initialize is proven.

If A works and C fails, treat that as direct evidence that the Free4Chat launcher recipe is wrong/stale.

If all fail, determine whether OpenCode 1.18.18 itself is incompatible with the current ACP client assumptions/version.

Do not silently test only a newer OpenCode and declare the existing built-in launcher fixed.

Likely implementation direction

Prefer the smallest launcher recipe that OpenCode itself documents and that passes the ACP wire test.

Do not keep legacy hostname/port/mDNS flags merely because they existed in an older integration if stdio ACP no longer needs or accepts them.

--pure may remain only if it is independently proven compatible and still serves a useful safety/reproducibility purpose. It disables external plugins; it is not a permission profile.

Acceptance

• the exact current OpenCode version under test completes ACP initialize through the chosen built-in launcher;
• session/new succeeds;
• one harmless retained-session prompt succeeds through the same generic ACP adapter;
• current launcher flags are either justified by evidence or removed;
• doctor / launcher diagnostics clearly report an incompatible OpenCode version or launch failure;
• no global OpenCode config is modified;
• no permission mode is broadened as part of this fix;
• existing Hermes/Codex/Claude/Pi/custom ACP launchers are unaffected.

Follow-up boundary

Only after this bug is resolved should #286 verify:

OpenCode permission allow / ask / deny
↔ ACP session/request_permission
↔ any session/process-scoped policy control

Do not block generic #286 ACP permission-relay foundation on OpenCode-specific product mapping, but do not advertise OpenCode policy support until this launcher is green.

Related

• ux(agent): minimize time-to-collaboration for a temporary Agent LAN #246 — real time-to-collaboration dogfood where OpenCode setup failed.
• ux/security(agent): Room-native ACP approval for resident Harnesses #286 — permission-policy compatibility spike; OpenCode policy verification is blocked by this transport/launcher issue.
• Core direction — temporary capability access and collaboration fabric #51 — Harness integration must remain thin and truthful.