fix(update): publish configuration backups transactionally

[tang-vu]

Why this matters

ods-update.sh backup produces the configuration snapshot that operators can later select through ods-update.sh rollback. Today it creates the final backup-* directory before copying any files. A failed copy or metadata write therefore leaves a partial directory that looks like a valid rollback candidate. Two calls with the same name in the same second also share that directory and silently overwrite/mix contents. Direct CLI labels are interpolated into the path without the host-agent's label validation, so path-like names can escape the intended leaf directory.

All three paths are reachable through the shipped Bash command; same-ID calls are also reachable through concurrent dashboard backup requests. A successful-looking or selectable partial backup weakens the update safety net exactly when rollback is needed.

Root cause and invariant

Root cause: backup construction and publication were the same directory operation (mkdir -p on the final path), with no transaction boundary, duplicate writer guard, or validation at the Bash entry point.

Invariant: only a fully copied snapshot with valid metadata may appear under the public backup-* namespace; one ID has one writer and can never overwrite a completed snapshot; labels remain plain identifiers at every entry point.

What changed

• Validate optional backup names with the same 1-64 character plain-label contract enforced by the host agent.
• Acquire a hidden per-ID directory lock before writing.
• Build into a unique hidden mktemp -d staging directory.
• Clean staging and lock paths on command errors/exits, with logged cleanup failures.
• Atomically rename the completed staging directory into the existing final naming scheme only after metadata succeeds.
• Refuse IDs that are already in progress or already complete instead of merging into their directories.
• Extend the real-script fixture with traversal, injected copy failure, repeated-ID preservation, and active-lock regressions.

Overlap check

Searched open and closed PRs for backup traversal/name validation, partial/transactional backups, concurrent backup collisions, and scanned every open PR changing ods/ods-update.sh.

• fix(backup): full backups now actually include (and restore) model weights #3018 changes full data/model backup/restore behavior and only touches the changelog section of ods-update.sh; it does not change cmd_backup.
• fix(update): roll source back with failed releases #2709 owns source rollback after failed releases, not general-backup publication.
• fix(rollback): resolve layered compose stack in ods-update.sh + ods-restore.sh #1755 and fix(update): preserve docker-compose override stack resolution in ods-update.sh #2455 own compose resolution during rollback/update.
• fix(ods-update): remove duplicate jq prerequisite check #2863, fix(ods-update): clean up temp version file on jq failure #2874, fix(ods-update): redirect health-check timeout output to stderr #2880, fix(update): changelog command hangs polling GitHub when tag fetch fails #3017, and other file-level matches cover prerequisites, a version temp file, health output, or changelog behavior.
• No semantic or file-level match owns label containment, partial publication, or duplicate writers in cmd_backup.

Focused validation

Concrete red evidence on the pre-fix production script after adding the first three regressions:

• bash tests/test-update-script-backup.sh ? 6 passed, 3 failed: path-like label accepted, failed copy left a selectable directory, repeated ID overwrote the completed snapshot.

After the fix:

• bash tests/test-update-script-backup.sh ? 10 passed, 0 failed
• bash tests/test-ods-update-runtime-compose.sh ? 5 passed
• bash tests/test-update-rollback-contract.sh ? 5 passed
• bash -n ods-update.sh tests/test-update-script-backup.sh ? passed
• shellcheck --rcfile /dev/null --severity=error ods-update.sh tests/test-update-script-backup.sh ? passed
• git diff --check ? passed

The ordinary local ShellCheck invocation could not parse the checkout's CRLF .shellcheckrc and also reported pre-existing warnings in unrelated lines; the explicit error-severity run bypassed that local config artifact. No live operator backup or rollback was performed. The real script ran against isolated temporary HOME/install fixtures and the rollback contract verified restored hashes.

Design, platform, and rollback

The final backup-<name>-<timestamp> format and lexicographic rotation behavior remain unchanged. Hidden staging/lock names do not match rollback or rotation globs. Directory creation, mktemp -d, mv, and traps are available on the supported Bash paths: Linux, macOS, and Windows through WSL2/Git Bash; the focused suite ran under Git Bash on Windows.

A process killed without a catchable exit may leave hidden staging/lock directories, but they are deliberately invisible to rollback selection. A later timestamp remains usable, and operators can inspect/remove stale hidden paths manually. This PR does not add automatic stale-lock deletion because guessing whether another writer is alive would weaken the one-writer invariant.

Rollback is a normal revert, but restores partial-publication and same-ID overwrite behavior. Human review is requested because this code protects rollback artifacts.

[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 548dda8414b8f3519c0be8f80787b2d26ccd9d8b.

• 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.