Agents start dev servers, watchers and log tails in the background and move on. The runtime already counted them (to keep the idle reaper off), but nothing showed them. Now each driver publishes its agent's live set on TurnControl, the engine mirrors it on the chat's session row, and the composer shows it in a Background tray above the checklist: what runs, for how long, the tail of its output, and a Stop per process. - Claude: the background_tasks_changed roster (local_bash), joined to the spawning Bash/Monitor command via task_started, output from the task's output file, stopped with the stop_task control request. - Codex: commandExecution items still open after their turn, without the login-shell wrapper; output from outputDelta (no longer opted out), stopped with thread/backgroundTerminals/terminate. - StopBackgroundTask / ReadBackgroundTaskOutput, relay-forwardable, behind the background-tasks-v1 capability. - Mock: ZERON_MOCK_BACKGROUND=1. Co-authored-by: Wing <44917547+wingleeio@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>
5.7 KiB
Background processes
Agents start processes and move on: a dev server, a test watcher, a tail -f.
They keep running after the turn that started them, and until now the only
sign was a transcript chip saying "running in background". The composer now
carries a Background tray listing what the chat's agent still runs, for how
long, with each process's latest output and its own Stop.
Screenshots: docs/screenshots/background-processes/.
Data
The runtime is the authority. Each driver publishes its agent's whole set on
TurnControl (set_background_processes), never a delta, and says where each
process's output can be read (OutputSource). The engine watches that set and
mirrors it on the chat's session row (Session::background_tasks), so every
device sees it, opened or not. The row's 15 s live heartbeat keeps it fresh for
as long as the runtime lives; view::background_tasks treats a row past
SESSION_STALE_MS as an engine that took its processes with it. When the run
ends, the list is cleared.
| Harness | Listed | Command | Output | Stop |
|---|---|---|---|---|
| Claude | background_tasks_changed roster, task_type: "local_bash" (Bash run_in_background, a command moved to the background, Monitor) |
the spawning tool_use's input.command, joined via task_started.tool_use_id; else the roster's description |
the task output file the tool_result names ("Output is being written to: …"), or <tasks dir>/<task id>.output |
stop_task control request (perTaskStopAffordance is already declared) |
| Codex | commandExecution items still open after their turn ended |
item.command, without the login-shell wrapper (/usr/bin/zsh -lc '…') |
item/commandExecution/outputDelta, kept as the last 16 KB per open command (no longer opted out at initialize) |
thread/backgroundTerminals/terminate {threadId, processId}, then the command's item/completed (or the existing prune) removes it |
| Mock | ZERON_MOCK_BACKGROUND=1 |
three scripted processes | each prints its script once, a line every 1.6 s | honored after 250 ms |
Other harnesses publish nothing, and the tray stays hidden for their chats.
Claude reports background agents in the same roster; they are subagents, shown
by their spawn chips, and stay out of this list (they still count toward
TurnControl::background_live, which keeps the idle reaper off). Wire shapes
were captured live from Claude Code 2.1.312; the roster arrives before
task_started, so a late start republishes the list with its command. Codex
commands of an interrupted turn are held back until the existing prune has told
the killed foreground command from the ones still running.
Output is plain text: background::plain_text drops terminal escapes,
collapses carriage-return rewrites (progress bars) to their final state, and
trims trailing blank lines. Files are read from their last 16 KB, starting at a
whole line.
RPC
Both are relay-forwardable and addressed to the chat's host:
StopBackgroundTask {chatId, taskId}→{stopping}.falsewhen no live runtime lists the process (it ended meanwhile). A process leaves the list only when the agent reports it gone, never on the request alone.ReadBackgroundTaskOutput {chatId, taskId}→BackgroundTaskOutput {text, truncated}, ornullwhen it is not listed.
Hosts and engines that answer them advertise background-tasks-v1. A viewport
offers Stop and output only when the chat's host and its own engine (which
forwards the request) do; otherwise the rows only say what runs. Older peers
never publish the field, so their chats show no tray at all.
Behaviour
crates/ui/src/background_tray.rs, mounted by the composer at the top of its
tray stack: above the checklist and the queue, one step narrower than the tray
below it.
- Collapsed (the default):
Background · 3and the commands, in the mono face, joined with·. It is ambient state, so it never opens by itself. - Expanded: one row per process, oldest first: a still busy-tone dot, the
command (mono, truncated), the agent's description (faint), how long it has
run (
12m 34s), and a Stop button. - Output: clicking a row opens the tail of its output beneath it (up to 200 lines, 8 visible, scrolling), following the end unless scrolled up. "Earlier output not shown" marks a cut; "No output yet" an empty one.
- Stopping: the row dims and reads
Stopping…until the next session row drops it. A failed request shows "Couldn't stop that process" under the list. - State (open flag, open row, stops in flight) is per chat, in memory for the app run, like the todo tray's.
- Accessibility: the header, rows and Stop are buttons with
aria_label, tab stops and a focus ring; Stop has a tooltip.
Performance
A collapsed tray costs no frames: there is no animation (the dot is still), and its 1 s tick (clocks, plus re-reading the open output) runs only while it is expanded and stops when it collapses, empties or the chat changes. Session-row writes happen when the set changes, plus the heartbeat the live runtime already sends.
Testing
cargo test --locked -p zeron-harness background # BackgroundWork, Claude roster joins
cargo test --locked -p zeron-harness --test claude background_shells
cargo test --locked -p zeron-harness --test codex background
cargo test --locked -p zeron-doc background_processes
cargo test --locked -p zeron-ui --lib background_tray -- --test-threads=1
Live: ZERON_HARNESS=mock ZERON_MOCK_BACKGROUND=1 fills the tray.
Not done
- Mobile (iOS/Android) tray.
- MCP
get_chat/list_chatsdon't report background processes yet. - Other harnesses (OpenCode, ACP agents, Cursor, Pi) don't report theirs.