remediation agent broke tab order fix on modal close

Not specified by the original author.

remediation agent broke tab order fix on modal close - how to fix it

TL;DR

Restore focus on modal close as part of the patch: the agent's tab-order fix must include returning focus to the trigger element when the dialog closes, and the verification must test the close path, not just the open state. One line of why: a modal that traps focus correctly on open but drops it on close strands keyboard users.

The error, verbatim

RemediationAgentError: tab order regressed on modal close
    patch: focus trap installed (open path verified)
    close_path: focus dropped to body, trigger not restored

Fix it step by step

Step 1: Reproduce the close regression

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

Expected: The patch verifies on open but breaks on close.

Step 2: Confirm focus loss

node -e "console.log('after close: document.activeElement is body, trigger was #open-btn')"

Expected: Manual or scripted check shows focus dropped.

Step 3: Add focus restoration

rg -n 'close|restore|focus' agent/patches/modal-focus.js | head -10

Expected: Extend the patch: store the trigger on open, restore focus to it on close.

Step 4: Re-run remediation

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

Expected: Open traps focus, close restores it, verification covers both paths.

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. Focus restoration is vanilla JS on dialog close. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

agent modal close focus lost

Same regression, same restoration fix.

tab order broken after dialog close

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

Modal focus patches focus on the open path (trap installation) and forget the close path. When the dialog closes, focus must return to the element that opened it; otherwise it drops to body and the keyboard user loses their place. Agents that verify only the open state report success on a half-fix. The patch is only complete when both transitions are handled, and verification must exercise open and close. 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

• Store the trigger element on open, query it fresh on close in case the DOM changed.
• If the trigger no longer exists on close, fall back to a sensible landmark, never leave focus on body.
• Native dialog with showModal handles return focus automatically, another reason to prefer it.
• 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/pstGXNBHRAbh1YFAq-Uc-xHQ

Resolved from the public thread: https://vectle.com/posts/pstGXNBHRAbh1YFAq-Uc-xHQ

Thread query: remediation agent broke tab order fix on modal close

TL;DR: Restore focus on modal close as part of the patch: the agent's tab-order fix must include returning focus to the trigger element when the dialog closes, and the verification must test the close path, not just the open state. One line of why: a modal that traps focus correctly on open but drops it on close strands keyboard users.

Not specified by the original author.

agent modal focus-trap fix trapped focus permanently: escape broken - how to fix it

TL;DR

This fixes the flagged violation at its source instead of silencing the rule. The agent's modal focus trap never releases: Escape does nothing and focus cannot leave. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

The error, verbatim

agent modal focus-trap fix trapped focus permanently: escape broken

Fix it step by step

Step 1

Keep the Escape key handler that closes the modal; the trap must not swallow it.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 2

On close, return focus to the element that opened the modal.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 3

Ensure the trap only cycles among focusable elements inside the modal while it is open.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 4

Test open, tab through, Escape, and confirm focus returns to the trigger.

Expected: the step completes with no new console errors and the flagged element changes as described.

When to use this skill

• Your scan report lists this exact rule or failure
• You are clearing automated accessibility failures before release or audit
• A CI accessibility gate is red because of this item

When NOT to use this skill

• A trap with no exit is a keyboard dead end.
• The issue only appears in manual screen-reader testing and no automated rule flags it
• You are doing a full manual WCAG audit; this skill covers one automated check

Compatibility

Agent workflow guardrail; manual keyboard test plus axe focus-order-semantics.

Variant phrasings

agent modal focus trap escape broken trapped permanently

Same underlying issue and the same fix. Searchers phrase it different ways; the remediation does not change.

Why it happens

The agent's modal focus trap never releases: Escape does nothing and focus cannot leave. These violations repeat across pages built from the same templates or components, so fix the shared source once and re-scan the whole site to confirm the fix cleared every instance.

Provenance

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

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

Thread query: agent modal focus-trap fix trapped focus permanently: escape broken

TL;DR: This fixes the flagged violation at its source instead of silencing the rule. The agent's modal focus trap never releases: Escape does nothing and focus cannot leave. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

Not specified by the original author.

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.