fix(ansible): install Herdr's omp state integration on every apply

[undeemed]

Intent

dot not updating its tatus despite secondmate working

Context: the dot is the state icon on each entry of the Herdr sidebar on the fleet host. Every dot stayed hollow (idle) while a second mate was visibly working. Cause, measured: herdr integration status reported omp: not installed (~/.omp/agent/extensions/herdr-omp-agent-state.ts), and herdr agent explain <pane> for an omp pane reported manifest: none, fallback_reason: default_known_agent_idle_fallback. So Herdr had no state reporting from omp and showed every omp agent as idle. Running herdr integration install omp installed the extension (status then omp: current (v10)). Code-Factory's docs/agent-host-move.md names that command as a manual host-move step, but no Code-Factory apply runs it, so every host built or moved with Code-Factory comes up with idle-forever dots. Generic host setup on this host must be reproduced by Code-Factory on every run.

im using herdr --remote, so i need to update my macbooks herdr too

What Changed

• ansible/tasks/herdr.yml and ansible/group_vars/all.yml: with the agents profile on, apply now creates the omp extensions directory and runs herdr integration install omp. This installs herdr-omp-agent-state.ts, so Herdr gets pane state from omp instead of showing every omp agent as idle. Apply reports a change only when the file's checksum changes, and the install is skipped in check mode.
• ansible/tasks/verify.yml: verification now reads herdr integration status and fails unless it reports omp: current.
• docs/herdr.md and docs/agent-host-move.md: added a "Pane state" section. The host-move step no longer tells you to run the install by hand and now excludes herdr-omp-agent-state.ts from the omp extensions rsync. For machines that view a host with herdr --remote, the docs say to run herdr update and compare herdr --version with the host's.

Risk Assessment

⚠️ Medium: The install path correctly reproduces herdr integration install omp on every apply and the docs match, but the new verify task can fail spuriously when the connecting user is not the target account.

Testing

I drove the changed Ansible tasks with real ansible-core and the real herdr against disposable homes. Fresh install, idempotent re-run, stale-file refresh, profile-off skip, and the verify assert failing when the integration is missing all behaved as intended. The playbook ran as a non-root user with become disabled, so the missing become on the verify status task (review round 2, declined) was not exercised. The transcript is saved as evidence and the temp dirs were removed. The docs scenario is untested because it is documentation only and was verified by reading, not by a live run. I did not exercise the herdr --remote viewer-side update, which is documentation only.

• Live validation: ✅ go - 5 of 6 scenarios driven live against the product

Scenario	Result	Live	Evidence
Fresh host apply creates ~/.omp/agent/extensions, installs the Herdr omp extension, and verify sees omp: current	✅ pass	live	ansible-run.txt scenario A: changed=2, failed=0; status omp: current (v10)
Second apply reports no change	✅ pass	live	ansible-run.txt scenario B: changed=0
A stale or outdated extension file is refreshed by apply and reported as a change	✅ pass	live	ansible-run.txt scenario C: omp: outdated before, changed=1 then omp: current (v10)
agents profile off skips the install and verify tasks and leaves the home untouched	✅ pass	live	ansible-run.txt scenario D: skipped=6, empty home
Adversarial: verify fails with a clear message when the omp integration is missing	✅ pass	live	ansible-run.txt scenario E: fatal assert, omp: not installed
Docs cover the pane-state mechanism, the host-move step, and the herdr --remote viewer version note	⏸️ untested	no	The prior payload only read docs/herdr.md and docs/agent-host-move.md. It did not establish a live result, and the change is documentation only with no runtime surface to drive.

Evidence: Ansible run transcript for all five scenarios

=== A fresh home, no .omp dir
TASK [Ensure the omp extensions directory] *************************************
changed: [localhost]
TASK [Checksum the Herdr omp integration before install] ***********************
ok: [localhost]
TASK [Run herdr integration install omp] ***************************************
ok: [localhost]
TASK [Checksum the Herdr omp integration after install] ************************
changed: [localhost]
TASK [Read the Herdr integration status] ***************************************
ok: [localhost]
TASK [Assert Herdr's omp integration is current] *******************************
ok: [localhost]
PLAY RECAP *********************************************************************
localhost                  : ok=6    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
omp: current (v10) (/tmp/pt/home.R118/.omp/agent/extensions/herdr-omp-agent-state.ts)
=== B second apply (idempotent)
TASK [Ensure the omp extensions directory] *************************************
ok: [localhost]
TASK [Checksum the Herdr omp integration before install] ***********************
ok: [localhost]
TASK [Run herdr integration install omp] ***************************************
ok: [localhost]
TASK [Checksum the Herdr omp integration after install] ************************
ok: [localhost]
TASK [Read the Herdr integration status] ***************************************
ok: [localhost]
TASK [Assert Herdr's omp integration is current] *******************************
ok: [localhost]
PLAY RECAP *********************************************************************
localhost                  : ok=6    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
omp: outdated (legacy < v10) (/tmp/pt/home.R118/.omp/agent/extensions/herdr-omp-agent-state.ts)
=== C stale file refreshed
TASK [Ensure the omp extensions directory] *************************************
ok: [localhost]
TASK [Checksum the Herdr omp integration before install] ***********************
ok: [localhost]
TASK [Run herdr integration install omp] ***************************************
ok: [localhost]
TASK [Checksum the Herdr omp integration after install] ************************
changed: [localhost]
TASK [Read the Herdr integration status] ***************************************
ok: [localhost]
TASK [Assert Herdr's omp integration is current] *******************************
ok: [localhost]
PLAY RECAP *********************************************************************
localhost                  : ok=6    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
omp: current (v10) (/tmp/pt/home.R118/.omp/agent/extensions/herdr-omp-agent-state.ts)
=== D agents profile off
TASK [Ensure the omp extensions directory] *************************************
skipping: [localhost]
TASK [Checksum the Herdr omp integration before install] ***********************
skipping: [localhost]
TASK [Run herdr integration install omp] ***************************************
skipping: [localhost]
TASK [Checksum the Herdr omp integration after install] ************************
skipping: [localhost]
TASK [Read the Herdr integration status] ***************************************
skipping: [localhost]
TASK [Assert Herdr's omp integration is current] *******************************
skipping: [localhost]
PLAY RECAP *********************************************************************
localhost                  : ok=0    changed=0    unreachable=0    failed=0    skipped=6    rescued=0    ignored=0   
.
..
=== E verify only with integration missing (adversarial)
[WARNING]: No inventory was parsed, only implicit localhost is available
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
PLAY [localhost] ***************************************************************
ok: [localhost]
[ERROR]: Task failed: Action failed: `herdr integration status` does not report `omp: current`, so Herdr shows every omp agent as idle: omp: not installed (/tmp/pt/home.R118/.omp/agent/extensions/herdr-omp-agent-state.ts)
fatal: [localhost]: FAILED! => {"assertion": "factory_verify_herdr_integrations.stdout is search('(?m)^omp: current')", "changed": false, "evaluated_to": false, "msg": "`herdr integration status` does not report `omp: current`, so Herdr shows every omp agent as idle: omp: not installed (/tmp/pt/home.R118/.omp/agent/extensions/herdr-omp-agent-state.ts)"}
PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0   

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning

• ⚠️ docs/herdr.md:126 - The intent's second sentence says "im using herdr --remote, so i need to update my macbooks herdr too". The change covers only host-side provisioning: apply now installs the omp extension, and verify asserts omp: current. Nothing handles or documents the viewing machine. docs/herdr.md has no step for updating or checking the client Herdr, and no stated requirement about client/host version compatibility for pane state under herdr --remote. The extension runs on the host, so the macbook may need nothing beyond a Herdr update, but the change does not say so. This may be a manual step for the user rather than repo work. Decision needed: is a docs note or client-version check expected, or is the macbook update out of scope for this change?

🔧 Fix applied.
1 warning still open:

• ⚠️ ansible/tasks/verify.yml:229 - Read the Herdr integration status is the only new command that does not run as the target account. It has no become, become_user or environment: factory_user_env. The verify tasks that read the target account's state use become: "{{ factory_become_target | bool }}", become_user: "{{ factory_cfg.user }}" and factory_user_env, for example verify.yml:319-321 and 345-347. Verify runs in post_tasks with the play default become: false, unlike the install task in herdr.yml, which inherits the import-level become and HOME from site.yml. Concrete failure: when Ansible connects as an account other than factory_cfg.user, factory_become_target is true. The install task then writes ~<factory user>/.omp/agent/extensions/herdr-omp-agent-state.ts. The status check runs under the connecting user's HOME and reports omp: not installed, so the new assert fails on a correctly provisioned host. If the connecting user can run herdr and has no omp extension, the failure is spurious. The fix is to add the same three keys that the verify.yml:319-321 tasks use.

✅ **Test** - passed

✅ No issues found.

• Live validation: ✅ go - 5 of 6 scenarios driven live against the product

Scenario	Result	Live	Evidence
Fresh host apply creates ~/.omp/agent/extensions, installs the Herdr omp extension, and verify sees omp: current	✅ pass	live	ansible-run.txt scenario A: changed=2, failed=0; status omp: current (v10)
Second apply reports no change	✅ pass	live	ansible-run.txt scenario B: changed=0
A stale or outdated extension file is refreshed by apply and reported as a change	✅ pass	live	ansible-run.txt scenario C: omp: outdated before, changed=1 then omp: current (v10)
agents profile off skips the install and verify tasks and leaves the home untouched	✅ pass	live	ansible-run.txt scenario D: skipped=6, empty home
Adversarial: verify fails with a clear message when the omp integration is missing	✅ pass	live	ansible-run.txt scenario E: fatal assert, omp: not installed
Docs cover the pane-state mechanism, the host-move step, and the herdr --remote viewer version note	⏸️ untested	no	The prior payload only read docs/herdr.md and docs/agent-host-move.md. It did not establish a live result, and the change is documentation only with no runtime surface to drive.

• Ran the changed 'Install Herdr's omp state integration' block and the two new verify tasks through real ansible-core (via uvx) with the real herdr, in throwaway HOMEs under /tmp, using a throwaway playbook.
• Fresh home with no ~/.omp dir: the directory is created, the extension is installed, status reports omp: current (v10), and the verify assert passes (changed=2).
• Second apply on the same home: changed=0, so it is idempotent.
• Stale extension file (status omp: outdated): apply rewrites it, reports one change, and status returns to omp: current.
• agents profile off: all six tasks are skipped and the home stays empty.
• Integration file removed, then verify run alone: the assert fails with the 'shows every omp agent as idle' message and omp: not installed.
• Read docs/herdr.md and docs/agent-host-move.md to confirm the Pane state section and the herdr --remote viewer note are present, and that the host-move row no longer asks for a manual herdr integration install omp. This was reading only, not a live run.
• Read ansible/tasks/verify.yml to confirm verification is skipped in check mode, so a plan run on a fresh host cannot fail the new assert. This was reading only.

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.