Skip to content

feat(audit): name findings and remove platform chrome noise - #4652

Open
thymikee wants to merge 20 commits into
mainfrom
feat/audit-findings-usable
Open

thymikee wants to merge 20 commits into
mainfrom
feat/audit-findings-usable

Conversation

@thymikee

@thymikee thymikee commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Audit findings show their role and include the captured label or identifier when available. Guidance appears once per finding kind. Size and name checks skip UIKit sheet grabbers. Direct items of recognized native iOS bars keep name checks and skip size checks. Custom bar children and nested app content retain size checks.

Audit reports covered controls inside scroll views. Recognized persistent bars require native source evidence and get visible-target or inspection guidance. ARIA and custom toolbar overlays keep generic cover recovery. Scroll clearance is separate work that requires capture-owned travel bounds and live Android and iOS cases.

29 files. agent-device audit can report @e20~s815872 small-target button "Save Lemon Herb Rice" 22×22pt, below 44×44pt. agent-device audit --json adds optional label and identifier plus top-level guidance.

Audit still uses full capture. In fixture output, Safari History at 370×28 pt and nested-scroll Row high at 370×40 pt disappear in the interactive projection.

Validation

pnpm check:affected --run --head c70a9dd57c0a485d76a591360be06b8cfa625a55 passed with exactCommit=true. GitHub owns hosted checks.

A live iOS 26.2 capture showed an OS-generated Add label. Offline replay through ea1bbc8 retained the unnamed native item’s missing-name finding and the custom-bar child’s small-target finding. Exact-head live iOS and Android-helper evidence remains pending. The T3 client supports RPC protocol 2 and the branch daemon requires 3.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.39 MB 6.39 MB +3.4 kB
Package (unpacked) 6.39 MB 6.39 MB +3.4 kB
Package (download) 1.94 MB 1.94 MB +1.4 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 44.6 ms 37.5 ms -7.1 ms
CLI --help 82.7 ms 90.0 ms +7.3 ms

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on af69e16. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

Both findings are fixed in 45bb635.

The MCP audit fixtures now include guidance. I checked all audit result literals in the MCP pin tests, CLI formatter fixtures, audit formatter tests, and daemon fake. The MCP fixtures and the generic CLI fixture table now use satisfies AuditSnapshotCommandResult.

The MCP test file is included in the root typechecked project through include: ["src", ...]. The gap was its argument type. mergeCommandResult accepts the union CommandExecutionResult. That union includes CommandRequestResult, which permits a generic Record<string, unknown>. It therefore accepted the incomplete audit objects. The new audit type assertions produced two TS1360 errors before I added guidance.

The size exemption now requires a direct bar parent. Scroll containers, content containers, and other controls stop the exemption. The four new negative cases failed at af69e16. All 139 focused tests and typecheck pass at 45bb635. The affected gate passed with exactCommit=true.

The review thread is resolved. Hosted CI must validate the pushed head.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 45bb635. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

Thanks for this. This review covers 45bb635; b61e3a1 landed while it ran and gets its own delta review. At 45bb635 the audit still reports bar-item small-targets and scroll-under-bar covered-controls on one iOS shape, so it needs one more change. All 21 checks pass at this commit.

The persistent-chrome list in snapshot-audit.ts:310 copies the first five bar fragments from snapshot-occlusion.ts:16-21. It reads only node.type (see line 140). The occlusion owner reads type, role and subrole through normalizeNodeKind (snapshot-occlusion.ts:682-684). The occlusion tests pin an iOS shape with type Other and role UITabBar (test:395). On that shape the 36x36pt bar items are not treated as platform-sized, and the scroll-chrome exclusion misses because coveredBy.kind is the display string other. The help and docs promise that bar items skip size checks and that controls under persistent bars are excluded, so this is the noise the PR removes. Which capture route emits this shape is not confirmed, so this is likely rather than certain. The rule: one owner decides whether a node is persistent bar chrome from type, role and subrole. Please add one role-shaped bar case to snapshot-audit.test.ts to show it.

Could one exported predicate from snapshot-occlusion.ts (for example isPersistentBarChrome(node) over normalizeNodeKind with the existing bar fragments) replace the copied list? describeCoveringNode could also publish a typed flag on SnapshotCoveringNode (for example persistentBar: true). Then the audit would drop PERSISTENT_CHROME_KINDS and isPersistentChromeKind. It would check that flag plus the scroll ancestor, and call the predicate on the immediate parent. That looks like fewer lines, and the role and subrole shapes come for free. The typed field would need to be added to SnapshotCoveringNode in contracts first, and to snapshot-unchanged equivalence if it compares coveredBy fields.

The open thread on the type-only parent check still stands and is covered above. Its fixture citation is off (the iOS 27 toolbar node has type Toolbar), but the Other plus UITabBar shape holds. The thread on the ancestor walk no longer applies, because the immediate-parent check replaced the walk at lines 139-140, so it can be resolved.

Not blocking, and you can take or leave these: the --json sentence in commands.md:440 lists label but findings also carry identifier, which has no doc comment either. The missing-name and small-target guidance at snapshot-audit.ts:341 names iOS, Android and React Native APIs on every platform, and falls back to Material for any non-iOS platform. Keying the size sentence off the resolved size rule would fix that.

This change is not device-facing, so no live run is needed. There are no conflicts. Before merge, route the bar-chrome check through the occlusion owner and add the role-shaped test.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

Thanks for the update. At b61e3a1 the parent check now goes through isSnapshotBarNode, but the covered-control half of the same shape is still open, so this needs one more change. CI is green (21 checks, none failing), and there are no conflicts.

The scroll-chrome exclusion still reads the display string coveredBy.kind and matches it against the copied PERSISTENT_CHROME_KINDS list (snapshot-audit.ts:327, list at L314-324). coveredBy comes from describeCoveringNode, which reads only node.type and drops role and subrole (snapshot-occlusion.ts:157-170). The occlusion scan itself treats a node of type Other with role UITabBar (or subrole AXToolbar) as an overlay (:347; shape pinned at snapshot-occlusion-sibling-sized-chrome.test.ts:395-396). A row in a ScrollView under that bar is then covered with coveredBy null or kind other, and isScrollableChromeOcclusion returns false. On that iOS publication the audit would still report scroll-under-bar covered-control noise, while the audit help and commands.md:436 say those controls are excluded. The rule the code must satisfy: one owner decides "this cover is persistent bar chrome" from the covering node's type, role and subrole, and the audit reads that typed fact, never the display kind. Every shape the occlusion scan treats as a bar should publish it, including anonymous ones. To validate, add an audit test where the covered row's coveredBy is produced by the occlusion scan over an Other + UITabBar bar, not a hand-written kind. Which live capture route publishes a bar in that shape is not confirmed, so this is likely rather than proven.

Could the simpler route be a typed persistentBar flag on SnapshotCoveringNode, set by describeCoveringNode (fed type, role and subrole) from the shared bar predicate? The audit would then check that flag plus the scroll ancestor, and PERSISTENT_CHROME_KINDS and isPersistentChromeKind could go. That looks like fewer lines and covers every publication shape. It needs the new field in the kernel snapshot type, a wider CoveringNodeEvidence, and a check that areCoveringNodesEquivalent in snapshot-unchanged.ts handles it.

Not blocking, take or leave: the --json sentence in commands.md:440 lists label but findings also carry identifier, and AuditFindingBase.identifier has no doc comment while label does; and the scroll-chrome tests in snapshot-audit.test.ts:337 use hand-written coveredBy kinds, which the producer-driven test above would replace.

The two earlier inline threads on the type-only parent check (r4604751593) and the ancestor walk (r4604548741) look fixed at this commit, so you can resolve them. Before merge, the covered-control exclusion needs to go through the typed bar flag with the producer-driven test.

@thymikee

Copy link
Copy Markdown
Member Author

Thanks. The covered-control exclusion now reads a typed bar fact. Head is 12e6d1b.

What changed:

  • SnapshotCoveringNode has a new optional field, persistentBar: true.
  • describeCoveringNode sets the field from isSnapshotBarNode, which reads type, role, and subrole. Bottom navigation also sets it.
  • CoveringNodeEvidence now includes role and subrole.
  • An unnamed bar with a generic type (Other + UITabBar) now publishes coveredBy. Before, it published no cover.
  • The audit checks coveredBy?.persistentBar === true and the scroll ancestor. PERSISTENT_CHROME_KINDS and isPersistentChromeKind are deleted.
  • areCoveringNodesEquivalent compares persistentBar. The unchanged test has a case for it.
  • The scroll-chrome audit tests are now producer-driven. annotateCoveredSnapshotNodes produces each coveredBy. The cases are type only, Other + role UITabBar, Other + subrole AXToolbar, Toolbar, NavigationBar, and Android BottomNavigationView. Sheet, dialog, and alert covers stay findings.
  • snapshots.md documents persistentBar.
  • commands.md now lists identifier in the --json sentence. AuditFindingBase.identifier has a doc comment.
  • Two refusal tests now expect persistentBar: true on a scanned tab-bar cover.

Evidence:

  • I ran the new audit test against the b61e3a1 source. Only the audit assertion was active.
  • The Other + UITabBar case failed at b61e3a1.
  • The Other + subrole AXToolbar case failed at b61e3a1.
  • All cases pass at 12e6d1b.

Gate: pnpm check:affected --run passed at 12e6d1b (exactCommit=true).

The inline threads r4604751593 and r4604548741 were already resolved.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 12e6d1b. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

One problem from the earlier review (#4652 (comment)) is still open at 12e6d1b. The other earlier points look fixed in this update. All 18 checks pass at this commit, and there are no conflicts.

An unnamed persistent bar with a generic type now publishes a cover in snapshot-occlusion.ts:164, but its kind stays other. The press refusal in interaction-error.ts:87-114 then says "Covered by the other at (0, 791 402x83). Dismiss or close that element". At b61e3a1 this input published no cover, so the agent got the generic recovery hint. On the target_covered route, an agent covered by an Other+UITabBar bar is now told to dismiss chrome it cannot dismiss. Which live capture (XCTest, Appium or macOS AX) produces this shape is not confirmed, so this is likely rather than proven. The rule: a published cover's kind always names a surface a reader recognizes. When persistentBar is true and the type kind is anonymous, describeCoveringNode should publish a bar kind from the matched fragment, such as tab-bar, toolbar, navigation-bar or bottom-navigation. Rendering persistentBar in describeCoverForHint would also satisfy it. Please add one refusal-hint assertion over the scanned Other+UITabBar tree.

No device run is needed for this change. The open inline thread on this kind (#4652 (comment)) still stands. Two other threads no longer apply and can be resolved: the ancestor walk now uses a visited set (#4652 (comment)), and the parent check goes through isSnapshotBarNode (#4652 (comment)).

Before merge, give an unnamed persistent-bar cover a recognizable kind so the refusal never says "the other ... Dismiss or close that element".

@thymikee

Copy link
Copy Markdown
Member Author

Thanks. The unnamed persistent-bar cover is fixed in 9c3d971.

  • An unnamed Other + UITabBar cover now publishes kind tab-bar, not other. The bar kind comes from the shared bar predicate.
  • The refusal hint for a persistent bar does not tell the agent to dismiss it. It tells the agent to scroll the target clear of it.
  • A new producer-driven refusal test covers the scanned Other + UITabBar tree. It failed at 12e6d1b and passes at 9c3d971.
  • pnpm check:affected --run passed at 9c3d971.
  • I resolved thread r4611770407. Threads r4604548741 and r4604751593 were already resolved.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

Thanks for the update. At 9c3d971 the earlier persistent-bar cover finding is fixed: an unnamed Other+UITabBar cover now publishes kind tab-bar, and the persistent-bar hint no longer suggests dismiss. One defect remains in the same hint.

The persistentBar branch in interaction-error.ts:94 tells every target to scroll clear of its cover. The cover marker only identifies the cover. It carries no evidence that the target can scroll. The new click regression has a fixed Save draft button under the bar, with a sibling tab bar and no scroll container. The audit fixture keeps that fixed control under the bar too (snapshot-audit.test.ts:377-420). An agent that gets a click refusal for a fixed control is sent to a scroll that cannot move it, and it may retry in a loop. Please make the scroll suggestion conditional on scrollable content. For a fixed target, point to a different visible target or to snapshot inspection. Update the hint assertion and the snapshot docs to match.

Simplicity question: could snapshot-audit.ts keep the persistent-bar suppression rule and use findNearestScrollableAncestor from snapshot-visibility.ts:216 for the ancestor lookup? It already walks the same parent chain with the same scrollability predicate and a cycle guard.

The open inline thread on the tab-bar kind is fixed at this head, so you can resolve it: #4652 (comment)

CI is green: 18 checks, none failing at 9c3d971. There are no conflicts. Which live capture (XCTest, Appium, macOS AX) emits an unlabeled Other with role UITabBar is not confirmed, so the fixture shape is synthetic. No device run is needed. Before merge, the hint needs the fix above.

@thymikee

Copy link
Copy Markdown
Member Author

Thanks. The persistent-bar hint is fixed in 0c64c70.

  • The occlusion scan now sets coveredBy.targetInScrollableContent: true when the covered node has a scrollable ancestor. It uses findNearestScrollableAncestor from contracts.
  • The persistent-bar hint suggests a scroll only when the cover has that fact.
  • For a fixed target under a bar, the hint says "Use a different visible target, or inspect with snapshot/screenshot before retrying." It does not suggest a scroll or a dismiss.
  • About the simplification question: the audit now reads the same typed fact (persistentBar and targetInScrollableContent). It no longer walks the ancestors itself. The persistent-bar suppression rule is unchanged. The scroll lookup now has one owner, the occlusion scan.
  • areCoveringNodesEquivalent compares the new field. snapshots.md documents the field and the two hint forms.

Evidence:

  • There are two new runtime tests over scanned Other + UITabBar trees. A scrollable target gets the scroll suggestion. The fixed Save draft button gets no scroll and no dismiss.
  • At the 9c3d971 source, the fixed-target assertion failed. The hint said "Scroll the target clear of it". Both tests pass at 0c64c70.
  • pnpm check:affected --run passed at 0c64c70 (exactCommit=true).
  • Thread r4611770407 is resolved.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 0c64c70. The verdict and the full list are in the summary comment.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The hint finding from the earlier review (9c3d971) is fixed at 8a867b5: covered-control guidance in snapshot-audit.ts no longer tells the reader to dismiss persistent bar chrome, and snapshot-audit.test.ts pins it. One docs mismatch remains.

agent-device help manual-qa still says the named cover is what to dismiss for target_covered on a fixed control under a persistent tab bar, or to scroll the target clear (cli-help-workflows.ts:56). The production hint at the same head says to use a different visible target or inspect with snapshot or screenshot. An agent that follows the QA help can retry the same blocked action after steps that cannot uncover a fixed control. Please point the help at the recovery in the error hint. Reserve dismissal for dismissible covers, and recommend scrolling past persistent bars only for targets in scrollable content.

Could packages/contracts/src/snapshot-text.ts own the full bar identity, including bottom navigation, with packages/capture-kit/src/snapshot-occlusion.ts selecting the three existing kinds for viewport exemptions? Capture would still own the occlusion facts, and audit and interaction would still consume those facts without parsing platform role strings.

The open inline thread on covered-control guidance (#4652 (comment)) no longer applies at 8a867b5, so the author can resolve it.

All 18 checks pass at 8a867b5, and there are no conflicts. No device run is needed for this diagnostic text. After the help text matches the hint and the bar-identity question above is answered (a smaller design, or why it was rejected), nothing else stands between this PR and merge.

@thymikee

Copy link
Copy Markdown
Member Author

Both review items are addressed at a83226f.

Item 1 (docs): `agent-device help manual-qa` no longer tells the reader to dismiss or scroll clear any cover for `target_covered`. The recovery now matches the production hint in `packages/selectors/src/interaction-error.ts`: dismiss only dismissible covers (sheet, dialog, alert); under a persistent bar (tab bar, toolbar, navigation bar, bottom navigation) use a different visible target or inspect with snapshot/screenshot, scrolling past the bar only when `coveredBy.targetInScrollableContent` is true. The old wording had no other copies in `src/`, `website/docs`, or `skills/`; `website/docs/docs/snapshots.md` already matched the hint. `cli-help-workflows.test.ts` now pins the new wording and the absence of the old.

Item 2 (bar identity): `packages/contracts/src/snapshot-text.ts` now owns the full bar identity; `SNAPSHOT_BAR_KINDS` includes `bottomnavigation` mapped to `bottom-navigation`, so `snapshotBarKind`/`isSnapshotBarNode` cover it. `packages/capture-kit/src/snapshot-occlusion.ts` dropped its separate `BOTTOM_NAVIGATION_KIND_FRAGMENTS` match and now selects the three existing kinds (`tab-bar`, `toolbar`, `navigation-bar`) for the viewport-chrome exemptions via a local `VIEWPORT_CHROME_BAR_KINDS` set. An Android `BottomNavigationView` is therefore still excluded from the viewport exemption: it keeps covering the content behind it while publishing `persistentBar: true`. Capture still owns the occlusion facts, and audit and interaction consume those facts without parsing platform role strings.

Test evidence: focused vitest on the touched files passes (192 tests, including 6 new pins for bar identity in `snapshot-text.test.ts` and for a full-viewport BottomNavigationView still covering in `snapshot-occlusion.test.ts`). The broader suites for `packages/capture-kit`, `packages/contracts`, `packages/selectors`, and `src/commands/schema` pass (2453 tests across 279 files). `pnpm format` is clean.

Gate: `pnpm build` succeeded and `pnpm check:affected --run` reported all runnable checks passed (exactCommit=true). The branch was pushed as a83226f.

Review thread r4616012731 was already resolved; confirmed isResolved=true via the GraphQL API, so no resolve action was needed.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on a83226f. The verdict and the full list are in the summary comment.

Comment thread packages/contracts/src/snapshot-text.ts Resolved
@thymikee

Copy link
Copy Markdown
Member Author

Thanks for the update. At 3fa25fb the earlier covered-control guidance concern is fixed, and bar identity now lives in snapshot-text.ts: the scroll advice at snapshot-audit.ts:311 is gated on persistentBar && targetInScrollableContent, so it no longer tells the reader to dismiss bar chrome. One defect remains.

In snapshot-occlusion.ts:228, findNearestScrollableAncestor accepts any scroll-like ancestor. A button in an Android HorizontalScrollView that sits entirely behind a full-width bottom navigation bar is therefore marked targetInScrollableContent. Horizontal movement never brings it clear of the bar. In a check that loaded the committed scan, audit and hint modules with a 400x65 horizontal viewport wholly inside a 400x75 bar: the merge base reports the covered-control finding, while this head keeps the covered refusal, drops the finding, and tells the caller to scroll clear. Audit then omits a control that stays untouchable, and the target_covered hint points to a recovery that cannot work. Please keep the covered finding and the fixed-target recovery whenever the cover contains the entire usable scroll viewport. If audit and interaction need to tell scroll ancestry apart from a possible recovery, publish a separate scroll-clearance fact.

Could snapshot-occlusion own one shared decision on whether scrolling can reveal the target, based on the available viewport and direction evidence, and publish it through SnapshotCoveringNode for both audit and interaction recovery?

Of the open threads from other reviewers, this one on the bottom navigation role no longer applies. snapshot-text.ts:23-24 checks bottomnavigation first, and snapshot-text.test.ts pins the case, so it can be resolved. The covered-control guidance thread is fixed at this head.

No checks had reported on 3fa25fb yet, and none are failing. All 18 checks passed at 8a867b5. No conflicts are known. Before merge, the scroll-viewport case needs the fix above and the checks must report green at 3fa25fb.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 3fa25fb. The verdict and the full list are in the summary comment.

thymikee and others added 4 commits November 18, 2026 18:33
…hint; own full bar identity in contracts

- cli-help-workflows.ts: the manual-qa recovery for target_covered no longer tells
  the reader to dismiss or scroll clear any cover. It now points at the production
  hint's recovery: dismiss only dismissible covers (sheet, dialog, alert); under a
  persistent bar use a different visible target or inspect with snapshot/screenshot,
  scrolling past the bar only when coveredBy.targetInScrollableContent is true.
  cli-help-workflows.test.ts pins the new wording and the absence of the old.
- contracts/snapshot-text.ts: SNAPSHOT_BAR_KINDS gains bottomnavigation ->
  bottom-navigation, so snapshotBarKind/isSnapshotBarNode own the full bar
  identity. capture-kit/snapshot-occlusion.ts drops its separate
  BOTTOM_NAVIGATION_KIND_FRAGMENTS match and selects the three existing kinds
  (tab-bar, toolbar, navigation-bar) for the viewport-chrome exemptions via a
  local VIEWPORT_CHROME_BAR_KINDS set, so an Android BottomNavigationView still
  covers content instead of being exempted. New tests pin the bar identity in
  contracts and the bottom-navigation occlusion behavior in capture-kit.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
@thymikee

Copy link
Copy Markdown
Member Author

At 3fa25fb this branch now conflicts with main. Please rebase onto main and push; the open scroll-viewport finding from the last review still stands.

@thymikee
thymikee force-pushed the feat/audit-findings-usable branch from 3fa25fb to 7d61884 Compare November 18, 2026 17:52
@thymikee

Copy link
Copy Markdown
Member Author

Rebased on main and resolved the overlapping recovery help entries. The updated keyboard guidance and covered-target guidance are both present.

  • Audit and interaction now share coveredBy.scrollCanReveal. The Android horizontal viewport wholly behind bottom navigation retains its covered-control finding and gets the fixed-target recovery. Regression tests also cover clipping to the screen and a horizontal tap path blocked along its entire width.
  • The iOS size exemption requires an exact native bar identity. The new HomeToolbarView and BottomTabBar cases retain their small-target findings.

The affected gate passed at 7d61884d69e7ad018166a61536c41b575b5d6216 with exactCommit=true. Both requested earlier threads were already resolved.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on 7d61884. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

Addressed both Sentinel findings in 0a7e56ecd93eaa83abe6aa8837f29a72d491cc81. Scroll recovery requires direction evidence, and persistent covers publish canonical kinds even when capture gives the bar a concrete native class. The three regression assertions failed on 7d61884d69 and pass with the fix. The affected gate passed on the pushed commit with exactCommit=true.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

At 95758cb, the earlier conflict is fixed, but the clearance decision and its coverage still need changes. The other checks pass, and the remaining one is a review check. No conflicts are known. Before merge, correct the clearance decision and regression coverage, align the help, record device evidence.

Could the scan use the measured viewport from state assembly, with valid root geometry as fallback? A rootless Android helper capture can retain a scroller beyond the display, so the off-screen segment can suppress a covered finding and suggest an unreachable scroll. Pin this path through state assembly. The earlier synthetic helper XML reproduced the geometry; its occurrence on a live device remains unverified. Scan

Require capture evidence that movement can take the center toward an exposed point on each axis and direction. An explicit axis alone can suppress a finding when content fits or the scroller is at its forward limit, and Android currently drops horizontal action hints. Keep the marker absent without evidence, and replace the directionless positive with a movable case plus fit and end-of-range cases. Decision

Qualify the exclusion in audit help with supported scroll clearance, following the shared producer's rule. Controls whose whole usable path is covered remain in the audit, contrary to the current description. Help

Say findings show their role and include the captured label when available. Missing-name findings and controls named by descendants or placeholders may have no label of their own. Reference

Please provide same-head Android helper and native iOS commands and output for wholly blocked and genuinely revealable horizontal scrollers through the daemon. On Android, show androidSnapshot.backend=android-helper and the matching helperVersion in snapshot -i --json. On both platforms, show audit --json and a fresh-ref covered press: the blocked case must show covered-control, target_covered, no scrollCanReveal and alternate-target or inspection advice; the revealable case must show scrollCanReveal, no covered finding and a scroll hint, followed by a scroll, refreshed ref and successful press. On iOS also show an unnamed native direct bar item retaining missing-name and a small custom-bar child retaining its size finding. Fixtures alone do not establish what live capture publishes. Decision

Drive the clipping regression through buildSnapshotState with a measured 400×800 viewport, rootless nodes and movement evidence toward an off-screen exposed segment. Verify that removing the measured clip changes the marker or finding. The current fixture passes without the clip because it has no hidden-content evidence. Test

Use available travel bounds to prove an exposed point, or retain the finding and use alternate-target recovery when the bound is insufficient. A center at y=860 behind a bar at y=791..874 cannot clear it with only 10pt of upward travel, although the current path extends to the viewport edge. Decision

Align the snapshot explanation with the corrected capture-evidence contract. Until then, describe the geometry and class-based inference: rootless Android ignores its measured viewport and an explicit class axis can publish the marker without directional evidence. Snapshot docs

Describe the size exemption as applying to direct items of recognized native iOS bars in both the command reference and audit help. Custom bar children remain subject to the size check. Reference

Could one occlusion decision and the existing marker use normalized movement evidence from capture and the measured viewport from state assembly, intersect the supported reachable path with that viewport once, and check it against the cover? Extend the existing projection with supported axis, direction and sufficient travel evidence where available, reuse the existing rect and scroll contracts, remove class-name reachability branches and assumed edge travel, and retain the finding when clearance cannot be established.

One lower-priority thread still applies. These threads can be resolved: bottom navigation classification is fixed at head (#4652 (comment)); exact native parent identity and the custom-bar regression are present (#4652 (comment)); canonical bottom-navigation kind is published for concrete Android classes (#4652 (comment)).

Not blocking: the interaction error comment can be removed or updated to describe the guarantee after the shared decision enforces it; take or leave this change.

Please also include before-and-after fixture output for the named Safari History and nested-scroll Row findings, and a live record at this head of OS-generated iOS labels.

This is the fourth round on the scroll-clearance decision. If it does not converge in the next push, please consider splitting it out: land the finding names and the persistent-bar noise removal here, and move scroll clearance to its own PR with the live evidence.

@thymikee

Copy link
Copy Markdown
Member Author

I split scroll clearance out of this PR in ea1bbc878b. Audit now retains covered controls inside scroll views. Interaction refusals at persistent bars direct the caller to a visible target or to inspection. The package no longer publishes the inferred clearance marker. The help and docs cover captured labels, recognized native iOS bars, and persistent-bar recovery.

The remaining clearance work needs capture-owned travel bounds. The Android helper’s scroll actions and the iOS direction hints do not supply the distance. A follow-up needs a rootless 400×800 state-assembly test that fails without clipping, fit and edge cases, a short-travel case, and live blocked and revealable paths on Android and iOS.

I reran the ref fixtures with the production presenter and audit code. Full capture reports Safari History @e7 at 370×28 pt and nested scroll Row high @e4 at 370×40 pt. Both findings are absent from the interactive projection. Audit still uses full capture.

On iOS 26.2, T3 captured a native toolbar with a 30×30 pt unnamed direct item and a system Add item whose label was supplied by UIKit. It also captured a named 24×24 pt child of HomeToolbarView. Replaying the live capture through the audit code at ea1bbc878b reported missing-name @e3 for the unnamed direct item and small-target @e6 for the custom-bar child. T3's installed client could not connect to the checkout daemon because their RPC protocols differ. This is live capture plus offline audit replay.

The affected gate passed on ea1bbc878b with exactCommit=true.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on ea1bbc8. The verdict and the full list are in the summary comment.

@thymikee

thymikee commented Nov 18, 2026 •

Copy link
Copy Markdown
Member Author

This review covers ea1bbc8. The newer head 6d872cc requires exact persistent-bar identity, which answers the open custom-cover question, and it will get its own delta review. The items below do not depend on it. The earlier clearance policy is removed at ea1bbc8, and the changed assertions distinguish it from the retained behavior. The audit promises and live evidence still need work before merge.

The help says UIKit sheet grabbers are skipped, but the independent covered pass can still report a grabber covered by a later overlay. Can the system ownership rule also apply to covered findings and their duplicate-parent check, or can the help and reference limit the promise to size and name checks? Audit

The reference says captured labels are included when available, but a missing-name finding omits an Android resource identifier even when it was captured as the only label. Please state that missing-name findings omit labels rejected by the accessible-name check and can display the captured identifier. Reference

The supplied iOS capture used a different client and daemon pair followed by offline replay, and there is no daemon output at this head for either platform. Please record same-head native iOS and Android-helper runs through a protocol-compatible daemon, including commands, device, SHA and outputs. For each platform, show snapshot -i --json identifying the persistent cover, audit --json reporting covered-control for a covered control in a scroll view, and a fresh-ref press returning target_covered with the canonical cover, persistentBar: true and alternate-target or inspection guidance. The payload must omit scrollCanReveal and the hint must omit scroll and dismiss advice. On Android, show androidSnapshot.backend=android-helper and helperVersion matching package.json. On iOS, include the native direct item and custom-bar child, and show the daemon audit reporting missing-name without small-target for the unnamed native item, small-target for the custom child, and no missing-name for the captured Add label. The clearance matrix and clipping mutation belong with the deferred clearance implementation. Recovery

The custom cover persistence thread still applies; no lower-priority threads remain applicable. The bottom navigation thread is fixed by kind ordering and the viewport exemption. The iOS size thread is fixed by exact native identity and custom-child coverage. The clearance thread is fixed by removing the clearance policy. The Android kind thread is fixed by canonicalizing the bottom-navigation kind.

All 18 checks pass at ea1bbc8. There are no known conflicts. Align the grabber and label promises with the audit paths and attach the same-head daemon evidence before merge.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

b584745f7b limits the grabber exemption in help and the command reference to size and name checks. The reference now explains that missing-name findings omit rejected labels and show the captured identifier when available. The separate covered-control pass can report grabbers.

The affected gate passed with exactCommit=true. Same-head iOS and Android-helper daemon evidence remains open. The T3 device host still pins agent-device 0.21.36 at RPC protocol 2. Connecting that client to the branch-built protocol 3 daemon returns “Remote daemon RPC protocol is incompatible.” The prior iOS capture and offline replay remain separate evidence.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

At b584745, the HomeToolbarView name-fragment issue is fixed, but source identity and live device evidence still need work. All 18 hosted checks pass. There are no conflicts.

Could persistence require source-qualified native type or role evidence, or an explicit backend fact, on both cover construction routes? A labelled DOM toolbar can currently receive persistentBar from hit-test evidence, and a custom Android class can collide after its namespace is stripped. This can mark an app overlay as persistent and remove dismiss or scroll recovery for a covered ref. Please retain names and geometry for generic covers and add a labelled ARIA toolbar regression alongside the native and HomeToolbarView cases. https://github.com/callstack/agent-device/blob/b584745/packages/contracts/src/snapshot-text.ts#L35

Please attach raw output with the command, device and build SHA from the branch-built CLI (node bin/agent-device.mjs after pnpm build) and its own daemon on native iOS and Android-helper. On each device, show snapshot -i --json identifying the persistent cover, audit --json reporting covered-control for a covered scroll-view control, then take a fresh snapshot and press its fresh ref. The result must show target_covered, canonical coveredBy.kind, persistentBar: true, no scrollCanReveal, and an alternate-target or inspection hint without scroll or dismiss advice. Show androidSnapshot.backend=android-helper and helperVersion matching package.json. On iOS, also show missing-name without small-target for the unnamed native direct item, small-target for the custom-bar child, and no missing-name for the item with the generated Add label. The earlier capture and offline replay do not exercise the changed request route, and the reported installed client and branch daemon use different RPC versions. https://github.com/callstack/agent-device/blob/b584745/packages/selectors/src/interaction-error.ts#L91

Could the existing snapshot producer identity qualify persistence at cover construction, with viewport geometry kept local, generic named covers retained, and audit using verified direct-parent identity for the size exemption? What would have to change first to narrow the cover-evidence input so a generic role cannot authorize persistence while retaining the two marker consumers?

The HomeToolbarView thread can be resolved: exact matching and the dismissal regression address its reported case.

Before merge, please qualify persistence on both cover routes and attach the same-head iOS and Android-helper evidence.

@thymikee

Copy link
Copy Markdown
Member Author

c70a9dd57c qualifies persistent covers with snapshot producer identity. State assembly passes the producer to the geometric scan. Apple captures must supply a recognized native bar type or role, and Android captures must supply the full recognized class. The viewport host geometry remains local to the scan. The audit uses the same identity check on the immediate parent for the iOS size exemption.

The shared cover descriptor receives a verified bar kind separately from the observed type, role, label and rect. The backend hit-test and Android replacement-surface routes cannot pass a verified kind through their generic evidence. A future backend that can attest to a persistent cover would need a separate typed fact from that backend. Snapshot output and refusal recovery continue to read the one published marker.

The ARIA regression preserves the labelled cover and its rect without marking it persistent. Android snapshot assembly distinguishes the Material BottomNavigationView class from a custom class with the same leaf name. The affected gate passed with exactCommit=true.

The requested same-head live runs remain open. The local T3 device host still requires client 0.21.36, which supports RPC protocol 2. The branch daemon requires protocol 3. The earlier iOS capture and offline audit replay are separate evidence.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of c70a9dd

Since the review of b584745: 0 new · 0 still open · 0 no longer raised

No open findings.

1 new finding away from what changed since b584745 not shown. Comment @apex-sentinel-staging review for a full review.

Reviewed with this repository's own Sentinel configuration (6e18ea334968).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@thymikee

Copy link
Copy Markdown
Member Author

At c70a9dd, persistence now requires source-qualified native evidence, and the HomeToolbarView fix holds, but the native capture behavior still needs live evidence before merge. No conflicts are known. All 18 checks pass.

Could you attach raw output from c70a9dd using the branch-built node bin/agent-device.mjs and its own daemon on native iOS and Android-helper? The audit and covered-refusal route now depends on the capture producer and native type or class values, while the cited iOS capture and offline replay precede this change. Record the build SHA, device, commands, and output. On each device, show snapshot -i --json identifying a recognized persistent cover over a scroll-view control, audit --json reporting covered-control, and a fresh snapshot followed by a press of that covered ref. The refusal must show target_covered, the canonical coveredBy.kind and persistentBar: true, omit scrollCanReveal, and offer visible-target or inspection recovery without scroll or dismissal advice. The Android output must show androidSnapshot.backend=android-helper and a helperVersion matching package.json. On iOS, also show that an unnamed native direct item gets missing-name without small-target, a custom-bar child gets small-target, and the captured generated Add label avoids missing-name. This will establish that native capture preserves the class and producer through daemon assembly, audit, and a fresh-ref press. Capture route

Not blocking: The producer rows could own the native bar naming capability, with the classifier and iOS eligibility derived from that capability and the existing channel; take or leave this suggestion. Could SnapshotProducerFacts be extended under ADR 0038 so the contracts matcher and iOS exemption share that match, removing repeated producer checks while leaving cover publication and viewport geometry with their current owners? No new transport field or ADR appears necessary.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant