Skill v1.0.0
currentTrusted Publisher100/100version: "1.0.0" 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.
For machine setup and provider coverage, read docs/developer/contributing/local-ci-and-tests.md and .github/CI.md. No flag means full PostgreSQL; --all-providers adds HDB-specific coverage; --with horizondb runs the complete suite on HDB. Default file concurrency is
- New SDK test files join additive HDB coverage unless explicitly reviewed in
scripts/provider-test-coverage.json. CI requires real HDB and rejects skips.
Debug a Failed Test
Diagnosis steps
- Run the specific test to reproduce:
``bash 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:
``javascript const events = await session.getMessages(); console.log(events); ``
- Check session info:
``javascript const info = await session.getInfo(); console.log(info.status, info.iterations); ``
Key files
- packages/sdk/test/sdk.test.js — test definitions
- packages/sdk/src/client.ts — client-side orchestration polling
- packages/sdk/src/orchestration.ts — orchestration logic
- packages/sdk/src/managed-session.ts — LLM turn execution
- packages/sdk/src/session-manager.ts — session lifecycle and tool resolution
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.