feat(herdr): name each spawned agent after its task - #1905
Open
ecloin wants to merge 1 commit into
Open
Conversation
Herdr's agents sidebar lists agents by the agent record's own name field, which is separate from the fm-<id> tab label, so every firstmate worker read as the same anonymous entry there. After the launch key lands, a herdr spawn now issues a bounded best-effort `agent rename <pane> fm-<task-id>` (2ndmate-<id> for a secondmate, matching the home workspace label form). The name is presentation only: it never gates the spawn, retries are bounded and silent, and no code path reads it back for identity, lookup, or targeting - Herdr would accept a unique agent name as a selector, so the adapter keeps addressing recorded pane ids.
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.
Problem
Herdr's agents sidebar lists each agent by the agent record's own
namefield, which is separate from thefm-<id>tab label.Firstmate never set it, so every worker in the fleet read as the same anonymous entry there.
Change
After the launch key lands, a herdr spawn issues a bounded best-effort
herdr agent rename <pane> fm-<task-id>.A secondmate is named
2ndmate-<id>, matching the form its home workspace label already uses rather than inventing a second convention.bin/backends/herdr.shgainsfm_backend_herdr_agent_name(kind + task id to name) andfm_backend_herdr_name_agent_best_effort(the rename itself, through the existing session-scopedfm_backend_herdr_cli).bin/fm-spawn.shcalls it once, guarded on the herdr backend, after the launch key and every delivery confirmation.The retry loop exists because the agent record only appears once the harness registers itself, measured at 90-490ms after Enter for real claude and codex.
A rename fired the instant Enter lands can legitimately lose that race.
A successful rename is itself proof the agent had registered, so no separate presence probe is needed.
The loop is bounded at 5 attempts 0.4s apart, stays silent on failure, and always returns 0, so a spawn can neither fail nor stall past that window over a cosmetic name.
Presentation only
The name never authorizes lookup, adoption, reuse, closure, task ownership, or endpoint selection, and no code path reads it back for control flow.
Recovery and orphan discovery keep matching
fm-<id>TAB labels throughfm_backend_herdr_list_live.That contract is ours to keep rather than Herdr's to enforce:
herdr agent --helpstates a target may be "a unique agent name", so Herdr itself would resolve one of these names as a selector, and two homes running the same task id would make that selector ambiguous.Every adapter call therefore keeps addressing the exact recorded pane id.
Remote secondmates
A remote secondmate route returns from
fm-spawn.shwell before the local launch section, and the remote host's ownfm-spawn.shrun performs the rename through its own local session-scoped CLI.No new remote plumbing was added for a cosmetic name.
Tests
Eight new cases in
tests/fm-backend-herdr.test.sh, following the existing fake-herdr-CLI patterns:bin/fm-spawn.shagainst a purpose-built fake CLI (make_herdr_spawnfake): one asserting the spawn names its agentfm-<task-id>on the pane it just launched, one asserting a rename that never lands is bounded and still reports a successful spawn.Verification
Both
--changedfailures were confirmed to reproduce unchanged on the base commit345de4eand are environmental, not from this change:tests/fm-backend.test.sh- teardown refused withfm-decision-hold: compatible tasks-axi is required; no compatibletasks-axiin this environment.tests/fm-backend-herdr-presentation-e2e.test.sh-error: treehouse get did not enter a worktree within 60s, a worktree-acquisition timeout under a contended pool.The real-Herdr presentation e2e therefore has not been proven green locally in either direction and is worth a clean CI run before merge.
Verification record
docs/verification/runtime-backends.mdgains one CLI-matrix row for the rename shape.The availability half was checked directly here with a read-only probe on the installed client:
The behavioral half of that row - that a 0.8.x rename sets the record's
name, which then appears inherdr agent listand in the sidebar - comes from a live session observation supplied with the task, not from a run in this branch.No live rename was issued here, because that would have mutated real agent records outside a lab session.