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.

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. For binary verification details, consult Binary authenticity.