docs(solutions): gateway OpenCode mention-loop best practices

[marcusrbrown]

Captures the load-bearing patterns from the @fro-bot mention-execution loop as a best-practices reference, so later gateway work can reuse them instead of rediscovering them.

Covers:

• Remote-attach topology — driving OpenCode in another container is the same HTTP+SSE transport as in-process; the SDK's fetch-based SSE path honors a custom Authorization header on the /event stream.
• Bearer-token reverse proxy fronting a loopback-bound OpenCode server (the server has no native auth; network isolation + proxy auth is the trust model).
• Recovery lock-ownership gate — verify the lock record's run_id matches the stale run before releasing, so recovery never deletes a newer run's lock.
• Failure-path partial-output flush — flush buffered agent output before the coarse error reply so timeouts and stream failures still surface partial work.
• Bounded execution + dual-finally release — AbortSignal.timeout plus nested finally blocks that always release the lock and concurrency slot.
• Terminal-signal correctness — EOF before session.idle is a failure, not success; classify auth by numeric status, not message text.

Cross-links the two existing gateway solution docs (slash-command orchestration, webhook ingress hardening) and the resource-cleanup doc as adjacent references.

[fro-bot]

Verdict: PASS

Docs-only PR adding a single best-practices learning file (docs/solutions/best-practices/gateway-opencode-mention-loop-best-practices-2026-05-30.md, +215). No executable code, no public API surface, no migrations. I verified the substantive risk for a learnings doc — that its claims and references match reality — and everything checks out.

Verification performed:

• All 7 referenced source files exist and the quoted snippets match the actual code:
  • remote-client.ts — createOpencodeClient({baseUrl, headers}), no-op close/shutdown, fetch-based-SSE header note all match (the doc's claim is even backed by an in-source comment).
  • opencode-attach.ts — attachOpencode(baseURL, token) → createRemoteOpenCodeHandle(baseURL, {Authorization: \Bearer ${token}`})` matches verbatim.
  • workspace-agent/main.ts — ports 54321 / 9200 and 127.0.0.1 loopback binding match (doc omits that the proxy binds 0.0.0.0, but that's implied by "sandbox-net-reachable").
  • opencode-proxy.ts — length pre-check before timingSafeEqual, fixed 401 body all match.
  • recovery.ts — the lockFetch.runId === run.run_id ownership gate (line 144) and runId: null fail-safe (line 124) match the doc's P0 narrative exactly.
  • run.ts — AbortSignal.timeout(runTimeoutMs) (206), catch-path sink.flush().catch(...) (296), dual-finally with concurrency.release in outer finally (330–332) all match.
  • run-core.ts — auth by numeric status === 401 || status === 403 (89), aborted → timeout (108), sawIdle === false → stream-ended (115) all match the doc's terminal-signal/auth claims.
• All 3 cross-linked docs exist (slash-command orchestration, webhook ingress hardening, resource-cleanup).
• Frontmatter is complete and consistent with the category/path convention (category: best-practices, dated filename matches date:).

Blocking issues

None

Non-blocking concerns

• The proxy section (§2) says the bearer proxy is "the sole sandbox-net-reachable surface" but omits that it binds 0.0.0.0:9200 while OpenCode binds 127.0.0.1:54321. Stating both bindings explicitly would make the isolation model unambiguous for a future reader. Optional.
• Filename date (2026-05-30) and PR title (2026-05-30) agree, but the doc was captured "after the work cleared review" — fine as-is, just noting the date reflects capture, not the underlying work.

Missing tests

None — documentation has no testable behavior. The patterns it describes (recovery ownership gate, failure-path flush, dual-finally, terminal-signal) live in the gateway packages and are out of scope for this PR; this doc references them rather than introducing them.

Risk assessment (LOW/MED/HIGH): LOW

Single additive markdown file, zero deletions, no code paths touched. Blast radius is limited to documentation. Only failure mode for a learnings doc is inaccuracy or dead references — both checked and clean. No regression, security, or runtime exposure.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	26705699650
Cache	hit
Session	ses_18336700cffeoaCL7BR0JgA9eO

[fro-bot]

Re-checked after the main merge commit (4e190e0). The effective diff is unchanged — still exactly one added file (docs/solutions/best-practices/gateway-opencode-mention-loop-best-practices-2026-05-30.md, +215/-0); the merge does not touch the doc. My prior APPROVED review stands.

Verdict: PASS

Blocking issues

None

Non-blocking concerns

• §2 (proxy) could state both bindings explicitly (0.0.0.0:9200 proxy vs 127.0.0.1:54321 OpenCode) to make the isolation model unambiguous. Optional, carried over from the prior review.

Missing tests

None — documentation with no testable behavior; the patterns it describes already live in the gateway packages and are out of scope here.

Risk assessment (LOW/MED/HIGH): LOW

Single additive markdown file, zero deletions, no code paths touched. The merge commit introduced no new changes to review. No regression, security, or runtime exposure.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	26707303349
Cache	hit
Session	ses_18336700cffeoaCL7BR0JgA9eO