feat(swarm): broadcast a message to every slot's agent; show time per slot

CHANGELOG.md

@@ -28,6 +28,14 @@ Notable changes to the Swarm plugin. Format follows
   agent) as settled, instead of refusing cleanup until its tab is focused.
 
 ### Added
+- `broadcast` harvest verb: types one single-line message into every running
+  slot's agent (or `HERDR_SWARM_TARGETS`) and submits it. A slot is only typed
+  into when its pane still holds the slot's terminal and a program, not the
+  shell, is in the foreground. Multi-line text, control characters, and a
+  leading `-` are refused.
+- Elapsed time per slot in the status pane and the compare view (fan-out now
+  records `started_at`). Token and cost display is deferred: Herdr has no
+  usage channel and agents do not report usage to it.
 - Per-slot tasks without a TTY: `<!-- swarm-slot: N -->` marker lines split
   `HERDR_SWARM_TASK_FILE` into per-slot sections after a shared preamble.
   The highest section sets the slot count when `HERDR_SWARM_SLOTS` is unset,

README.md

@@ -468,6 +468,60 @@ stdout and stderr are logged there **verbatim and indefinitely** — the state
 dir is `0700`, but don't `echo`/`set -x` secrets in `setup.sh`: a token
 printed during dependency install stays on disk until you delete the log.
 
+## Steering a running swarm
+
+Send one message to every running slot's agent. It is typed in and submitted,
+as if you had typed it into each agent:
+
+```sh
+HERDR_SWARM_MESSAGE="Also add tests for the edge cases, then commit." \
+  bash scripts/harvest-step.sh broadcast
+```
+
+- `HERDR_SWARM_MESSAGE_FILE` takes the message from a file instead.
+- `HERDR_SWARM_TARGETS=1,3` limits it to some slots.
+- Output: one record per targeted slot:
+  - `broadcast_sent<TAB>slot`
+  - `broadcast_skipped<TAB>slot<TAB>why`
+  - `broadcast_partial<TAB>slot<TAB>why`: the text was typed but **not
+    submitted**. Clear that pane's input line rather than re-running.
+- The verb exits 36 unless every target received the message. Targets are
+  slot numbers, each named at most once.
+
+**One line of plain text.** A newline inside the text reaches the agent as a
+real line break, so a terminal agent would submit half the message
+(live-verified). Control characters are keystrokes (Ctrl-C, escape sequences),
+not text. Swarm refuses both, plus Unicode line separators,
+direction overrides, invalid UTF-8, and a leading `-` (which the Herdr CLI
+would parse as a flag). This check doesn't depend on your locale. For longer
+instructions, write a file and broadcast "read NOTES.md and follow it".
+
+**Only into the slot's own agent.** Typing into the wrong program can *run*
+the message: a shell executes it, `less` runs `!…`, `vim` treats it as
+commands, and an approval dialog takes letters as choices and Enter as "yes".
+Right before typing, a slot must pass all of these:
+
+- its pane still holds the slot's own terminal;
+- Herdr doesn't report the agent `blocked`;
+- the foreground process group's **leader** is the slot's own agent program
+  (recorded at fan-out as `agent_command`, e.g. `claude`, or `codex` when
+  launched as `node …/codex`), not the shell or anything started in the pane;
+- the agent hasn't finished by exiting.
+
+The program is checked again between typing and Enter. If it changed, Enter is
+withheld, because unsubmitted text is inert. Rows from runs started before this
+version have no `agent_command` and are skipped. On Herdr 0.7.5+ Swarm reports
+the agent's state itself, so a `blocked` approval prompt isn't visible. Don't
+broadcast while an agent may be asking for approval. Herdr's `agent prompt`
+isn't used, because on 0.7.5+ it refuses panes where Swarm reports the agent
+state (live-verified: `agent_not_ready`).
+
+**Elapsed time** per slot shows in the status pane's `time` column and the
+compare view. It runs from when the slot started to when finish detection
+recorded it done, or to now. Token usage and cost aren't shown: Herdr has no
+channel that carries them (its pane `tokens` are display metadata), and no
+agent reports them to it.
+
 ## Comparing slots and picking a winner
 
 In the harvest pane, `w` opens the compare view, which replaces the slot list

bin/renderer-harvest.mjs

@@ -13,6 +13,7 @@ import {
 	sanitizeText,
 	manifestPath,
 	parseManifest,
+	formatDuration,
 } from "./renderer-shared.mjs";
 
 // --- harvest mode (U6) -------------------------------------------------------
@@ -95,7 +96,7 @@ export function gitDisplayEnv(env) {
 // Every field is manifest- or git-derived text, so all of it is sanitized.
 export function renderCompare(view, cols = 80) {
 	const lines = [
-		` ${pad("rank", 5)}${pad("#", 3)}${pad("checks", 16)}${pad("commits", 8)}${pad("files", 6)}${pad("+/-", 12)}${pad("dirty", 6)}${pad("finished", 9)}label`.slice(0, cols),
+		` ${pad("rank", 5)}${pad("#", 3)}${pad("checks", 16)}${pad("commits", 8)}${pad("files", 6)}${pad("+/-", 12)}${pad("dirty", 6)}${pad("finished", 9)}${pad("time", 7)}label`.slice(0, cols),
 	];
 	if (!view.slots?.length) lines.push("  (no slots to compare)");
 	for (const s of view.slots ?? []) {
@@ -108,7 +109,7 @@ export function renderCompare(view, cols = 80) {
 		)}${pad(s.insertions == null ? "-" : `+${s.insertions}/-${s.deletions}`, 12)}${pad(s.dirty ?? "-", 6)}${pad(
 			sanitizeText(s.finished ?? (s.candidate ? "no" : s.status ?? "")),
 			9,
-		)}${sanitizeText(s.label ?? "")}`.slice(0, cols);
+		)}${pad(formatDuration(Number.isSafeInteger(s.elapsed_seconds) ? s.elapsed_seconds : null), 7)}${sanitizeText(s.label ?? "")}`.slice(0, cols);
 		// Failed checks are the one thing that must not be missed when picking.
 		lines.push(v.status === "failed" ? `${ESC}[7m${line}${ESC}[0m` : line);
 	}

bin/renderer-shared.mjs

@@ -65,7 +65,27 @@ export const TERMINAL_STATUSES = new Set(["archived", "merged", "skipped", "fail
 //
 // agents: array from the agent-list query, or null when it was unanswerable.
 // gitFacts: { [slot]: { worktreeMissing, branchMissing, committed, uncommitted } }
-export function reconcileSlots(manifestSlots, agents, gitFacts) {
+// Elapsed time for a slot: from its recorded start (started_at, written when
+// fan-out marks it running; older rows fall back to the run's created_at) to
+// its finish (finished.at from settle), or to `now` while it is still going.
+// null when no valid start is known — rendered "-", never guessed.
+export function slotElapsedSeconds(row, runCreatedAt, now = Date.now()) {
+	const start = Date.parse(row?.started_at ?? runCreatedAt ?? "");
+	if (!Number.isFinite(start)) return null;
+	const finished = Date.parse(row?.finished?.at ?? "");
+	const end = Number.isFinite(finished) ? finished : now;
+	return Math.max(0, Math.round((end - start) / 1000));
+}
+
+export function formatDuration(seconds) {
+	if (seconds == null) return "-";
+	if (seconds < 60) return `${seconds}s`;
+	const m = Math.floor(seconds / 60);
+	if (m < 60) return `${m}m`;
+	return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+
+export function reconcileSlots(manifestSlots, agents, gitFacts, runCreatedAt = null, now = Date.now()) {
 	return (manifestSlots || []).map((row) => {
 		const facts = (gitFacts && gitFacts[row.slot]) || {};
 		let state;
@@ -108,6 +128,8 @@ export function reconcileSlots(manifestSlots, agents, gitFacts) {
 			agent_name: row.agent_name,
 			state,
 			finished: row.finished ?? null,
+			// Settled history (merged, skipped…) has no live clock to show.
+			elapsed: TERMINAL_STATUSES.has(row.status) && !row.finished ? null : slotElapsedSeconds(row, runCreatedAt, now),
 			committed: facts.committed ?? null,
 			uncommitted: facts.uncommitted ?? null,
 		};

bin/renderer-status.mjs

@@ -17,6 +17,7 @@ import {
 	parseDiffStat,
 	parseStatusPorcelain,
 	pollDelay,
+	formatDuration,
 } from "./renderer-shared.mjs";
 
 const pExecFile = promisify(execFile);
@@ -26,15 +27,15 @@ const pExecFile = promisify(execFile);
 // inverse+red — R5 says loud, and color alone is invisible on some themes,
 // so inverse carries the weight even without color support.
 export function renderStatus(rows, cols = 80) {
-	const head = ` ${pad("#", 3)}${pad("state", 9)}${pad("c/u", 8)}${pad("label", 14)}${pad("branch", 28)}path`;
+	const head = ` ${pad("#", 3)}${pad("state", 9)}${pad("time", 7)}${pad("c/u", 8)}${pad("label", 14)}${pad("branch", 28)}path`;
 	const lines = [head.slice(0, cols)];
 	if (rows.length === 0) lines.push("  (no slots in this run)");
 	for (const r of rows) {
 		const counts = `${r.committed ?? "-"}/${r.uncommitted ?? "-"}`;
 		// state comes from herdr's agent_status — externally controlled text on
 		// the same footing as a branch name, so it sanitizes like one.
 		const line =
-			` ${pad(r.slot, 3)}${pad(sanitizeText(r.state ?? ""), 9)}${pad(counts, 8)}${pad(
+			` ${pad(r.slot, 3)}${pad(sanitizeText(r.state ?? ""), 9)}${pad(formatDuration(r.elapsed ?? null), 7)}${pad(counts, 8)}${pad(
 				sanitizeText(r.label ?? ""),
 				14,
 			)}${pad(sanitizeText(r.branch ?? ""), 28)}${sanitizeText(r.path ?? "-")}`.slice(
@@ -247,7 +248,7 @@ export class Renderer {
 		m.slots.forEach((row, i) => {
 			gitFacts[row.slot] = factsList[i];
 		});
-		this.rows = sortSlots(reconcileSlots(m.slots, agents, gitFacts));
+		this.rows = sortSlots(reconcileSlots(m.slots, agents, gitFacts, m.created_at));
 		this.banner =
 			agents === null ? "agent list unavailable — states shown as unknown" : "";
 		this.paint();

docs/residual-review-findings/broadcast-2026-10-04.md

@@ -0,0 +1,58 @@
+# Residual review findings — broadcast and elapsed time, accepted 2026-10-04
+
+From an adversarial review of the uncommitted broadcast change: six
+findings, two high. The reviewer found no data or git risk, and found the
+elapsed-time change safe (no manifest validator rejects `started_at`; old
+manifests fall back to `created_at`). Fixed before commit:
+
+- **High — the message could reach a program other than the agent.** "Busy"
+  only meant "not the shell", so a `bash`, `less`, or `vim` started in a
+  finished slot's pane would receive it. A slot now receives it only when the
+  foreground group's *leader* is its recorded agent program, and slots
+  finished as `exited` are skipped. Mutation-checked: matching any group
+  member instead of the leader fails the test.
+- **High — keystrokes into an approval prompt.** A slot Herdr reports as
+  `blocked` is skipped (see residual 1).
+- **Duplicate targets typed twice.** They are now refused.
+- **Partial delivery reported as skipped.** It is now `broadcast_partial`,
+  told not to re-run, with a nonzero exit.
+- **The agent exiting between check and send.** The program is re-checked
+  between typing and Enter; Enter is withheld if it changed.
+- **A locale-dependent control-character filter.** Validation moved to Node
+  with explicit code points, plus a UTF-8 validity check; tested under `C` and
+  UTF-8.
+
+The items below were accepted as residual.
+
+## 1. Plugin-reported panes cannot show `blocked`
+
+On Herdr 0.7.5+ Swarm reports the slot's agent state itself, so an approval
+prompt reads as `working`. Broadcast can then type into the prompt. This is
+documented in the README.
+
+## 2. The check-then-act window is narrowed, not closed
+
+Four CLI calls are not atomic. With the Enter re-check, a lost race leaves
+unsubmitted text in the shell. That is inert until someone presses Enter.
+
+## 3. Herdr key syntax inside send-text is unverified
+
+The live probe covered a raw newline only. If `pane send-text` interprets
+key names inside text (`<Enter>`, `{Enter}`), a printable message could
+still inject keys.
+
+## 4. The terminal-id check assumes ids are never recycled
+
+Pane reuse is caught by comparing `terminal_id`. That is safe only if Herdr
+never reissues one; this is unverified.
+
+## 5. Broadcast holds the repo lock across its Herdr calls
+
+Up to about 6 calls per slot at 5 s each. Settle and harvest verbs wait
+behind it.
+
+## 6. Token usage and cost are not shown
+
+Herdr's pane `tokens` are display metadata, and nothing reports LLM usage
+to Herdr. Deferred by decision on 2026-10-03 until an agent actually reports
+usage.

scripts/compare.mjs

@@ -43,13 +43,23 @@ function validationFor(stateDir, runId, slot, tip) {
 	return { status: value.status, failed_checks: failed };
 }
 
-export function compareSlots({ repo, fork, runId, stateDir, rows }) {
-	const slots = rows.map(({ slot, label, branch, path: wt, status, finished }) => {
+// Seconds from a slot's start to its finish, or to now while it runs; null
+// when the start is unknown ("-" in the manifest).
+function elapsedSeconds(startedAt, finishedAt, now) {
+	const start = Date.parse(startedAt ?? "");
+	if (!Number.isFinite(start)) return null;
+	const end = Date.parse(finishedAt ?? "");
+	return Math.max(0, Math.round(((Number.isFinite(end) ? end : now) - start) / 1000));
+}
+
+export function compareSlots({ repo, fork, runId, stateDir, rows, now = Date.now() }) {
+	const slots = rows.map(({ slot, label, branch, path: wt, status, finished, startedAt, finishedAt }) => {
 		const tip = git(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`])?.trim() || null;
 		// files stays null when the diff could not be read: "no files" would be
 		// a false claim of zero overlap with every other slot.
 		const out = { slot, label, branch, status, finished: finished || null, tip, commits: null,
-			files: null, insertions: null, deletions: null, dirty: null, validation: { status: "none" } };
+			files: null, insertions: null, deletions: null, dirty: null, validation: { status: "none" },
+			elapsed_seconds: elapsedSeconds(startedAt, finishedAt, now) };
 		if (tip) {
 			const count = git(repo, ["rev-list", "--count", `${fork}..${tip}`]);
 			out.commits = count === null ? null : Number(count.trim());
@@ -111,8 +121,8 @@ function main() {
 	const [repo, fork, runId, stateDir] = process.argv.slice(2);
 	// Fields are \x1f-separated, like read_slot's: TAB is legal in a path.
 	const rows = fs.readFileSync(0, "utf8").split("\n").filter(Boolean).map((line) => {
-		const [slot, label, branch, wt, status, finished] = line.split("\x1f");
-		return { slot: Number(slot), label, branch, path: wt, status, finished };
+		const [slot, label, branch, wt, status, finished, startedAt, finishedAt] = line.split("\x1f");
+		return { slot: Number(slot), label, branch, path: wt, status, finished, startedAt, finishedAt };
 	});
 	const { slots, overlaps } = compareSlots({ repo, fork, runId, stateDir, rows });
 	for (const s of slots) {

scripts/fanout-pane.sh

@@ -201,15 +201,20 @@ parse_start_json() {
 }
 
 running_patch_json() {
-	# argv: name pane terminal ws → the row-running patch.
+	# argv: name pane terminal ws command → the row-running patch.
 	node -e '
-		const [an, pi, ti, w] = process.argv.slice(1);
+		const [an, pi, ti, w, cmd] = process.argv.slice(1);
 		process.stdout.write(JSON.stringify({
 			status: "running",
 			agent_name: an || null,
 			pane_id: pi || null,
 			terminal_id: ti || null,
 			workspace_id: w || null,
+			// The program the slot runs (basename of the preset argv[0]): broadcast
+			// types only into a pane whose foreground leader is this program.
+			agent_command: cmd ? require("path").basename(cmd) : null,
+			// Elapsed time per slot (status and compare views) counts from here.
+			started_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
 		}));
 	' "$@"
 }
@@ -762,7 +767,7 @@ for ((i = 1; i <= n; i++)); do
 	IFS=$'\t' read -r a_name a_pane a_term a_ws <<<"$sinfo"
 	# Row running with the ids the START returned (spike (k)): the agent's
 	# pane, not the worktree root pane recorded above.
-	rpatch="$(running_patch_json "$a_name" "$a_pane" "$a_term" "$a_ws")" || fatal 1 "herdr-swarm: internal error building the running patch."
+	rpatch="$(running_patch_json "$a_name" "$a_pane" "$a_term" "$a_ws" "${argv_arr[0]}")" || fatal 1 "herdr-swarm: internal error building the running patch."
 	manifest_update_slot "$i" "$rpatch" || fatal 1 "herdr-swarm: manifest write failed marking slot $i running — stopping."
 	started=$((started + 1))
 	echo "herdr-swarm: slot $i running — $branch -> $wt_path"