archy/docs/RESUME.md

RESUME — Rust orchestrator migration, Step 8b

Last updated: 2026-04-23 (evening, post-architecture-audit)

Read this first if you're a fresh OpenCode session resuming work. Paste the "Resume prompt" below verbatim.

---

Resume prompt (paste this into a new opencode session)

We are mid-migration: docs/rust-orchestrator-migration.md + docs/bulletproof-containers.md are the plan, Steps 1–7 + 8a are shipped on main, Step 8b is next. Read docs/RESUME.md + docs/STEP-8B-PORT-AUDIT.md in full. Do NOT run any container mutations or edit scripts/container-specs.sh, scripts/first-boot-containers.sh, or scripts/reconcile-containers.sh — those are dead code scheduled for deletion in Step 8c. Work happens in core/container/src/manifest.rs, core/archipelago/src/container/prod_orchestrator.rs, and apps/<id>/manifest.yml. Summarize back to me what you understand the current state to be, wait for approval before touching anything.

---

Standing directive from the user

Please get back to a well architected, minimal as possible, perfect working container architecture. If we've gone off track and the system is getting complex rather than elegant and perfect best containers ever then we need to review all the current state of the system and get back to making the best container system ever and according to our projects goals. We will be working on this until it's perfect.

Interpretation (validated with the user): resume the Rust orchestrator migration. Stop patching bash scripts. The bash scripts were supposed to be deleted three months of commits ago and we drifted into maintaining them by accident.

Latest user comment (must be followed)

please continue, please state my last comment in the resume doc and first before making this plan to adhere to

Adherence rule for this session:

• Before proposing or executing a plan, first record the user's latest directive in docs/RESUME.md.
• Keep work aligned to Step 8 migration goals and avoid off-scope drift.

Most recent directive:

And we need to get every container working on .116 and tested before we release

Release gate update:

• .116 must have all required containers healthy and tested before release is allowed.
• Treat runtime stabilization on .116 as immediate priority while continuing Step 8 migration work.

---

Where we actually are

Shipped (Steps 1–7 + 8a)

Commits on main (unpushed to origin/tx1138 until release gate; user-visible history):

Step	Commit	What
1	(schema in place from earlier commits)	ContainerConfig.image ⊕ ContainerConfig.build — mutually exclusive pull-or-build source
2	34af4d9d	ContainerRuntime trait gains image_exists + build_image; PodmanRuntime impl
3	b6a04d31	ProdContainerOrchestrator with build-or-pull + adoption + reconcile
4	e8a59c93	ContainerOrchestrator trait; RpcHandler uses it in prod
5	fc39b04b	BootReconciler — periodic reconcile loop
6	48f08aa3	Wire both into main.rs
7	069bc4a5	bitcoin-ui pre-start hook renders nginx.conf from embedded template (the pattern for "derived config" at apply time)
8a	a0707f4d, 1c81a739	Retire archipelago-reconcile systemd timer; split Step 8 into 8a/8b/8c

Three apps/*/manifest.yml are genuinely ported and running under the Rust orchestrator on .116 + .228: bitcoin-ui, electrs-ui, lnd-ui (Step 7).

Where we drifted (the session that produced the previous RESUME.md)

On 2026-04-23 a fedimint outage on .116 pulled a session into patching scripts/reconcile-containers.sh, scripts/container-specs.sh, scripts/first-boot-containers.sh — files that Step 8c is scheduled to delete. Five bugs deep, the user halted the session. That cluster of bugs is a symptom of running two incompatible codepaths in parallel (bash first-boot/reconcile + Rust BootReconciler), which is exactly the condition Step 8c fixes by deleting the bash half.

Discard-of-scope decision: the uncommitted bash edits on .116 (listed in the previous RESUME.md's "Uncommitted script changes" section) are not going to be committed. The fedimint mDNS-URLs fix, the filebrowser custom-args fix, the bcrypt-escape fix — these all land as changes to apps/<id>/manifest.yml + the Rust orchestrator in Steps 8b.0 – 8b.3. See docs/STEP-8B-PORT-AUDIT.md for the exact mapping.

Current container state on .116

Running but drifted. See the "Current container state" section in the previous RESUME.md. Decision (approved by user): accept .116 is limping until 8b.3 lands. Do not run scripts/reconcile-containers.sh or any mutations; all rescues go through the Rust orchestrator or wait for the manifest port.

.228 is happier — it's already adopted by the Rust orchestrator for the three UI apps.

---

Next step — Step 8b.0

Concretely: schema extensions to core/container/src/manifest.rs + unit tests. No orchestrator changes, no manifest changes, no container mutations.

Fields to add (justified in docs/STEP-8B-PORT-AUDIT.md§Schema gaps):

• container.network: Option<String> — podman --network value ("archy-net", "host", or None = isolated default).
• container.custom_args: Vec<String> — appended to the container command.
• container.entrypoint: Option<Vec<String>> — override.
• container.derived_env: Vec<{key, template}> — template strings resolved against HostFacts { host_ip, host_mdns, disk_gb } at apply time.
• container.secret_env: Vec<{key, secret_file}> — read from /var/lib/archipelago/secrets/<file> at apply time.
• container.data_uid: Option<String> — "NNNNN:NNNNN" applied via chown -R before container create.
• Volume.volume_type: "tmpfs" + Volume.tmpfs_options: String — OR a new container.tmpfs: Vec<{target, options}>. Pick one at implementation time.

Tests (block the commit until green):

• Every existing apps/*/manifest.yml still parses (parse_every_real_manifest test).
• Each new field parses correctly with sensible defaults.
• validate() rejects: empty custom_args elements, empty entrypoint elements, duplicate derived_env keys, derived_env templates referencing unknown host facts, secret_env with .. or / in secret_file (path-traversal guard).
• resolve_env(HostFacts) returns expected strings for each supported placeholder.
• resolve_secret_env(SecretsProvider) returns expected strings; missing secret file is a hard error.

This is the smallest useful commit and unblocks every port in 8b.1+.

---

Project ground rules (standing)

• archy SSH alias = .116. archy228 = .228. Do not swap.
• SSHFS at /Users/dorian/mnt/archy-thinkpad/ = archy:Projects/archy/.
• .116 sudo password: ThisIsWeb54321@ — works passwordless in-session via sudo -nS after first use.
• .228 has NOPASSWD.
• Git commits on .116 MUST use git commit -F /tmp/tmp-msg.txt over ssh archy — SSHFS git commit hangs.
• Never push except current release (granted: gitea-local + gitea-vps2).
• No em-dashes. Conventional Commits.
• No altcoin mentions, Bitcoin-only.

---

Recommended next action for the fresh session

1. Read this file + docs/STEP-8B-PORT-AUDIT.md + the "Open decisions" section of the audit.
2. Answer the four open decisions (or confirm the recommended defaults).
3. Implement 8b.0 commit 1: add network, custom_args, entrypoint, derived_env, secret_env, data_uid fields to ContainerConfig + validation + unit tests. Backwards-compat: every existing apps/*/manifest.yml must still parse.
4. Commit + cargo test -p archipelago-container + stop.

Do not touch scripts/*.sh. Do not run reconcile-containers.sh. Do not live-test on .116 or .228 until the schema + orchestrator pieces in 8b.0 + 8b.1 are both in.

---

Recent release (out of scope, for grep context)

v1.7.43-alpha shipped yesterday: tarball-only OTA, async install/uninstall/update lifecycle, install UX polish, .23 VPS retirement. Manifest at gitea-local + gitea-vps2. .228 on the new binary. See docs/STATUS.md for the full rundown.

Earlier session notes (container rescue on .116, "never fails" directive, env-drift detector experiment) are obsolete — superseded by this file. The directive ("never fails") is honored by the Step 8 migration itself: a declarative manifest regenerated on every reconcile tick can't bake stale IPs into consensus data because the env comes from derived/secret sources that are re-resolved every apply.