e2e-debug

E2E Debug — trace analysis + healer (close the loop)

The third leg of the harness. A CI failure is a sensor reading; this skill turns it back into a green test (or an honest quarantine), closing the planner -> generator -> healer self-improving loop.

Two runtime families, three execution paths, same bounded loop: on Claude Code the healer is the named agent e2e-setup generated (Path A); on Codex 0.135 that agent file is not registerable, so the healer runs as a generic subagent carrying the bundled contract from references/role-contracts.md (Path B), or in-agent sequentially when no delegation is available (Path C).

Verified against Playwright 1.61.0. The headless npx playwright trace CLI was introduced in 1.59; the subcommand set below is confirmed on 1.61. The GUI viewer npx playwright show-trace <trace.zip> is also available if a human wants to look.

Precondition check

• Need gh CLI authenticated to fetch CI artifacts.
• Path A only: confirm the named healer exists (.claude/agents/playwright-test-healer.md). If missing and you are on Claude Code, route to e2e-harness:e2e-setup. Do not demand this Claude agent file under Codex — there the bundled healer contract stands in (see Step 0).
• Requires Playwright >= 1.59 for the headless npx playwright trace CLI used in Step 2 (npx playwright --version to check). On older versions there is no headless trace CLI — fall back to the GUI viewer npx playwright show-trace <trace.zip>.

Workflow

1. Resolve the plugin root + pick the execution path — run once. The resolver reaches the bundled healer contract on Path B/C; the path decision governs Step 3. Tell the user which path you took in one sentence.

   # Claude exports CLAUDE_PLUGIN_ROOT; Codex 0.135 does not. Each branch verifies
   # the target (CHK) exists before committing, so a stale env falls through.
   CHK="references/role-contracts.md"
   PLUGIN_ROOT=""
   [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -e "$CLAUDE_PLUGIN_ROOT/$CHK" ] && PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"
   [ -z "$PLUGIN_ROOT" ] && [ -e "plugins/e2e-harness/$CHK" ] && PLUGIN_ROOT="plugins/e2e-harness"
   if [ -z "$PLUGIN_ROOT" ]; then
     cache_root="${CODEX_PLUGIN_CACHE:-$HOME/.codex/plugins/cache}"
     while IFS= read -r d; do
       [ -e "$d/$CHK" ] && { PLUGIN_ROOT="$d"; break; }
     done < <(ls -1d "$cache_root"/*/e2e-harness/*/ 2>/dev/null | awk -F/ '{print $(NF-1)"\t"$0}' | sort -t. -k1,1rn -k2,2rn -k3,3rn | cut -f2- | sed 's#/$##')
   fi
   { [ -n "$PLUGIN_ROOT" ] && [ -e "$PLUGIN_ROOT/$CHK" ]; } || { echo "e2e-debug: role contracts not resolved (need $CHK)" >&2; exit 1; }
   echo "PLUGIN_ROOT=$PLUGIN_ROOT"
   

   • Path A — named playwright-test-healer is registered (Claude Code): dispatch it by name (Step 3, unchanged).
   • Path B — named agent not registerable but a generic subagent tool is available (Codex Task): dispatch a generic subagent carrying the healer contract from ${PLUGIN_ROOT}/references/role-contracts.md inline.
   • Path C — no delegation available: run the healer role yourself per the same contract.