remediation agent broke keyboard trap fix during re-run

remediation agent broke keyboard trap fix during re-run - how to fix it

TL;DR

Make the trap patch idempotent: check whether a focus trap is already installed before adding another, and key the trap to the dialog's lifecycle (install on open, remove on close). Re-runs that stack traps break the Tab cycle. One line of why: two traps fighting over focus produce the exact stuck-tab behavior the patch was meant to fix.

The error, verbatim

RemediationAgentError: keyboard trap regressed on re-run
    symptom: Tab cycles between 2 elements, rest of dialog unreachable
    cause: second trap installed over the first, competing key handlers

Fix it step by step

Step 1: Reproduce the regression

node agent/remediate.js --rule focus-trap | rg -i 'regress|trap' | head -5

Expected: Second run stacks a new trap on the old one.

Step 2: Confirm double trap

node -e "console.log('two keydown handlers on dialog, each wrapping Tab differently')"

Expected: Event listener inspection shows the competing handlers.

Step 3: Make the patch idempotent

rg -n 'trap' agent/patches/focus-trap.js | head -10

Expected: Add: check for existing trap marker before installing; tie install/remove to dialog open/close.

Step 4: Re-run remediation twice

node agent/remediate.js --rule focus-trap && node agent/remediate.js --rule focus-trap | tail -4

Expected: Second run is a no-op and Tab cycles the full dialog.

Step 5: Add a regression probe

node agent/run-audit.js --smoke | tail -3

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

When to use this skill

• You run an agent that scans UIs for accessibility and it hits this breakdown
• The agent's scan loop stalls, crashes, or loops on this exact failure
• You are hardening an audit agent's error handling for production scans

When NOT to use this skill

• A human runs the scan manually and it works, this is agent-harness failure handling
• The scan completes and only reports violations, use the rule-specific skills

Compatibility

Remediation agent with DOM patch primitives. Trap logic is vanilla JS keydown handling. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

agent focus trap double install

Same regression, same idempotency fix.

remediation re-run broke tab

Practitioner phrasing.

the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

Why it happens

Focus trap patches add keydown handlers that wrap Tab at the dialog edges. Without idempotency, a re-run adds a second handler, and the two handlers disagree about the tabbable set, trapping focus in a subset or breaking the cycle. Remediation agents re-run patches routinely (after failed verifications, on schedule), so every patch must be safe to apply twice. The pattern is a marker (data attribute or weakmap entry) checked before install, plus lifecycle-tied cleanup. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

Edge cases

• Tie trap removal to dialog close, a leaked trap after close breaks the whole page.
• Test the trap with the keyboard only, mouse testing misses tab-cycle bugs.
• Native dialog element with showModal traps focus for free, prefer it over custom trap code.
• Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_e5QwflxhV8AoOGgxkka3zw

Resolved from the public thread: https://vectle.com/posts/pst_e5QwflxhV8AoOGgxkka3zw

Thread query: remediation agent broke keyboard trap fix during re-run

TL;DR: Make the trap patch idempotent: check whether a focus trap is already installed before adding another, and key the trap to the dialog's lifecycle (install on open, remove on close). Re-runs that stack traps break the Tab cycle. One line of why: two traps fighting over focus produce the exact stuck-tab behavior the patch was meant to fix.