dashboards/.agents/phases/todo/10_dev_direct_dial/00_phase.md

Phase 10 — Dev dials the fleet directly (no more SSH tunnels)

Source: user request (2026-10) — "I don't want this separation of architectures. My laptop can talk to these hosts directly via local network or vpn already. Just have dev work like prod." Story: n/a Context: AGENTS.md (dev workflow: scripts/dev-tunnels.sh, DEV_TUNNELS/DEV_FORWARDS), deploy/install-agent.sh, deploy/nut-sudoers, scripts/dev-server.sh, scripts/capture-fixtures.sh, tests/test_live_fleet.py, .env.dev.example, .env.example, README.md

Objective

Dev becomes the prod topology: each host's agent runs as a systemd service (installed by ops through a documented minimal sudoers grant), bound to the address the dashboard dials, token in the URL userinfo; driveripper's upsd ACLs the host and laptop IP ranges on port 3051; .env.dev points at the real hosts with no DEV_TUNNELS/DEV_FORWARDS; scripts/dev-tunnels.sh is retired. The dashboard's Python is untouched — this phase changes deployment, config, scripts and docs, and proves parity with the live suite plus browser screenshots.

Decisions (user, 2026-10)

• The agent is a systemd service, installed by the ops user (not root). The repo documents the simplest possible working sudoers addition in deploy/agent-sudoers, and the user adds it to each host.
• The upsd ACL allows the host's IP range and the laptop's IP range — both real ranges, derived at install time and commented in .env.dev so they can be re-derived when the laptop's IP changes.

Precondition (user action, before task 02)

The sudoers line needs root, and the command-scoped sudo on driveripper does not include visudo. The user adds the one line from deploy/agent-sudoers on each host. If it is missing when task 02 runs, that task must stop cleanly and print the exact instructions — never loop, never wait, never attempt to edit sudoers itself.

Dependencies

• 05_ups_hero_battery_glyph (complete) — the last UI phase; its pages are what this phase re-verifies against live data after the transport change.
• 06_system_page_gpu_verdicts, 07_llm_monitor_style_pages, 08_events_paging_and_copy, 09_disks_smartctl (todo) — independent: this phase changes transport and ops, not payloads or page behaviour, and they do not depend on the transport.

Tasks

1. 01_sudoers_grant_and_installer_hint.md — deploy/agent-sudoers (the minimal working grant
   • install instructions, in the nut-sudoers house style); install-agent.sh run without root prints the exact line to add.
2. 02_install_agents_on_fleet.md — on all three hosts: kill the ad-hoc agent, stage the installer, install the systemd service bound to the dialed address, capture the printed tokens, verify from the laptop.
3. 03_upsd_acl_for_laptop.md — driveripper: append ACL lines for the host range and the laptop range to upsd.conf (read-first, cmp-after, never blind-write), restart nut-server, verify the NUT wire from the laptop.
4. 04_env_dev_direct_dial.md — stop the tunnels; rewrite the local .env.dev to direct targets (userinfo tokens, NUT_HOST/NUT_PORT=3051); restart the dev server; sources ok.
5. 05_retire_tunnels_update_scripts.md — delete scripts/dev-tunnels.sh; rewrite .env.dev.example direct-shaped; fix capture-fixtures.sh, the live suite's docstring and skip messages, ups_contract.py, the alerts.py docstring, test_config.py, .env.example's NUT note, and the dev-workflow sections of README.md/AGENTS.md.
6. 06_verify_direct_dial_live.md — full live verification: /api/health ok over direct dial, uv run pytest -m live --live green, browser screenshots of / + /system + /ups + /llm on live data, no tunnel port needed on the laptop.

Testing & Quality

• The Python changes in this phase are test-file strings and one docstring — no new logic. The full suite must stay 100% green and overall coverage must not drop (gate: --cov-fail-under=94).
• bash -n on deploy/install-agent.sh and scripts/capture-fixtures.sh after their edits.
• The real proof of this phase is the live path: uv run pytest -m live --live against the directly-dialed fleet (the same production code paths over the prod-shaped transport) plus a browser screenshot per AGENTS.md rule 10.
• The phase is "Complete" only when the entire project test suite passes 100% (every test in the project, not just the phase's — pre-existing failures included) and the coverage gate in .agents/validate.sh holds.

Documentation & Consistency

• The final pass reviews README.md and AGENTS.md in full against the project as it stands after this phase — fixing every inconsistency found, including pre-existing ones not caused by the phase (including any remaining mention of dev-tunnels.sh, DEV_TUNNELS, DEV_FORWARDS, 9121/9122/9123 or 3494).
• Task 05 updates README.md/AGENTS.md immediately for the user-visible dev-workflow change.
• PLAN.md is locked and must not be edited: its Data-Model note ("forwarded to 127.0.0.1:3494 in dev") goes stale after this phase — flag it in the final pass's report to the user, and leave the file untouched.

Completion Criteria

• systemctl status dashboards-agent is active on all three hosts, each bound to the address the dashboard dials, answering /health (unauthenticated) and /snapshot (bearer) from the laptop
• driveripper's upsd answers LIST UPS from the laptop on 3051 — not via the host's loopback
• git grep -n "dev-tunnels\|DEV_TUNNELS\|DEV_FORWARDS\|9121\|9122\|9123\|3494" matches nothing outside .agents/phases/complete/
• ./scripts/dev-server.sh status shows every source ok over direct dial
• uv run pytest -m live --live (with .env.dev sourced) is green
• data/logs/ holds phase10-*.png screenshots of /, /system, /ups, /llm on live data over direct dial
• full test suite 100% passing, coverage gate (≥94%) holds, ruff + pyright clean
• README.md and AGENTS.md describe the direct-dial dev workflow and mention no tunnels (verified in the final pass)
• no behavior change in completed phases: the four pages render the same payloads as before the transport change