docs: capture 1.8 app migration release plan
This commit is contained in:
archipelago
@@ -0,0 +1,216 @@
|
||||
# Current Agent Handoff - Bitcoin UI Recovery And `1.8-alpha` Resume
|
||||
|
||||
Last updated: 2026-06-10 05:33 EDT
|
||||
|
||||
## Read This First
|
||||
|
||||
This is a separate handoff from `docs/NEXT_TERMINAL_HANDOFF.md`. That file tracks
|
||||
an older/broader plan. For the next agent resuming this machine-switch pause,
|
||||
read this file first, then read:
|
||||
|
||||
- `docs/RESUME.md`
|
||||
- `docs/1.8-alpha-improvements-tracker.md`
|
||||
- `docs/CONTAINER_LIFECYCLE_HANDOFF.md`
|
||||
- `docs/MIGRATION_STATUS_REPORT.md`
|
||||
|
||||
Do not assume `docs/NEXT_TERMINAL_HANDOFF.md` is the current short-term plan.
|
||||
|
||||
## Current Goal
|
||||
|
||||
Cut Archipelago `1.8-alpha`, including a ready-to-test ISO image.
|
||||
|
||||
The release goal is not just "apps launch once"; the app/container system needs
|
||||
to be developer-ready and production-release ready:
|
||||
|
||||
- manifests and docs must describe the real runtime contract;
|
||||
- apps must install, start, stop, restart, uninstall, reinstall, survive reboot,
|
||||
report truthful status, and show useful progress;
|
||||
- My Apps must preserve last-known truth during Podman/scanner backoff instead
|
||||
of showing false empty/no-app states;
|
||||
- Bitcoin-dependent apps must explain sync/wallet readiness instead of looking
|
||||
broken;
|
||||
- final validation needs focused lifecycle, broad non-destructive lifecycle,
|
||||
then repeated reboot checks before ISO cut/smoke test.
|
||||
|
||||
## Current Estimate
|
||||
|
||||
As of this pause:
|
||||
|
||||
- Credible release candidate: roughly `87-91%`.
|
||||
- Production-quality release developers will love: roughly `73-79%`.
|
||||
- Calendar estimate if the remaining systemic lifecycle issues are bounded:
|
||||
`1-2 focused engineering days` for a release candidate, then additional
|
||||
reboot/ISO smoke time.
|
||||
- The biggest remaining risk is not catalog wiring; it is rootless Podman
|
||||
control-plane responsiveness, stale scanner state, lifecycle progress UX, and
|
||||
reboot validation.
|
||||
|
||||
## Validation Host
|
||||
|
||||
- Host: `192.168.1.198`
|
||||
- SSH user: `archipelago`
|
||||
- Password used in this session: `password123`
|
||||
- Active Bitcoin app on this host: `bitcoin-knots`, not `bitcoin-core`
|
||||
- Keep `archipelago-doctor.timer` and `archipelago-reconcile.timer` inactive
|
||||
for deterministic validation unless intentionally testing them.
|
||||
- Preserve app data.
|
||||
- Avoid broad Podman store/image cleanup commands on `.198`.
|
||||
|
||||
## Bitcoin UI Incident Summary
|
||||
|
||||
User reported the Bitcoin custom UI showing:
|
||||
|
||||
`Bitcoin node is starting or busy syncing; retrying automatically. Detail:
|
||||
getblockchaininfo: Bitcoin RPC request failed ... operation timed out`
|
||||
|
||||
Then after listener repair, the message changed through:
|
||||
|
||||
- `Connection refused`
|
||||
- `Verifying blocks...`
|
||||
- then the user reported it looked fine again.
|
||||
|
||||
What happened:
|
||||
|
||||
- The node is a `bitcoin-knots` node.
|
||||
- During live debugging, the wrong alias, `bitcoin-core`, was started/stopped.
|
||||
- `bitcoin-core` and `bitcoin-knots` compete for the same Bitcoin RPC/P2P ports.
|
||||
- That action left the real `bitcoin-knots` service active but without the host
|
||||
`8332` rootlessport listener for a while.
|
||||
- Stopping the stray `bitcoin-core.service` and restarting only
|
||||
`bitcoin-knots.service` recreated listeners on `8332` and `8333`.
|
||||
- After restart, bitcoind entered the normal `-28 Verifying blocks...` phase.
|
||||
- The user later reported the Bitcoin UI looked fine again.
|
||||
|
||||
Known live state observed during recovery:
|
||||
|
||||
- `bitcoin-knots.service`: active
|
||||
- `bitcoin-core.service`: inactive
|
||||
- `archy-bitcoin-ui.service`: active
|
||||
- listeners present after repair:
|
||||
- `8332` via `rootlessport`
|
||||
- `8333` via `rootlessport`
|
||||
- `8334` via nginx/Bitcoin UI
|
||||
- `bitcoin-knots` logs showed active IBD around height `4137xx` and progress
|
||||
about `0.09438`.
|
||||
|
||||
Do not restart Bitcoin again unless there is a fresh confirmed service/listener
|
||||
failure. If checking status, prefer read-only probes and avoid starting the
|
||||
wrong variant.
|
||||
|
||||
## Source Fixes Made Locally
|
||||
|
||||
These local edits were made after live Bitcoin recovered. They are not deployed
|
||||
yet and were not fully validated before the user paused.
|
||||
|
||||
### `core/archipelago/src/bitcoin_status.rs`
|
||||
|
||||
Changed Bitcoin status cache behavior and copy:
|
||||
|
||||
- refresh interval changed from `5s` to `10s`;
|
||||
- transient error backoff added at `15s`;
|
||||
- RPC client timeout increased from `8s` to `20s`;
|
||||
- error context now uses full anyhow chain with `{e:#}`;
|
||||
- transient classifications now include common overloaded/backend states;
|
||||
- user-facing copy now distinguishes:
|
||||
- `verifying blocks after restart`;
|
||||
- `waiting for the Bitcoin RPC listener`;
|
||||
- `busy and not answering RPC before the timeout`;
|
||||
- generic `starting or busy syncing`;
|
||||
- added unit tests for the three user-visible states above.
|
||||
|
||||
Intent: stop collapsing distinct backend states into the same stale
|
||||
"starting or busy syncing" timeout message.
|
||||
|
||||
### `core/archipelago/src/api/rpc/package/update.rs`
|
||||
|
||||
Narrow Bitcoin alias fix added:
|
||||
|
||||
- `orchestrator_update_app_id("bitcoin-knots")` now remains
|
||||
`"bitcoin-knots"` instead of mapping to `"bitcoin-core"`;
|
||||
- candidate app IDs for a Bitcoin container now prefer `bitcoin-knots` before
|
||||
`bitcoin-core`;
|
||||
- tests updated to lock this behavior.
|
||||
|
||||
Intent: `bitcoin-core` and `bitcoin-knots` can be dependency/status aliases,
|
||||
but must not be interchangeable lifecycle/update targets on a node that has a
|
||||
specific installed variant.
|
||||
|
||||
Important: this file also already contained other uncommitted update/pull
|
||||
timeout changes from prior work. Do not assume every diff in this file came
|
||||
from this interruption.
|
||||
|
||||
## Validation Status At Pause
|
||||
|
||||
Completed:
|
||||
|
||||
- `cargo fmt --manifest-path core/Cargo.toml --all` passed after the local
|
||||
Bitcoin edits.
|
||||
|
||||
Attempted but not completed:
|
||||
|
||||
- Targeted Cargo tests were first launched in three separate `/tmp` target dirs
|
||||
and failed due `/tmp` filling with `No space left on device`.
|
||||
- Those temporary dirs were removed:
|
||||
- `/tmp/archy-cargo-bitcoin-status`
|
||||
- `/tmp/archy-cargo-update-alias`
|
||||
- `/tmp/archy-cargo-container-candidates`
|
||||
- A second run using `CARGO_TARGET_DIR=.codex-tmp/cargo-bitcoin-fix` was still
|
||||
compiling when the user paused. It was terminated for handoff.
|
||||
- No successful Rust test result exists yet for the new Bitcoin status/alias
|
||||
tests.
|
||||
|
||||
Recommended validation after resume:
|
||||
|
||||
```bash
|
||||
git diff --check -- core/archipelago/src/bitcoin_status.rs core/archipelago/src/api/rpc/package/update.rs docs/CURRENT_AGENT_HANDOFF.md
|
||||
CARGO_TARGET_DIR=.codex-tmp/cargo-bitcoin-fix CARGO_BUILD_JOBS=2 cargo test --manifest-path core/Cargo.toml -p archipelago bitcoin_status::tests
|
||||
CARGO_TARGET_DIR=.codex-tmp/cargo-bitcoin-fix CARGO_BUILD_JOBS=2 cargo test --manifest-path core/Cargo.toml -p archipelago update_aliases_map_to_manifest_app_ids
|
||||
CARGO_TARGET_DIR=.codex-tmp/cargo-bitcoin-fix CARGO_BUILD_JOBS=2 cargo test --manifest-path core/Cargo.toml -p archipelago container_name_candidates_cover_common_aliases
|
||||
```
|
||||
|
||||
If Cargo target locking appears stale, check for real `cargo`/`rustc` workers
|
||||
before deleting anything. Prefer workspace-local target dirs under `.codex-tmp`
|
||||
over new cold `/tmp` targets.
|
||||
|
||||
## Immediate Next Steps
|
||||
|
||||
1. Confirm no lingering Cargo process:
|
||||
|
||||
```bash
|
||||
pgrep -af "cargo|rustc|cargo-bitcoin-fix"
|
||||
```
|
||||
|
||||
2. Validate the local Bitcoin source fixes listed above.
|
||||
|
||||
3. If validation passes, build/deploy the backend to `.198` only after
|
||||
confirming the user still wants deployment.
|
||||
|
||||
4. Recheck live Bitcoin non-destructively:
|
||||
|
||||
- `bitcoin-knots.service` active;
|
||||
- `bitcoin-core.service` inactive;
|
||||
- listeners on `8332`, `8333`, `8334`;
|
||||
- Bitcoin UI loads on `8334`;
|
||||
- `/bitcoin-status` returns useful copy if backend is busy.
|
||||
|
||||
5. Resume release backlog:
|
||||
|
||||
- rootless Podman lifecycle/control-plane responsiveness;
|
||||
- My Apps last-known-state truthfulness during scanner backoff;
|
||||
- progress UX for install/uninstall/start/stop/restart;
|
||||
- remaining tracker rows in `docs/1.8-alpha-improvements-tracker.md`;
|
||||
- focused lifecycle matrix on `.198`;
|
||||
- broad non-destructive lifecycle;
|
||||
- 3 clean reboot validations minimum, 5 preferred;
|
||||
- ISO cut and ISO smoke test.
|
||||
|
||||
## Cautions For Next Agent
|
||||
|
||||
- Do not start `bitcoin-core` on `.198` unless intentionally migrating variants.
|
||||
- Treat `bitcoin-knots` as the installed Bitcoin variant.
|
||||
- Do not run broad Podman prune/store cleanup.
|
||||
- Do not revert unrelated dirty worktree changes.
|
||||
- `docs/NEXT_TERMINAL_HANDOFF.md` exists but is not the short-term handoff for
|
||||
this pause.
|
||||
- Many repo files are dirty from broader release hardening. Read diffs before
|
||||
attributing changes.
|
||||
Reference in New Issue
Block a user