Repository navigation
feat: show launch model and effort in Herdr pane labels - #320
Merged
Merged
Conversation
- Every Herdr worker pane now carries a display-only label with the model it was launched with, so the captain can read a pane's model and effort at a glance. - bin/backends/herdr.sh owns the label: fm_backend_herdr_agent_display_label composes "<harness> · <model> <effort>" from the values fm-spawn.sh records in task metadata (unset sentinels omitted, no effort without a model), and fm_backend_herdr_report_agent_label publishes it with `pane report-metadata --source firstmate --display-agent`. - bin/fm-spawn.sh reports it once, immediately after the launch lands in the pane - the convergence point shared by a fresh spawn, a relaunch into a retained idle shell, and a relaunch that recreates a proven-absent pane. Raw launch commands are skipped: they have no verified adapter identity and no model flag. - Best effort by contract: a failing or unsupported call prints one warning with the CLI's own reason and returns success, and support is detected from the CLI's own refusal rather than a version string. Workspace and tab labels keep the `fm-<id>` identity grammar untouched, so tmux, zellij, cmux, and orca are unaffected. - Live evidence on herdr 0.9.5 protocol 22 in guarded lab sessions: a production spawn reported `claude · deepseek-v4.1-flash high` from meta harness/model/effort, survived 20s of work and agent Ctrl-C, a closed pane lost the label, and `--relaunch` re-reported it onto the replacement pane. Agent lifecycle reports never rewrite it; another source's display_agent does (last writer wins); `--clear-display-agent` is source-scoped. - Tests: tests/fm-backend-herdr.test.sh covers composition and the never-fail publish through the real CLI stub; tests/fm-spawn-relaunch-dead-endpoint.test.sh covers the relaunch re-report and a spawn that survives an unsupported CLI with exactly one warning. The opt-in OMP Herdr role matrix now asserts the label for worker, scout, secondmate, and the respawned secondmate pane; that matrix currently fails earlier on its OMP primary extension marker (installed OMP 18.20.3 vs the recorded 18.0.4 run), so those assertions are unverified until that drift is fixed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Herdr panes get a display-only label carrying the model they were launched with, so a captain can read a pane's model and effort without opening it.
Composition omits unset parts (
default,-, empty), so a launch with no model shows the harness alone and one with no effort shows<harness> · <model>.Publication is detached and bounded: it never fails the spawn, never holds the caller's captured output open, and a failure or an expired two-second bound costs exactly one warning in the owning home's
state/herdr-agent-label.log.Because publication is detached, spawn success does not confirm it by construction; live on the shipped head the label was already present at the first read after the spawn returned.
Evidence
herdr pane get <pane>->{"display_agent":null}, so the pane list shows no model.After: a production spawn whose metadata records
harness=claude model=deepseek-v4.1-flash effort=highreads back{"display_agent":"claude · deepseek-v4.1-flash high"}.pane_not_found);fm-spawn --relaunchrecreates the pane and re-publishes the label on the replacement. The label also survives the agent process exiting.workspace list->{"workspace_id":"w2","label":"firstmate"},tab list->{"tab_id":"w2:t2","label":"fm-label-live-worker"}.bin/fm-herdr-lab.shsessions with the default-session tripwire intact, summarized indocs/verification/runtime-backends.md; raw artifact in the task record.tests/fm-backend-herdr.test.sh(composition, publish contract, one-warning failure, hung CLI releasing combined-output capture and its descendant, no call when nothing is composable) andtests/fm-spawn-relaunch-dead-endpoint.test.sh(relaunch re-publish, raw-launch label, spawn surviving an unsupported CLI).Merge Danger
Door: two-way. The label is display-only pane metadata; reverting drops it and Herdr falls back to its default agent display. It carries no task identity, placement, or cleanup authority.
Blast Radius: Herdr panes only. tmux, zellij, cmux, and orca keep the identity-bearing window, tab, workspace, or terminal title that their placement and recovery already match on.
Intent
On the Herdr runtime backend, every worker pane must show the model and effort it was launched with, so the captain can see at a glance which model each pane runs.
Mechanism (already proven by hand on a live Herdr worker pane):
herdr pane report-metadata <pane_id> --source firstmate --display-agent '<harness> · <model> <effort>'sets.result.pane.display_agent, readable withherdr pane get <pane_id>. It changes only the pane's displayed agent label. It must never touch workspace or tab labels, which bin/backends/herdr.sh uses for task identity (└ <task> · p:<token>grammar) and which must stay byte-identical.Required change:
<harness> · <model> <effort>from the concrete launch values fm-spawn.sh already records in the task metadata.<harness>; no effort -><harness> · <model>.Non-goals: changing workspace or tab labels; live model tracking after an in-session /model switch; any non-Herdr backend.
Acceptance criteria:
<harness> · <model> <effort>from its recorded launch values, proven live in the named lab session withherdr ... pane getoutput.Herdr isolation hard safety contract: on the installed Herdr the API socket is not relocatable by HERDR_CONFIG_PATH, XDG_CONFIG_HOME, or HOME. A named non-default session plus a trailing
--session <name>on every call is the only viable local isolation. Provision, drive, and tear down only through bin/fm-herdr-lab.sh with a generatedfm-lab-session; never run a directherdr server stop,herdr session stop,herdr session delete, or any server-global operation; never scope a call only by ambient or inline HERDR_SESSION; the helper's default-session tripwire must stay intact. The captain's fleet uses the running default session.Pipeline
Updates from git push no-mistakes
✅ **Intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 2 issues found → auto-fixed (2) ✅
bin/backends/herdr.sh:2482- The requirement says a metadata failure must “never fail or delay the spawn,” buterr=$(fm_backend_herdr_cli ...)waits synchronously with no deadline. If Herdr stops responding after accepting the launch, spawn completion stalls before releasing the presentation lock or checking OMP readiness. The shared CLI wrapper adds no timeout. Correct this at the reporting boundary so publication cannot hold up launch completion. Related changed sites: bin/fm-spawn.sh:5655 invokes it synchronously; bin/fm-spawn.sh:5659 releases the presentation lock only afterward; docs/herdr-backend.md:212 promises continued spawning. This contradicts an explicit acceptance constraint.bin/fm-spawn.sh:5654- The new&& [ "$RAW_LAUNCH" -eq 0 ]exclusion exceeds the stated scope: the intent requires labels “after a successful Herdr spawn of a crewmate or scout” and specifies “no model -> <harness>.” An accepted raw launch such ascustom-agent --flagrecords harness=custom-agent and model=default, yet this branch publishes no label. Raw launches already establish their executable identity in HARNESS. Remove this exclusion and publish the recorded harness when no model exists. Related changed sites: bin/fm-spawn.sh:5650 explains the exclusion; docs/herdr-backend.md:204 explicitly documents it. No intent requirement needs this additional exception.🔧 Fix applied.
2 errors still open:
bin/backends/herdr.sh:2482- The requirement says a metadata failure must “never fail or delay the spawn,” buterr=$(fm_backend_herdr_cli ...)waits synchronously with no deadline. If Herdr stops responding after accepting the launch, spawn completion stalls before releasing the presentation lock or checking OMP readiness. The shared CLI wrapper adds no timeout. Correct this at the reporting boundary so publication cannot hold up launch completion. Related changed sites: bin/fm-spawn.sh:5655 invokes it synchronously; bin/fm-spawn.sh:5659 releases the presentation lock only afterward; docs/herdr-backend.md:212 promises continued spawning. This contradicts an explicit acceptance constraint.bin/backends/herdr.sh:2475- Round 1's fix moves the delay to output collection: the background Python process redirects stdout but inherits stderr. When spawning through combined-output capture, as tests/fm-spawn-relaunch-dead-endpoint.test.sh:801 does, a hung report-metadata keeps that pipe open until the two-second timeout, even after fm-spawn exits. This still contradicts “must never fail or delay the spawn.” Detach publication diagnostics from the caller's captured descriptors while preserving the warning contract. Related changed sites: bin/fm-spawn.sh:5647 invokes publication; tests/fm-backend-herdr.test.sh:489 redirects stderr to a regular file and therefore misses this failure; docs/herdr-backend.md:212 claims publication never delays completion.🔧 Fix applied.
✅ Re-checked - no issues remain.
🔧 **Test** - 2 issues found → auto-fixed ✅
bin/backends/herdr.sh:2472- Metadata publication still delays spawning. Against real fm-spawn and an isolated Herdr server, an injected hung report-metadata call held spawn completion for 1.995 seconds. The synchronous fm_run_timed call bounds the delay but contradicts the explicit requirement that publication never delay spawning. Move publication off the spawn completion path while preserving one warning and proper child cleanup.bash tests/fm-backend-herdr.test.sh— passed.bash tests/fm-spawn-relaunch-dead-endpoint.test.sh— passed.Executed.validation-tmp/live-driver.pyinside bwrap against named Herdr labs throughbin/fm-herdr-lab.sh.Executed.validation-tmp/optional-driver.pyfor raw-launch labels, omitted parts, and unchanged workspace/tab labels.Checkedpane --helpfor visual capture support; the headless CLI exposes no screenshot command.Awaited both live drivers, verified successful lab teardown, checked for surviving test processes, and removed disposable worktree files.🔧 Fix applied.
✅ Re-checked - no issues remain.
TMPDIR="$PWD/.test-label/tmp" bash tests/fm-backend-herdr.test.shTMPDIR="$PWD/.test-label/tmp" bash tests/fm-spawn-relaunch-dead-endpoint.test.sh— initial race reproduced; repaired rerun passedExecuted disposable Python drivers through bubblewrap, real fm-spawn and bin/fm-herdr-lab.shCaptured the real Herdr TUI through a 145×38 PTY and rendered its terminal frameConfirmed guarded teardown succeeded, default-session tripwire stayed unchanged, and disposable files and processes were removed✅ **Document** - passed
✅ No issues found.
🔧 **Lint** - 1 issue found → auto-fixed ✅
🔧 Fix applied.
✅ Re-checked - no issues remain.
✅ **Push** - passed
✅ No issues found.