gps-denied-onboard/_docs/02_tasks/todo/AZ-444_tier2_jetson_harness.md

Tier-2 Jetson harness wrapper

Task: AZ-444_tier2_jetson_harness Name: Tier-2 hardware-loop runner — run-tier2.sh, ssh provisioning, systemd service install, ASan-fuzz mode, image-flash automation Description: Implement the Tier-2 hardware-loop wrapper that AZ-406 stubs out — actual ssh-based runner, systemd service install for SUT on Jetson, tegrastats capture, ASan-fuzz launch path. Complexity: 5 points Dependencies: AZ-406 Component: Blackbox Tests / Tier-2 runner (epic AZ-262) Tracker: AZ-444 Epic: AZ-262 (E-BBT)

Problem

AZ-406 scaffolds Tier-2 (run-tier2.sh exists as a stub); but the actual hardware-loop semantics — ssh provisioning, image-flash automation, systemd service-life management, telemetry capture, ASan-fuzz launch — are non-trivial and need a dedicated task.

Outcome

• e2e/tier2/run-tier2.sh accepts the same pytest -k <selector> selector as Tier-1 and runs the selector against a configured Jetson host (env var TIER2_HOST).
• Provisioning: ssh-based; runs apt update && apt install -y ... for runner deps if not already present (idempotent).
• SUT lifecycle: installs the SUT as a systemd service (gps-denied-onboard.service); restart command is systemctl restart gps-denied-onboard.
• Telemetry capture: tegrastats runs as a parallel ssh stream during each test; output piped into the per-run evidence bundle.
• ASan-fuzz: separate --build-kind asan mode that flashes the ASan image (or builds it remotely) and runs the fuzz binary with stderr captured.
• Image-flash automation: --reflash flag (gated, OFF by default) re-flashes the Jetson via nvidia-sdkmanager-cli when needed.

Scope

Included

• run-tier2.sh runner.
• ssh-based provisioning + systemd install/restart.
• tegrastats parallel capture.
• ASan-fuzz launch.
• Image-flash automation (gated).

Excluded

• The CSV reporter — owned by AZ-406.
• Per-scenario test logic — owned by individual scenario tasks.
• Chamber automation for +50 °C — out of scope.

Acceptance Criteria

AC-1: selector parity Given the same pytest -k <selector> invocation Then both run-tier1.sh and run-tier2.sh accept it; the resulting test selection on Tier-2 is the same as Tier-1 (modulo tier == tier2-jetson skip rules).

AC-2: idempotent provisioning Given the Jetson host has the runner deps already installed When run-tier2.sh runs Then provisioning is a no-op (idempotent).

AC-3: systemd lifecycle Given a Tier-2 test triggers restart Then systemctl restart gps-denied-onboard is issued; the SUT process restarts within ≤5 s.

AC-4: tegrastats parallel capture Given any Tier-2 test Then tegrastats runs as a parallel ssh stream during the test; its output lands in e2e-results/run-${RUN_ID}/tegrastats-${tier2-host}-${test_id}.log.

AC-5: ASan-fuzz mode Given --build-kind asan flag Then the runner ensures the ASan SUT image is installed; the fuzz binary is launched; stderr is captured into e2e-results/run-${RUN_ID}/asan-fuzz-${test_id}.log.

AC-6: image-flash gating Given the --reflash flag is OFF (default) Then image-flash is NOT triggered; the runner errors out with a clear message if the on-Jetson SUT version does not match the test selection's expected version.

System Under Test Boundary

This task IS infrastructure — no SUT logic is exercised by it. The Tier-2 harness only orchestrates SUT lifecycle on real hardware.

Constraints

• ssh-based: requires TIER2_HOST + TIER2_USER + TIER2_KEY_PATH env vars; fails fast if any are missing.
• The reflash path uses NVIDIA's sdkmanager-cli and is environment-specific; it is gated OFF by default to prevent accidental hardware re-provisioning during routine CI.

Document Dependencies

• _docs/02_document/tests/environment.md § Tier-2 (Jetson hardware loop)
• _docs/02_document/tests/test-data.md § Tier-2-only fixtures (none beyond shared)