fix(firstrun): stop the setup screen timing out while it waits for you (#1376)

[debpalash]

Closes #1376.

The bug

BootstrapSplash.jsx flips any stage that sits still past a budget to failed, so a wedged bootstrap surfaces Retry and logs instead of an info-less spinner (#879). That is correct for every stage the machine owns.

awaiting_setup is not one of them:

First run with nothing installed: parked on the setup screen waiting for the user to confirm an install plan (mode, storage, mirrors). Nothing downloads or installs in this stage — complete_setup is the only way out of it.
— bootstrap.rs:24

It is the screen where you pick install mode, storage locations, region and mirrors. Built for deliberation — and given the default 120-second fuse.

const stallBudgetMs = (stage) => (stage === 'installing_deps' ? 20 * 60 * 1000 : 120 * 1000);

Read the setup screen for two minutes and the app declares "Setup failed — the backend never reported ready", replaces the setup screen, and returns out of the IPC poll. Retry re-enters the bootstrap, which parks at awaiting_setup again and fails again on the same clock.

There is no way out by retrying, and it lands on the first screen a new install ever shows.

Reproduced live

On a clean bun desktop-prod install, at the moment of failure:

• tauri.log ends at First run — awaiting setup screen confirmation before installing
• the app data dir is completely empty — no venv, no attempt
• complete_setup's own "Setup complete (…) — starting bootstrap" log line never appears

Nothing was ever attempted. The UI gave up on the user, then blamed the backend.

Fix

A stage only a person can leave cannot be judged stalled, so awaiting_setup gets no budget. AwaitingSetup is the only human-gated stage in the enum; every other one is bounded machine work and keeps its budget unchanged.

Tests

Three, in BootstrapSplashAwaitingSetupStall.test.jsx:

1. the setup screen survives ten minutes — fails before (expected 'failed' to be 'awaiting_setup')
2. it still hands off the moment the plan is submitted — fails before
3. a genuinely wedged starting_backend still fails — passes before and after, so this does not trade [Crash] Backend died (exit code 1) #1376 back for [Bug] After Windows BSOD/unclean shutdown, app stuck at "preparing" — WebView2 cache corruption blocks Tauri IPC custom protocol #879

Frontend suite: 1703 passed. Typecheck, format and lint clean.

The setup screen no longer times out while users select an installation plan because awaiting_setup is excluded from bootstrap stall detection. Machine-controlled stages retain their existing timeout limits, with tests covering prolonged setup, submission handoff, and stalled starting_backend detection. Review the timer exemption because setup can now remain active indefinitely if user input or setup progress never occurs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 03566025-889c-4b3c-a63c-ae2ccec8e6f3

📥 Commits

Reviewing files that changed from the base of the PR and between 129fee7 and f5f9bae.

📒 Files selected for processing (3)

• CHANGELOG.md
• frontend/src/components/BootstrapSplash.jsx
• frontend/src/test/BootstrapSplashAwaitingSetupStall.test.jsx

---

📝 Walkthrough

Walkthrough

The bootstrap stall policy now keeps the first-run setup stage active without a timeout. Existing timeout budgets remain for dependency installation and other stages. Tests cover prolonged setup, normal progression, and stalled backend startup.

Changes

Bootstrap timeout behavior

Layer / File(s)	Summary
Setup stall policy and validation frontend/src/components/BootstrapSplash.jsx, frontend/src/test/BootstrapSplashAwaitingSetupStall.test.jsx, CHANGELOG.md	awaiting_setup now uses an unlimited stall budget. Tests verify setup retention, transition to installing_deps, and timeout failure for stalled starting_backend. The changelog records the removed setup timeout.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 7 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The linked issue reports a Transformers backend crash, but this PR only fixes the first-run setup timeout.	Link this PR to the setup-timeout issue, or add changes that resolve the Transformers crash described in #1376.
Out of Scope Changes check	⚠️ Warning	The implementation addresses a setup-screen timeout that is unrelated to the linked issue's Transformers backend crash.	Relink the PR to the issue covering the setup-screen timeout, or remove the unrelated timeout changes.

✅ Passed checks (7 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses Conventional Commit format with scope and includes issue #1376.
Description check	✅ Passed	The description explains the bug, fix, tests, and validation results, but omits the repository template headings and checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Cross-Platform Default Parity	✅ Passed	The shared hook returns Infinity for awaiting_setup without platform checks, and Rust enters AwaitingSetup through the common first-run path on macOS, Windows, and Linux.
I18n Completeness (21 Locales)	✅ Passed	The frontend patch adds no t(...) keys or user-facing JSX strings; it only changes stall-budget logic and comments. All 21 locale JSON files exist and parse successfully.
Local-First Guarantee	✅ Passed	The PR only changes the local stall budget and adds mocked tests; it adds no cloud calls, accounts, keys, telemetry, dependencies, or configuration, and existing health probes target loopback.
Backward Compatibility	✅ Passed	The PR changes only BootstrapSplash stall handling, the changelog, and tests; it adds no DB/schema, omnivoice_data, engine, or model-installation changes, so no migration or re-download is required.

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}