# Chat: an honest in-flight state and background processes ## What this item changed Both areas, the chat's in-flight feedback. **Server (`internal/`).** - `protocol/chat.go` adds the `shell` frame kind (`ChatEventShell`), the `ChatShell` payload (`id`, `status`, `command`, optional `exit` — a pointer so exit `0` is not "absent"), the `ChatShellRunning`/`ChatShellExited` statuses and the `ChatEventFrame.shell` field. - `opencode/chat.go` maps the location-scoped `shell.created`/`shell.exited` firehose events onto that frame. A shell belongs to the session that started it only through `data.info.metadata.sessionID` (the agent's shell tool sets it); the exit event carries no session at all, so it is emitted only for a shell id the stream already surfaced. Another session's shell, and a shell with no attributed session, are ignored; a shell event with no id fails the stream. `NormalizeChatEvent` now folds a `ChatStreamState` (the retained last message id plus the session's running shell ids) across frames instead of a bare `*string`. - `server/chat_hub.go` retains each session's still-running shells (bounded by `chatShellLimit` and the per-session byte cap) and clears them on exit; `server/chat_stream.go` replays them on `chat_subscribe`, the shell half of the resume (the message snapshot cannot carry a shell, because a shell is not a turn). **App (`android/`).** - `data/protocol/Chat.kt` adds `ChatShell`, `ChatEventFrame.shell`, `EVENT_SHELL`, `SHELL_RUNNING`/`SHELL_EXITED`. - `ui/chat/ChatFormat.kt` adds the one pure derivation of a running turn's phase (`TurnPhase` + `turnPhase` + `turnPhaseLabel` + `TURN_THINKING_WINDOW_MILLIS`) and of the background processes (`runningBackgroundShells`, `shellCommandSummary`). - `ui/chat/ChatStore.kt`: `ChatThread.lastDeltaAt` (stamped on every text/reasoning delta, cleared when the turn settles) and `ChatThread.shells` (a shell joins on its running frame and leaves on its exited frame, never marking the thread running); `thread.phase(now)` and `thread.runningShells`; `streamResumed` drops shells so the subscribe replay re-syncs the ones still running. - `ui/chat/ChatTranscript.kt`: `RunningIndicator`'s headline is the phase label (was the bare `Working…`); a new `BackgroundProcessBar` names each running shell. - `ui/chat/ChatConversationPane.kt` shows the bar whenever a shell is running, whether or not a turn is. No percentage, ETA or progress bar is invented on either side. ## Shared documents this change makes stale `docs/cli.md` and `android/README.md`. The note is written here rather than edited in place; the `docs-fold` writer should update them. - `docs/cli.md`, the `chat_subscribe` bullet ("`chat_subscribe` attaches a connection to one session's shared live stream (body `session_id`) and replays the session's still-pending approval requests…") is now incomplete: attaching also replays the session's still-running shell commands as `chat_event` frames of the new kind `shell`, so a device that attaches after a background process started is shown it. - `docs/cli.md`, the chat-protocol type list, should name the new `chat_event` kind `shell`: its payload carries the shell's `id`, `status` (`running`/`exited`), the `command` it is running and, once it has exited, its `exit` code. It carries no message id, because a background process outlives the turn that started it. - `android/README.md:4719` — the **Running indicator** bullet reads "The transcript's indicator shows the spinner, `Working…` and the live elapsed time…". It should say the headline is the turn's actual state — `Thinking…` while text/reasoning deltas are still arriving, `Running a tool…` while calls are in flight, `Waiting…` otherwise — derived purely from the tool calls and the time since the last delta, never an invented percentage/ETA (the one-second tick, the elapsed living on the thread, and the tool lines below it are still true). - `android/README.md` should also record the new always-visible background-process strip: whenever a shell the agent started is still running it names the command, it is independent of the turn (a background process can outlive the turn and is shown then), it survives a chat switch, and it clears the moment the shell exits. Dates, counts and capture names in the dated README records are past evidence and stay as they are; only the behaviour statements above are now stale. ## Not stale - No packaged OpenCode skill reference documents either surface. The chat references in `internal/author/skill/references/` document the server's brokered `chat_*` protocol at a level this change extends additively; nothing there names the frame kinds or the app indicator. - `android/AGENTS.md` and `internal/server/AGENTS.md` already list the files touched, so they need no change. ## Not verified live The end-to-end behaviour on the operator's phone against a **changed** server was not captured: the deployed server (`0.0.0.0:8080`) predates the shell mapping, and redeploying it is forbidden while runs are in flight. The shell mapping itself was checked against the installed OpenCode 2.0.20 service's own event stream (a `shell.created` carries `metadata.sessionID`, a `shell.exited` carries only `id`/`exit`/`status`); the app path is covered by unit tests only.