Workspace/gateway reliability hardening: attach-path timeouts + readiness depth

[marcusrbrown]

Follow-up hardening surfaced while shipping the #749 supervisor-readiness fixes. None of these are required for the cold-boot mention-loop fix (that landed in #755 and #761), but each closes a residual failure or test gap. Grouping them so they can be picked up together or à la carte.

Attach-path hang windows (same class as the readiness-probe bug)

The #749 fix added a per-probe timeout to the workspace readiness probe because a fetch that is accepted but never answered hangs forever. The same pattern exists on two other paths:

• Gateway SDK calls don't carry the run abort signal. packages/gateway/src/execute/run-core.ts receives a signal (used only for event-stream iteration), but client.session.create(), client.event.subscribe(), and client.session.promptAsync() are called without it. If the workspace proxy accepts the connection but stalls, a mention run can hang before the iteration loop ever observes signal.aborted. Thread the run signal (and/or a bounded AbortSignal.timeout) into those calls.
• The workspace OpenCode proxy has no upstream request timeout. apps/workspace-agent/src/opencode-proxy.ts forwards via http.request() and only handles the error event — a stalled upstream leaves the gateway call hanging. Add an upstream timeout for non-streaming requests. Careful: the proxy also carries the SSE event stream, so a short total timeout must NOT be applied to event streams — only to ordinary request/response calls.

Readiness depth

• /readyz reflects only the loopback OpenCode status, not the path the gateway actually attaches through. Readiness currently mirrors the supervisor's opencodeStatus (loopback :54321). The gateway attaches via the bearer proxy on :9200. Consider gating readiness on the proxy listening/healthy as well, so /readyz means "the attach path is usable" rather than "OpenCode booted." (The post-ready-exit case — OpenCode dying after reaching ready — is handled by the supervisor respawn work tracked under v0.52.1: workspace-agent OpenCode supervisor is brittle — cold-boot mention runs fail (15s one-shot timeout, no per-probe timeout, no retry, /healthz masks dead OpenCode) #749.)
• The overall readiness timeout is not a hard cap. A single probe can overshoot the configured WORKSPACE_OPENCODE_READY_TIMEOUT_MS by up to one per-probe timeout (~3s). Immaterial at the 60s default; only matters if an operator sets a very low overall timeout. Cap each probe to the remaining deadline if a hard bound is wanted.

Test gaps

• No cross-package type-mirror test. apps/workspace-agent/src/types.ts ReadyzResponse (flat) and packages/gateway/src/workspace-api/types.ts (discriminated union) are wire-compatible by hand. A compile-time equivalence/assignability test would catch future drift before runtime.
• No entrypoint-wiring test for the readiness timeout. apps/workspace-agent/src/main.ts is side-effectful (binds ports at import), so there's no clean seam to assert the resolved WORKSPACE_OPENCODE_READY_TIMEOUT_MS reaches startOpencodeServer. Extracting a small startWorkspaceAgent(deps) would make the wiring testable.

Priority is low — these are resilience and coverage improvements on top of a working fix.

[fro-bot]

Triage: Workspace/gateway reliability hardening

I verified every claim in the issue against the current code on main. All five points are accurate and reproducible by inspection. This is a well-scoped follow-up to the #749 readiness-probe work (landed via #755/#761). Below is a confirmation pass plus a recommended sequencing.

Verification

1. Gateway SDK calls don't carry the run abort signal — Confirmed.
packages/gateway/src/execute/run-core.ts accepts signal (run-core.ts:86) but only consults it inside the iteration loop (if (signal.aborted) break at run-core.ts:254 and the post-loop check at run-core.ts:393). The three pre-loop SDK calls are signal-less:

• client.session.create() — run-core.ts:190
• client.event.subscribe({query: {directory}}) — run-core.ts:216
• client.session.promptAsync({...}) — run-core.ts:227

If the proxy accepts the TCP connection but stalls, any of these can hang before the loop ever observes signal.aborted. Same failure class the readiness probe already fixed.

2. Workspace OpenCode proxy has no upstream request timeout — Confirmed.
apps/workspace-agent/src/opencode-proxy.ts forwards via http.request() and only wires the error event (opencode-proxy.ts:106). There is no upstreamReq.setTimeout(...) / socket timeout. A stalled upstream leaves the gateway call hanging indefinitely.
Critical constraint holds: the same proxy pipes the SSE event stream (opencode-proxy.ts:103, comment at :12). A blanket total timeout would kill long-lived event streams. Any timeout must be scoped to non-streaming request/response calls only (e.g. an idle/headers timeout, or skip the timer once the upstream response begins streaming for SSE content-types).

3. /readyz reflects only loopback OpenCode status, not the attach path — Confirmed.
apps/workspace-agent/src/server.ts:53-61 gates /readyz solely on opencodeStatus.status (the loopback :54321 server). The bearer proxy on :9200 — the port the gateway actually attaches through — is booted fire-and-forget in main.ts:71-79 and its listen state is never reflected in readiness. /readyz currently means "OpenCode booted," not "the attach path is usable." Note the proxy listen() failure is only logged (main.ts:76-79), so a proxy that fails to bind still reports ready: true.

4. Overall readiness timeout is not a hard cap — Confirmed.
startOpencodeServer loops while (Date.now() < deadline) (opencode-server.ts:183) and each iteration awaits pollReadyFn(url, signal) with an independent per-probe deadline (probeTimeoutMs = 3000, opencode-server.ts:99). A probe started just before the deadline can overshoot by up to one full probe timeout (~3s). Immaterial at the 60s default; only matters under a very low configured WORKSPACE_OPENCODE_READY_TIMEOUT_MS. Fix is to clamp each probe to min(probeTimeoutMs, deadline - Date.now()).

5a. No cross-package type-mirror test — Confirmed.
apps/workspace-agent/src/types.ts:65-69 (ReadyzResponse, flat) and packages/gateway/src/workspace-api/types.ts:61-76 (discriminated ReadyzReady | ReadyzNotReady) are wire-compatible by hand, maintained in two places with explicit "narrows the flat ... emitted by ..." comments. No compile-time assignability assertion guards against drift.

5b. No entrypoint-wiring test for the readiness timeout — Confirmed.
apps/workspace-agent/src/main.ts binds ports at import (main.ts:32, :48, :76) and is side-effectful, so there's no seam to assert the resolved WORKSPACE_OPENCODE_READY_TIMEOUT_MS (readReadyTimeoutMs(), main.ts:46) actually reaches startOpencodeServer (main.ts:53). Extracting startWorkspaceAgent(deps) would make this assertable.

Reproduction notes

These are latent hang/coverage gaps, not crashes — they don't reproduce from a normal happy-path run. They manifest only when an upstream/proxy accepts a connection then stalls (1, 2), when the proxy fails to bind but OpenCode is up (3), or under an unusually low overall timeout (4). The cleanest "reproduction" is the static evidence above; runtime repro would require a fault-injecting stub upstream that accepts then never responds.

Proposed next steps (ordered by value/risk)

1. Thread the run signal into the three SDK calls (feat: update repo settings for agent #1) — highest impact, lowest risk. Pass {signal} (or compose with AbortSignal.timeout(...) for a bounded attach) into session.create, event.subscribe, and promptAsync. Closes the largest remaining hang window in the mention loop.
2. Add a scoped upstream timeout to the proxy (Dependency Dashboard #2) — high impact. Apply an idle/headers timeout to ordinary request/response forwarding; explicitly exempt SSE (don't arm/total-cap once streaming begins or for event-stream paths). Add a test asserting a stalled non-stream upstream returns a bounded error while an SSE stream survives.
3. Deepen /readyz to gate on proxy health (ci: update renovate and fix version branch #3) — medium. Track proxy listen state in a shared ref (mirroring opencodeStatus) and require both OpenCode ready AND proxy listening for ready: true. Surface proxy bind failure instead of swallowing it.
4. Extract startWorkspaceAgent(deps) + add wiring test (#5b) — medium, unblocks coverage. Gives a testable seam; also makes ci: update renovate and fix version branch #3 easier to assert.
5. Add the compile-time type-mirror test (#5a) — low effort. A satisfies/assignability check (or expectTypeOf) tying the two ReadyzResponse shapes together.
6. Clamp per-probe timeout to remaining deadline (Action Required: Fix Renovate Configuration #4) — lowest priority. One-line min() in the poll loop; only matters for very low configured timeouts.

Items are independent and can be picked up à la carte, but doing #4 (startWorkspaceAgent) before #3 reduces rework. All are resilience/coverage improvements on top of a working fix — priority low, as the issue states. I'd suggest splitting into per-item PRs rather than one large change, since the proxy-timeout/SSE work (#2) carries the most regression risk and deserves isolated review.

---

Run Summary

Field	Value
Event	issues
Repository	fro-bot/agent
Run ID	26962395502
Cache	hit
Session	ses_16cb55935ffeeujx0R4K29Wf8j

[marcusrbrown]

Reconciled against current main. The highest-impact item shipped; the rest are still valid low-priority resilience/coverage work, so keeping this open with a narrowed list.

Shipped:

• Run signal threaded into the SDK calls (item 1). run-core.ts now passes the run's AbortSignal into session.create (and aborts the event iteration), with explicit abort checks before/after each external call. Combined with the directory-threading fix, session.create / event.subscribe / promptAsync all carry directory + signal, so an aborted/expired run no longer hangs the mention loop on a stuck SDK call. This was the largest remaining hang window.

Still open (all low-priority, independent à-la-carte PRs):
2. Scoped upstream timeout on the bearer proxy. opencode-proxy.ts still only wires upstreamReq.on('error') — a stalled upstream that accepts then never responds hangs indefinitely. Must be an idle/headers timeout scoped to ordinary request/response and exempt SSE (the same proxy pipes the event stream).
3. /readyz depth. Still gates only on the loopback OpenCode status, not the :9200 bearer-proxy bind state — and a proxy listen() failure is only logged. /readyz should require both OpenCode ready AND proxy listening.
4. Clamp per-probe timeout to remaining deadline. The readiness loop runs independent 3s probes; a probe started near the deadline can overshoot by ~one probe. One-line min(probeTimeoutMs, deadline - now). Immaterial at the 60s default.
5a. Cross-package ReadyzResponse type-mirror test — the flat workspace-agent shape and the gateway's discriminated shape are hand-kept wire-compatible with no compile-time assignability assertion.
5b. Extract startWorkspaceAgent(deps) — main.ts binds ports at import (side-effectful), so there's no seam to assert the resolved ready-timeout reaches startOpencodeServer. Doing this first makes #3 easier to test.

Suggested order if picked up: #2 (highest remaining impact, but isolate it — SSE regression risk), then #5b → #3, then #5a/#4. Keeping open against items 2–5.