phase: 10_dev_direct_dial

**Phase 10 final pass — repo green; live criteria blocked off-repo.**

- Verified: `gateway` runs `dashboards-agent` (active/enabled, `10.1.1.27:9120` → `/health` 200, `/snapshot` 401 no-token / 200 bearer on-host, token matches `/etc/dashboards-agent.token`); `driveripper`/`deskwork` inactive, `sudo -n` → "a password is required", `:9120` empty.
- New measurement (transient runtime rule on gateway `firewall-cmd --add-port=9120/tcp`, **reverted** — runtime+permanent port lists verified back to the original set, no rich rules): laptop still gets no SYN through, while `:22`/`:80` on the same address answer in ms ⇒ the block is the lab gateway `10.2.0.1` port filter, not this app/host firewall/agent. No other live change made (no sudoers, no upsd, no UPS command).
- Tests/lint (exact): `bash .agents/validate.sh` → **EXIT 0** — `uv run pytest --cov --cov-fail-under=94` **793 passed, 11 skipped, coverage 98.33 %**; `ruff check src tests agent` clean; `pyright` 0 errors; `node --check` clean; hygiene clean; `uv pip list --outdated` empty (bumped fastapi 0.143.3→0.143.5, `uv.lock` only).
- `uv run pytest -m live --live` (`.env.dev` sourced): **4 passed, 1 skipped, 6 failed** — all six are `:9120`/`:3051` connect timeouts; zero parse/contract failures.
- Dev server restarted on current code: engines `ok`; 3×`host` + 3×`disks` + `nut` `DOWN` with real reasons (designed degradation, stub rows intact, no credential leakage).
- Completion criteria: screenshots ✓ (`data/logs/phase10-{index,system,disks,llm,ups}-live.png`); tunnel-vocabulary grep ✓ outside `.agents/` history (PLAN.md locked line, phase overviews, past reports; fixtures/`uv.lock` hits are digit substrings — `tests/test_deploy_scripts.py` guards operational files); no page-payload change ✓ (contract tests). **Not met, operator-side:** agents on all three hosts, `LIST UPS` from the laptop, `dev-server.sh status` all-ok, live suite green.
- Fixed in this pass: `sources/nut.py` unreachable-upsd message no longer prints a bare `(TimeoutError: )` (now `(timed out after 4s)` / `(ConnectionRefusedError: …)`), pinned by a new test + extended refused-port test.
- Docs: README verified consistent (every env var in `config.py` documented, routes/flags/`--with-llm`/pager sizes checked) — no changes needed. AGENTS.md fixed 4 inconsistencies: per-host sudo reality (gateway grants `NOPASSWD ALL`, which is why it installed without `agent-sudoers`; driveripper scoped; deskwork unrelated), the now-proven firewall finding, `/system` table typo ("agent per host"), gap-4 DB/WAL sizes + test count. `.env.example` `upsd.users` sample now one `instcmds` per line (it contradicted README and the in-app copy). `.env.dev` (gitignored) comment corrected to match the evidence.
- Flagged, untouched (locked): `.agents/PLAN.md` L92–95 still says upsd is "forwarded to `127.0.0.1:3494` in dev" — false after this phase; evidence + exact operator commands appended to `data/logs/NOTES-verify.md` §11.
- Next pending phase: `11_admin_login`.

tests/test_nut.py

@@ -249,6 +249,31 @@ async def test_connection_refused_is_reported_as_unreachable() -> None:
     with pytest.raises(NutError) as excinfo:
         await client.connect()
     assert excinfo.value.code == "UNREACHABLE"
+    # The reason is the sentence the operator actually reads (health record, alert, feed).
+    assert "ConnectionRefusedError" in str(excinfo.value)
+
+
+async def test_connect_timeout_names_the_timeout_instead_of_an_empty_parenthetical(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """`wait_for()` raises a TimeoutError with no message of its own.
+
+    A firewalled port therefore used to print `… (TimeoutError: )`, which explains nothing.
+    This is the exact state the fleet is in while the laptop cannot reach upsd, so the
+    message has to carry the timeout it hit.
+    """
+
+    async def never_connects(*_args: object, **_kwargs: object) -> None:
+        await asyncio.sleep(0.2)
+
+    monkeypatch.setattr(asyncio, "open_connection", never_connects)
+    client = NutClient("ups.example.net", 3051, timeout=0.01)
+    with pytest.raises(NutError) as excinfo:
+        await client.connect()
+    assert excinfo.value.code == "UNREACHABLE"
+    message = str(excinfo.value)
+    assert "timed out after 0.01s" in message
+    assert "TimeoutError" not in message
 
 
 async def test_server_closing_early_is_reported() -> None: