fix(setup): executor install ref pointed at a non-existent branch

[ProtocolWarden]

Problem

ensure_executor_installed defaulted to:

ref = install_ref or "dev"

TeamExecutor has no dev branch. git ls-remote --heads … TeamExecutor.git dev returns nothing, so uv tool install git+https://github.com/ProtocolWarden/TeamExecutor.git@dev failed on ref resolution. The operator saw only the generic [executor] ERROR: installation failed, with no indication that the ref was the cause.

Default is now main (resolves to 45f54ab3).

Two-repo defect

This is the OC-side half. The other half: TeamExecutor declared no [project.scripts], so even a successful install produced no team-executor binary — check_command_installed (a shutil.which) would still fail, and verify_executor's team-executor --help would raise executor not functioning.

Fixed upstream in ProtocolWarden/TeamExecutor#19. The two changes are only useful together — merge that one first, or this still cannot complete an install.

On the documentation

Worth stating plainly, because this was initially mis-diagnosed as a stale doc line.

docs/operator/setup.md's install/verify steps were accurate all along. They faithfully described a code path that could not succeed. With both halves landed, the documented flow — "checks whether team-executor is on PATH", "verifies the install with team-executor --help" — is true for the first time. No correction was needed there.

The one real doc defect was a different line in that section: it implied the team-executor CLI is how OC executes tasks. It is not. Execution runs through the library API in-process via the editable sibling install performed by ensure_executor_backends; the CLI is only the verification surface. This PR says so explicitly.

Verification

Against OC's own consumers with a real install:

check_command_installed('team-executor') -> True
verify_executor('team-executor')         -> passes (previously raised)
dependency_check probe                   -> 'team-executor 0.1.0' -> '0.1.0', executor_installed True

13 setup CLI tests green. Custodian pre-push gate clean.

Note

The library path (ensure_executor_backends editable sibling install) was never affected by any of this — it is what actually runs tasks, which is why the breakage stayed invisible.

🤖 Generated with Claude Code