Menu
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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
The order of operations for changing a live agent safely โ diagnose, patch, publish, converge, verify, roll back. Use whenever you are about to modify an agent package that something is already running on.
Deploy PilotSwarm to AKS using the repo's canonical scripts and checks. Use when refreshing secrets, building/pushing the worker image, rolling out to AKS, or verifying provider/model changes in the live cluster.
Reset remote PilotSwarm state for AKS safely. Use when wiping the PilotSwarm database/blob state, clearing stale orchestration history, or recovering from namespace drift and replay/nondeterminism issues.
Use when bringing up a fresh, isolated PilotSwarm environment (`mysandbox`, `myenv2`, etc.) via the npm Bicep/GitOps orchestrator at `deploy/scripts/deploy.mjs`. Covers `new-env` scaffolding, EDGE_MODE ร TLS_SOURCE selection, the `all` aggregate, per-service redeploys with `--steps`, force-redeploy semantics, verification, and teardown. Strictly separate from the legacy bash path operated by `scripts/deploy-aks.sh`.
Use after deploying a PilotSwarm stamp with VPN_GATEWAY_ENABLED=true when an operator needs the Azure VPN client profile (azurevpnconfig.xml). Wraps deploy/scripts/auth/Get-VpnClientProfile.ps1 โ downloads the gateway-issued profile zip via 'az network vnet-gateway vpn-client generate' and extracts it under the gitignored deploy/envs/local/<env>/vpn-client/ folder. The XML is the same for every user (no per-user credentials), and end users still authenticate with their own Entra ID at connect time.
How to compute model latency and estimated $ cost from PilotSwarm observability data. Read this before reporting that a model is "slow" or "expensive" โ most apparent slowness is orchestration overhead, not model inference, and most cost numbers are guesses unless they reference a real published price card.
| 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. |
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);
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.