Fix Bundle file not found on every remote-build submit

[bdraco]

What does this implement/fix?

Fixes "Bundle file not found" on every remote build the operator dispatches through remote_build/submit_job.

What was happening

SubmitJobReceiver._extract_and_queue was writing the assembled tarball to:

<config>/.esphome/.remote_builds/<dashboard_id>/<device_name>/bundle.tar.gz

…and then calling esphome.bundle.prepare_bundle_for_compile(bundle_path, target_dir) against that same <dashboard_id>/<device_name>/ directory.

The upstream helper preserves only .esphome / .pioenvs / .pio inside target_dir and wipes every other entry before its inner extract_bundle reads from bundle_path (esphome/bundle.py:752-758). So the just-written bundle.tar.gz got deleted between the executor write and the inner extract, and extract_bundle raised EsphomeError("Bundle file not found: …") at bundle.py:467. The receiver-side submit_job handler caught that, mapped it to a structured artifacts_end{accepted: false, reason: "extract_failed"} reject, and the user saw a failed build with this log line:

WARNING [remote_build.submit_job] submit_job from <dashboard_id>: extract failed for
job <job_id> (<config>.yaml): Bundle file not found:
<config>/.esphome/.remote_builds/<dashboard_id>/<device>/bundle.tar.gz

What changes

bundle_path moves from target_dir / "bundle.tar.gz" to target_dir.parent / f"{device_name}.tar.gz" — a sibling of the build subtree under the same <dashboard_id>/ parent. The wipe step can't reach it.

Path-traversal safety carries over unchanged: device_name is the canonical form _validate_configuration_filename returns (which already strips separators / ..), so a malicious sender still can't pick a shape that climbs out of the <dashboard_id>/ namespace. The constant rename (_BUNDLE_FILENAME → _BUNDLE_SUFFIX) flags the shape change; the comment on the new constant explains why "outside target_dir" is load-bearing.

Why the existing tests didn't catch it

• Unit tests (tests/test_remote_build_submit_job.py): every test that exercises the extract path stubs prepare_bundle_for_compile with a trivial pass-through that just asserts the bundle file exists at write time and returns a synthetic YAML path. They never modelled the upstream wipe semantics, so a regression in where the bundle lives relative to target_dir was invisible at the unit level.
• E2E tests (tests/e2e/): the harness has tests for pair/session lifecycle, JOB_* fan-out, cancel_job, and (newly in Add e2e coverage for download_artifacts round-trip (6a) #549) download_artifacts — but no test drives the offloader→receiver submit_job round-trip with the real upstream prepare_bundle_for_compile. test_submit_job_fanout.py's module docstring explicitly calls out the gap: "A submit_job e2e test is the natural next follow-up once the receiver-side firmware controller can be swapped for a recording stub without coupling the harness to DeviceBuilder."

So both the unit suite and the e2e harness had a blind spot at the same junction. New regression in this PR:

• test_submit_job_bundle_path_survives_prepare_bundle_wipe stubs prepare_bundle_for_compile with a wipe-emulating function (mirrors upstream's preserve set, deletes non-preserved entries in target_dir, then reads bundle_path). A regression that moves the bundle back inside target_dir trips the read_bytes() arm and the test fails. This catches the bug pattern without needing to build a real esphome bundle.

A real submit_job e2e test (constructing a real bundle via esphome.bundle.BundleBuilder, exercising upstream's prepare_bundle_for_compile end-to-end) is the broader fix for the e2e gap — separate follow-up.

Related issue or feature (if applicable):

• Part of Remote build offload: discover and delegate compiles to another dashboard on the LAN #106 (remote-build offload), phase 5c-2a regression.

Types of changes

• Bugfix (non-breaking change which fixes an issue) — bugfix
• New feature (non-breaking change which adds functionality) — new-feature
• Enhancement to an existing feature — enhancement
• Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
• Refactor (no behaviour change) — refactor
• Documentation only — docs
• Maintenance / chore — maintenance
• CI / workflow change — ci
• Dependencies bump — dependencies

Frontend coordination

• No frontend change needed
• Companion frontend PR: esphome/device-builder-dashboard-frontend#

Checklist

• The code change is tested and works locally.
• Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
• Tests have been added or updated under tests/ where applicable.
• components.json has not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
• Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing fix-submit-job-bundle-path (76a85e7) with main (ceace1b)}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.11%. Comparing base (ceace1b) to head (76a85e7).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #552   +/-   ##
=======================================
  Coverage   99.11%   99.11%           
=======================================
  Files          76       76           
  Lines        9993     9993           
=======================================
  Hits         9905     9905           
  Misses         88       88           

Flag	Coverage Δ
py3.12	99.08% <100.00%> (ø)
py3.14	99.11% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ice_builder/controllers/remote_build/submit_job.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Fixes a receiver-side remote-build regression where the assembled bundle tarball was written inside target_dir, then deleted by upstream esphome.bundle.prepare_bundle_for_compile() (which wipes non-preserved entries inside target_dir before extracting), causing "Bundle file not found" on every submit_job.

Changes:

• Move the assembled bundle tarball path to be a sibling of the per-device build subtree (<dashboard_id>/<device>.tar.gz) instead of a child of it.
• Rename the constant from a fixed filename to a suffix (_BUNDLE_SUFFIX) and document why the sibling placement is required.
• Add a unit test that emulates the upstream “wipe-then-read” behavior to prevent regressions.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
esphome_device_builder/controllers/remote_build/submit_job.py	Writes the assembled bundle tarball outside target_dir so upstream wipe semantics can’t delete it before extraction.
tests/test_remote_build_submit_job.py	Adds a regression test that simulates upstream wiping target_dir and then reading bundle_path.