# 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)