[tang-vu]

Why this matters

ods update changes ODS configuration and recreates containers. Before this refresh, it could change .env and .compose-flags before taking its pre-update snapshot, then continue pulling and recreating containers when the snapshot failed or its helper was missing. The fallback ods-backup.sh --type user-data does not capture the configuration that ods rollback restores.

The existing #3066 fix made ods-update.sh backup publish a completed backup atomically. Rebased on upstream main 03511352a4f846d3d0b8da009d83fbebb50a8da0, this refresh makes that snapshot a required boundary for the actual CLI update path. Head: c4d596428af0414d46121bc8bc15e2ac45606c98.

What changed

• Validate backup labels; lock each ID; copy into hidden staging; publish only after both metadata.json and snapshot.json are written. Stage .compose-flags and extension config-* directories too, so the published snapshot is flat and can restore them. Reject existing final names, including dangling symlinks.
• Reject invalid MAX_BACKUPS before copying. In particular, zero can no longer prune the newly created backup while returning success.
• In ods update, check version compatibility, then require successful ods-update.sh backup before CPU budget changes, Shield/Hermes token insertion, stale Compose cache removal, Docker pulls, or container recreation. Missing or failed snapshot stops the update with recovery guidance, including with --force.
• Remove the user-data fallback from this path because it cannot provide an ods rollback configuration snapshot. Update existing verification fixtures to supply the required snapshot helper.

Reproduction and validation

• Before the CLI fix, a disposable install with a backup helper exiting 42 changed .env and issued Compose pull/up after the failure. The new nearest-boundary test was red against that code.
• On Linux, test-ods-cli-update-backup-required.sh: 5 passed. It covers failed/missing helpers, a failure inside the shipped helper caused by an unusable temporary backup path, MAX_BACKUPS=0, and a successful update that captures byte-exact prior .env/.compose-flags before normal pull/up and Shield key creation. Failure cases verify unchanged config and no Compose pull/up.
• test-update-script-backup.sh: 14 passed (atomic flat layout, failure cleanup, duplicate ID/lock, retention). test-update-backup-restore-configs.sh: 7 passed, including actual restoration of config files, .compose-flags, and .env. test-update-rollback-latest-backup.sh: 6 passed. CLI update verification: 6 passed; legacy backup routing: 2 passed; second CLI verification: 1 passed.
• bash -n for changed shell files and git diff --check: passed. Pre-commit on the six changed files in a pristine Git clone: gitleaks, private-key, and large-file checks passed; remaining configured hooks do not target these paths. GitHub CI for this head is pending.

Tests ran against temporary install/HOME fixtures and fake Docker commands on an isolated Linux QA host. No operator installation or running ODS app was updated for this PR.

Scope and recovery limit

This is an ODS configuration snapshot requirement, not a promise of automatic full runtime restoration. Native Pixel rollback remains subject to the existing source-update safety preflight. Existing hidden lock/staging artifacts from an uncatchable process termination remain invisible to rollback selection and require operator inspection. This refresh stays on the existing #3066 PR because it completes the same pre-update snapshot safety outcome; no duplicate PR was opened.

[tang-vu]

Batch compatibility receipt (2026-08-23)

This head was merged locally with the independent candidate heads for #2114 (446099d), #2375 (2750621), #3040 (75deb4f), #3065 (bad25e7), and #3066 (ef87fce). The synthetic integration head was 548dda8.

• All five heads merged without conflicts; they have no merge-order dependency.
• Dashboard API boundary suites: 116 passed.
• Dashboard: 262 tests passed; ESLint and Vite production build passed.
• Update backup/runtime/rollback contracts: 20 passed; �ash -n and ShellCheck error-level validation passed.
• git diff --check upstream/main...HEAD passed.

This is compatibility evidence for the exact candidate heads, not a substitute for the live operator backup/rollback gate or independent review requested in the PR body. Keeping this PR in draft until that review/gate is resolved.