Updates and auto-recovery

This document explains the runtime internals behind Speedwave’s Update and auto-recovery mechanisms across macOS (Lima VM) and Windows (WSL2) environments.

Update installation and reconciliation state machine

When an update is confirmed, install_update_and_reconcile(expectedVersion) records currently active project workspaces, gracefully terminates running containers, applies the signed binary package, and restarts the application daemon. If installation fails prematurely, previous workspace containers are restored.

Following process restart, Speedwave inspects the application package’s bundle_id against the active configuration record. A mismatch transitions execution into an idempotent state machine:

1. Synchronize bundled claude-resources into persistent local directories.
2. Recompile container layers missing their deterministic input hash tag.
3. Execute transactional container recreation (--force-recreate) for previously active workspaces.

Container image compilation evaluates independent cryptographic hashes calculated from each Containerfile and local build inputs:

Rebuild trigger	Architectural effect
Missing input hash tag	Recompiles the specific container image layer.
Shared MCP base changes	Recompiles all dependent integration worker containers.
claude-resources updates	Synchronizes markdown and prompt assets without recompiling images.

Build input hashing

Cryptographic image tags hash local build sources and Containerfile specifications, allowing caching without locking external container base images.

Automated container health recovery

Speedwave automatically repairs stale container mounts following OS sleep states and recovers missing containers following system reboots. Prior to establishing interactive sessions, ensure_exec_healthy probes the project’s Claude container:

• Executes an exec probe.
• On stale mount or missing container detection, force-recreates the container instance.
• Re-probes container responsiveness, halting startup with actionable diagnostics if recovery fails.

On Windows, health checking monitors the underlying WSL2 subsystem directly, verifying containerd and buildkitd daemon statuses and automatically restarting services if unresponsiveness is detected.

On both platforms, the exec probe and the sign-in check that runs in the same container are limited to 60 seconds each, so a stalled container runtime surfaces as an error the interface can retry.

Container engine self-healing

Every compose up runs inside the virtual machine under a 180-second limit; when it expires, the whole nerdctl process group is stopped and the error says compose up did not finish within 180s. Two engine races are repaired automatically:

• Task creation race: containerd’s restart monitor can start the proxy container at the same moment compose up creates it, and the loser fails with file exists or already exists. Speedwave waits briefly and retries once; a single-service restart joins the container the other start already runs.
• Stale network chains: a container that crashed can leave its iptables chain behind, which blocks the next start. Speedwave removes the chain named in the error and retries.

A virtual machine that does not answer is reported as such (Container engine did not answer the image check) rather than as missing images, so Retry re-runs the check without a rebuild. Reading the VM state is limited to 10 seconds, and a failed read is never treated as a missing VM. Quitting the app and a factory reset stop the engine for good: a start still waiting in the queue cannot bring containers back while they shut down.

CLI update transaction lifecycle

Executing speedwave update (see CLI commands) enforces a complete transaction pipeline:

1. Validates host filesystem permissions.
2. Executes mandatory SecurityCheck audits (failing if security rules are violated).
3. Compiles missing container layers.
4. Generates an atomic configuration snapshot (~/.speedwave/snapshots/<project>/snapshot.json).
5. Recreates containers and validates container socket reachability.
6. Prunes obsolete image tags while preserving BuildKit build caches.

If updates fail following container destruction, Speedwave rolls back to the recorded snapshot state.

On Windows, the NSIS installer runs a clean-up step before every install or update: when Speedwave is installed in its default folder and the app is not running, it deletes the build-context, mcp-os, oauth, THIRD-PARTY-LICENSES and host_exec folders before copying the new version, so files removed from a release do not linger in image builds. For binary verification details, consult Binary authenticity.