[cocofhu]

What changed

Users who installed with git clone and bash scripts/install.sh need a documented upgrade path, and releasing a tag should verify that path with existing user data.

• Gate platform releases on a real installation of the preceding published stable version followed by an upgrade to the new image. Verify the pushed image digest, preserved configuration/database/login and user data, customized catalog, continuation of a waiting SOP, a new SOP, and repeated installation before promoting mutable image tags or creating the GitHub Release.
• Preserve the platform container's workspace hostname across replacements. An unmodified v0.3.3 → v0.3.4 upgrade reproduced HTTP 409 for an existing workspace because its host changed; the installer now adopts the legacy container's hostname without rewriting stored bindings.
• Add upgrade instructions to both READMEs, the deployment guide and generated release notes, including image overrides, backups and manual migration requirements.

Scope

• Platform core / API / runner
• Public adapter / deployment
• Classic
• Portable
• Shared behavior contract
• Installer / CLI
• Documentation only

Compatibility

Applies to the published-image Compose installation. Existing .env values, secrets, data paths and the Compose project name are retained. The first upgrade of a legacy installation adopts its existing platform container's hostname, including stopped containers; if that container was removed, operators must supply the previous workspace hostname as documented. No schema or data migration is added, and historical SQL migrations remain manual.

The gate selects the greatest earlier published stable platform version, excluding Local history, drafts and prereleases. Missing baselines fail except for the first platform release. Failed acceptance can leave the versioned image available, but does not promote mutable tags or create a GitHub Release.

Validation

After rebasing onto current main:

• python3 scripts/test-install.py -v — 37 passed.
• python3 scripts/test-release-upgrade.py -v — 6 passed.
• bash -n scripts/install.sh scripts/configure.sh scripts/test-upgrade.sh — passed.
• node --check e2e/upgrade-persistence.mjs — passed.
• git diff --check origin/main...HEAD — passed.
• python3 scripts/check-public.py — passed.
• bash scripts/scan-secrets.sh — passed; no leaks found.

GitHub Actions validation with actionlint passed during implementation. Real Docker acceptance installed official v0.3.3 through its installer, then used the changed installer/Compose configuration with the official 0.3.4 image verified against its published manifest. Retained data, old SOP continuation, new SOP execution and repeated installation passed; disposable resources were cleaned up. This local acceptance used released binaries; it did not build an unreleased platform binary or re-run the live scenario after rebasing. The tag workflow validates the newly built image digest. Details are recorded in docs/validation.md.

Full Go/frontend/Local suites were not run for these deployment and installer changes. No tag or release was published.

Safety

• I did not include credentials, internal endpoints, production data, or organization-specific infrastructure.
• I preserved user files and unrelated changes.
• I updated generated Classic host bundles when applicable.
• I documented third-party content and licensing changes when applicable.

Classic bundles and third-party licensing changes are not applicable.

[Robert0622]

LoopForge PR Review — head ca0356934cbab0bb2407ab628474c5a90b112bab
Verdict: ✅ Pass

• Scope: 16 files, +522/-12. Gates platform releases on a real install→upgrade→reinstall cycle (scripts/test-upgrade.sh, .github/workflows/release.yml), adds scripts/release-upgrade-base.py to pick the preceding published stable tag, and preserves the platform container's workspace hostname across replacement (scripts/install.sh, scripts/configure.sh) to fix the reported v0.3.3→v0.3.4 HTTP 409 regression for existing workspaces.
• Local verification (isolated sandbox, no secrets/prod access):
  • bash -n scripts/install.sh scripts/configure.sh scripts/test-upgrade.sh — syntax OK.
  • python3 -m py_compile scripts/release-upgrade-base.py scripts/test-release-upgrade.py scripts/test-install.py — OK.
  • python3 scripts/test-release-upgrade.py -v — 6/6 pass (numeric-version ordering, excludes local/draft/prerelease tags, first release has no baseline, rejects non-platform targets).
  • python3 scripts/test-install.py -v — 37/37 pass, including the two new hostname-adoption cases (test_upgrade_adopts_legacy_container_hostname_and_keeps_it, test_upgrade_adopts_hostname_when_existing_setting_is_empty).
  • node --check e2e/upgrade-persistence.mjs — syntax OK.
• Not run locally: the real Docker-based scripts/test-upgrade.sh end-to-end (needs Docker, unavailable in this sandbox) and the release.yml promote/release-notes steps — CI-only. CI on this head (ca03569) is green across all 16 checks (platform-required, e2e-required, validate, etc.).
• No blocking issues found in the reviewed diff (idempotent .env host handling, shlex.quoted writes, release notes now written to a file instead of an inline heredoc, image promoted only after both install and upgrade checks pass).