| name | debug-test |
| description | Diagnose and fix a failing integration test in PilotSwarm. Covers the full call chain from PilotSwarmSession.sendAndWait through duroxide orchestration to CopilotSession, common failure patterns, and how to inspect orchestration and CMS state. |
Debug a Failed Test
Diagnosis steps
-
Run the specific test to reproduce:
npm test -- --test=<name>
-
Identify the failure layer — the call chain is:
test → PilotSwarmSession.sendAndWait()
→ PilotSwarmClient._startAndWait()
→ duroxide orchestration
→ SessionProxy activity (runTurn)
→ SessionManager.getOrCreate()
→ ManagedSession.runTurn()
→ CopilotSession.send() + on()
-
Common failure causes:
| Symptom | Likely cause |
|---|
| Timeout with no response | Orchestration stuck — check duroxide logs |
| Tool handler not called | Tools not registered — check setSessionConfig or registerTools was called |
| Wrong tool called | System message not directive enough — use mode: "replace" |
| Assertion on content fails | LLM non-determinism — make assertions flexible (.includes(), case-insensitive) |
| "Not started" error | worker.start() or client.start() not called |
| Session not found | Session wasn't created in CMS — check catalog.createSession() |
| Warm session missing tools | updateConfig() not called — check session-manager.ts warm path |
nondeterministic: custom status mismatch | Orchestration code uses Date.now() or other non-deterministic values to branch before yields — use yield ctx.utcNow() instead. Can also happen after redeploying changed orchestration code without resetting the database. |
-
Check CMS events — verify what actually happened:
const events = await session.getMessages();
console.log(events);
-
Check session info:
const info = await session.getInfo();
console.log(info.status, info.iterations);
Key files
TUI note
If the bug touches TUI keybindings or keyboard help text, verify that the startup keybinding hint/splash and the help dialog/modal are still synchronized with the actual bound keys.
