Add top-level plugin switcher tabs

[harjothkhara]

Adds opt-in topLevel: true plugin tabs using the manifest name and icon. Stable plugin identities drive mouse/keyboard selection, Refresh and Cmd-R. A single plugin works without a redundant switcher, multiple plugin tabs work without built-in providers, and legacy appended cards remain reachable. Merge Icons disabled retains appended-card placement.

This changes presentation only: existing sandbox capabilities, network approval, settings enablement and provider-data isolation remain in place. Overview still summarizes built-in providers.

Native verification exposed a stale-card bug in the proposal: Cmd-R fetched the new plugin snapshot, but the open card kept its old value because it shared the built-in path that defers parent rebuilds. Plugin cards capture snapshots rather than using the built-in live-value monitor. Completed plugin refreshes now request the existing guarded rebuild only for menus containing that plugin’s card, preserving native-highlight and hosted-submenu safeguards. Card refresh buttons share the manual-refresh scope and in-flight guard. The maintainer pass also removes duplicated selection logic and an Overview wrapper.

Verification:

• The rendered-menu regression failed two assertions before the repair; 146 tests across plugin, architecture, persistent-refresh and viewport suites pass afterward.
• make check: zero violations across 2,171 Swift files. Independent P0–P2 review is clean.
• Matching Developer-ID-signed synthetic native hosts exercised real menu clicks, Cmd-R and a card refresh button. Atlas changed from 50% used to 24% used, and its open card immediately showed 76% left. The sibling stayed unchanged. Refreshing Legacy changed only that card to 60% left.
• Native switching reached both plugin tabs; disabling the built-in provider preserved the selected plugin and both tabs, with Legacy still accessible. The completed native test passed with no failures. No live account data or provider requests were used.
• The native proof’s source patch matches commit 8c359f56c894b106caffdf1be40f27df42cdd4e7.
• Final make test passed all 1,059 selections across 89 groups in 905.1 seconds. One group passed on automatic retry after two unchanged Kiro login fixtures failed their first attempt (missing captured output / timeout); 88 groups passed first try, with no group timeouts or isolated-selection retries.
• All exact-head CI checks passed, including both macOS shards, Linux x64/arm64/musl, lint and security checks.

Existing appended-card placement, with the opt-in disabled:

Top-level tabs, showing the updated value after Cmd-R:

Includes authoring documentation and an Unreleased changelog entry. Thanks @harjothkhara!

Fixes #2988.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 9, 2026, 3:59 PM ET / 19:59 UTC (Revision 10).

ClawSweeper review

What this changes

Adds opt-in provider-plugin tabs to the merged menu switcher, preserves legacy plugin cards, and routes standard Refresh controls to the selected plugin.

Merge readiness

⛔ Blocked before merge - 3 items remain

This remains a useful, owner-approved enhancement absent from current main and the latest release. Earlier concrete findings are addressed, but real native behavior and upgrade compatibility remain unproven.

Priority: P2
Reviewed head: b4cd88a019da01001895caf622123c6c8925ad3d

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch is focused and addresses prior defects, but fixture evidence cannot satisfy the native behavior proof gate.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The menu and Refresh changes have synthetic fixture coverage, but the captured native build stopped before launch, so visible tabs, after-refresh output, and upgraded preferences remain unobserved. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The menu and Refresh changes have synthetic fixture coverage, but the captured native build stopped before launch, so visible tabs, after-refresh output, and upgraded preferences remain unobserved. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	9 items	Applicable repository policy: Read the full root AGENTS.md and checked Sources, Tests, docs, and .agents for nested policies and maintainer notes; none were found. Applied provider isolation, isolated approval-store testing, and fresh-bundle UI proof guidance. No builds, tests, or repository mutations were performed. Owner approval resolves product direction: The OWNER comment explicitly endorses topLevel: true, stable plugin tab identity and icons, settings parity, and unchanged sandbox and approval boundaries: #2988 (comment). Verified introduced scope: Inspected the complete local merge-base-to-head diff across all 19 changed files. The branch adds 690 lines and removes 112; the supplied truncated patches were supplemented with local source reads.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar loads local provider plugins and displays their usage snapshots in its menu bar interface. The switcher combines enabled providers and plugin metadata to select which cards appear and which provider receives Refresh actions.

flowchart TD
  A[Plugin manifests and settings] --> B[Enabled provider identities]
  B --> C[Menu switcher selection]
  C --> D[Selected plugin and legacy cards]
  C --> E[Refresh action]
  E --> F[Existing plugin approval and runtime]
  F --> G[Provider usage snapshot]
  G --> D

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The menu and Refresh changes have synthetic fixture coverage, but the captured native build stopped before launch, so visible tabs, after-refresh output, and upgraded preferences remain unobserved. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - The new plugin manifest API changes menu placement and selection; fixture coverage supports compatibility, but preservation of existing preferences and legacy-card reachability has not been observed in a freshly built app after upgrade.
• Complete next step (P2) - Add real behavior proof from a freshly built app, including selected-plugin Refresh and preserved upgrade settings. Screenshots or recordings are preferred for visible behavior; redacted logs or live output also count. Remove private information before posting. Updating the PR body should trigger another review; otherwise ask a maintainer to comment @clawsweeper re-review.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	Production +304/-85 lines; tests +385/-27 lines; docs +1 line	Production growth implements the approved tab and refresh integration, while most added lines exercise compatibility and prior edge cases.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #2988
Summary: This PR implements the linked open request for first-class plugin switcher entries; the issue should remain open until implementation lands.

Members:

• canonical: Feature request: Allow user-installed provider plugins to appear as first-class entries in the provider switcher #2988 - The request describes the same manifest opt-in and placement change, and this PR explicitly proposes to close it.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Demonstrate preserved plugin setups (recommended)
   Provide fresh-bundle evidence that existing selections and legacy cards survive upgrade while opted-in plugins remain reachable and refresh correctly.

Technical review

Best possible solution:

Keep the approved opt-in design, with unchanged legacy placement and preferences demonstrated on fresh and upgraded installations.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this adds an approved capability, and current-main and release source confirm that plugin tabs are absent.

Is this the best way to solve the issue?

Yes: the opt-in flag reuses existing provider identities, settings, rendering, and approval checks; native compatibility validation is still needed.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 5e5a9003efb2.

Labels

Label justifications:

• P2: This is a bounded, approved navigation improvement for users of local provider plugins.
• merge-risk: 🚨 compatibility: The manifest API and merged-menu selection behavior expand without observed fresh-install and upgrade compatibility proof.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The menu and Refresh changes have synthetic fixture coverage, but the captured native build stopped before launch, so visible tabs, after-refresh output, and upgraded preferences remain unobserved. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Applicable repository policy: Read the full root AGENTS.md and checked Sources, Tests, docs, and .agents for nested policies and maintainer notes; none were found. Applied provider isolation, isolated approval-store testing, and fresh-bundle UI proof guidance. No builds, tests, or repository mutations were performed. (AGENTS.md:1, b4cd88a019da)
• Owner approval resolves product direction: The OWNER comment explicitly endorses topLevel: true, stable plugin tab identity and icons, settings parity, and unchanged sandbox and approval boundaries: Feature request: Allow user-installed provider plugins to appear as first-class entries in the provider switcher #2988 (comment).
• Verified introduced scope: Inspected the complete local merge-base-to-head diff across all 19 changed files. The branch adds 690 lines and removes 112; the supplied truncated patches were supplemented with local source reads. (b4cd88a019da)
• Current main retains appended plugin cards: Current main enumerates enabled plugins as appended cards and its manifest parser has no topLevel field. This is a distinct missing presentation capability, not a duplicate of supported configuration. (Sources/CodexBar/StatusItemController+UserPlugins.swift:7, 5e5a9003efb2)
• Latest release lacks dynamic plugin tabs: The v0.57.0 switcher initializer accepts built-in UsageProvider entries only; it has no plugin-provider input. (Sources/CodexBar/StatusItemController+SwitcherViews.swift:48, 45cda6084d64)
• Previous concrete findings addressed: Singleton selection no longer requires multiple switcher entries, selected plugin content includes legacy cards, and Refresh retains the dynamic provider ID and calls refreshUserPlugin. The refresh fixture records approval and injects its isolated approval store. The earlier review's native-proof request remains outstanding. (Sources/CodexBar/StatusItemController+Actions.swift:245, b4cd88a019da)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add fresh-bundle screenshots or a recording with observable Refresh results and fresh-install/upgrade evidence for singleton, mixed, and plugin-only configurations.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (9 earlier review cycles; latest 8 shown)

• reviewed 2026-09-08T20:09:08.454Z sha 60ce671 :: needs real behavior proof before merge. :: [P1] Keep legacy plugin cards reachable without built-in tabs | [P2] Resolve a sole top-level plugin independently of switcher count | [P2] Route standard Refresh controls to the selected plugin
• reviewed 2026-09-08T21:13:52.221Z sha 9dc6be9 :: needs real behavior proof before merge. :: [P1] Keep legacy plugin cards reachable without built-in tabs | [P2] Resolve a sole top-level plugin independently of switcher count | [P2] Route standard Refresh controls to the selected plugin
• reviewed 2026-09-08T21:32:33.696Z sha 7454ac9 :: needs real behavior proof before merge. :: [P1] Keep legacy plugin cards reachable without built-in tabs | [P2] Resolve a sole top-level plugin independently of switcher count | [P2] Route standard Refresh controls to the selected plugin
• reviewed 2026-09-08T22:58:30.540Z sha 933f47a :: needs real behavior proof before merge. :: [P2] Resolve singleton plugins without the multiple-provider merge gate
• reviewed 2026-09-08T23:55:51.212Z sha 657bf0a :: needs real behavior proof before merge. :: [P2] Approve the fixture plugin through an isolated approval store
• reviewed 2026-09-09T00:06:30.241Z sha 4c9575a :: needs real behavior proof before merge. :: [P2] Pass the isolated approval store to the remaining fixture call
• reviewed 2026-09-09T00:09:51.320Z sha 4c9575a :: needs real behavior proof before merge. :: [P2] Pass the isolated approval store to the remaining fixture call
• reviewed 2026-09-09T00:29:26.951Z sha 024fb34 :: needs real behavior proof before merge. :: none

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 681c63098f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-08T20:00:38.427269Z	681c630	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[harjothkhara]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[harjothkhara]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: Add top-level plugin switcher tabs This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

[steipete]

Landed in e9da079; #2988 is closed. Enabled plugins can opt into their own switcher tabs with topLevel: true, including plugin-only configurations, while legacy cards remain reachable. Contributor credit and the Unreleased changelog entry are preserved. Thanks @harjothkhara!

Native testing caught a real gap in the proposal: Cmd-R fetched the right snapshot but left the open card stale. Completed plugin refreshes now use the existing guarded rebuild path only for menus containing that plugin’s card. Card refresh buttons also share the scoped manual-refresh lifecycle and in-flight guard.

Verification, with credential and session isolation:

• swift test --filter 'UserProviderPluginTests|ProviderArchitectureGatekeeperTests|StatusMenuPersistentRefreshTests|StatusMenuViewportRestoreTests': 146 tests passed. The new rendered-menu regression failed two assertions before the repair.
• make check: zero violations across 2,171 Swift files.
• make test: 1,059 selections across 89 groups passed in 905.1 seconds. One group recovered on automatic retry after two unchanged Kiro login fixtures failed initially; 88 groups passed first try, with no group timeouts or isolated-selection retries.
• Independent P0–P2 review was clean, and every check passed in CI run 34498055897.
• Developer-ID-signed native proof exercised actual tab clicks, Cmd-R, a card refresh button, and disabling the built-in provider. Atlas immediately displayed 76% left after its scoped refresh; the sibling stayed unchanged. Legacy’s button updated only its card to 60% left. Both plugin tabs and the selection survived the plugin-only transition. The native test passed with no failures, and its source patch matches the reviewed commit.

The PR body contains inspected synthetic before/after screenshots. No real account data or live provider requests were used. Main is synchronized and clean.