Skip to content

feat: show launch model and effort in Herdr pane labels - #320

Merged
dnth merged 7 commits into
mainfrom
fm/fm-herdr-model-label
Nov 17, 2026
Merged

dnth merged 7 commits into
mainfrom
fm/fm-herdr-model-label

Conversation

@dnth

@dnth dnth commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

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.

 bin/backends/herdr.sh
+fm_backend_herdr_agent_display_label()   # "<harness> · <model> <effort>" from the recorded launch values
+fm_backend_herdr_report_agent_label()    # detached publish: pane report-metadata --source firstmate
+fm_backend_herdr_publish_agent_label()   # bounded worker, warns once into state/herdr-agent-label.log
 bin/fm-spawn.sh
 launch lands in the pane
+  └─ queue the display label once   # fresh spawn, retained-shell relaunch, recreated pane, raw launch
   release the presentation lock
   wait for OMP readiness

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

  • Before: a firstmate-launched Herdr pane reads 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=high reads back {"display_agent":"claude · deepseek-v4.1-flash high"}.
  • Recovery: closing the pane drops it (pane_not_found); fm-spawn --relaunch recreates the pane and re-publishes the label on the replacement. The label also survives the agent process exiting.
  • Identity untouched: live workspace list -> {"workspace_id":"w2","label":"firstmate"}, tab list -> {"tab_id":"w2:t2","label":"fm-label-live-worker"}.
  • Live evidence on herdr 0.9.5 protocol 22 in bin/fm-herdr-lab.sh sessions with the default-session tripwire intact, summarized in docs/verification/runtime-backends.md; raw artifact in the task record.
  • Deterministic coverage: 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) and tests/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 with herdr 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:

  • After a successful Herdr spawn of a crewmate or scout, and on every relaunch/resume path that recreates or re-attaches the agent in a pane, report the display-agent label <harness> · <model> <effort> from the concrete launch values fm-spawn.sh already records in the task metadata.
  • Omit missing parts cleanly: no model -> <harness>; no effort -> <harness> · <model>.
  • Keep the behavior in the Herdr backend so tmux, zellij, cmux, and orca are unaffected, and state for each why it is not applicable.
  • Best effort: a failing or unsupported report-metadata call must never fail or delay the spawn; log one concise warning and continue. Detect support from the installed CLI's behavior, not a version-string guess.
  • Decide and document whether persistent second-mate panes get the same label (recommended yes when the same launch path applies).
  • Verify empirically whether Herdr clears display_agent when the agent process exits or is replaced, and whether a different --source or the OMP integration's own reports overwrite it; the relaunch path must re-report so the label converges.
  • Record the findings in docs/herdr-backend.md (one sentence per line) and dated live evidence in docs/verification/runtime-backends.md.
  • Extend the existing Herdr backend tests under tests/ to cover label composition and the never-fail-the-spawn behavior through a public interface (a stub herdr on PATH is fine for the composition and failure cases); live verification only inside the named lab session.

Non-goals: changing workspace or tab labels; live model tracking after an in-session /model switch; any non-Herdr backend.

Acceptance criteria:

  • AC1: A Herdr-launched crewmate pane reports display_agent equal to <harness> · <model> <effort> from its recorded launch values, proven live in the named lab session with herdr ... pane get output.
  • AC2: The relaunch/resume path re-reports the label, and the documented behavior on agent exit/replacement is backed by live lab evidence.
  • AC3: A failing or unsupported report-metadata call leaves the spawn successful with one warning, proven by a test.
  • AC4: Workspace and tab labels and all non-Herdr backends are unchanged, shown by existing tests passing and the diff.
  • AC5: docs/herdr-backend.md and docs/verification/runtime-backends.md describe the label and its limits; bin/fm-lint.sh and the touched test files pass.

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 generated fm-lab- session; never run a direct herdr 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,” but err=$(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 &amp;&amp; [ &#34;$RAW_LAUNCH&#34; -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 as custom-agent --flag records 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,” but err=$(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.
  • 🚨 live validation verdict: no-go (5 of 5 scenarios were driven live against the product); failed: An injected hung metadata command must not delay local spawn completion
  • Live validation: ❌ no-go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Local worker and scout launches through endpoint recovery publish their recorded model and effort ✅ pass live live-product.log
Relaunch restores the label after another source overwrites it and after the pane is replaced ✅ pass live live-product.log
Raw launches and missing profile parts produce clean labels without changing workspace or tab labels ✅ pass live live-omission-and-identity.log
An injected unsupported metadata command leaves the local spawn successful with one publication warning ✅ pass live live-product.log
An injected hung metadata command must not delay local spawn completion ❌ fail live publication-delay.json
  • bash tests/fm-backend-herdr.test.sh — passed.
  • bash tests/fm-spawn-relaunch-dead-endpoint.test.sh — passed.
  • Executed .validation-tmp/live-driver.py inside bwrap against named Herdr labs through bin/fm-herdr-lab.sh.
  • Executed .validation-tmp/optional-driver.py for raw-launch labels, omitted parts, and unchanged workspace/tab labels.
  • Checked pane --help for 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.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
A local Herdr worker launched with synthetic model and effort reports the recorded display label ✅ pass live live-core.log: recorded metadata and pane get
Missing model or effort is omitted cleanly while workspace and tab identities remain byte-identical ✅ pass live live-core.log: omission labels and before/after workspace and tab responses
Another source overwrites the label, firstmate restores it, and OMP lifecycle reports preserve it ✅ pass live live-core.log: competing metadata and OMP lifecycle reports
After foreground exit or pane replacement, relaunch restores the recorded launch label ✅ pass live live-core.log: retained-shell and replacement relaunch results
Unsupported or hung metadata publication leaves local spawn successful without awaiting publication ✅ pass live fault-driver-output.log: successful spawns, single warnings and publication timing
  • TMPDIR="$PWD/.test-label/tmp" bash tests/fm-backend-herdr.test.sh
  • TMPDIR=&#34;$PWD/.test-label/tmp&#34; bash tests/fm-spawn-relaunch-dead-endpoint.test.sh — initial race reproduced; repaired rerun passed
  • Executed disposable Python drivers through bubblewrap, real fm-spawn and bin/fm-herdr-lab.sh
  • Captured the real Herdr TUI through a 145×38 PTY and rendered its terminal frame
  • Confirmed 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 ✅
  • ⚠️ linter found issues (exit code 1)

🔧 Fix applied.
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.

dnth added 7 commits November 17, 2026 15:42
- 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.
@dnth
dnth merged commit dd9993d into main Nov 17, 2026
21 checks passed
@dnth
dnth deleted the fm/fm-herdr-model-label branch November 17, 2026 09:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant