ci: publish traceable example firmware bundles

[vincentkoc]

Problem

The example CI jobs build firmware but do not retain downloadable bundles with enough provenance to distinguish the built source, SDK, and board configuration.

Changes

• Package and upload four example build bundles: generic ESP32-S3, ESP-BOX-3, Waveshare AMOLED room node, and M5Stack Tab5. The Unity test application is excluded.
• Include every image in the ESP-IDF flash map, relocated flash arguments, flashing instructions, metadata, and SHA-256 checksums.
• Record checked-out source, event, and PR-head commits separately from the actual SDK commit/build revision and requested image. Include dependency, submodule, selected defaults, partition, and Tab5 BSP bridge identities.
• Reject unsupported targets, missing or overlapping images, path escapes, known credential-bearing configuration, and signed/encrypted builds before leaving uploadable output.
• Document download, checksum verification, provenance limits, and explicit-device flashing precautions.

Checks

• Focused host suite: eight tests passed; one real YAML-reader test was skipped locally because the IDF parser is absent. That test is wired into the existing IDF CI environment.
• actionlint and git diff --check passed.
• Independent scoped review and final implementation/source-contract review found no blocker.
• Final diff and publication text checked for private data.
• Hosted CI for PR head c3867131285ecd0f3ddc6c7c644b4d71282f5a84: all five builds passed in https://github.com/openclaw/esp-openclaw-node/actions/runs/34130585677.
• Downloaded Tab5 artifact 10022176321 (2.75 MiB): the artifact digest, all 11 file checksums, and four offset-mapped flash images were verified. Download verification is limited to this Tab5 bundle.
• The Tab5 manifest records checked-out source test merge e37937d8b3b796a5f4c64d7207d729371f49f3fd, distinct from the PR head. Its actual IDF commit is 362a1776ec212788fda95f75b733bfdde3a0c394, build revision v5.5.5-648-g362a1776ec2, with esptool 4.12.0.

The observed SDK comes from the existing moving release-v5.5 image, not the pristine v5.5.5 tag. SDK-selection changes remain separate from this PR: #34.

Hardware Smoke Evidence

The actual test-merge image identified above was flashed onto an M5Stack Tab5 with ESP32-P4 revision 1.3 and 16 MiB flash. A full-flash erase and four image writes completed with hash verification. ST7121 LCD selection and readable local diagnostics rendering were observed. External Osmo Pocket 3 measurement confirmed approximately one second of 1 kHz speaker output.

Microphone/AFE activity was observed, but controlled speech response was inconclusive. Physical touch, the Tab5 camera, network pairing, Canvas RPC, and provider Talk were not run. No provider API calls were made and no provider key was loaded.

The initial diagnostics-close attempt hit a display-lock TIMEOUT. UI progress was verified, then one explicit retry closed diagnostics. This intermittent failure remains unresolved; no source fix was made. These observations are not clean, complete GUI or board qualification.

The other three bundles have not been download-verified here. These are traceable CI bundles, not reproducible-build guarantees, authenticated release artifacts, or security/hardware-qualified firmware. Checksums do not authenticate the publisher, and metadata sanitization is not a binary secret scan. The Tab5 bundle contains P4 firmware only; compatible C6 firmware is a separate prerequisite and is not included. No release or Pages deployment was performed for this change.

Landing Disposition

The manual-only release guard landed first in #38. This firmware-packaging change does not dispatch a component release or change a component version.

The original reviewed head and its evidence identities remain unchanged. The landing tree is checked against current main plus this PR's exact original delta; tree equivalence is not additional build or hardware coverage.

Voice remains unverified. A separate later preclaim device-status request ended with a disconnected node before Talk or provider startup. That outcome is not a timeout finding or a firmware-packaging defect, and it does not qualify voice for this PR.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 10, 2026, 5:49 AM ET / 09:49 UTC (Revision 4).

ClawSweeper review

What this changes

The PR packages four example firmware builds into downloadable CI artifacts with flashing instructions, checksums, and source, SDK, dependency, and board-configuration provenance.

Merge readiness

✅ Ready for maintainer review

This PR remains useful: current main does not provide downloadable firmware bundles. No blocking defect was found, and the previous draft-only blocker is resolved.

Priority: P2
Reviewed head: c3867131285ecd0f3ddc6c7c644b4d71282f5a84

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with meaningful rejection coverage and real artifact evidence has no identified blocking defect.
Proof confidence	🐚 platinum hermit (4/6) ✨ media proof bonus	Sufficient (linked_artifact): The real CI entrypoint ran the production packager and uploaded all four bundles; the captured body additionally records Tab5 checksum validation and successful physical flashing. Direct ZIP reinspection was blocked by this reviewer's network boundary, which does not invalidate that evidence or imply full hardware qualification.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (linked_artifact): The real CI entrypoint ran the production packager and uploaded all four bundles; the captured body additionally records Tab5 checksum validation and successful physical flashing. Direct ZIP reinspection was blocked by this reviewer's network boundary, which does not invalidate that evidence or imply full hardware qualification.
Evidence reviewed	8 items	Policy and introduced scope: No AGENTS.md or maintainer-note files were found. The pinned introduction contains four files, with 766 additions and one deletion; all four files were read fully. The checkout remained clean. Still necessary on main: Current main builds the examples but has no firmware packaging or upload step. Its scripts contain the separate component-release checker. The GitHub releases endpoint returned no releases, so no shipped implementation was established. Packaging and publication safeguards: The packager validates supported boards, metadata targets, file containment, image overlap, clean source, known credential settings, and signed/encrypted configurations. It stages output before publishing the bundle directory. CI uploads only that directory with contents-read permission; the tests cover relocation, rejection, sanitization, submodules, and Tab5 provenance.
Findings	None	None.
Security	None	None.

How this fits together

The example CI jobs compile firmware for supported ESP boards. The new packaging step turns their build outputs and metadata into downloadable bundles for explicitly selected devices.

flowchart LR
  A[Four example builds] --> B[Images and build metadata]
  B --> C[Validate targets and public configuration]
  C --> D[Package images and provenance]
  D --> E[Upload CI artifacts]
  E --> F[Verify checksums and select device]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Code growth	Production +355 lines; tests +333 lines	The new packager's growth is justified by validation, provenance, and portable bundle generation.
Published build coverage	4 example artifacts; 1 test application excluded	GitHub confirms the intended publication boundary was exercised.

Technical review

Best possible solution:

Retain a single CI packaging path with explicit provenance and flashing precautions, while keeping release publication and hardware qualification separate.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this adds artifact distribution rather than repairing an established runtime failure; current main's CI lacks that capability.

Is this the best way to solve the issue?

Yes. Packaging the existing ESP-IDF flash map after successful builds avoids a parallel build path and preserves the existing SDK and device configuration.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 675485e6b388.

Labels

Label justifications:

• P2: Downloadable, traceable example firmware is a bounded developer and device-setup improvement.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (linked_artifact): The real CI entrypoint ran the production packager and uploaded all four bundles; the captured body additionally records Tab5 checksum validation and successful physical flashing. Direct ZIP reinspection was blocked by this reviewer's network boundary, which does not invalidate that evidence or imply full hardware qualification.
• proof: sufficient: Contributor real behavior proof is sufficient. The real CI entrypoint ran the production packager and uploaded all four bundles; the captured body additionally records Tab5 checksum validation and successful physical flashing. Direct ZIP reinspection was blocked by this reviewer's network boundary, which does not invalidate that evidence or imply full hardware qualification.

Evidence

What I checked:

• Policy and introduced scope: No AGENTS.md or maintainer-note files were found. The pinned introduction contains four files, with 766 additions and one deletion; all four files were read fully. The checkout remained clean. (c3867131285e)
• Still necessary on main: Current main builds the examples but has no firmware packaging or upload step. Its scripts contain the separate component-release checker. The GitHub releases endpoint returned no releases, so no shipped implementation was established. (.github/workflows/ci.yml:68, 675485e6b388)
• Packaging and publication safeguards: The packager validates supported boards, metadata targets, file containment, image overlap, clean source, known credential settings, and signed/encrypted configurations. It stages output before publishing the bundle directory. CI uploads only that directory with contents-read permission; the tests cover relocation, rejection, sanitization, submodules, and Tab5 provenance. (scripts/package_firmware.py:163, c3867131285e)
• Direct SDK metadata contract: The packager consumes ESP-IDF-generated project_description.json and flasher_args.json. The upstream templates at the reported SDK commit confirm schema version 1.2, configuration and revision fields, the image map, flash settings, and esptool arguments used by this implementation. (tools/cmake/project_description.json.in:2, 362a1776ec21)
• Actual packaging and upload results: GitHub run 34130585677 identifies the exact PR head and succeeded. All four example jobs completed Build and Upload firmware; the component test application skipped upload. GitHub lists four unexpired artifacts bearing compiled test-merge identity e37937d. (.github/workflows/ci.yml:89, c3867131285e)
• Captured after-change proof and limits: The supplied complete PR body records verification of Tab5 artifact 10022176321, all 11 checksums, four flash images, and physical flashing with hash verification. GitHub independently confirms that artifact and its digest. This reviewer could not repeat ZIP inspection because the artifact-storage redirect was blocked; the scratch directory contained no downloaded media. The captured proof remains sufficient for packaging, without claiming complete board, voice, or other-bundle download qualification. (c3867131285e)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• vincentkoc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (3 earlier review cycles)

• reviewed 2026-09-07T14:04:45.777Z sha c386713 :: needs maintainer review before merge. :: none
• reviewed 2026-09-07T14:17:49.223Z sha c386713 :: needs changes before merge. :: none
• reviewed 2026-09-07T14:57:39.132Z sha c386713 :: needs changes before merge. :: none