contrib: openipc-bisect — host-side firmware bisect driver

[widgetii]

Summary

PR-D of six in the nightly-build redesign. Adds contrib/openipc-bisect, a host-side POSIX shell driver that performs a binary search across dated nightly builds using #2114's sysupgrade --build=<id>.

Key design property: state lives on the workstation, never on the camera. A brick mid-bisect (kernel/driver regression that prevents boot → UART/TFTP recovery required, per kaeru uart-recovery-via-uboot-tftp-recipe) cannot lose progress — recover the camera by any means and openipc-bisect bad (or skip) resumes the loop.

Subcommands

openipc-bisect start <host> [--good=<id|sha>] [--bad=<id|sha>] [--platform=<id>]
openipc-bisect good | bad | skip      # mark current candidate, flash next median
openipc-bisect status                 # window size, verdicts, rounds remaining
openipc-bisect reset                  # flash back to channels.nightly, clear state
openipc-bisect resume                 # re-attach after host restart/disconnect

Defaults

• --bad → channels.nightly (current rolling tip from manifest.json)
• --good → oldest build in the manifest window for this platform
• --platform → autodetected from the camera's fw_printenv soc + /etc/os-release BUILD_OPTION

Ref normalization

Accepts: exact build_id, short sha (matches trailing -<short> on build_id), full sha (matches manifest.builds[].sha), and channels.{nightly,latest} keywords.

Verified locally

• sh -n clean.
• Live https://openipc.github.io/firmware/manifest.json parses.
• resolve_channel, builds_for_platform, and normalize_ref all return expected results against the real schema published by ci/nightly: manifest aggregator + 90-build retention sweep #2112.

Caveats

• End-to-end loop is not exercisable on a single dated nightly — needs ≥2 builds for a non-degenerate window. The manifest will accumulate one per night going forward.
• The current sysupgrade resolves --build=<id> strictly through the firmware manifest. fpv-variant cameras (whose firmware comes from OpenIPC/builder per kaeru openipc-firmware-vs-builder-variant-split) won't be bisectable through this tool until a parallel manifest exists for that ecosystem.

Dependencies

• Host: sh, jq, curl, ssh. No new rootfs dependency on the camera.

Test plan

• CI passes on this PR (no buildable code; only Preflight + shell-tests will run).
• Once ≥2 dated nightlies exist on master, run:
  OPENIPC_BISECT_WAIT=180 contrib/openipc-bisect start openipc-hi3520dv200.dlab.torturelabs.com --good=<id-2-back>
  and convergence over 1-2 rounds with the expected window narrowing.
• Kill the host process mid-bisect; openipc-bisect resume re-attaches from ~/.local/state/openipc/bisect/<host>.json.
• Simulate a brick (yank power mid-flash); recover via UART/TFTP per kaeru recipe; openipc-bisect bad continues.
• openipc-bisect reset returns the camera to the rolling nightly channel.

🤖 Generated with Claude Code