Skip to content

fix(tray): close the 16 findings of the macOS tray UX + settings-parity audit - #1055

Merged
github-actions[bot] merged 5 commits into
mainfrom
fix/tray-ux-audit
Aug 25, 2026
Merged

github-actions[bot] merged 5 commits into
mainfrom
fix/tray-ux-audit

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 25, 2026 •

Copy link
Copy Markdown
Member

Fixes all 16 findings of the macOS tray UX + settings-parity audit (docs/qa/ux-audit-macos-tray-2026-08.md on audit/ux-macos-tray-sweep), in the sequence that audit suggests.

P1

  • F1 — the menu-bar icon now badges server health. Menu/TrayIcon.swift (a SwiftUI label nothing ever instantiated) is deleted along with AppState.healthLevel/HealthIndicator, and updateStatusIcon() draws the red/orange severity dot itself. It is an attributed-title glyph, not a composite image: the status image must stay isTemplate to follow the menu bar, and a template image is re-rendered monochrome.
  • F2 — every updateStatusIcon() pass sets the image's accessibilityDescription, the button's toolTip and its accessibility label ("MCPProxy — 13/29 servers, 942 tools — 3 server errors").
  • F3 — enable/disable/restart/login no longer swallow errors. One perform(_:on:id:) helper dispatches all of them and raises an NSAlert on failure, offering Open Server Details / Report an Issue / Dismiss.
  • F4 — a "Needs Attention" row no longer runs an API action on a click that reads as navigation. Actioned rows became submenus carrying the verb (Sign in, Restart) plus Open Server Details; rows with no action stay plain navigate-only rows.
  • F5 — SidebarItem.tokens wires the finished TokensView into the main window.

P2

  • F6 — security.deep_scan.enabled, instructions (new .textarea control, placeholder fetched live from /api/v1/status.default_instructions) and code_execution_max_parallel added. scripts/check-settings-parity.py — already a required CI gate — was widened from duration fields to full key coverage plus control / placeholder / optional / step / min / max / restart / select options, excluding server_edition.*. It strips comments, rejects duplicate keys and refuses a non-string-literal key rather than skipping it. It now pins 58 settings.
  • F7 — Enable/Disable unconditionally; stdio no longer gets Start/Stop (which contradicted its own "Disabled" status line).
  • F8 — (a) Review quarantine… in the per-server submenu, deep-linking to Server Detail → Tools. Residual: (b) is not in this PR — a native Security section wrapping deep scans, scan reports and TPA findings is the audit's own L-sized item and wants its own spec.
  • F9 — "Run at Startup" → Launch at Login (the name Settings already used), "Open MCPProxy..." → Open MCPProxy Window, "Open Web UI" → Open Web UI in Browser, plus a Settings footnote separating the two core-start controls from the menu's "Start/Stop MCPProxy Core".
  • F10 — a glance row's session id now reaches ActivityView and seeds a session_id filter with its own dismissable chip. Handed over on AppState, not by a delayed notification: a window created by the click subscribes its observers only after the post would have landed.

P3

  • F11 — profiles read "deploy (2 servers · 27 tools)", and one whose servers are not in the config reads "research — no servers" with a tooltip naming them.
  • F12 — Protocol: is display-normalised (HTTP (streamable), HTTP (SSE), HTTP, stdio).
  • F13 — 512m / 1.0 / docker.io placeholders, step on entropy_threshold and oauth_expiry_warning_hours (with a stepper control), telemetry copy caught up to the Web UI. All now held by the parity gate.
  • F14 — ProjectLinks.issues/.discussions are used: Report an Issue and Discussions in the About panel, in Settings → App, and as a button on the F3 failure alert. The unreferenced openConfigFile() selector is deleted. Deviation from the audit's literal fix: not a new top-level menu row — fix(tray): slim the menu + represent code_execution by its sub-calls #1023 deliberately cut the menu to stop it scrolling and MenuStructureTests pins that; these homes cost no row.
  • F15 — the Servers submenu groups by state (needs attention → active → disabled) and folds 3+ disabled servers behind Disabled (N) ▸.
  • F16 — a native Tools sidebar item: the whole catalogue when the box is empty, BM25 ranking over /api/v1/index/search when it is not. (APIClient.searchTools was calling /api/v1/tools?q= — an endpoint with no q — and reading a field that endpoint never returns, so it had always returned []; nothing consumed it.)

Three new Swift suites (TrayPresentationTests, TrayAuditMenuTests, TrayAuditSurfacesTests) drive the real rebuildMenu() and the presentation rules; the suite is 1110 tests. No Go changes.

Cross-model review

Reviewed with opencode (gpt-5.6-sol) over four rounds; every finding was verified against the source before being acted on, and round 4 returned CLEAN.

  1. Query values were encoded with .urlQueryAllowed, which deliberately permits &, =, + and ? — a tool search for a&limit=1 became a second parameter. Added APIClient.escapeQueryValue; the activity list, the export and the tool search all use it.
  2. "Export with current filters" dropped two of them. The export built its own query and never carried parent_id (pre-existing) or the new session_id, so a filtered view exported the whole log. Both now come from the same activeFilterParams the list uses.
  3. The status item could say "4 server errors" over a badge that counted three. worstDiagnosticSeverity looks only at enabled servers; the label was counting every diagnostic of any severity. Added AppState.diagnosticCount(severity:).
  4. Server names are validated only against :, so my/server would split the /servers/{id}/… path every menu action posts to. Added APIClient.escapePathComponent.
  5. optionalScalarStored trimmed spaces but not newlines — with the new textarea, a box holding one stray newline saved as custom instructions instead of resetting to the default.
  6. Parity-gate false negatives: a commented-out field counted as editable, a duplicate key silently won, a drifting control or a removed select option passed, and a non-literal key was skipped. All four now fail the gate (each verified by breaking the catalogue and watching it fail).

…rity audit

Menu-bar icon now badges server severity and is labelled for VoiceOver;
per-server actions report failure instead of closing silently; a "Needs
Attention" row navigates and its remediation lives under its own verb.
Agent Tokens and a new global Tools search reach the sidebar, the Servers
submenu groups by state, and the settings catalogue regains the three
web-only fields behind a full key-coverage parity gate.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 25, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: c173342
Status: ✅  Deploy successful!
Preview URL: https://d2fd355c.mcpproxy-docs.pages.dev
Branch Preview URL: https://fix-tray-ux-audit.mcpproxy-docs.pages.dev

View logs

Cross-model review round 1: escape query values (urlQueryAllowed lets
&/=/+ through), carry the sub-call and session filters into the activity
export, count only the badged severity in the status-item label, treat a
newline-only optional field as unset, and widen the settings parity gate
to control/restart/options with comment stripping and duplicate detection.
Cross-model review round 2: server names are only validated against ':',
so 'my/server' would split the /servers/{id}/... path the menu's enable,
disable, restart and sign-in actions all post to.
Cross-model review round 3: publish the pending session on AppState so a
window created by the click picks it up on appear (a delayed notification
lands before ActivityView subscribes), and make the parity gate refuse a
non-string-literal field key instead of silently skipping it.
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Aug 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: fix/tray-ux-audit

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (25 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (21 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 32848108497 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved (Model B): Paperclip review verdicts = ACCEPT and qa-gate green at this head SHA. Arming auto-merge; GitHub merges when all required checks pass.

@github-actions
github-actions Bot enabled auto-merge (squash) August 25, 2026 17:24
@github-actions
github-actions Bot merged commit 7e33f68 into main Aug 25, 2026
38 checks passed
github-actions Bot pushed a commit that referenced this pull request Aug 25, 2026
…ve catalog (#1056)

PR #1050 marked the field restart-required in the Web UI one minute before
PR #1055 landed the widened settings-parity gate; neither branch saw the
other, and native-tests.yml is path-filtered to native/**, so main went red
on a job that had not run since 08-22. One-line catalog sync; parity now
reports 58 settings consistent.
Dumbris added a commit that referenced this pull request Aug 26, 2026
The document read as an open backlog, but #1055 ("fix(tray): close the 16
findings of the macOS tray UX + settings-parity audit", merged 2026-08-25) fixed
all 16, with #1056 as a catalogue follow-up. The header's "no version skew, so
every finding below is reproducible from source" is no longer true against main.

- Header scopes that claim to the time of the walk and carries a status banner.
- New §6 Resolution records the two fixes whose obvious implementation is wrong:
  F1's severity dot is an attributed-title glyph, not a composite image (the
  status image stays isTemplate and a template image renders monochrome), and F6
  added a parity gate rather than just the three missing keys.
- Verified on main rather than taken on trust: Menu/TrayIcon.swift is deleted,
  TokensView is reachable from Views/MainWindow.swift, MCPProxyApp.swift sets
  isTemplate + accessibilityDescription + toolTip + attributedTitle glyph, and
  SettingsCatalog.swift carries deep_scan / instructions /
  code_execution_max_parallel.

Note for anyone tracing this later: #1053's body claims to fix these 16 tray
findings, but #1053 touches no Swift file — it is the Web UI cluster its own
title names. #1055 is the tray PR.

The caveat is stated rather than hidden: this pass could not re-walk the live
tray, because macOS Accessibility was revoked on the reviewing machine
(check_accessibility -> trusted:false), so the resolution is read from the #1055
diff, not from a second walk.
Dumbris added a commit that referenced this pull request Aug 26, 2026
The document read as an open P0-P3 backlog, but seven PRs merged on 2026-08-25
(#1044, #1048, #1049, #1051, #1052, #1053, #1054) closed it. Anyone opening this
file against current main was being handed 36 stale defects.

Added a status banner and a Resolution section that separates three things
honestly:

- Re-checked live on v0.61.0 against a running isolated core with real /mcp
  traffic: F1, F4, F5, F7, F8, F12, F13, F20, F24, F26, F33 confirmed fixed,
  each with the observed evidence rather than a PR reference.
- Still open: F6 is half fixed. Focus enters the Add Server dialog and submit is
  in a sticky footer, but Escape still does not close it - AddServerModal.vue has
  no key handler and JsonViewer.vue is the only component under components/ that
  handles Escape at all. F28's "key called optional" half is fixed; its
  three-surfaces state is not.
- Not re-checked: named explicitly rather than implied, so the next reader knows
  which closures rest on a PR body and which on an observation.

Five defects found on main while re-checking are recorded separately, since they
are not regressions of anything in the audit. The first is security-relevant:
quarantining a server through the config file leaves its tools in the search
index, so retrieve_tools still hands the agent their names and descriptions -
which is exactly what quarantine exists to prevent - before the call is refused.
Runtime.QuarantineServer purges the index; the reload path detects the same
transition (quarantined_changed: true) and does not.

Also corrects the record on #1053: its body names F1-F16, which is the tray
audit's numbering mis-pasted. #1055 is the tray PR; #1053 touches no Swift file.
Dumbris added a commit that referenced this pull request Aug 26, 2026
The document read as an open P0-P3 backlog, but eight PRs merged on 2026-08-25
(#1044, #1048, #1049, #1050, #1051, #1052, #1053, #1054) closed it. Anyone
opening this file against current main was being handed 36 stale defects.

Added a status banner and a Resolution section that separates four things:

- Re-checked live on v0.61.0 against a running isolated core with real /mcp
  traffic: F1, F4, F5, F6, F7, F8, F12, F13, F20, F24, F26, F33 confirmed fixed,
  each with the observed evidence rather than a PR reference.
- Not re-checked: named explicitly rather than implied, so the next reader knows
  which closures rest on a PR body and which on an observation. F28 is called
  out as partial - its "key called optional" half is fixed, its
  three-surfaces-at-once state is not.
- Corrections to the audit itself: F23 mis-diagnosed a per-request structural
  estimate as a stale aggregation, and F31's "Manual badge has no tooltip" half
  was wrong even at audit time (spec-088 trust-mode badge, already titled).
- Five defects found on main while re-checking, recorded separately since they
  are not regressions of anything in the audit. The first is security-relevant:
  quarantining a server through the config file leaves its tools in the search
  index, so retrieve_tools still hands the agent their names and descriptions -
  which is exactly what quarantine exists to prevent - before the call is
  refused. Runtime.QuarantineServer purges the index; the reload path detects
  the same transition (quarantined_changed: true) and does not.

F6 carries a methodology note. Re-checking it produced a false negative: Escape
driven through the browser-automation layer never reaches the page's document
keydown listener, so the dialog looked stuck open. Dispatched in-page it closes
at once, and #1050's useModalA11y is wired into all five <dialog :open> modals.
The sweep assertion this document proposes must dispatch in-page, or it tests
the automation layer instead of the app.

Also corrects the record on #1053: its body names F1-F16, which is the tray
audit's numbering mis-pasted. #1055 is the tray PR; #1053 touches no Swift file.
Dumbris added a commit that referenced this pull request Aug 26, 2026
Replaces the "could not re-walk" caveat with the walk itself. macOS
Accessibility was granted, so mcpproxy-ui-test works now; the walk reproduces
this audit almost verbatim, because the installed tray is still v0.60.0 with
"Update 0.61.0 — ready to restart?" sitting in the menu.

Reproduced live: F2 (empty status-bar title, no description, no tooltip), F5 (no
Agent Tokens entry), F7 (ElevenLabs "Stop" vs cloudflare-graphql "Disable"; and
memory showing status Disabled above action Start), F8 (all three quarantined
servers offer only Disable/Stop, Restart, View Logs), F11 (research and deploy
still offered at 0 tools), F12 (streamable-http beside http and sse), F15 (29
flat entries), F16 (no tool search), and the pre-#1055 menu labels.

One drift worth noting: the Clients block now reads "No clients in the last 24h"
rather than listing an idle client - the empty state H5 exists to avoid.

The consequence for the resolution section: #1055's fixes are real in the diff
but remain unverified against a running tray. That needs the pending 0.61.0
restart or the dev bundle-swap, neither of which this pass did - restarting the
tray kills the core it manages.
Dumbris added a commit that referenced this pull request Aug 26, 2026
* docs(qa): Web UI UX audit — ranked findings (ux-audit epic)

Heuristic + live-instance audit of every routed Web UI view in light/dark,
first-run and populated states, at 1440/820/390px. 36 findings ranked P0-P3
with view, evidence, heuristic violated, suggested fix and effort.

Audited against standard heuristics plus the house activity-UI rules
(grouping, failure-only status, intent reason, histogram/log parity).

* docs(qa): record what the Web UI audit's backlog actually resolved to

The document read as an open P0-P3 backlog, but eight PRs merged on 2026-08-25
(#1044, #1048, #1049, #1050, #1051, #1052, #1053, #1054) closed it. Anyone
opening this file against current main was being handed 36 stale defects.

Added a status banner and a Resolution section that separates four things:

- Re-checked live on v0.61.0 against a running isolated core with real /mcp
  traffic: F1, F4, F5, F6, F7, F8, F12, F13, F20, F24, F26, F33 confirmed fixed,
  each with the observed evidence rather than a PR reference.
- Not re-checked: named explicitly rather than implied, so the next reader knows
  which closures rest on a PR body and which on an observation. F28 is called
  out as partial - its "key called optional" half is fixed, its
  three-surfaces-at-once state is not.
- Corrections to the audit itself: F23 mis-diagnosed a per-request structural
  estimate as a stale aggregation, and F31's "Manual badge has no tooltip" half
  was wrong even at audit time (spec-088 trust-mode badge, already titled).
- Five defects found on main while re-checking, recorded separately since they
  are not regressions of anything in the audit. The first is security-relevant:
  quarantining a server through the config file leaves its tools in the search
  index, so retrieve_tools still hands the agent their names and descriptions -
  which is exactly what quarantine exists to prevent - before the call is
  refused. Runtime.QuarantineServer purges the index; the reload path detects
  the same transition (quarantined_changed: true) and does not.

F6 carries a methodology note. Re-checking it produced a false negative: Escape
driven through the browser-automation layer never reaches the page's document
keydown listener, so the dialog looked stuck open. Dispatched in-page it closes
at once, and #1050's useModalA11y is wired into all five <dialog :open> modals.
The sweep assertion this document proposes must dispatch in-page, or it tests
the automation layer instead of the app.

Also corrects the record on #1053: its body names F1-F16, which is the tray
audit's numbering mis-pasted. #1055 is the tray PR; #1053 touches no Swift file.
Dumbris added a commit that referenced this pull request Aug 27, 2026
* docs(qa): macOS tray UX + settings-parity audit

Read-only sweep of the running v0.60.0 tray (accessibility-tree menu walk)
plus a static comparison of the tray's native surfaces and settings
catalogue against the Web UI.

Parity matrix (feature surfaces, settings fields, per-server actions) and
16 ranked findings: dead menu-bar health badge, unlabelled status item,
silent action failures, unreachable Agent Tokens view, and three settings
fields that drifted out of the tray catalogue.

* docs(qa): mark the tray audit resolved, and say what was not re-verified

The document read as an open backlog, but #1055 ("fix(tray): close the 16
findings of the macOS tray UX + settings-parity audit", merged 2026-08-25) fixed
all 16, with #1056 as a catalogue follow-up. The header's "no version skew, so
every finding below is reproducible from source" is no longer true against main.

- Header scopes that claim to the time of the walk and carries a status banner.
- New §6 Resolution records the two fixes whose obvious implementation is wrong:
  F1's severity dot is an attributed-title glyph, not a composite image (the
  status image stays isTemplate and a template image renders monochrome), and F6
  added a parity gate rather than just the three missing keys.
- Verified on main rather than taken on trust: Menu/TrayIcon.swift is deleted,
  TokensView is reachable from Views/MainWindow.swift, MCPProxyApp.swift sets
  isTemplate + accessibilityDescription + toolTip + attributedTitle glyph, and
  SettingsCatalog.swift carries deep_scan / instructions /
  code_execution_max_parallel.

Note for anyone tracing this later: #1053's body claims to fix these 16 tray
findings, but #1053 touches no Swift file — it is the Web UI cluster its own
title names. #1055 is the tray PR.

The caveat is stated rather than hidden: this pass could not re-walk the live
tray, because macOS Accessibility was revoked on the reviewing machine
(check_accessibility -> trusted:false), so the resolution is read from the #1055
diff, not from a second walk.

* docs(qa): correct two §1 claims that were wrong at the time of the walk

Verified against v0.60.0 rather than taken on trust:

- The tray Settings tab is named "Raw", not "Raw JSON"
  (native/macos/MCPProxy/MCPProxy/Views/SettingsView.swift:38 at v0.60.0). The
  §1.2 inventory, the §2 parity matrix and F6's body all said "Raw JSON".
- The Web UI had no /usage route at v0.60.0 - the router's path list runs
  /, /servers, /repositories, /search, /settings, /secrets, /sessions, /tools,
  /activity, /security, /tokens with no usage or overview entry. Usage was a
  Dashboard tab; /usage became a route later, in #1044. The parity matrix's
  "Usage report | ⚠ savings % on Dashboard | ✅ /usage | inconsistent" overstated
  the Web UI side of that comparison.

Also noted in §6 that three §1.1 menu labels have changed since the walk as part
of the F9 fix: Open MCPProxy Window, Open Web UI in Browser, Launch at Login.

* docs(qa): re-walk the live tray and record that the findings still hold

Replaces the "could not re-walk" caveat with the walk itself. macOS
Accessibility was granted, so mcpproxy-ui-test works now; the walk reproduces
this audit almost verbatim, because the installed tray is still v0.60.0 with
"Update 0.61.0 — ready to restart?" sitting in the menu.

Reproduced live: F2 (empty status-bar title, no description, no tooltip), F5 (no
Agent Tokens entry), F7 (ElevenLabs "Stop" vs cloudflare-graphql "Disable"; and
memory showing status Disabled above action Start), F8 (all three quarantined
servers offer only Disable/Stop, Restart, View Logs), F11 (research and deploy
still offered at 0 tools), F12 (streamable-http beside http and sse), F15 (29
flat entries), F16 (no tool search), and the pre-#1055 menu labels.

One drift worth noting: the Clients block now reads "No clients in the last 24h"
rather than listing an idle client - the empty state H5 exists to avoid.

The consequence for the resolution section: #1055's fixes are real in the diff
but remain unverified against a running tray. That needs the pending 0.61.0
restart or the dev bundle-swap, neither of which this pass did - restarting the
tray kills the core it manages.
Dumbris added a commit that referenced this pull request Aug 28, 2026
#1075)

* fix(tray): stop the permanent red badge, and shrink it to a corner dot

The v0.61.0 tray badge (#1055) sat red indefinitely on an install whose
only error-severity diagnostics belonged to quarantined servers, and it
was drawn as a full-size glyph beside the icon rather than a badge on it.

Tray badge — quarantined servers no longer tint it
  worstDiagnosticSeverity and diagnosticCount excluded OAuth
  login-required servers but not quarantined ones. mcpproxy still attempts
  a connection to a quarantined server so the scanner can export its tool
  definitions, and the failed attempt leaves an error-severity diagnostic
  behind — while the same payload reports health.level "healthy" /
  admin_state "quarantined". The menu header drew a calm yellow dot from
  serversNeedingAttention under a red menu-bar dot from
  worstDiagnosticSeverity, and the user could not clear it without
  approving or disabling the server.

  Both properties now share one ServerStatus.isBadgeExempt predicate so
  they cannot drift apart, and any future intentional non-connected state
  has one place to be added.

Tray badge — drawn as a corner dot, not a glyph beside the icon
  The severity badge was a full-size "●" plus a leading space in the
  button's attributed title, which widened the status item by about a
  character and read as a second icon. It is now a 6pt dot in the icon's
  bottom-right corner, as a subview: the status-item image must stay
  isTemplate to track the light/dark menu bar and to invert while the menu
  is open, and template rendering forces every pixel monochrome, so a
  coloured dot composited into the image comes back black. The view is
  hit-test transparent and ignored by accessibility, since the button
  already publishes the whole state as its label.

  ⏹ (core stopped) and ⚠ (core error) keep their full-size glyphs: those
  mean "nothing is working", which is worth the width and would be lost if
  collapsed into the same dot.

Diagnostics — two of mcpproxy's own messages no longer say "file a bug"
  `command "npx" has no args` (emitted by our own pre-spawn validation in
  connection_stdio.go) and the legacy-SSE `4xx for initialize POST` both
  fell through to MCPX_UNKNOWN_UNCLASSIFIED, whose catalog entry offers a
  "Report a bug" button. They now classify as MCPX_CONFIG_INVALID_COMMAND
  and MCPX_HTTP_LEGACY_SSE, with catalog entries and docs pages. The
  legacy-SSE rule is matched before the generic HTTP status-text fallback,
  which would otherwise claim it as a bare 403/404 and send the user
  hunting for a credential problem that does not exist.

Logging — one ListTools failure was three ERROR lines
  core.Client, managed.Client and Manager.discoverTools each logged the
  same failed list operation at ERROR. On an install with several stdio
  servers the periodic sweep hit this roughly once a minute per server,
  indefinitely. The two inner layers drop to Debug; the manager keeps the
  line at Warn, since it deliberately skips markSwept so the next sweep
  retries — a failure the code already plans to retry is not an error.

Tests
  - Swift: quarantine/OAuth badge exemption from live /api/v1/servers
    payload shapes, including that a genuinely broken server still tints
    red and that the spoken count agrees with the badge.
  - Swift: corner-dot geometry and colour asserted by rendering the view
    offscreen and reading pixels back — the status item cannot be
    screenshotted without a Screen Recording grant, and "it looked right
    once" is not a regression test.
  - Go: both new codes classify from the verbatim v0.61.0 error strings,
    ordinary HTTP statuses are unaffected, and both codes are registered.
  - Go: one ListTools failure is reported by exactly one layer, not at
    ERROR, and is still reported at all.

* fix(tray): anchor the badge dot to the icon, not the button

Cross-model review (opencode, gpt-5.6-sol) caught a real defect in the
corner-dot badge: it was a 6x6 subview positioned from `button.bounds` at
update time and pinned with `[.minXMargin, .maxYMargin]`. That anchors to
the BUTTON's bottom-right, but the dot belongs to the CENTRED 18pt icon,
and it broke in two independent ways.

  * Rate mismatch. When the status button shrinks by N, a right-pinned
    subview moves left by N while the centred icon's right edge moves left
    by only N/2 — the badge slides off the glyph it is badging.
  * Stale bounds. NSStatusItem is variableLength and resizes
    asynchronously, so the `button.bounds` read immediately after clearing
    `attributedTitle` (which updateStatusIcon does, in the same pass) is
    still the old, wider value. The dot is then laid out against an icon
    centre that no longer exists.

The overlay now fills the button, autoresizes with `[.width, .height]`,
and computes the dot inside `draw(_:)` from its own live bounds. Any
resize simply repaints in the right place, which removes both failure
modes rather than patching either. `hitTest` already returned nil, which
is what keeps the now-full-size overlay from swallowing every click.

Note `needsDisplayOnBoundsChange` is a CALayer property and does not exist
on NSView — the review suggested it and it does not compile. `setFrameSize`
is overridden instead.

Tests
  The drawing tests now RENDER the view and scan the bitmap for the pixels
  it actually painted, converting device pixels to points, rather than
  sampling one computed point. The earlier version guessed the bitmap's
  y-flip, read a transparent pixel, and would have reported "the view drew
  nothing" as a colour failure. Scanning asserts position, colour and
  restraint together and survives a geometry retune. Added:
  - the dot tracks the icon across button widths (the regression above)
  - a resize re-renders it in its new place
  - only the corner dot is painted, never a wash over the whole icon

* fix(tray): the status button is FLIPPED — pin it, test it, document it

Multi-agent verification found what both I and the cross-model review
missed, by compiling against real AppKit rather than reasoning about it:

    NSView().isFlipped          = false
    NSButton().isFlipped        = true
    NSStatusBarButton.isFlipped = true

The first commit in this PR (9c740c0) therefore shipped the badge in the
icon's TOP-right corner, not the bottom-right its comment and commit
message both claimed. `y = 2` in a flipped button is 2pt from the TOP, and
`.maxYMargin` pins to the TOP. Rendered inside a real 36x22 status button
the dot landed at bitmap rows 4-15 of 44 (top-first).

The second commit (5e773a9) already corrected it — but incidentally,
because TrayBadgeDotView is a plain NSView and computes the dot in its own
unflipped space. Nothing recorded that the design depends on that, and no
test could tell the two apart: every badge test rendered the view
standalone, where the flip never enters the picture.

  * `isFlipped` is now overridden to `false` explicitly. It is load-bearing,
    not incidental — overriding it to true silently moves the badge back to
    the top-right.
  * TrayBadgeDotView's and badgeDotFrame's comments described the OLD bug
    wrongly (they said the mask pinned bottom-right). Corrected, with the
    flipped-coordinate trap written down as the reason the design is shaped
    the way it is.
  * New TrayBadgeInStatusButtonTests renders the overlay inside a REAL
    NSStatusBarButton and asserts the dot is in the visual lower-right.
    Mutation-tested: flipping the overlay fails it with "badge is in the
    TOP half — the flipped-coordinate bug is back (rows 4...15 of 44)",
    matching the shipped bug's measured position exactly.

Also from the sweep:

  * The legacy-SSE string is mcp-go's exported `transport.ErrLegacySSEServer`,
    NOT one of ours as the classifier comment, the test file and the PR body
    all claimed. Corrected, `errors.Is` added as the primary check (the
    substring fallback stays, since the upstream layer stringifies the error
    and breaks the errors.Is chain), and TestLegacySSESentinelStillMatches
    pins the vendored wording — otherwise a routine mcp-go bump silently
    regresses MCPX_HTTP_LEGACY_SSE to MCPX_HTTP_404 with the suite green.
  * `serversWithDiagnostic` was left on the narrower OAuth-only predicate
    when isBadgeExempt was introduced, breaking the "these filter
    identically" invariant at birth. Nothing consumes it today, which is
    precisely why the drift would have surfaced late. Aligned, and pinned by
    a test.
  * `isQuarantineReview`'s comment claimed `quarantined` and `admin_state`
    were two independent signals. They are not — health/calculator.go derives
    the second from the first. The check is kept as belt-and-braces; the
    claim is corrected.
  * Added the composition case nothing covered: servers are quarantined on
    add, so a newly added npx-with-no-args server is quarantined AND broken.
    It asks for review rather than raising a red badge — deliberate, now
    pinned, along with the case that it DOES alarm once released.

* test(tray): skip the status-button render test when there is no window server

TrayBadgeInStatusButtonTests creates a real NSStatusBar item, which is the
whole point — the flipped-coordinate bug is invisible to a standalone
render. But `swift test` runs on a macos-latest runner whose window-server
state is not guaranteed, and there `item.button` is nil. XCTUnwrap turned
that into a FAILURE, so a green local run could have gone red in CI for a
reason the test cannot assert there.

Throws XCTSkip instead. The assertions are about AppKit geometry inside a
real button; with no button there is nothing to assert, and that is a skip,
not a defect.
Dumbris added a commit that referenced this pull request Aug 29, 2026
…inish the ux-audit sweep (#1085)

* chore(roadmap): truth-sync ux-audit and upgrade-nudge

Two epics claimed a state the repo contradicts.

upgrade-nudge was `done` with all four tasks done, but Spec 079 FR-002 —
the human-readable "N releases / M weeks behind" delta required on status,
doctor, the startup log, the Web UI and both trays — was never built. The
four shipped tasks are US-slices and the FR belonged to none of them; spec
079 has only spec.md, so no checkbox surface could catch the gap. It
survived only as TODO(spec-079/FR-002) comments in
internal/updatecheck/checker.go and cmd/mcpproxy/status_cmd.go, which is
how an outside contributor found it (#1081). Epic back to in_progress with
an explicit upgrade-nudge-delta task.

ux-audit was `todo` with both sweeps todo, but both shipped in August
(#1046 Web UI, 36 findings; #1043 macOS tray, 16 findings) along with ten
PRs closing every finding and the five defects the re-check pass raised
(#1061/#1064/#1065, all closed). Recorded the sweeps and fix waves as done
and added the two items that really are open: folding the audit's F6 modal
Escape/focus and F1 cross-view total assertions into e2e/web-ui-sweep, and
verifying the tray fixes on a running tray (the 2026-08-26 re-walk found
the installed tray still on v0.60.0, so #1055 remains unobserved).

Also cleared the two --check-github errors, neither introduced here:

- tpa-db and mcp-2026-upgrade each linked a docs(specs) PR in `pr:`. That
  field is implementation evidence, so a spec merge read as "epic done".
  Both entries' own notes already said implementation had not started;
  moved the refs into the notes and left the statuses honest at todo.
- analytics-default-landing (#1044) and schema-deferred (#1063, tasks.md
  89/89) were genuinely finished and are now done.

* feat(079): "N releases / M weeks behind" upgrade delta (FR-002)

Closes the last outstanding slice of Spec 079. FR-002 requires the
current version, the latest version AND a human-readable delta on
`mcpproxy status`, `doctor`, the startup log, the Web UI and both trays;
what shipped was latest-version-only, and the deferral survived as
TODO(spec-079/FR-002) comments that an outside contributor found (#1081).

The blocker was data, not rendering: the checker fetched only
/releases/latest, so it had the offered release's publish date but not the
running one's, and no tag sequence to count.

internal/updatecheck/delta.go computes the delta as a pure, network-free,
clock-free function, so every spec rule is a table row. Fetching is a
best-effort enrichment hung off the existing check — never a second check
pipeline (FR-001):

- one page of /releases (ETag-conditional, so a repeat costs no rate-limit
  budget), plus a by-tag lookup only when the running build predates that
  page and its date is therefore unknown;
- both requests share one context deadline. A per-request timeout bounds
  each hop and nothing bounds the total, and CheckNow runs synchronously
  inside GET /api/v1/info?refresh=true, so an unbounded delta would stall
  a request a user is waiting on;
- counting is by semver, never by list position: GitHub orders the list by
  created_at, and the live data has v0.53.0-rc.9 sitting ahead of the
  later-published rc.10.

Three degradation rules matter more than the feature. A delta miss must not
set CheckError (statusVersionSuffix returns "" whenever it is non-empty, so
that would DELETE the nudge instead of enriching it), must not touch the
FR-018 backoff counters, and must leave every surface rendering exactly what
it rendered before. There is a regression test per rule.

The clause is rendered once in Go (FormatBehindSummary) and printed verbatim
by every surface, with the raw numbers alongside for machine consumers. That
is deliberate: GuidanceLine is already hand-ported into UpdateBanner.vue with
a "keep the two in sync" comment, and FR-002 asks for consistent framing
across five surfaces.

Fields are additive per FR-021 and had to be threaded through six
hand-maintained mirrors — VersionInfo, the InfoResponseUpdate DTO and its
copier, internal/contracts (→ make swagger), the contracts.ts generator,
status_cmd's map decoding, and the Swift tray's Codable, which turned out
never to have decoded the US2 fields either.

Two adjacent bugs fixed because the delta sits on the same code:

- GetLatestReleaseIncludingPrereleases returned releases[0] from a
  created_at-ordered list, so an RC user could be offered a release older
  than one already published. Now max-by-semver.
- GetReleaseByTag interpolated an unvalidated tag into the request path and
  deferred validation to callers by comment only. The delta feeds it the
  ldflags-stamped version, so it now validates and escapes.

Both trays render the delta in the update item's tooltip rather than its
title: Spec 092 FR-010 fixes the title's exact shape, and a menu row reading
"Update v0.62.0 — ready to restart? — 8 releases / ~14 weeks behind" stops
being scannable.

Known bound, accepted deliberately: the scan reads one 100-release page, so a
build older than that window reports a lower bound ("59+ releases") and a
semver-in-range release created long ago can be missed without setting that
flag. Spec 079's own assumption (L159) allows an approximation where an exact
count is unavailable, and the figure is motivational, not load-bearing.

Verified: unit + integration tests against an httptest GitHub (delta,
saturation, tag fallback, 304 reuse, budget, malformed tags), `go test -race`
across internal and cmd, golangci-lint v2 clean, 962 frontend unit tests, and
a live version-stamped instance confirming the degradation path renders the
pre-delta output when the check fails.

* test(ux-audit): finish the sweep's regression net, and fix what it caught

The August Web UI audit closes by asking for four assertions to be folded
into the committed sweep. Three were already there (F9 contrast, F30
accessible names + aria-live, F14 responsive); this adds the two that were
not, and then fixes the defects they immediately exposed on main.

F6 — the Add Server modal takes focus, traps Tab, closes on Escape and
restores focus to its trigger. These `<dialog :open>` modals are opened by
the `open` attribute rather than showModal(), so none of that comes from the
browser; it all comes from useModalA11y, whose own comment delegates the
real-browser half of its coverage to "the Playwright sweep" — a promise the
sweep did not keep. Escape is dispatched IN-PAGE, never via
page.keyboard.press: re-checking F6 during the audit produced a false
negative for exactly that reason, because a synthetic key never reaches the
document listener under test.

F1 — Activity and Usage must report the same 24h numbers as the API. The
invariant is not naive equality: Usage folds `blocked` into its error tile
while Activity splits them, and /activity/usage is served from a short read
cache while /activity/summary counts live, so the assertion polls for
convergence and encodes the real relationship.

Running the completed sweep turned up three defects already on main, none of
them regressions of the audit's 36:

1. The LANDING PAGE failed AA in both themes (3.09-4.23:1) and two of its
   controls had no accessible name. Usage.vue uses the raw `opacity-*`
   utility for muted text; #1054 fixed that failure mode for the
   text-base-content ramp and .stat-* but never covered raw opacity, and
   nothing caught it because the audit walked `/` before #1044 made Usage
   the landing page. Moved onto the AA-checked --tone-muted; both selects
   got an aria-label.

2. The Activity status pill clips at 390px for any status outside the known
   four. An unmapped status falls through to a ghost pill carrying the raw
   value, and `tool_auto_approved` measured 145px inside a 93px cell (the
   table is table-fixed below 640px). The pill now truncates against the
   cell and keeps the full value in its title, rather than the column being
   sized to today's longest label — which would hold only until the next
   status is added.

The phone check that finally caught #2 had been passing vacuously: it
measures rows.first(), and a `success` row — ~90% of traffic — renders an
sr-only label of zero width. It only became a real assertion once the new F1
check generated an error row and put one first. That coupling is worth
knowing about: the sweep shares one instance, so one check's traffic is the
next check's data, and a newly-failing neighbour after adding a check is more
likely a real find than a flake. Both were separated from the change under
test by running the same sweep against clean HEAD.

Sweep: 25 passed / 3 failed on clean HEAD, 30 passed / 0 failed now.

Roadmap: ux-audit was still carrying both sweeps as `todo` although they and
every finding shipped in August; recorded here along with what the completed
net found.
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.

2 participants