fix: gate SSH dispatch to Docker-capable workers

[kaiitunnz]

Purpose

An SSH task could be dispatched to a worker that cannot run it, then fail deep in the executor with Docker is not available; cannot run SSH executor: ... FileNotFoundError(2, 'No such file or directory'). Two gaps combined: (1) the dispatcher filtered candidates only by hardware fit (hw_satisfies), never by whether a worker can actually service SSH; and (2) ssh_limits is None both when SSH is disabled and when SSH is enabled-but-uncapped, so it cannot stand in for an SSH-capable signal. In a multi-node cluster, a node missing ENABLE_SSH_BY_DEFAULT=true brings up workers without the Docker socket mounted, yet the scheduler still routes SSH tasks to them — non-deterministically, depending on which worker it picks — and the SSH executor raises a controlled (non-retryable) error, so the task fails terminally even when an SSH-capable worker exists.

Changes

• Worker — probes the Docker daemon once at startup and advertises a WorkerCapabilities (ssh) at registration; the SSH executor and the probe now share a single Docker-connection helper.
• Server — carries WorkerCapabilities on each registered worker and gates SSH-task selection on it (capability_satisfies, alongside the existing hardware check), failing fast with an SSH-specific message when no capable worker exists.
• Shared / SDK — a WorkerCapabilities schema, also surfaced on the SDK Worker model so flowmesh worker list shows which workers are SSH-capable.
• Docs — capability-gated SSH dispatch noted in the architecture and worker docs.

Design

Capability is reported by the entity that actually runs SSH — the worker process — and reflects ground truth (Docker reachable) rather than echoing a server config flag, so it catches every cause of the original failure the same way: unmounted socket (the per-node ENABLE_SSH_BY_DEFAULT miss), dead daemon, or a missing docker-group gid. Capability and hardware stay separate concerns — capability_satisfies gates which kinds of task a worker can take, hw_satisfies gates how big. A worker that reports no capabilities is treated as incapable (strict default): during a rolling upgrade an SSH task waits for an upgraded worker rather than risking a wrong dispatch, which is the safe direction. WorkerCapabilities is a model rather than a bare boolean so future specialized executors can gate the same way without another wire-format change.

Test Plan

uv run pytest tests --ignore=tests/worker/test_mp_executor_cleanup_gpu.py
uv run pre-commit run --all-files

End-to-end against a local single root + CPU worker on freshly built images carrying this branch (2 scenarios / 10 assertions). It targets what the unit suite cannot reach — the full worker-probe → registration → registry → dispatch path: (A) with only an SSH-incapable worker (enable_ssh=false, no Docker socket mounted), the SSH task is excluded from selection and fails fast instead of being dispatched and erroring inside the executor; (B) on a mixed fleet, the SSH task is routed to the SSH-capable worker, spawns a session container, and runs to completion.

Test Result

$ uv run pytest tests --ignore=tests/worker/test_mp_executor_cleanup_gpu.py   # All passed
$ uv run pre-commit run --all-files  # isort / black / ruff / mypy / codespell / gitleaks passed

End-to-end suite: 2 scenarios, 10/10 assertions passed — the incapable-only fleet failed fast, and the mixed fleet routed the task to the capable worker and ran it to DONE.

---

Pre-submission Checklist

• I have read the contribution guidelines.
• I have run pre-commit run --all-files and fixed any issues.
• I have added or updated tests covering my changes (if applicable).
• I have verified that uv run pytest tests/ passes locally.
• If I changed shared schemas or proto definitions, I have checked downstream compatibility across Server and Worker.
• If I changed the SDK or CLI, I have verified the affected packages work (uv sync --all-packages --group ci --frozen).
• If this is a breaking change, I have prefixed the PR title with [BREAKING] and described migration steps above.
• I have updated documentation or config examples if user-facing behavior changed.