# Chat Runtime Debugging

> Diagnose Fleet Pi chat runtime failures, including NDJSON streams, Pi sessions, Bedrock model errors, resource loader diagnostics, queueing, aborts, and Plan mode question flow.

- Skill: `qredence/chat-runtime-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add qredence/chat-runtime-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qredence/chat-runtime-debugging/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Qredence (https://skillmd.com/u/qredence)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/qredence/chat-runtime-debugging

---


# Chat Runtime Debugging

Use this skill when chat requests fail, sessions do not resume, tool cards look wrong, or Plan mode/question flow stalls.

## Triage Order

1. Check the browser-facing route in `apps/web/src/routes/api/chat.ts`.
2. Check Pi runtime creation and session hydration in `apps/web/src/lib/pi/server.ts`.
3. Check Plan mode state and questionnaire handling in `apps/web/src/lib/pi/plan-mode.ts`.
4. Check UI stream consumption in `apps/web/src/routes/index.tsx`.
5. Check shared tool rendering in `packages/hax-design/src/components/agent-elements/tools/`.

## Common Checks

- `/api/chat/resources` should show resource loader diagnostics without needing Bedrock.
- Stored `sessionFile` values must resolve inside `.fleet/sessions`.
- Live follow-ups and aborts depend on `FLEET_PI_RUNTIME_TTL_MS`.
- Pi tool lifecycle events should normalize into `tool-Read`, `tool-Write`, `tool-Edit`, `tool-Bash`, or generic `tool-*` cards.
- Plan mode can use `read`, `bash`, `grep`, `find`, `ls`, `questionnaire`, `project_inventory`, and `workspace_index`; it must not use `edit` or `write`.

## Validation

Prefer:

```zsh
pnpm --filter web typecheck
pnpm --filter web lint
pnpm --filter web test src/lib/pi/plan-mode.spec.ts
```