fix: don't flash the empty-state screen while the agent is still scanning

[AprilNEA]

Follow-up to #212 — the startup sequence still flashed the device empty-state screen for users with paired devices.

Problem

While the agent's first enumeration is in flight (inventory_ready == false), the home body rendered the full empty-state screen — search icon, headline, Add-Device CTA, pairing hints — with only the headline swapped to "Scanning for devices…". For a user whose devices are about to appear that is still a "no devices" flash. And since the GUI polls on a 2 s timer, the gallery could lag a full period behind the agent actually knowing the devices.

Fix

• Scanning is unknown, not empty: while scanning is set, the home body shows the same quiet spinner frame as the pre-connection view (caption "Scanning for devices…", string already in all locales). The empty-state screen with its Add-Device CTA is reserved for a completed scan that genuinely found nothing. The two loading phases share one layout (loading_body), so startup renders as a single continuous frame whose caption changes, resolving into the gallery.
• Fast startup polling: the IPC client polls every 250 ms until the first inventory_ready snapshot arrives, then drops to the steady 2 s cadence; it falls back to fast when the connection is lost so an agent restart (binary-update exec, crash) re-converges just as quickly. A status+inventory round every 250 ms is noise for the agent.
• Docs: recorded the tarpc/bincode invariant that method order is part of the wire format — protocol_version stays first, new methods append-only — and why the protocol deliberately has no minor version (single-bundle shipping + agent self-exec make strict equality the whole contract).

Startup now (cold, devices paired)

connecting spinner (≈agent boot) → scanning spinner (≈one enumeration, sub-second with fast polling) → gallery. No empty-state flash at any point.

Verification

cargo test, full-workspace clippy pass; the scanning frame reuses the connecting-frame layout verified in #212.

[greptile-apps]

Greptile Summary

This PR fixes the empty-state flash during startup by separating "scan in progress" (scanning == true) from "scan complete, no devices found," so users with paired devices see a continuous spinner frame rather than a momentary add-device CTA. It also introduces fast 250 ms polling until the first inventory_ready snapshot arrives, then drops to the steady 2 s cadence.

• app.rs: Extracts a shared loading_body helper used by both connecting_view and the new device_scanning_state; the three home-body states (has devices → gallery, scanning → spinner, empty → CTA) are now cleanly separated.
• ipc_client.rs: Adds STARTUP_POLL_PERIOD (250 ms) with automatic promotion to the caller-supplied steady period on inventory_ready, and reversion to fast on poll-detected connection loss; the poll return type is widened to Ok(Some(inventory_ready)) / Ok(None) / Err to carry readiness without a separate channel.
• ipc.rs: Documentation-only addition recording the tarpc/bincode wire-format invariant (method order, append-only, no minor version).

Confidence Score: 4/5

The UI and state-management changes are correct and safe to merge. The fast-polling logic in ipc_client.rs has a gap: a connection drop caught by the command arm doesn't revert the interval to fast cadence, so agent restarts that happen mid-command recover more slowly than intended.

The cmd arm of the select! loop sets client = None on handle() error but does not reset steady or the interval, leaving recovery at the 2 s steady cadence instead of 250 ms. The poll arm correctly does this reset, and the UI and loading_body refactoring are clean, but the inconsistency in the command path contradicts the stated reconnect-speed guarantee.

crates/openlogi-gui/src/ipc_client.rs — the cmd arm's error path is missing the steady/interval reset that the poll arm has

Important Files Changed

Filename	Overview
crates/openlogi-gui/src/ipc_client.rs	Adds fast-startup polling (250 ms) that promotes to steady (2 s) on first inventory_ready, and reverts to fast on connection loss — but the cmd arm doesn't reset steady/interval on error, so an agent restart triggered during a command keeps polling at 2 s instead of 250 ms.
crates/openlogi-gui/src/app.rs	Extracts a shared loading_body helper, adds device_scanning_state using it, and properly separates the scanning-unknown path from the empty-state path — clean refactor with no issues.
crates/openlogi-agent-core/src/ipc.rs	Documentation-only addition explaining the tarpc/bincode wire-format invariant (method order, append-only evolution, no minor version). No logic changes.

Sequence Diagram

sequenceDiagram
    participant GUI as GUI (app.rs)
    participant IPC as ipc_client.rs
    participant Agent

    Note over GUI: AppState.scanning = true
    GUI->>GUI: connecting_view (loading_body)

    loop Every 250 ms (STARTUP_POLL_PERIOD)
        IPC->>Agent: ensure() + inventory() + status()
        alt agent not up yet
            Agent-->>IPC: Err (socket not bound)
            IPC-->>IPC: Ok(None) — keep fast cadence
        else "agent up, inventory_ready = false"
            Agent-->>IPC: Ok(Some(false))
            IPC-->>GUI: "PollUpdate (scanning=true)"
            GUI->>GUI: device_scanning_state (loading_body)
        else "agent up, inventory_ready = true"
            Agent-->>IPC: Ok(Some(true))
            IPC-->>IPC: "steady=true, switch to poll_period (2s)"
            IPC-->>GUI: "PollUpdate (scanning=false)"
            alt devices present
                GUI->>GUI: device_gallery
            else no devices
                GUI->>GUI: device_empty_state
            end
        end
    end

    Note over IPC: On poll Err() (dropped connection)
    IPC-->>IPC: "steady=false, revert to 250 ms"

Loading

Comments Outside Diff (1)

1. crates/openlogi-gui/src/ipc_client.rs, line 153-158 (link)

   Fast-polling not restored on command-arm connection drop

   When handle() returns Err(()), client is set to None but steady is left true and the interval remains at poll_period (2 s). Because ensure() returns Ok(None) (not Err(())) while the agent is still coming back up, the poll arm's Err branch never fires to reset steady and the interval. The PR explicitly states "falls back to fast when the connection is lost so an agent restart (binary-update exec, crash) re-converges just as quickly", but that only holds for drops detected by the poll arm, not here. Recovery after a mid-command agent restart polls at 2 s cadence instead of 250 ms — up to 8× slower.

   Mirroring the poll arm's Err block here fixes it:

   if handle(&mut client, cmd).await.is_err() {
       client = None;
       if steady {
           steady = false;
           interval = tokio::time::interval(STARTUP_POLL_PERIOD);
       }
   }

   

_{Reviews (2): Last reviewed commit: "fix(gui): don't double-poll on the stead..." | Re-trigger Greptile}