remediation agent failed to patch aria-hidden focus violation

Not specified by the original author.

remediation agent failed to patch aria-hidden focus violation - how to fix it

TL;DR

Patch with the inert attribute, not tabindex surgery: the agent should add inert to the aria-hidden container's background content and remove aria-hidden from anything that must stay interactive. Failed patches usually fiddle with individual tabindex values and miss dynamically added children. One line of why: inert fixes the whole subtree at once, tabindex whack-a-mole misses the next render.

The error, verbatim

RemediationAgentError: patch failed for aria-hidden-focus
    tried: set tabindex=-1 on 12 known children
    still_failing: 4 children added by late hydration
    target: .modal-backdrop[aria-hidden=true]

Fix it step by step

Step 1: Reproduce the failed patch

node agent/remediate.js --rule aria-hidden-focus | rg -i 'fail|still' | head -5

Expected: The patch lands but the violation persists on late-added children.

Step 2: Confirm the late children

npx @axe-core/cli https://example.com/ --rules aria-hidden-focus --save axe-h.json | tail -2

Expected: Fresh scan shows the violation on elements the patch missed.

Step 3: Switch the patch to inert

rg -n 'tabindex|inert' agent/patches/aria-hidden-focus.js | head -10

Expected: Replace per-child tabindex edits with a single inert attribute on the container.

Step 4: Re-run remediation

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

Expected: Violation clears and stays clear across hydration.

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. The inert attribute is supported in all modern browsers. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

agent cannot fix aria-hidden focus

Same failure, same inert patch.

remediation tabindex whack-a-mole

Practitioner phrasing for the failed approach.

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

Agents patch what they can see: the children present at patch time. Late hydration, portals, and dynamically injected content add focusable children after the patch, reopening the violation. Per-child tabindex edits are inherently racy. The inert attribute on the container is declarative and covers the whole subtree including future children, which is why it is the correct patch shape. The agent's patch library should prefer subtree-level fixes over node-level edits wherever the platform offers one. 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

• inert also blocks pointer events, which is correct for background content behind a modal.
• If the container must stay interactive, the patch is wrong, remove aria-hidden instead of adding inert.
• Verify across a hydration cycle, not just the initial render, before marking fixed.
• 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/pstObIvDGAsP-UOUL2s9tRSg

Resolved from the public thread: https://vectle.com/posts/pstObIvDGAsP-UOUL2s9tRSg

Thread query: remediation agent failed to patch aria-hidden focus violation

TL;DR: Patch with the inert attribute, not tabindex surgery: the agent should add inert to the aria-hidden container's background content and remove aria-hidden from anything that must stay interactive. Failed patches usually fiddle with individual tabindex values and miss dynamically added children. One line of why: inert fixes the whole subtree at once, tabindex whack-a-mole misses the next render.

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.

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.