Skip to main content

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.

Updated
Reviewed

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.

Note
Focusing an armed follower makes it the primary. To send to only one terminal, disarm that terminal or exit Fleet first, then check that its input bar no longer shows mirroring before submitting. Switching focus alone does not isolate a command.

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.

The same draft resolves issue_number separately for each armed terminal

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.

VariableResolves ToExample
{{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.

Warning
Fleet broadcast variables are a different namespace from the remote-compute lifecycle scripts on the Worktrees page. They share names with the Recipe prompt variables by design, since both cover the same worktree context, but if a doc mentions {{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.

StatusMeaning
submittingThe fan-out is still writing to targets.
watchingEvery write has landed; targets are still working.
completedEvery sent target settled.
cancelledYou aborted mid-submission.
failedNo target accepted the write.
supersededA 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.

Note
There is deliberately no MCP tool that broadcasts to a fleet. An agent orchestrating its own fan-out sends one prompt per terminal and watches with 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.

Warning
Cancelling cannot revoke writes that have already been dispatched. Targets that received their payload before you hit Cancel will run it. Cancel only stops the batches that have not gone out yet, so it has the most effect on a batched broadcast.

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….

Note
The two paths classify unknown errors differently, on purpose. On a structured submit an unrecognized rejection is treated as transient, because it may be an infra hiccup where your retry is the right recovery, and wrongly disarming would silently drop fleet membership. On the raw keystroke path a missing errno means a single keystroke that is not worth replaying, so the target is disarmed instead.