Broadcasting & Runs
How a Fleet broadcast works: live keystroke mirroring, per-target variable resolution and overrides, supervised runs with durable history, and what happens when a target rejects the write.
Two Broadcast Paths
Once a fleet is armed, everything you type in the primary terminal goes to every armed peer. There are two paths, and they behave differently enough to be worth naming.
- Raw input mirroring replicates keystrokes as you type. It is a live stream with no payload and nothing to replay.
- Structured submission is what Enter does. The composed draft becomes one payload per target, with variables resolved per worktree, and the result is tracked as a supervised run.
Arming is the consent boundary for both. There is no confirmation step on submit: once a fleet is armed, submit just submits. Destructive payloads, large pastes, and multi-line text all fan out immediately. If you want to check what each target will receive before sending, the per-target preview is the review surface.
Live Keystroke Mirroring
When two or more terminals are armed and you start typing in the primary terminal's input bar, an amber Mirroring to N peers pill appears in that input bar. N counts the armed panes the next send can actually reach: it leaves out the pane you are typing in, any armed pane that has lost its PTY, and any target you have skipped in the preview. The composed draft text is copied live into the input bars of armed peers. Editing changes the shared draft; this does not synchronize caret positions or text selections. Raw typing directly into a terminal is a separate byte-stream broadcast path and can originate from any armed terminal outside Fleet Deck.
The input bar itself tints amber on the fleet primary, in the same amber family as the pill, so the shell around what you are typing says "Enter broadcasts" at the point of typing rather than only in a chip above it.
Submitting with Enter
Pressing Enter in the focused primary sends the composed draft to every armed peer. The progress counter on the ribbon reads Sending 3/6 while the fan-out is in flight, adding a failed count if any target rejects the write, except on a small fleet where the broadcast finishes inside the Doherty threshold, in which case the counter is suppressed to avoid a flicker. A successful, complete fan-out fires a one-shot flash on the ribbon. Any send you did not cancel also plays a short confirmation sound when Play sound and UI feedback sounds are on in Settings > Notifications > Sound.
A second Enter while a broadcast is in flight pre-empts the first. The earlier run is recorded as superseded rather than silently dropped.
A fleet broadcast is not added to the primary input bar's prompt history, so ↑ there recalls what you last sent to that terminal alone. For a record of what went out to the fleet, use Run History.
Agents in the fleet that run on another host get the draft over that host's link, verbatim, with no variable resolution. If every member is on another host, the ribbon shows its own message field to type in.
Per-Target Preview and Overrides
The Fleet broadcast preview belongs to drafts that contain at least one {{variable}}. It opens on its own the moment the draft gains one;
close it and it stays closed until you click the drafting pill, which shows a chevron while the
draft has variables. Each row is one armed target, showing an include checkbox, the terminal's
title, the raw draft with amber spans on the variables, and a textarea labeled Resolved holding the payload that target will actually receive.
Edit a textarea to set a per-target override; its label changes to Edited. Enter inside it finishes the edit without sending, and Shift+Enter adds a line. Uncheck the include checkbox to skip that target for this broadcast; the row reads Skipped. The pill names what is pending, as in Mirroring to 2 peers · 1 edited · 1 skipped, so you can tell at a glance that the fan-out is no longer uniform. Pressing Esc inside an open textarea reverts that target to the resolved default and blurs the field rather than closing the popover.
Overrides and skips are per-broadcast. Enter snapshots them at press time, so a popover that closes mid-send cannot change what was already captured, and the store is cleared once the send settles. Closing the preview without sending clears them too. They are also reconciled against the armed set: a pane that leaves the fleet (by manual disarm, or by auto-prune when it is trashed or its PTY dies) drops its override and its skip flag on the way out. Without that, a disarmed-then-rearmed pane would carry a stale skip and quietly miss the next broadcast.
Skipping every target is handled explicitly: the Enter is absorbed, nothing is dispatched, and the announcer says the broadcast was skipped because all targets were excluded.
Variables in Fleet Broadcasts
Fleet broadcasts resolve a small set of variables per target, using each terminal's worktree context. This is the mail-merge path: you write one draft, and every armed terminal substitutes its own values before anything reaches the agent. Names are case-insensitive.
| Variable | Resolves To | Example |
|---|---|---|
{{issue_number}} | Issue number linked to this target's worktree | #412 |
{{pr_number}} | Pull request number linked to this target's worktree | #418 |
{{number}} | Issue number if set, otherwise PR number | #412 |
{{worktree_path}} | Absolute path to this target's worktree directory | /Users/you/proj/.worktrees/feature |
{{branch_name}} | Branch name (falls back to the worktree name if no branch is set) | feature/issue-412 |
A variable that cannot be resolved for a given target (no linked issue, no worktree association) resolves to an empty string, and the preview row flags it with an unresolved chip. A name Daintree does not recognize is left in the text unchanged rather than blanked, so a typo reaches the agent visibly instead of silently vanishing. An override is sent exactly as you typed it, so any variable left in an edited textarea goes out as literal text, and the row flags that too.
{{project_root}} or {{endpoint}}, that is the remote-compute namespace and it does
not resolve inside a Fleet broadcast.Supervised Runs
A structured broadcast does not end when the bytes land. Daintree tracks it as a run: one submission, followed by a watch phase that follows each target's agent state until every target settles. Settling means leaving working or directing: an agent that comes back waiting for input has settled, because it has reached a detected input boundary. A completed run means the targets settled; it does not verify that their tasks succeeded or that their code is correct.
| Status | Meaning |
|---|---|
submitting | The fan-out is still writing to targets. |
watching | Every write has landed; targets are still working. |
completed | Every sent target settled. |
cancelled | You aborted mid-submission. |
failed | No target accepted the write. |
superseded | A newer broadcast pre-empted this run before it settled. |
The ribbon reuses the progress counter's slot for this. While a run is watching it shows live
counts, such as 3 working · 1 waiting · 2 done, with a failed count
when any write was rejected, and a finished run leaves a dismissible Run finished summary. A target on another host reads as 2 sent to studio-02 until its host
reports on it. A run that failed outright reads Run failed · nothing sent.
Canceled and superseded runs render nothing, because the announcer and the progress counter
already covered them.
The count chip's armed list is the per-target drill-down for the same run: a pane whose write was rejected carries a Send failed marker beside its live agent-state badge.
Run History
When a run finalizes it appends a record to a durable history kept in the main process, alongside the records that recipe runs write. Because it lives outside the renderer it survives reloads and window eviction. Read it at Settings > Run history, under the Integrations group.
A fleet record carries the run's outcome, a short preview of the draft, target and success and failure counts, and a per-target list with each pane's title and final state. References are stored as snapshots taken at run time and never re-resolved, so a record stays readable after the terminal is closed or the worktree is deleted. The buffer is a ring capped at 100 records, roughly 200 KB on disk. Scrollback and git state are deliberately not recorded; the record is the automation outcome, not a transcript.
Reading a Run from an Agent
fleet.getRunStatus returns the current run in one call over MCP: per-target submission outcome, whether each failure was
permanent or transient, a live agent-state snapshot, settled flags, and aggregate counts. It is
read-only and dispatches nothing.
terminal.getStatus or a
bounded wait. The Daintree Assistant sends with terminal.sendCommand (or terminal.sendCommandMany for several at
once); any other MCP session gets terminal.sendCommandOwned, which only reaches
terminals that session created. The agent state in a run snapshot is a heuristic and a parsed
check result is not a process exit code, so confirm both before acting on them.Large Broadcasts and Cancelling
Daintree batches large broadcasts so the renderer stays responsive. When a payload reaches 100 KB and there are more than five targets, the fan-out runs in batches of five, yielding to the event loop between batches so the main thread can render and drain IPC.
While a broadcast to more than five targets is in flight the ribbon shows a Cancel button next to the progress counter. Cancelling stops the remaining batches and dismisses the counter.
Failure Handling
Broadcasts fail for two distinct reasons, and Daintree treats them differently.
Permanent PTY errors (EPIPE, EIO, EBADF, ECONNRESET, ENOTCONN, ENXIO, EINVAL)
auto-disarm the failing target. The PTY is gone or invalid, so retrying would do nothing. No
failure chip is recorded for these, because disarming would auto-dismiss it immediately.
Transient errors leave the armed set intact. Each failed pane gets a small red
dot in its title bar (click it to dismiss), and a banner above the ribbon reads Broadcast failed, naming how many terminals rejected the write and, when both
happened in the same broadcast, how many unreachable terminals were disarmed alongside them. Its Retry button re-dispatches the last payload to the still-failed targets only,
through fleet.retryFailures. Re-entrancy is guarded, so retries cannot stack. A
later broadcast that reaches a pane clears its dot.
Raw keystroke broadcasts cannot be replayed: there is no persistent payload for a stream of keystrokes. When the failure was raw input, the banner says so ("Single keystrokes can't be replayed") and omits the retry button entirely rather than showing a dead one.
A send to an agent on another host that the host never confirmed is handled more carefully, because a blind resend could deliver the prompt twice. See Add Agents on Another Host to a Fleet for the Broadcast unconfirmed banner and Send again….