fix(manual-qa): async-dispatch metrics fixes + full tokenomics parity in bundle

[olexis-st]

Summary

Claude Code's current build dispatches the Agent tool asynchronously (an immediate "launched" acknowledgment, with real per-dispatch usage delivered later via <task-notification> messages on the orchestrator's own transcript) instead of the synchronous, blocking dispatch the manual-qa metrics pipeline was designed around. Left as-is, this silently breaks per-TC metrics for any project on this bundle: tcs[]/tokens_by_agent go empty, the SubagentStop hook fires prematurely on every orchestrator pause (wiping in-flight trace data), and the ccusage pre-snapshot race can silently fall back to summing every session on the machine instead of just the current run.

All of this was root-caused and fixed against real runs this week in qa-project, verified, then synced into elitea-testing/qa-challenges (2026-07-31). This PR ports the same fixes into the bundle so any project installing manual-qa via npx github:arozumenko/sdlc-skills init --bundle manual-qa gets them too — plus closes a separate, longstanding gap where the bundle's build-run-metrics.mjs had fallen behind its own documentation (knowledge/metrics-format.md already described turns/tokens_by_model/etc. as part of the schema; the code didn't produce them).

Commit 1 — fix(manual-qa): port async-dispatch trace recovery + hook-timing fixes into bundle

• scripts/resolve-subagent-traces.mjs (new): backfills the tc-trace from the orchestrator transcript's own <task-notification>/<usage> blocks instead of trusting benchmark-tc-hook.mjs's real-time capture (which async dispatch makes unreliable). Wired into benchmark-stop, which now also resolves the true parent transcript for SubagentStop firings (this bundle copy didn't have that resolution at all yet, unlike elitea-testing/qa-challenges).
• benchmark-stop: re-derives real subagent identity from the payload's own agent_type field (empty on a premature firing, "test-reporter" only on genuine completion) instead of trusting the SubagentStop matcher alone; elapsed-time-since-last-dispatch kept as a secondary net. Debug logging added (gitignored).
• scripts/ccusage-wait.sh (new) + use in benchmark-session-start/benchmark-preflight: retries ccusage session --json for up to 60s of real elapsed time (not a fixed attempt count — disproven by real timing data) until the session's own entry appears, instead of one un-retried call.

Commit 2 — feat(manual-qa): bring bundle's build-run-metrics.mjs to full tokenomics parity

• build-run-metrics.mjs: ported the fuller feature set already present in elitea-testing/qa-challenges/qa-project — countTurns() (via the transcript_path resolved in commit 1), subagent_dispatches, orchestrator_cost_pct, tokens_by_model + cache_read_share_pct (keyed off ccusage's own scoped modelsUsed[]), models_used.
• benchmark-stop: now actually passes transcript_path through to build-run-metrics.mjs (resolved in commit 1 for resolve-subagent-traces.mjs's sake only, until this commit could consume it too).
• Diffed build-tokenomics-report.mjs/build-tokenomics-html.mjs/compare-runs.mjs against elitea-testing for completeness — already at parity (compare-runs.mjs doesn't even exist there — bundle is ahead). Docs (knowledge/metrics-format.md, hooks/README.md, templates) were already accurate for this schema — no doc changes needed, only the code catching up to what they promised.

Test plan

• Replayed real SubagentStop payloads (captured live in qa-project) through the full benchmark-stop -> resolve-subagent-traces.mjs -> build-run-metrics.mjs chain in an isolated scratch dir — premature firings correctly skipped, genuine completion correctly proceeds.
• resolve-subagent-traces.mjs run against a real orchestrator transcript — output matched that run's actual Performance Metrics table exactly.
• ccusage-wait.sh run against a real, already-indexed session id — immediate scoped match; against a synthetic non-existent id — correctly exhausts the 60s budget and falls back without hanging.
• Full chain verified end-to-end: real turns/subagent_dispatches/tokens_by_model/cache_read_share_pct/models_used/tokens_by_agent all populate correctly, real per-TC tokens/tool_uses match the source transcript.
• All scratch-directory testing — no production repo state (this bundle's own reports/ etc.) was touched during verification.

🤖 Generated with Claude Code