Bug
On Electron app open, the UI briefly shows the first-run onboarding/welcome page, then switches to the existing project list. The onboarding page should only appear when there are actually no registered projects, not while daemon/API discovery is still settling.
Source: human report in AO session chat on 2026-07-08
Reported by: @chauhan
Analyzed against: f9a25a7467aaba3f17fbb4699d80e8a618ba3da6 in AgentWrapper/agent-orchestrator
Verified binary: /tmp/ao built from this checkout; /tmp/ao status reported ready on port 3001
Local state: /tmp/ao project ls showed existing projects (agent-orchestrator, punereads)
Confidence: High
Priority: medium — visible startup flicker/confusing first-run state; no data loss.
Reproduction
- Have at least one project registered in AO.
- Open the Electron app fresh.
- Watch the initial board content before the projects/sidebar list appears.
Expected
The onboarding/welcome page appears only when the authoritative project query has completed against the daemon and returned zero projects.
When projects exist, startup should show a loading/shell state until the real project list is known, then render the project list/board directly.
Actual
The app can briefly render the first-run onboarding page, then replace it with the project list once daemon discovery/API state catches up.
Root Cause
fetchWorkspaces() returns an empty array before the renderer has a trusted daemon API base URL:
frontend/src/renderer/hooks/useWorkspaceQuery.ts: if !hasTrustedApiBaseUrl(), it returns [].
React Query treats that [] as a successful workspace query result. The board then interprets isSuccess && all.length === 0 as a true first-run state:
frontend/src/renderer/components/SessionsBoard.tsx: showWelcome = !projectId && isLoaded && all.length === 0.
Later, when daemon status becomes ready, _shell invalidates the workspace query and the real /api/v1/projects + /api/v1/sessions result replaces the empty list:
frontend/src/renderer/routes/_shell.tsx: the daemon-ready effect invalidates workspaceQueryKey.
That makes the onboarding page a transient daemon-discovery placeholder rather than an authoritative no-projects state.
Fix Shape
Do not represent "API base not trusted yet" as an authoritative empty project list. Possible approaches:
- Make
fetchWorkspaces() stay pending or throw a typed not-ready state until the daemon API base is trusted.
- Gate
showWelcome on a query result that definitely came from /api/v1/projects, not the pre-daemon fallback [].
- Add a test that simulates
hasTrustedApiBaseUrl() === false followed by daemon-ready invalidation and asserts the welcome page does not flash when projects later exist.
Duplicate Search
Searched AgentWrapper/agent-orchestrator issues with:
onboarding page project list
Welcome to Agent Orchestrator projects
onboarding flash
hasTrustedApiBaseUrl
first launch welcome projects
No exact duplicate found.
Bug
On Electron app open, the UI briefly shows the first-run onboarding/welcome page, then switches to the existing project list. The onboarding page should only appear when there are actually no registered projects, not while daemon/API discovery is still settling.
Source: human report in AO session chat on 2026-07-08
Reported by: @chauhan
Analyzed against:
f9a25a7467aaba3f17fbb4699d80e8a618ba3da6inAgentWrapper/agent-orchestratorVerified binary:
/tmp/aobuilt from this checkout;/tmp/ao statusreported ready on port3001Local state:
/tmp/ao project lsshowed existing projects (agent-orchestrator,punereads)Confidence: High
Priority: medium — visible startup flicker/confusing first-run state; no data loss.
Reproduction
Expected
The onboarding/welcome page appears only when the authoritative project query has completed against the daemon and returned zero projects.
When projects exist, startup should show a loading/shell state until the real project list is known, then render the project list/board directly.
Actual
The app can briefly render the first-run onboarding page, then replace it with the project list once daemon discovery/API state catches up.
Root Cause
fetchWorkspaces()returns an empty array before the renderer has a trusted daemon API base URL:frontend/src/renderer/hooks/useWorkspaceQuery.ts: if!hasTrustedApiBaseUrl(), it returns[].React Query treats that
[]as a successful workspace query result. The board then interpretsisSuccess && all.length === 0as a true first-run state:frontend/src/renderer/components/SessionsBoard.tsx:showWelcome = !projectId && isLoaded && all.length === 0.Later, when daemon status becomes ready,
_shellinvalidates the workspace query and the real/api/v1/projects+/api/v1/sessionsresult replaces the empty list:frontend/src/renderer/routes/_shell.tsx: the daemon-ready effect invalidatesworkspaceQueryKey.That makes the onboarding page a transient daemon-discovery placeholder rather than an authoritative no-projects state.
Fix Shape
Do not represent "API base not trusted yet" as an authoritative empty project list. Possible approaches:
fetchWorkspaces()stay pending or throw a typed not-ready state until the daemon API base is trusted.showWelcomeon a query result that definitely came from/api/v1/projects, not the pre-daemon fallback[].hasTrustedApiBaseUrl() === falsefollowed by daemon-ready invalidation and asserts the welcome page does not flash when projects later exist.Duplicate Search
Searched
AgentWrapper/agent-orchestratorissues with:No exact duplicate found.