Native fast iterative deploy

Summary

The deploy flow now supports a safer native worker iteration model without requiring public edge cutover first. It can run directly from the VPS checkout without SSH, emits phase timings, includes checked-in native unit files plus install/rollback/smoke-test helpers, and documents the staged cutover path. During live audit, the previously reported /replay/options proxy issue and duplicate islandflow compose stack were both confirmed resolved on the host.

Changes Made

• Extended scripts/deploy.ts with deploy timing summaries for precheck, rollout, and verification phases.
• Added --workers-only deploy scope for Docker and native runtimes.
• Changed native --fast behavior so default full-scope fast deploys become worker-only instead of touching web/API.
• Added native edge guardrails via DEPLOY_NATIVE_EDGE_READY=1 before web/API native deploys are allowed.
• Added local-server execution mode so ./deploy can run from /home/delta/islandflow without SSHing back into the same host.
• Added DEPLOY_SSH_KEY_PATH and DEPLOY_FORCE_SSH overrides for operators with non-default SSH setups.
• Checked in native ops assets under deployment/native/:
• install-user-units.sh, check-native-health.sh, rollback.sh
• six user unit files in deployment/native/systemd/user/
• Updated README.md, deployment/docker/README.md, and deployment/native/README.md to document the worker-first model, local execution mode, validation matrix, and staged cutover guidance.
• Synced deployment/docker/workspace-root/package.json so Docker workspace validation passes again.
• Installed the checked-in user unit files onto the live VPS in disabled form under ~/.config/systemd/user.

Context

The plan targeted faster deployment iteration while avoiding a premature move of the public edge away from the current Docker + Nginx Proxy Manager topology. The practical target was to make native runtime useful immediately for backend-worker iteration, while leaving web/API cutover deliberate and reversible.

Important Implementation Details

• Native fast mode now defaults to --workers-only; Docker fast mode still defaults to --services-only.
• Native deploys that include public web/API scope now fail fast unless DEPLOY_NATIVE_EDGE_READY=1 is set.
• Running from the live VPS checkout automatically switches deploy execution from SSH mode to local mode.
• The checked-in native unit files are user units aimed at the current VPS layout: /home/delta/islandflow and /home/delta/.bun/bin/bun.
• install-user-units.sh now installs units safely without enabling anything by default; enabling is explicit and scope-based.
• rollback.sh intentionally uses a detached git ref to make one-off native rollback practical without rewriting branch history.

export DEPLOY_NATIVE_SYSTEMCTL_PREFIX="systemctl --user"
./deploy main --runtime native --fast
# resolves to worker-only native deploy before public edge cutover

Expected Impact for End-Users

End-users should see indirect benefits first: faster backend iteration, safer operational changes, and clearer rollback paths. Public traffic behavior should remain unchanged until a deliberate native edge cutover is performed.

Validation

• Passed: bun run scripts/check-public-api-routes.ts https://flow.deltaisland.io
• Passed: direct public /replay/options curl returned JSON
• Passed: live Nginx Proxy Manager config contains /replay in the API route matcher
• Passed: docker compose ls shows no duplicate islandflow project
• Passed: bash -n deployment/native/install-user-units.sh deployment/native/check-native-health.sh deployment/native/rollback.sh
• Passed: systemd-analyze verify deployment/native/systemd/user/*.service
• Passed: bun run check:docker-workspace after syncing workspace snapshot
• Passed: native edge guard refusal for bun run scripts/deploy.ts main --runtime native --web-only --no-build
• Passed: ./deployment/native/install-user-units.sh followed by systemctl --user list-unit-files 'islandflow*'

Issues, Limitations, and Mitigations

• Native units were installed but not enabled or started. This is intentional to avoid conflicting with the current Docker production edge.
• Public web/API native deploys are still gated. Mitigation: explicit DEPLOY_NATIVE_EDGE_READY=1 acknowledgment and staged cutover documentation.
• Native worker runtime has not yet been exercised live against the existing Docker worker stack. Mitigation: follow-up issue to soak worker-only native units before any default-runtime decision.
• The known untracked Signal CLI tarball remains in the repo checkout. This is already tolerated by the deploy helper allowlist and was not changed here.

Follow-up Work

• Open follow-up: islandflow-vvw — stage native public-edge cutover after worker soak.
• Decide whether native should ever replace Docker as the default runtime only after worker soak data and deliberate edge cutover validation.