[Juliusolsson05]

Closes #881.

What was wrong

Agent Code launches the OpenCode TUI with --hostname 127.0.0.1 --port <free>, where "free" comes from a loopback probe that releases the port before the TUI binds. If another process takes it in that window, the TUI neither paints nor exits — in the recording it was still running 25 s later, with zero PTY bytes, and only ended because the recorder killed it.

The package already detects this: after its connect deadline it reports live-state { connected: false, reason: 'server-unreachable' }. The adapter already forwards that as a transcript-diagnostic. Nothing reads it.

So the user got a blank pane: no status, no conditions, no error, a process that looks alive — and a composer that would take text and silently fail, because programmatic delivery goes through the very server that never came up (#877).

The fix

The adapter raises a jsonl-error as well — the route every other unrecoverable channel fault in this file already takes — and withdraws input readiness. The message names the port and says what to do:

OpenCode's terminal never answered on http://127.0.0.1:57497. Another process most likely took that port while the TUI was starting. This pane cannot be pointed at a new port — reload this agent to retry with a fresh one. (provider_server_unreachable)

The code rides in the message as well as on the Error, because Electron preserves message across IPC and drops custom Error properties — the same reason the adapter's other errors do it.

In the renderer it joins the lifetime banner (transcriptChannelError), not the transient diagnostics. AgentTerminalLeaf stands that field over the terminal, and its own comment says why the distinction matters: transient warnings train people to ignore the banner. This pane is dead until something real changes.

Three distinctions that are load-bearing

• A flap is not a death. The adapter checks the reason, not just connected === false. An SSE drop after a healthy connection is something the package reconnects from; treating it as a dead server would stand a permanent "reload this agent" banner over a pane that is about to be fine.
• One error per backend generation, so a retry cannot bury the first verdict — and the latch resets on start, because a reload gets a fresh port and a second contested one has to be reported too.
• The diagnostic is not latched. Recordings and the debug bundle want every transition; this adds a user-facing route rather than moving the existing one.

Tests

Driven by the recording, not by imagination. port-conflict.json's own notes are the spec — the contested port answered 418, the TUI never painted, it never exited — so the harness plays a stranger that answers 418 on /event and writes zero PTY bytes.

• Adapter, end to end through the real opencode-terminal-headless package and real sockets: the error, its content, readiness withdrawal, the reload verdict, the repeat guard, and the flap control.
• Renderer, end to end through the harness that runs main's real SessionManager and forwarder: the pane shows the error, it is the lifetime banner, Agent Status and managedTranscriptUnavailableReason agree, and a history load does not write ready over it (the feat(opencode): build opencode-terminal-headless so OpenCode Terminal agents report status and serve MCP reads #864 AC8 failure mode). Plus a control that a healthy pane gets none of this.

All fail first: before the fix the three adapter cases time out waiting for an error that never arrives.

Mutations, all killed:

mutation	result
no jsonl-error (the bug)	3 failed
renderer drops the lifetime banner	1 failed
no latch	1 failed
latch never resets	1 failed
readiness left ready	1 failed
any disconnect counts as unreachable	1 failed
port omitted from the message	2 failed
reload guidance omitted	2 failed

npx tsc -b clean; src/providers/opencode + src/renderer/src/workspace/hook/ipc 31 files / 225 tests pass.

Not done here: the issue's alternative of one automatic respawn on a fresh port. Surfacing is the smaller change and the issue accepts either; an automatic respawn needs its own decision about how a user-visible pane may restart itself, and would sit on top of this signal rather than replace it.

🤖 Generated with Claude Code

[Juliusolsson05]

Finding 1 is right and it is the sharper version of the bug this PR set out to fix: I replaced a silent pane with a pane that lies permanently. Fixed in aa4127d5.

1. [HIGH] A recovered pane kept the banner, and parents kept getting transcript_unavailable. Accepted in full. Your framing — a deadline verdict, not a death certificate — is the sentence that decided the fix, and PROBE A is unanswerable: the live channel connects at 31 s and the pane is healthy in every respect except what it tells the user and what it tells every parent agent reading it.

I took your "smallest fix" and made the diagnostic readable rather than inventing a second route. The recovery signal already crossed to the renderer and nothing subscribed — which is the complaint this PR makes about the FAILURE signal, one channel over. So SessionFeed now carries channel-health diagnostics, and the renderer clears this one fault on a live-state that says connected. Narrow deliberately: only connected: true, and only over an error this same fault raised.

The remote feed gets a documented no-op rather than a sub(...): the host does not forward that channel, and a subscription would look wired when it is not.

On PROBE B — routing a live-channel fault through the durable-transcript surface — you are right that this is the underlying shape, and the clearing path is what makes it tolerable rather than correct. The truly correct version is #881's own suggestion (a process-level error that ensureSessionLive clears), and I did not take it because processStatus: 'failed' would be a different lie: the TUI process is alive and painting nothing. If the next change to this area wants a new surface for "the pane's live channel is down but its transcript is fine", that is the place to put it.

2. [MEDIUM] The vacuous history assertion. Caught cleanly, and your M18b is the proof I should have run: reintroducing the entire #864 AC8 regression and watching my test stay green. The history source is installed now and the call asserted, exactly as the sibling AC8 test does. The comment says why the install is load-bearing, so the next person does not drop it again.

3. [MEDIUM] No negative test for the predicate. Fixed with a sink_failed case driven through the real subscription, plus a live-state that is still DOWN. serverUnreachable = true and clear on any live-state both fail now.

4. [LOW] state.connected ||. I kept it and wrote your equivalence argument into the code — one emit site, literal connected: false, so no test can distinguish it. Better that a reader finds the reasoning than wonders whether a test is missing.

5. [LOW] The harness's stranger. Fixed: ReplayServer.setBlocking(true), whose own comment names port-conflict.json. I had not found that helper; failing /event alone was a stranger that somehow speaks our protocol.

6. [INFERRED] A server that dies mid-session. Your enumeration is now the body of #1097, including why "report that one too" is not the answer (a disconnect is recoverable by design, and reporting every one retrains the user to ignore the banner) and why this PR's recovery path makes a persistent-drop report safe to build on later.

Post-fix mutations, src/renderer/src/workspace + src/providers/opencode (1255 tests):

mutation	result
never clear the banner on recovery	1 failed
clear on ANY connected diagnostic	3 failed
every jsonl-error is a lifetime banner	1 failed
clear on a disconnected live-state too	1 failed

npx tsc -b clean; 371 files / 2690 tests pass across renderer, system and unit.