القائمة
Known bugs and root causes encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
How the multi-backend adapter system works — AgentAdapter interface, ACP protocol, session resume, and how to add new provider adapters
When debugging why an agent has the wrong provider/model, or when modifying agent creation or delegation flows.
How to get agents to use group chats for peer coordination in flightdeck-based crews. Covers hub-and-spoke anti-pattern, auto-grouping triggers, and file-lock-linked groups. Use when setting up multi-agent crews with 3+ agents or diagnosing why agents aren't collaborating directly.
When fetching from the `/coordination/activity` API and you only need specific action types (e.g., `progress_update`, `task_completed`, `delegated`).
When fetching activity data for UI display, or debugging why activity-based features show empty/stale data.
Architecture decisions and patterns from Flightdeck development (Phases 2–4). Covers feature architecture, state management, component patterns, and API design.
| name | common-bugs |
| description | Known bugs and root causes encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue. |
Bugs encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue.
/api/ PrefixSymptom: API calls return HTML instead of JSON, 404 errors.
Cause: apiFetch() already prepends /api. Writing apiFetch('/api/projects') produces /api/api/projects.
Fix: Use apiFetch('/projects') — no /api prefix.
Symptom: Network tab shows hundreds of identical requests, browser freezes.
Cause: Putting setState return value or fetched data in useCallback/useEffect dependency arrays creates a render → fetch → setState → render cycle.
Fix: Use refs for mutable values that shouldn't trigger re-renders, or move fetch logic into the effect body.
Symptom: Overview page shows blank panels despite data existing. Cause: Multiple possible issues:
SessionReplay.ts KEYFRAME_TYPES must map activity actionType to keyframe type.leadId vs projectId confusion — some APIs filter by one, frontend passes the other.'Created &' prefix in activity label — if format changes, agents aren't detected.
Fix: Check KEYFRAME_TYPES mapping, verify API query parameters, check activity label format.Symptom: TypeError when rendering agent details or activity data.
Cause: API returns nested objects (e.g., { status: { phase: "running" } }), but component expects strings.
Fix: Use a safeText() helper: typeof val === 'object' ? JSON.stringify(val) : String(val).
Symptom: Chart axis labels, tick marks disappear on dark background.
Cause: SVG <text> ignores CSS classes and CSS variables. Default fill is black (#000), invisible on dark bg.
Fix: Pass fill="#9ca3af" directly via tickLabelProps or inline style. Never rely on Tailwind/CSS for SVG text color.
Symptom: Clicking a link reloads the entire app, losing state.
Cause: Using <a href="/path"> instead of React Router <Link to="/path">.
Fix: Replace all internal <a href> with <Link to> from react-router-dom.
Symptom: Component exists in DOM (visible in DevTools) but not visible on screen.
Cause: Parent container has overflow: hidden and the component renders below the visible area.
Fix: Either move the component outside the clipped container, make it position: sticky, or change overflow: hidden to overflow: auto.
Symptom: Console warning about passive event listeners on wheel events.
Cause: Calling preventDefault() on wheel events added without { passive: false }.
Fix: Add wheel listeners via addEventListener('wheel', handler, { passive: false }) instead of React's onWheel.
Symptom: API calls fail, CORS errors, connection refused.
Cause: Server port comes from SERVER_PORT env (currently 3006). Vite proxies from :5173.
Fix: Check SERVER_PORT env var. In dev, always use Vite's port (5173) — it proxies to the server.
Symptom: TypeScript error "Cannot redeclare block-scoped variable".
Cause: Multiple developers editing the same file, each adding their own const declarations.
Fix: Check for existing declarations before adding. Use file locking to prevent concurrent edits.
Symptom: Vertical mouse wheel causes horizontal movement on Timeline.
Cause: wheel handler using deltaY for horizontal panning.
Fix: deltaY → vertical only (let browser handle), deltaX / Shift+wheel → horizontal pan, Ctrl+wheel → zoom.
Symptom: Token tab shows "not available" for agents.
Cause: Agent objects lack inputTokens/outputTokens (Copilot CLI doesn't provide them).
Fix: Estimate from outputPreview length (~4 chars/token). Show with ~ prefix and (est.) suffix.
Symptom: Component exists in DOM (DevTools shows it) but user can't see or interact with it.
Cause: Parent container has overflow: hidden and the component renders below the visible area. Example: ReplayScrubber rendered after a 1000px Gantt chart inside a 713px container.
Fix: Move the component outside the scrollable container as a sibling with shrink-0. Or use position: sticky; bottom: 0 to pin it.
Symptom: Monospace text falls back to system font when offline or in restricted networks.
Cause: Font loaded via Google Fonts CDN <link> tag — requires network.
Fix: Always bundle fonts locally. Download woff2 files → public/fonts/ → @font-face in CSS. Remove any CDN <link> and preconnect tags from index.html.
Symptom: Tests or Playwright can't find elements that should be in a list.
Cause: react-virtuoso only renders visible items. Off-screen items are virtualized away and not in the DOM.
Fix: In tests, mock Virtuoso to render all items. In production, use Virtuoso's scrollToIndex API to bring items into view.
Symptom: Header or footer components inside Virtuoso flicker, lose state, or remount on every scroll.
Cause: Passing inline component definitions to components={{ Header: () => <div>...</div> }} creates new component references on every render.
Fix: Extract Header/Footer to stable refs or define them outside the render function.
Symptom: Milestone or keyframe labels cut off even though frontend has room.
Cause: Backend applies .slice(0, 80) to labels before sending to frontend.
Fix: Remove backend truncation. Let the frontend handle display with CSS (line-clamp-2, title tooltip).
Symptom: QA automation can't test Ctrl+wheel zoom, keyboard nav, or drag on SVG chart elements.
Cause: Playwright's keyboard/mouse simulation doesn't reliably trigger React synthetic events on SVG elements, especially with modifier keys.
Fix: Write unit tests with fireEvent.wheel/fireEvent.keyDown from @testing-library/react for interaction logic. Use Playwright only for visual/screenshot verification.