feat: add Wayfinder provider

[steipete]

Summary

Adds opt-in Wayfinder support for its local, read-only gateway: health, configured-route request split, savings, and average routing-decision latency in the menu, CLI, widget snapshot, and Settings.

This maintainer branch supersedes #1966 because the contributor branch does not allow maintainer edits. It preserves all of @tcballard's commits and co-author credit.

Maintainer hardening

• Follow the configured gateway URL for fetches and dashboard navigation, including path prefixes.
• Use an isolated ephemeral, cookie-free transport for the loopback service.
• Preserve cancellation from required and best-effort requests; keep ordinary metrics failures best-effort.
• Render the gateway, routed split, savings, and latency consistently across rich menu and CLI surfaces.
• Describe savings against the highest-cost route instead of assuming an always-cloud topology.
• Allow Wayfinder's credentialless API source to validate without a false missing-key warning.
• Keep configuration validation/provider lists and provider docs generated from shared supported-provider sets where practical.

Proof

Exact head: 3544b634eb79f645cebf373555cc36cfca6493be

• Public Model Identifier Gate: PASS; fixtures use clearly fictitious stand-in names only.
• Focused Wayfinder/menu/config suites: 48 passed.
• make check: passed.
• make test: all 50 shards passed.
• Structured branch review: clean after fixing its credentialless-config finding.
• Developer-ID signed debug package: CodexGitCommit=3544b634; deep/strict signature valid; Gatekeeper accepted; app binary SHA-256 fecca15cb16772ba0d91138d40e6ee44d17e22f373c8657a0ae5b29f2e1ed83f.
• Actual Wayfinder gateway 2026.7.0 on a non-default loopback port: packaged CLI reported Config: OK, healthy 2-model dry-run state, and average decision latency; unreachable gateway exited 1 with actionable guidance.
• Exact signed app: menu showed healthy 2-model dry-run state and latency; Settings showed the configured gateway and read-only/no-prompt guidance; changing the gateway to http://localhost:9191 persisted across relaunch and remained healthy.
• Screenshots stayed local.
• Dependencies unchanged; no dependency-freshness audit required.

Risk

Low and isolated: provider defaults off, requires no credentials, calls only documented read-only accounting endpoints, rejects unsafe remote plain HTTP and cross-origin redirects, and never sends or reads prompts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 9, 2026, 10:45 AM ET / 14:45 UTC.

Summary
The branch adds a default-off Wayfinder provider with local gateway polling, Gateway URL settings, menu/CLI/widget/docs wiring, and focused tests.

Reproducibility: not applicable. for the feature itself; current main has no Wayfinder provider, and I found no current-head review finding that needs a failing reproduction path.

Review metrics: 3 noteworthy metrics.

• Diff surface: 33 files changed, +1567/-177. The provider touches core, app UI, CLI, widget, docs, and tests, so maintainers should wait for full required checks.
• Provider default: 1 default-off provider added. Existing users are not opted into Wayfinder unless they explicitly enable it.
• Endpoint boundary: 4 read-only endpoints pinned. Tests verify the integration stays on health, model, savings, and metrics endpoints rather than prompt-routing APIs.

Root-cause cluster
Relationship: canonical
Canonical: #2006
Summary: This maintainer PR supersedes the earlier contributor Wayfinder PR while preserving its commits and adding hardening/proof.

Members:

• superseded: Add Wayfinder Provider (Local vs Hosted Router) #1966 - The current PR body explicitly says it supersedes the contributor branch because maintainers could not edit that branch, and it carries forward the same Wayfinder work with additional hardening.

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

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] This adds a built-in provider and Gateway URL setting, so final acceptance remains a product and maintenance-surface decision even though the implementation is default-off and owner-sponsored.
• [P1] Several live GitHub checks were still in progress when inspected, so required CI should finish before merge.

Maintainer options:

1. Decide the mitigation before merge
   Merge the default-off provider after maintainer scope approval and required checks, keeping the read-only endpoint boundary and shared provider UI/test coverage intact.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] Human merge/sign-off remains because this owner-authored feature adds built-in provider/config surface; I found no narrow repair for automation.

Maintainer decision needed

• Question: Should CodexBar land Wayfinder as a built-in default-off provider once required checks finish?
• Rationale: The patch looks technically clean, but it adds built-in provider/config surface; VISION.md treats new features as sign-off work and this owner-authored PR should not be auto-merged by cleanup automation.
• Likely owner: steipete — The PR is owner-authored and Peter is also the clearest provider/dashboard history owner from current-main provenance.
• Options:
  • Land after checks (recommended): Accept Wayfinder as a built-in default-off provider after required CI completes and normal maintainer review is satisfied.
  • Hold provider scope: Keep the PR open or defer it if maintainers decide Wayfinder should not become a bundled provider yet.

Security
Cleared: No concrete security or supply-chain concern was found; the PR adds no dependencies or credentials, validates endpoint overrides, and pins read-only gateway polling in tests.

Review details

Best possible solution:

Merge the default-off provider after maintainer scope approval and required checks, keeping the read-only endpoint boundary and shared provider UI/test coverage intact.

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

Not applicable for the feature itself; current main has no Wayfinder provider, and I found no current-head review finding that needs a failing reproduction path.

Is this the best way to solve the issue?

Yes, technically: the implementation follows the existing descriptor/fetch strategy/settings patterns, uses shared provider rendering, validates gateway overrides, and adds focused regression coverage. Product acceptance remains the maintainer decision.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ba64aa02f4e2.

Label changes

Label changes:

• add P3: This is an optional, default-off provider feature with limited existing-user blast radius.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this owner-authored PR, though the body includes live gateway, CLI, signed-app, menu, Settings, and relaunch proof.

Label justifications:

• P3: This is an optional, default-off provider feature with limited existing-user blast radius.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this owner-authored PR, though the body includes live gateway, CLI, signed-app, menu, Settings, and relaunch proof.

Evidence reviewed

What I checked:

• Repository policy read: Read the full 48-line AGENTS.md; provider-validation, proof, and check guidance informed the review. (AGENTS.md:1, ba64aa02f4e2)
• Wayfinder is new relative to main: The PR adds the wayfinder provider enum/registry wiring; current main does not already contain this provider, so the PR is not obsolete on main. (Sources/CodexBarCore/Providers/Providers.swift:60, 3544b634eb79)
• Provider implementation is default-off and credentialless: The descriptor registers Wayfinder as defaultEnabled=false with auto/api source modes, and the fetch strategy validates the endpoint override before fetching from the configured base URL. (Sources/CodexBarCore/Providers/Wayfinder/WayfinderProviderDescriptor.swift:30, 3544b634eb79)
• Read-only endpoint boundary: The fetcher polls healthz, router/models, v1/savings, and metrics; metrics are best-effort while cancellation is preserved. (Sources/CodexBarCore/Providers/Wayfinder/WayfinderUsageFetcher.swift:264, 3544b634eb79)
• Gateway URL validation and dashboard path: Wayfinder gateway overrides allow HTTPS or loopback HTTP only, strip query/fragment for dashboard navigation, and append /router to the configured base path. (Sources/CodexBarCore/Providers/Wayfinder/WayfinderSettingsReader.swift:19, 3544b634eb79)
• Earlier dashboard blocker fixed: StatusItemController now has a Wayfinder-specific dashboard branch that resolves the URL from Settings instead of falling back to the descriptor default. (Sources/CodexBar/StatusItemController+Actions.swift:295, 3544b634eb79)

Likely related people:

• steipete: Git history ties the current provider registry, endpoint validator, and adjacent ClawRouter provider pattern to Peter, and this owner branch adds the Wayfinder hardening commits. (role: provider/dashboard area owner and PR sponsor; confidence: high; commits: a83a83fa4131, efb7839ddf99, 0e864d70fd1a; files: Sources/CodexBarCore/Providers/ProviderDescriptor.swift, Sources/CodexBarCore/ProviderEndpointOverrideValidator.swift, Sources/CodexBarCore/Providers/ClawRouter)
• tcballard: The preserved branch commits and related contributor PR add the original Wayfinder core, app wiring, tests, docs, and route-summary fix. (role: original Wayfinder implementation contributor; confidence: high; commits: d9ceb664f2dd, 6db1876c9e4b, 59f2236174b3; files: Sources/CodexBarCore/Providers/Wayfinder, Sources/CodexBar/Providers/Wayfinder, TestsLinux/WayfinderProviderLinuxTests.swift)
• JC: CrossModel is a recent adjacent provider addition with similar loopback-friendly endpoint validation patterns used by the Wayfinder implementation. (role: adjacent provider pattern contributor; confidence: low; commits: 0a18391e1838; files: Sources/CodexBarCore/Providers/CrossModel, Sources/CodexBar/Providers/CrossModel)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.

[steipete]

Maintainer proof for exact head 3544b634eb79f645cebf373555cc36cfca6493be:

• Public Model Identifier Gate: PASS. The only model labels added are clearly fictitious fixtures.
• Focused Wayfinder/menu/config coverage: 48 passed.
• make check: passed; make test: all 50 shards passed.
• Structured branch review: clean after the credentialless-config fix.
• Developer-ID signed debug app: CodexGitCommit=3544b634; deep/strict signature valid; Gatekeeper accepted; app binary SHA-256 fecca15cb16772ba0d91138d40e6ee44d17e22f373c8657a0ae5b29f2e1ed83f.
• Real Wayfinder 2026.7.0 gateway on a non-default loopback port: packaged CLI showed healthy 2-model dry-run state and latency; an unreachable gateway exited 1 with actionable guidance.
• Exact signed app showed the same healthy state. Changing the gateway to http://localhost:9191 persisted across relaunch and remained healthy. Settings correctly described read-only polling and no prompt access.
• Exact-head CI: Linux x64/arm64, lint, changes, security, and all four macOS shards passed.
• Dependencies unchanged; no freshness audit required.

Screenshots remained local. This is ready to land.