fusion/docs/solutions/logic-errors/terminal-bootstrap-list-serialized-before-auto-create.md

category, module, tags, problem_type, applies_when

category	module	tags	problem_type	applies_when
logic-errors	dashboard-terminal	terminal bootstrap latency websocket xterm performance	unnecessary-serialization	A client bootstrap sequence gates a decision-irrelevant network round trip in front of the round trip that actually creates the resource the user is waiting on.

Terminal initial load blocked by a no-op session-list round trip (FN-7686)

Problem

Opening the dashboard terminal rendered the terminal chrome immediately but the xterm surface stayed blank for seconds before the first shell prompt/output appeared. The delay lived in the bootstrap sequencing, not in xterm rendering or steady-state I/O.

useTerminalSessions.ts's validateAndRestore() effect always called listTerminalSessions() (bounded by BOOTSTRAP_LIST_TIMEOUT_MS = 15000) and did not set isReady=true — the gate the auto-create effect waits on — until that HTTP round trip resolved. On a fresh open (no persisted kb-terminal-tabs), that round trip's result is provably discarded: with zero local tabs, the stale-session filter always reduces to an empty array regardless of what the server returns. The list call was validation in name only, yet it fully serialized in front of createTerminalSession() — the round trip that actually spawns the PTY session the terminal needs before a WebSocket can even attempt to connect.

Root cause pattern

A bootstrap step (list) is unconditionally awaited before a dependent step (create), even when the first step's result cannot change the second step's outcome for a specific precondition (here: nothing to validate). This is the general "unnecessary round-trip serialization" trap — the code reads as "validate then create" but for one common branch, "validate" does nothing.

Fix

Skip the list-validation round trip entirely when readTabsFromStorage(projectId) is empty on mount, and mark serverAvailable=true/isReady=true immediately so the auto-create effect is not gated behind a discardable network call. Leave the list call fully in place whenever there ARE persisted tabs to validate (that case IS decision-relevant — the server tells you which sessionIds still exist).

// packages/dashboard/app/hooks/useTerminalSessions.ts
if (readTabsFromStorage(projectId).length === 0) {
  setServerAvailable(true);
  setIsReady(true);
  return; // skip listTerminalSessions() — nothing to validate
}

Guardrails preserved

• generationRef staleness guards against stale bootstrap completions.
• Windows no-auto-create suppression (unchanged — still runs before this branch).
• bootstrapCreateInFlightGenerationRef create-dedup and the setTimeout(…, 0) micro-guard.
• The 15s BOOTSTRAP_LIST_TIMEOUT_MS/BOOTSTRAP_CREATE_TIMEOUT_MS bounds (unchanged for the reload-with-persisted-tabs path).
• --login shell profile execution (left untouched — real, environment-dependent cost, not "fixed" by dropping shell setup).

What was ruled out with evidence (do not re-attempt without new evidence)

• xterm dynamic import/init (TerminalModal.initTerminal) — already runs concurrently with session bootstrap; not serialized.
• READY_QUIET_WINDOW_MS/resize-suppression buffering — bounded at 150ms.
• resolveScopedStore (multi-project) — resolves synchronously from an already-live engine on the warm-project path.
• WebSocket connect gated behind session creation — inherent and correct; a session must exist before its socket can open.

Regression command

pnpm --filter @fusion/dashboard exec vitest run app/hooks/__tests__/useTerminalSessions.test.ts app/hooks/__tests__/useTerminal.test.ts app/components/__tests__/TerminalModal.test.tsx --silent=passed-only --reporter=dot

The key regression (bootstrap sequencing (FN-7686) describe block in useTerminalSessions.test.ts) holds listTerminalSessions() permanently pending on a fresh (empty-localStorage) mount and asserts auto-create still completes — this fails pre-fix (timeout) and passes post-fix.