docs: explain why Herdr's Agents pane omits tmux-backed workers

[MrGTV-love]

Intent

The captain, 2026-09-27, verbatim: "herdr is not showing firstmate crewmates in the agents pane as it is supposed to. this is important because it is the only way the user can observe firstmate's secondmates and crewmates' activity. I do not know why we do not see the agents by default." Then: "please get started with herdr investigation and fix."

Context the captain shared, from another agent not connected to this codebase (unverified; it said it did not diagnose directly): his tmux list-windows -t firstmate lists every second mate and worker as a tmux window; Herdr shows only his primary Claude pane and a diagnostic shell; that agent concluded Herdr's Agents pane tracks only Herdr-owned panes, so tmux-backed workers never appear, and suggested --backend herdr or config/backend.

Firstmate's read-only facts at filing: this home has no config/backend and no lane home has one; the main firstmate session's environment has no HERDR_* variables, so backend auto-detection falls through to tmux; every live second mate and worker records a tmux endpoint (window=firstmate:fm-). On 2026-09-21 a spawn refused on herdr because the session's inherited HERDR_ named a closed Herdr workspace ("launcher pane could not be read"), and the fleet was then spawned with --backend tmux on purpose.

What Changed

• Adds a "Missing agents" section to docs/herdr-backend.md. It explains that Herdr's Agents pane lists only agents detected in Herdr terminal panes, so tmux-backed tasks do not appear there. It tells you to check the task's recorded backend first. It covers what backend auto-detection needs (HERDR_ENV=1 on the spawning Firstmate process), how to set config/backend=herdr for a home, the rule against faking or clearing a launcher identity, and the agent list / agent get / agent explain checks for tasks already on Herdr.
• Adds a "Moving an existing tmux fleet" section. It says a backend change affects only new spawns. It says relaunch keeps the recorded backend and cannot convert tmux endpoints to Herdr. It describes a gradual transition: select Herdr for new work and let existing tmux workers finish.
• Adds text to "Firstmate running outside Herdr". With no HERDR_SESSION, operations go to the default session and a home-labeled parent workspace. It also links back to the launcher-identity rule. Adds a quick-reference row that points to the new "Missing agents" section.

Risk Assessment

✅ Low: Documentation-only change whose round-2 fix correctly restores the 'for that reason' referent, keeps a single launcher-identity rule plus link, and whose new anchors and technical claims (HERDR_ENV detection, default session fallback, selection order) are verified against source.

Testing

The local command bash bin/fm-test-run.sh tests/fm-backend.test.sh fails at zsh: fm_backend_source herdr should load the adapter when sourced. It fails identically on a clean detached copy of freshly fetched origin/main at 050a44643af4f7c9b7a20b1bf165d4834d064c1b (exit 1 after the same passing selection cases). This documentation-only change does not fix that pre-existing failure.

This is a docs-only change with no runtime product surface, so the verdict is no-surface. As a non-live check, I ran the real backend picker code in a disposable lab home. It confirmed each backend-selection claim in the new doc text: without markers the backend is tmux, HERDR_ENV=1 selects herdr, a nested TMUX marker wins over HERDR_ENV, config/backend=herdr selects herdr even outside Herdr, FM_BACKEND overrides config/backend, the session is 'default' when HERDR_SESSION is not set, and a legacy meta with no backend= line means tmux. All new anchor links resolve. I removed the lab afterwards, and the worktree is clean.

• Live validation: ⚠️ no-surface - 0 of 5 scenarios driven live against the product

Scenario	Result	Live	Evidence
Operator reads the new 'Missing agents' section and learns why tmux-backed crewmates are not in Herdr's Agents pane	⏸️ untested	no	Docs-only change. There is no runtime surface to drive live. A human must judge the prose. The non-live code cross-check in backend-selection-doc-claims.txt agrees with the doc (a legacy meta with no…
Operator follows the doc, sets config/backend=herdr, and new spawns resolve to herdr even when Firstmate runs outside Herdr	⏸️ untested	no	The change does not modify spawn behavior, so there is no new product surface to validate live. The existing selector code was run in a throwaway lab home, which is not live, and it gave herdr as the…
Adversarial: a nested TMUX marker or an FM_BACKEND override beats Herdr detection or config/backend, as the doc warns	⏸️ untested	no	Docs-only change. The selector code confirms the warning (TMUX+HERDR_ENV gives tmux, and FM_BACKEND=tmux overrides config/backend=herdr). This was a non-live library call, not a driven product scenari…
With no HERDR_SESSION, Herdr operations target the 'default' session (new 'Firstmate running outside Herdr' note)	⏸️ untested	no	Docs-only change. fm_backend_herdr_session gave 'default' in the lab home. No live Herdr session was driven, because the change alters no Herdr behavior.
New in-doc links (Missing agents, selection order, relaunch, launcher identity, agent-status authority) resolve to real headings	⏸️ untested	no	A static doc check is not a live product surface. All 8 targets exist.

Evidence: Backend-selection doc-claim cross-check (real fm-backend.sh, throwaway lab home)

Source: Backend-selection doc-claim cross-check (real fm-backend.sh, throwaway lab home)

## Doc-claim cross-check against real bin/fm-backend.sh (isolated FM_HOME=lab)
1. no config/backend, no HERDR_ENV, no TMUX:
backend=tmux herdr_session=default
2. no config/backend, TMUX set (Firstmate inside tmux):
backend=tmux herdr_session=default
3. no config/backend, HERDR_ENV=1:
backend=herdr herdr_session=default
4. TMUX + HERDR_ENV=1 (nested tmux marker wins):
backend=tmux herdr_session=default
5. config/backend=herdr, no HERDR_* (Firstmate outside Herdr):
backend=herdr herdr_session=default
6. config/backend=herdr, TMUX set:
backend=herdr herdr_session=default
7. config/backend=herdr, FM_BACKEND=tmux override:
backend=tmux herdr_session=default
8. legacy meta with no backend= line:
fm_backend_of_meta=tmux

- Outcome: ⚠️ 1 warning across 1 run (2m26s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 3 issues found → auto-fixed (2) ✅

• ⚠️ docs/herdr-backend.md:130 - The new guidance on secondmates is incomplete, and it leads the reader to a setting that the system will undo. Line 128 says to set 'its local config/backend', and line 130 says a secondmate's spawns resolve against 'that secondmate's own home'. But config/backend is an inherited item that the primary controls (.agents/skills/secondmate-provisioning/SKILL.md lines 115-116; bin/fm-config-inherit-lib.sh). 'A present primary value always converges byte-exact into validated secondmate homes, and primary absence removes the destination.' This home has no primary config/backend today. So if someone writes config/backend=herdr directly into a secondmate home, the next bootstrap sweep or fm-config-push puts that copy in quarantine and removes it. The secondmate's crewmates then go back to tmux, which is the exact problem the captain reported. Fix: say that the primary home's config/backend decides the default for secondmates. For secondmates that are already running, tell the reader to push the change with bin/fm-config-push.sh, which delivers the config reread. Also say not to edit the secondmate home's copy.
• ⚠️ docs/herdr-backend.md:115 - Intent check. The captain asked: 'please get started with herdr investigation and fix.' The change only adds documentation. It changes no code and no config. The captain's reported problem, 'herdr is not showing firstmate crewmates in the agents pane', stays the same after merge. The new section says why: every live worker and secondmate records a tmux endpoint, and 'relaunch ... cannot convert a tmux endpoint into a Herdr endpoint' (line 142). The only fix it offers is operational: an operator creates the gitignored primary config/backend=herdr, and only new spawns are affected. The captain must decide if this is enough. There are three options: (a) accept docs plus a manual config/backend change, and let the current tmux fleet finish while it stays invisible; (b) also authorize a backend migration path for live workers and secondmates, which is new machinery and outside this change; (c) accept some other visibility mechanism. The remedy needs the captain's approval. The docs themselves are not the defect.
• ⚠️ docs/herdr-backend.md:188 - Simplification: lines 188-189 ('Having no launcher identity is different from claiming a stale one. Explicit backend selection does not bypass the launcher-identity checks...') say the same rule as lines 132-133 in the new 'Missing agents' section ('Do not fabricate a launcher identity... the unresolvable-identity refusal remains in force even when Herdr is explicitly selected'). The intent does not need the rule written twice. Keep one copy, or replace the second copy with a link.

🔧 Fix applied.
1 warning still open:

• ⚠️ docs/herdr-backend.md:188 - The fix round put the new line 'A process that carries a stale pane identity still follows the launcher-identity rule.' between 'Two workspaces sharing it are an unresolvable placement and refuse rather than adopting either.' (line 186) and 'Avoid naming a personal workspace firstmate or 2ndmate-<id> for that reason.' (line 190). In the base file (050a446), 'for that reason' pointed to the duplicate-label refusal. It now points to the stale-pane-identity sentence. So the doc now says the wrong reason for not naming a workspace firstmate. Fix: move the one-line link so it does not split the paragraphs. Put it after the 'Also avoid it because...' paragraph (line 191), or before 'That path needs the home label...' (line 185). Keep the text of the link line the same, as the firstmate asked. The content does not change.

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

⚠️ **Test** - 1 warning

• ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 5 scenarios were driven live against the product); Operator reads the new 'Missing agents' section and learns why tmux-backed crewmates are not in Herdr's Agents pane: Docs-only change. There is no runtime surface to drive live. A human must judge the prose. The non-live code cross-check in backend-selection-doc-claims.txt agrees with the doc (a legacy meta with no backend= reads as tmux).; Operator follows the doc, sets config/backend=herdr, and new spawns resolve to herdr even when Firstmate runs outside Herdr: The change does not modify spawn behavior, so there is no new product surface to validate live. The existing selector code was run in a throwaway lab home, which is not live, and it gave herdr as the doc claims. A full Herdr lab spawn would test old behavior only. It needs bin/fm-herdr-lab.sh with a named fm-lab-* session if a human wants that proof.; Adversarial: a nested TMUX marker or an FM_BACKEND override beats Herdr detection or config/backend, as the doc warns: Docs-only change. The selector code confirms the warning (TMUX+HERDR_ENV gives tmux, and FM_BACKEND=tmux overrides config/backend=herdr). This was a non-live library call, not a driven product scenario.; With no HERDR_SESSION, Herdr operations target the 'default' session (new 'Firstmate running outside Herdr' note): Docs-only change. fm_backend_herdr_session gave 'default' in the lab home. No live Herdr session was driven, because the change alters no Herdr behavior.; New in-doc links (Missing agents, selection order, relaunch, launcher identity, agent-status authority) resolve to real headings: A static doc check is not a live product surface. All 8 targets exist.
• Live validation: ⚠️ no-surface - 0 of 5 scenarios driven live against the product

Scenario	Result	Live	Evidence
Operator reads the new 'Missing agents' section and learns why tmux-backed crewmates are not in Herdr's Agents pane	⏸️ untested	no	Docs-only change. There is no runtime surface to drive live. A human must judge the prose. The non-live code cross-check in backend-selection-doc-claims.txt agrees with the doc (a legacy meta with no…
Operator follows the doc, sets config/backend=herdr, and new spawns resolve to herdr even when Firstmate runs outside Herdr	⏸️ untested	no	The change does not modify spawn behavior, so there is no new product surface to validate live. The existing selector code was run in a throwaway lab home, which is not live, and it gave herdr as the…
Adversarial: a nested TMUX marker or an FM_BACKEND override beats Herdr detection or config/backend, as the doc warns	⏸️ untested	no	Docs-only change. The selector code confirms the warning (TMUX+HERDR_ENV gives tmux, and FM_BACKEND=tmux overrides config/backend=herdr). This was a non-live library call, not a driven product scenari…
With no HERDR_SESSION, Herdr operations target the 'default' session (new 'Firstmate running outside Herdr' note)	⏸️ untested	no	Docs-only change. fm_backend_herdr_session gave 'default' in the lab home. No live Herdr session was driven, because the change alters no Herdr behavior.
New in-doc links (Missing agents, selection order, relaunch, launcher identity, agent-status authority) resolve to real headings	⏸️ untested	no	A static doc check is not a live product surface. All 8 targets exist.

• git diff 050a446 83e3c80 confirms that only docs/herdr-backend.md changed (40 added lines)
• Checked that every new link target heading exists: configuration.md#runtime-backend-configbackend--fm_backend, configuration.md#backend-selection-order, agent-control.md#transactional-relaunch, herdr-backend.md#unresolvable-launcher-identity, #agent-status-authority-and-relaunch, #firstmate-running-outside-herdr, #presentation-spaces, #missing-agents
• Created a throwaway lab home with bin/fm-lab-home.sh create $LAB, ran fm_backend_name, fm_backend_herdr_session and fm_backend_of_meta from bin/fm-backend.sh and bin/backends/herdr.sh under 8 environment/config combinations, then ran rm -rf $LAB
• Read the Transactional relaunch section of docs/agent-control.md to check the claim that relaunch keeps the recorded worktree and endpoint

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.