bug: a stalled agent session hangs the chat task forever, and the whole transcript is lost if you kill it

[ThalynLabs]

Summary

If an agent session stops without emitting a terminal event, the chat task waits forever. There is no timeout anywhere in the path. The message stays done=0, the UI shows a task in progress indefinitely, and — because streamed text is only persisted when the run completes — the entire transcript is unrecoverable if the user kills the process to escape.

Separately, the error that caused the stall is silently discarded, so nothing anywhere explains what happened.

Observed on an opencode profile, but the timeout gap is structural rather than adapter-specific.

Environment

• cptr 0.9.20
• opencode 1.18.5
• macOS, Python 3.11, host install via uvx

What happened

A long agent run executed normally for about a minute (multiple read and bash tool calls), then stopped dead. It sat for 49 minutes before I investigated. From the outside it was indistinguishable from a model still working.

State at that point:

• agent server process alive, 0.1% CPU, no child processes
• no outbound connection from the model provider — the upstream call had long since ended
• chat message: done=0, content empty, output null
• last streamed-text flush in the server log: 49 minutes earlier

Querying the agent server directly showed the cause — the final assistant message ended on a tool part still marked running:

{"status": "running",
 "input": {"command": "grep -n \"...\" \"$SCRATCH/...\" | head",
           "workdir": "/Users/u/GitHub/YitHub/project"}}

The model had emitted a corrupted workdir (a mangled path segment) that does not exist. The spawn failed, and the tool part never left running. No terminal event was ever emitted.

Why it hangs forever

In cptr/utils/agents/opencode.py:

• _collect_opencode_events only puts the sentinel that ends the run when it sees session.status with status.type == "idle". A session that stalls without reaching idle never produces it.
• run_opencode_agent then blocks on await event_queue.get() with no timeout and no watchdog.
• The HTTP client is constructed as httpx.AsyncClient(base_url=server_url, timeout=None) — explicitly unbounded.
• The only asyncio.wait_for calls in the module guard server startup and process teardown. Neither covers the event stream.
• cptr/utils/chat_task.py imposes no per-task timeout either.

So there is no layer that can end a stalled run.

Why nothing is diagnosable

async def _drain_stderr(proc):
    while await proc.stderr.readline():
        pass

The agent process's stderr is read and thrown away. Whatever the tool layer reported about the failed spawn was discarded, which is why neither the UI nor the server log nor the database contained any hint.

The severity is in the data loss, not the wait

Streamed text is accumulated in memory and written on AgentDone. Resume state — chat.meta.agent_sessions[<profile>].session_id — is also only written then. So while the task is hung:

• the transcript exists nowhere on disk
• no resume handle exists

The instinctive fix (kill the server, restart) therefore destroys the whole run. In my case that was 29 messages and 28 completed tool calls.

Recovery that does work

Posting an abort to the agent session — rather than killing anything — makes the agent emit its terminal events. cptr then completes normally: it flushed 4668 characters / 72 output items into the message and wrote the resume handle. The session survived on disk, a fresh server found all 29 messages, and a resumed prompt had the model correctly recall its exact position mid-task.

Worth documenting regardless of the fix, since the intuitive recovery is the destructive one.

Suggested fixes

1. A watchdog on the event stream. If no event of any kind arrives for N seconds, emit AgentError instead of waiting forever. A generous default (several minutes) preserves long tool calls while bounding the failure.
2. Give the HTTP client a real read timeout rather than timeout=None, at least on the event stream.
3. Stop discarding stderr. Capture it and include the tail in the AgentError. This one change would have made the incident self-explanatory.
4. Persist streamed text incrementally, or write resume state as soon as the session id is known, so an interrupted run is recoverable rather than lost.
5. Optionally, treat a tool part sitting in running with no further events as a terminal condition — that is the concrete shape this took.

Items 1 and 3 are individually sufficient to turn a silent 49-minute hang into an immediate, readable failure.

Related

#212 — a different defect in the same adapter (prompt/abort routes built from OpenAPI operationIds). Independent of this one: that fails loudly and immediately, this fails invisibly.

[owui-terminator]

🔍 Related Issues Found

I found some existing issues that might be related. Please check if any of these are duplicates or contain helpful solutions:

1. 🟣 #195 bug: the claude CLI subprocess is torn down at the end of every turn, killing in-flight background agents
   Shares the same class of adapter-session failure where an agent's work is lost because the underlying subprocess/client is torn down or otherwise ends before the run completes. While the mechanism differs, both issues center on long-running agent work not surviving the lifecycle boundary.
   by penradioGables

2. 🟣 #177 issue: tool calls stuck forever, never finish unusable
   This is a prior report that tool calls can get stuck forever and never finish. It matches the key symptom in the new issue: a run that never reaches a terminal state and leaves the chat task hanging indefinitely.
   by Classic298

3. 🟣 #180 issue: multiple tool calls never finish
   Very close to the new report's core failure mode: chained or multiple tool calls never complete, which is another manifestation of the agent run getting stuck instead of emitting a terminal event.
   by Classic298

---

💡 If your issue is a duplicate, please close it and add any additional details to the existing issue instead.

This comment was generated automatically. React with 👍 if helpful, 👎 if not.

[ThalynLabs]

Follow-up after a day of use. It recurred twice more, which changes this from a one-off to something reproducible in normal operation — and I need to correct one thing in the original report.

Correction: the corrupted workdir is not the trigger

I framed the original report around a bash call carrying a mangled path. That explained the first occurrence only. Two later stalls had valid, existing working directories. Please don't spend time on workdir validation on my account — it isn't the cause.

Three occurrences, same shape

#	stalled at	tool	workdir
1	09:45	bash	corrupted (non-existent)
2	11:48	bash	valid
3	12:34	bash	valid

Identical state each time:

• final assistant message ends on a tool part with "status": "running"
• no child process under the agent server
• agent server alive at ~0.1% CPU
• no outbound connection to the model provider
• no terminal event, so the chat task waits forever

So the process is gone but the part state never advances.

Hypotheses I tested and ruled out

Recording these so nobody re-chases them:

1. Corrupted workdir — explains occurrence 1 only. See above.
2. SIGPIPE from a | head pipeline. All three stalled commands happened to end in | head, which looked compelling. It is not it: driving seq 1 200 | head -5 and cat <3.7 MB file> | head -20 through POST /session/{id}/shell returned 200 in under two seconds, every attempt.
3. A slow or heavy command. Occurrence 3's full command was a recursive grep over a ~7 MB directory. Run by hand it completes in 0 seconds with 0 output.

The commands are benign and complete instantly outside the tool. My working conclusion is that the bash tool intermittently fails to report completion, but I have not isolated the trigger.

One consequence I under-reported: it blocks the queue

New messages are queued while a task is in flight. A stalled task therefore wedges the entire conversation — anything typed afterwards sits in the queue indefinitely, with no indication that it is waiting on a task that will never finish. From the user's side the UI simply stops responding to input.

When the session is aborted, the queued messages fire automatically and correctly. So the queue itself is fine; it is just held behind a task that can never complete. This makes the missing timeout considerably more user-visible than "one reply never arrives."

Recovery confirmed repeatable

The abort path worked identically the second time, on a much larger run: 26,675 characters / 226 output items (55 messages, 86 function calls, 85 outputs) flushed into the message, resume handle written, queue drained, and the follow-up message resumed the same session with full history.

So the recovery advice in the original report generalises. The data is recoverable at the moment of the stall — it is only lost if the user kills the process, which remains the intuitive thing to do when a UI has been unresponsive for the better part of an hour.

Restating the ask

Given it recurs and the trigger is unclear, the value of a watchdog goes up rather than down: whatever causes the tool to stop reporting, a bounded wait converts a silent indefinite stall into a readable error, and captured stderr would likely reveal what the tool layer saw. Items 1 and 3 in the original list remain the ones I would prioritise.

[ThalynLabs]

The bot surfaced #177 and #180, which report the same user-visible symptom ("tool calls stuck forever", "if model emits chained tool calls it never finishes"). Both are closed, #180 as "Addressed!". Flagging why I don't think this is fixed by that work, so this doesn't get closed as a duplicate of it:

Timeline

	when
#180 closed	2026-07-31 22:21 UTC
cptr 0.9.19 published	2026-07-31 22:39 UTC
cptr 0.9.20 published	2026-08-01 01:29 UTC
my three stalls	2026-08-01, on 0.9.20

So all three occurrences are on a build published about three hours after #180 was closed.

Why it's plausibly a different path

For an agent profile, cptr does not execute the tools. The tools run inside the agent's own process, and the adapter only reads their state off the event stream (_tool_from_event parsing message.part.updated) to render it. A fix to cptr's own tool loop would not reach this path.

That also means the stuck "status": "running" part almost certainly originates upstream in the agent, not in cptr. The defect I'm reporting here is narrower and squarely cptr's: when an agent stops reporting for any reason, there is no timeout, nothing is persisted, and the queue wedges. That holds regardless of what makes the tool stop reporting — which is exactly why a watchdog is worth having even if the upstream cause is fixed separately.

If it's useful I can open a matching report upstream against the agent CLI for the running-that-never-advances half.

[ThalynLabs]

A structural narrowing, from the user noticing a pattern I had missed: the stalls only ever happen on the opencode profile — never on the Claude Code or Codex ones.

That turns out to be explainable from the adapter design rather than from anything about the models:

adapter	transport	unbounded wait
claude_code	subprocess / stdio	no
codex	subprocess / stdio	no
opencode	HTTP + SSE event stream	yes (httpx.AsyncClient(..., timeout=None))

The CLI-backed adapters talk to a child process over a pipe. When that process exits the pipe closes and the read loop ends — process death is an out-of-band signal the OS delivers whether the agent cooperates or not. Those lanes cannot hang this way even if the agent misbehaves.

The opencode adapter is the only one that spawns an HTTP server and consumes an event stream. Its completion signal is in-band and advisory: the run ends only when the server chooses to emit session.status: idle. If that event never comes there is no other termination path — the socket stays open, the stream stays silent, and silence is indistinguishable from a model thinking.

Why this matters for the fix. I originally argued for a watchdog as defence in depth. That undersells it: for this adapter a watchdog is not a second line of defence, it is the only termination guarantee the lane has. Every other adapter gets one from the operating system for free. This one has none.

It also means the fix does not need to wait on identifying what makes the tool stop reporting. Whatever the upstream trigger turns out to be, this adapter is structurally exposed to it in a way the others are not.

Two smaller notes:

• The synchronous POST /session/{id}/message returns the completed assistant message in the HTTP response, unlike prompt_async which returns 204 and relies entirely on the stream. That would give the adapter an out-of-band completion signal much closer to what the subprocess adapters get, and it can carry a read timeout where stream silence cannot. It is not a complete fix on its own — a genuinely wedged turn would block that call too — but a blocked call with a timeout is recoverable, and an idle socket is not.
• A watchdog that merely raises still leaves the user to recover by hand. Since an abort makes the server emit its terminal events and lets the adapter finish normally — flushing the transcript and writing resume state — a watchdog that aborts and then completes would turn this from a dead session into a finished turn the user can simply continue from. That matters for anyone driving this from a browser rather than a shell.

Sample-size caveat, stated plainly: the Claude comparison rests on ~18 completed runs, the Codex one on only 2. But the structural argument does not depend on the sample — a closed pipe cannot be waited on.