Skip to content

feat(herdr): name each spawned agent after its task - #1905

Open
ecloin wants to merge 1 commit into
kunchenguid:mainfrom
ecloin:fm/herdr-agent-names
Open

feat(herdr): name each spawned agent after its task#1905
ecloin wants to merge 1 commit into
kunchenguid:mainfrom
ecloin:fm/herdr-agent-names

Conversation

@ecloin

@ecloin ecloin commented Aug 7, 2026

Copy link
Copy Markdown

Problem

Herdr's agents sidebar lists each agent by the agent record's own name field, which is separate from the fm-<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.sh gains fm_backend_herdr_agent_name (kind + task id to name) and fm_backend_herdr_name_agent_best_effort (the rename itself, through the existing session-scoped fm_backend_herdr_cli).
  • bin/fm-spawn.sh calls 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 through fm_backend_herdr_list_live.

That contract is ours to keep rather than Herdr's to enforce: herdr agent --help states 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.sh well before the local launch section, and the remote host's own fm-spawn.sh run 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:

  • the two name forms (worker and secondmate);
  • one session-scoped rename of the task's exact pane when the agent is already registered;
  • retry past a not-yet-registered agent, stopping on first success;
  • a never-landing rename giving up silently inside its attempt budget;
  • no rename at all for an unparseable target or an empty name;
  • two cases driving the real bin/fm-spawn.sh against a purpose-built fake CLI (make_herdr_spawnfake): one asserting the spawn names its agent fm-<task-id> on the pane it just launched, one asserting a rename that never lands is bounded and still reports a successful spawn.

Verification

bash tests/fm-backend-herdr.test.sh      # 179 ok, 0 failures
bin/fm-lint.sh                           # ShellCheck 0.11.0 (pinned 0.11.0), rc=0
bin/fm-doc-audience-check.sh             # ok surfaces=65 local_links=205
bin/fm-test-run.sh --changed --base main # total=51 failed=2 skipped_gate=3

Both --changed failures were confirmed to reproduce unchanged on the base commit 345de4e and are environmental, not from this change:

  • tests/fm-backend.test.sh - teardown refused with fm-decision-hold: compatible tasks-axi is required; no compatible tasks-axi in 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.md gains one CLI-matrix row for the rename shape.
The availability half was checked directly here with a read-only probe on the installed client:

herdr --version          # herdr 0.7.4
herdr agent --help       # lists: herdr agent rename <target> <name>|--clear

The behavioral half of that row - that a 0.8.x rename sets the record's name, which then appears in herdr agent list and 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.

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