fix(model-b): first-launch onboarding + background-delivery gate (fixes the Connecting-to-network hang)

[torlando-tech]

First-launch background-delivery gate — fixes the "Connecting to network…" hang

The bug

The first real Model-B TestFlight build hung on "Connecting to network…" for minutes on first open, then limped to the UI with no working node.

Under Model B the Network Extension is the node, so ProxyRnsBackend.start() round-trips to the NE over the VPN tunnel session. But on a fresh install there's no VPN config, and nothing on the init path ever installed/started one — the only install()+start() call sites were the Settings / Background-Transport toggles, which are unreachable while the app is stuck on the loading screen behind that very start(). So backend.start() spun ~30×8s (connectedSession) on a dead session, then failed → no node. Bootstrap deadlock; every clean install hit it. (It only "worked" in dev because the tunnel was already installed+approved on the device.)

The fix — explicit first-run gate

A VPN-approval prompt is unavoidable for any NetworkExtension app; this makes it a deliberate step rather than a silent hang.

• AppServices.ensureBackgroundDeliveryTunnel() runs right before backend.start() (Model B only):
  • Returning users (approval persisted in the App-Group flag) → silent install → start → waitUntilConnected, no prompt.
  • First run (or if the silent reconnect can't connect, e.g. the user revoked the VPN in iOS Settings) → suspend init on a continuation and set needsBackgroundDeliveryApproval.
• RootView shows the new BackgroundDeliveryGateView while suspended (instead of an indefinite spinner). Its Enable button → approveBackgroundDelivery(): install()+start() (fires the iOS VPN prompt) → waitUntilConnected → persist approval → resume init, so backend.start() connects in seconds. Denied/timeout → error + Try Again (init stays suspended; never spins).
• TunnelManager.waitUntilConnected(timeoutMs:) added.
• Everything NE-specific is under #if ENABLE_NETWORK_EXTENSION; the Python flavor is untouched.

Verification

On-device (fresh background_delivery_enabled flag), the app now logs:

[RNS] identityBytes=64
[TUNNEL-GATE] awaiting background-delivery approval (showing gate)

— it suspends at the gate and never calls backend.start() until the tunnel is up. The multi-minute hang is gone and the gate is shown immediately. (The VPN "Allow" tap + connect is the user's manual step, as for any NE app.)

Model-B build (ColumbaNetworkExtension scheme, Debug-Swift) is green; the Python Columba scheme is covered by CI.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR fixes the Model-B first-launch hang ("Connecting to network…") by introducing an explicit VPN-approval gate (BackgroundDeliveryGateView) that suspends AppServices.initialize() via a CheckedContinuation until the Network Extension tunnel is confirmed connected before backend.start() is ever called.

• AppServices.ensureBackgroundDeliveryTunnel() (called inside startPythonBackend for Model B) checks a persisted approval flag: returning users get a silent reconnect; first-run (or revoked VPN) suspends init and exposes needsBackgroundDeliveryApproval for RootView to swap in BackgroundDeliveryGateView.
• TunnelManager.waitUntilConnected now delegates to the existing connectedSession polling loop, eliminating the near-duplicate logic flagged in a previous review.
• BackgroundDeliveryPage is added as onboarding step 5, letting users enable the VPN tunnel in-flow so that post-onboarding init takes the silent reconnect path immediately.

Confidence Score: 5/5

Safe to merge. The gate logic is sound and the CheckedContinuation is used correctly — resume() is always preceded by a nil-check and the optional is cleared immediately after, so double-resume on the @mainactor is not possible.

The gate mechanism is architecturally clean: the continuation is stored and resumed correctly, waitUntilConnected now delegates to connectedSession rather than duplicating the polling loop, and the @Observable/@mainactor observation chain that drives the RootView swap is correct. The only findings are a stale comment and a latent compile-guard gap that the current build configuration prevents from manifesting.

No files require special attention beyond the two minor items in OnboardingView.swift.

Important Files Changed

Filename	Overview
Sources/ColumbaApp/Services/AppServices.swift	Core gate logic: ensureBackgroundDeliveryTunnel, approveBackgroundDelivery, and enableBackgroundDeliveryForOnboarding added. The first initialize(tcpServerAddress:) overload remains missing ensureTunnelManager() (pre-existing latent issue already flagged in a prior review).
Sources/ColumbaApp/Services/TunnelManager.swift	waitUntilConnected added and now correctly delegates to connectedSession, fixing the near-duplicate polling loop flagged in a previous review.
Sources/ColumbaApp/Views/Onboarding/BackgroundDeliveryGateView.swift	New gate view; uses a plain let for appServices (addressing prior @bindable comment), disable-while-working guard, and error/retry path on denial.
Sources/ColumbaApp/Views/Onboarding/OnboardingView.swift	BackgroundDeliveryPage added as page 4; the onEnable closure calls enableBackgroundDeliveryForOnboarding (ENABLE_NETWORK_EXTENSION-only) without a compile-time guard, and the Skip button comment is now stale.
Sources/ColumbaApp/Views/Onboarding/BackgroundDeliveryPage.swift	New onboarding step for Model B; seeds interfaces before NE start, idempotent identity preparation, error/retry UI.
Sources/ColumbaApp/App/ColumbaApp.swift	RootView now swaps in BackgroundDeliveryGateView while needsBackgroundDeliveryApproval is true (under #if ENABLE_NETWORK_EXTENSION), replacing the indefinite spinner.
Sources/ColumbaApp/ViewModels/OnboardingViewModel.swift	seedInterfaces() added as a public idempotent helper; pageCount bumped to 6 for the new BackgroundDeliveryPage step.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App as ColumbaApp (RootView)
    participant AS as AppServices
    participant TM as TunnelManager
    participant Gate as BackgroundDeliveryGateView
    participant iOS as iOS VPN Subsystem

    App->>AS: initialize() [second overload]
    AS->>AS: ensureTunnelManager()
    AS->>AS: startPythonBackend()
    AS->>AS: ensureBackgroundDeliveryTunnel()

    alt "backgroundDeliveryEnabledKey == true (returning user)"
        AS->>TM: install() + start()
        AS->>TM: waitUntilConnected(20s)
        TM-->>AS: connected
        AS->>AS: return (silent reconnect)
    else first run or VPN revoked
        AS->>AS: withCheckedContinuation suspend
        AS->>AS: "needsBackgroundDeliveryApproval = true"
        App->>Gate: show BackgroundDeliveryGateView
        Gate->>AS: approveBackgroundDelivery()
        AS->>TM: install() + start()
        TM->>iOS: VPN Allow prompt
        iOS-->>TM: approved
        TM-->>AS: connected
        AS->>AS: persist backgroundDeliveryEnabledKey
        AS->>AS: "needsBackgroundDeliveryApproval = false"
        AS->>AS: continuation.resume()
        AS-->>Gate: return true
        Gate->>App: "isWorking = false, view swapped by RootView"
    end

    AS->>AS: backend.start()
    AS->>App: "isInitialized = true"
    App->>App: show MainTabView

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant App as ColumbaApp (RootView)
    participant AS as AppServices
    participant TM as TunnelManager
    participant Gate as BackgroundDeliveryGateView
    participant iOS as iOS VPN Subsystem

    App->>AS: initialize() [second overload]
    AS->>AS: ensureTunnelManager()
    AS->>AS: startPythonBackend()
    AS->>AS: ensureBackgroundDeliveryTunnel()

    alt "backgroundDeliveryEnabledKey == true (returning user)"
        AS->>TM: install() + start()
        AS->>TM: waitUntilConnected(20s)
        TM-->>AS: connected
        AS->>AS: return (silent reconnect)
    else first run or VPN revoked
        AS->>AS: withCheckedContinuation suspend
        AS->>AS: "needsBackgroundDeliveryApproval = true"
        App->>Gate: show BackgroundDeliveryGateView
        Gate->>AS: approveBackgroundDelivery()
        AS->>TM: install() + start()
        TM->>iOS: VPN Allow prompt
        iOS-->>TM: approved
        TM-->>AS: connected
        AS->>AS: persist backgroundDeliveryEnabledKey
        AS->>AS: "needsBackgroundDeliveryApproval = false"
        AS->>AS: continuation.resume()
        AS-->>Gate: return true
        Gate->>App: "isWorking = false, view swapped by RootView"
    end

    AS->>AS: backend.start()
    AS->>App: "isInitialized = true"
    App->>App: show MainTabView

Loading

_{Reviews (10): Last reviewed commit: "Model B: Settings network card lists act..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[torlando-tech]

@greptile review