command-center/agent/managed-skills/dankvoice-bats-serialization/SKILL.md

name, description

name	description
dankvoice-bats-serialization	Run dankvoice bats suites without hangs: serialize builds on shared dist/, DV_HOLD is seconds, stub needs sleep&wait trap before hold, timing tests assert CALLS/at not tail PLAYS.

Dankvoice bats: serialization and hang-proofing

Serialize builds on the shared artifact

tests/behavior.bats setup runs bun run build into the repo's shared dist/index.js before EVERY test (DV_EXT="$REPO/dist/index.js"). Any second concurrent bats run, bun run build, or bun run typecheck racing the same repo contends on that file and can stall single tests past 60 s. NEVER run two bats processes (or bats + build) against ~/Projects/dankvoice at the same time — including harness background jobs. If a suite gets backgrounded, kill it before launching any other repo command; re-run serially.

The stub player's units and traps

• DV_HOLD is in seconds (sleep "${DV_HOLD:-0.1}"), not ms. DV_HOLD=1500 means a 25-minute "hung" test. Use DV_HOLD=2 for multi-second holds.
• The stub must sleep as sleep "${DV_HOLD:-0.1}" & + wait $!, with trap 'printf "KILLED\n" >> "$DV_STUB_LOG"; exit 143' TERM installed before the sleep: a foreground sleep defers the trap until the sleep finishes, so SIGTERM-kill tests (shutdown/interrupt pins) stay red and every kill test eats the full hold.
• Keep the cp *.wav "$DV_COPY" loop when editing the stub — the byte-equality test depends on it.

Timing-sensitive assertions

The driver prints PLAYS from the stub log at scenario end (~800 ms settle), so with a long DV_HOLD in-flight playback is UNDERCOUNTED — assert CALLS/arrival timestamps, not tail PLAYS. The fixture stamps every request with at= (ms since driver start, comparable between CALL lines); prefetch overlap = t2 - t1 < 1500 with DV_HOLD=2 (sequential chain cannot answer inside 2000 ms).

Diagnosing a hung bats test (deterministic recipe)

1. timeout 45 bats -f "<name>" tests/behavior.bats; echo rc=$? — rc=124 confirms hang.
2. Launch the same test as a background job, then probe live: pgrep -af "driver.ts|bats" and ps afx | grep -E "sleep|stub" — a sleep <N> child with N seconds in the stub log names the culprit (usually DV_HOLD misuse).
3. Detached (cmd &) inside a temp shell is KILLED when the shell exits — use the harness background jobs for anything you must probe.
4. Direct driver repro: extract the heredoc with sed -n '/cat > "$WORK\/driver.ts" <<.TS./,/^TS$/p' tests/behavior.bats | sed '1d;$d' > $W/driver.ts, build a fresh ext, then run bun $W/driver.ts <scenario> with the env the setup block exports. Caveat: hand-made fixture env can yield different segment counts than bats — trust in-bats numbers for assertions.