feat(linux): support Cursor provider via app auth token

[DonnieFi]

Summary

Adds Linux Cursor usage support by reading the signed-in Cursor app token from its XDG state database and reusing the existing cursor.com usage endpoints. macOS browser-cookie import and WebKit login behavior remain unchanged.

Maintainer improvements

• rebased on current main
• added Linux CSQLite3 support for direct state-database reads
• accept only absolute XDG_CONFIG_HOME values; otherwise use the standard ~/.config fallback
• keep Linux-only coverage compile-gated and use readable Swift Testing names
• corrected the disabled-source regression to exercise .web, not .auto
• advertise .web as an explicit Cursor source so the CLI can reach the supported manual-cookie path
• removed an inaccurate Linux Cursor path from macOS provider-storage tracking
• clarified manual configuration and Linux default/legacy path guidance

Behavior

Linux Cursor auth order remains explicit and fail-safe:

1. manually configured cookie header
2. cached session
3. signed-in Cursor app access token

Automatic browser-cookie import on Linux remains out of scope.

Proof

• clean Linux ARM64 container: release static CLI build succeeded
• Linux-focused Cursor suite: 7 tests passed in a clean ARM64 container
• macOS focused suites: 38 Cursor probe tests and 23 CLI entry tests passed
• full suite: all 47 shards passed
• make check: clean
• autoreview: final exact-head review clean, with no actionable findings
• direct production app-auth path against a real signed-in Cursor account returned valid finite plan usage; no identity, token, or usage details recorded
• the final maintainer delta is limited to source-mode alignment, regression coverage, and changelog credit; the production probe used by the live account proof is unchanged

Exact reviewed head: bdc9ae94a68dd35df7f2302ea5f65b70c93fc9d6

Thanks @DonnieFi for the contribution.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 5:34 AM ET / 09:34 UTC.

Summary
The PR adds Linux Cursor usage support by reading Cursor's XDG state SQLite app token, reusing the existing cursor.com web endpoints, adding Linux coverage/docs, and updating release notes.

Reproducibility: not applicable. for the feature request itself. For the prior review findings, source inspection shows Cursor .web is accepted by the descriptor and covered by Linux regression tests.

Review metrics: 2 noteworthy metrics.

• Diff surface: 6 files, +147/-10. The patch is small but crosses provider auth, CLI source routing, Linux tests, docs, and release notes.
• Linux Cursor coverage: 1 new file, 6 tests. The added tests directly cover XDG path resolution and the Linux Cursor source-mode contract that earlier review cycles flagged.

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

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

Rank-up moves:

• none.

Risk before merge

• [P1] The PR relies on Cursor's Linux state DB key and app-token-to-web-cookie behavior continuing to match Cursor's external service contract; tests can cover routing and parsing but cannot freeze that auth contract.
• [P1] When inspected, the current-head GitHub rollup still had some CI jobs queued or in progress, so merge should wait for the exact-head checks to finish cleanly.

Maintainer options:

1. Accept current Linux Cursor auth boundary (recommended)
   Merge after normal checks if maintainers are comfortable with the local Cursor app-token fallback and current auth precedence.
2. Require extra auth-path proof
   Ask for one more redacted Linux validation transcript covering automatic app auth and explicit manual-cookie mode before merge.
3. Defer the app-token path
   Pause or close this PR if Linux support should wait for a different Cursor-auth integration contract.

Next step before merge

• No ClawSweeper repair lane is needed; the remaining action is maintainer acceptance of the Linux Cursor app-token auth boundary and current-head check completion.

Maintainer decision needed

• Question: Should CodexBar accept Linux Cursor usage support by reading the signed-in app token from Cursor's XDG state database and deriving a first-party cursor.com session cookie?
• Rationale: The code path handles a provider credential and depends on Cursor's local app state and web-auth contract, so CI and source review cannot fully substitute for maintainer intent on that boundary.
• Likely owner: steipete — He owns the recent Cursor provider history and authored the latest maintainer repair commits on this auth path.
• Options:
  • Accept current Linux Cursor auth boundary (recommended): Merge after the current-head checks complete, relying on the existing precedence, Linux regression coverage, docs, and redacted live app-auth proof.
  • Require one more Linux auth transcript: Ask for an additional redacted transcript that separately demonstrates automatic app-auth and manual-cookie source behavior on Linux before merge.
  • Defer Linux app-token auth: Close or pause this PR if maintainers do not want CodexBar to derive Cursor web sessions from the local Linux app token.

Security
Cleared: The diff reads an existing local first-party Cursor token and does not add token logging, new dependency sources, broader permissions, or unrelated code execution paths.

Review details

Best possible solution:

Land the PR after current-head checks finish and maintainers accept the Linux Cursor app-token auth boundary, preserving macOS browser/WebKit behavior and the documented auth precedence.

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

Not applicable for the feature request itself. For the prior review findings, source inspection shows Cursor .web is accepted by the descriptor and covered by Linux regression tests.

Is this the best way to solve the issue?

Yes, pending maintainer acceptance of the auth boundary. The patch reuses the existing Cursor web strategy, keeps macOS browser/WebKit behavior gated, and adds Linux app auth as a fallback with focused coverage.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body reports reviewed-head Linux/macOS validation plus a redacted real Cursor account app-auth run that returned finite plan usage, and the maintainer delta did not change that production probe path.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P2: This is a normal-priority Linux provider feature with limited blast radius and no remaining actionable correctness finding.
• merge-risk: 🚨 auth-provider: The PR adds Linux Cursor app-token discovery and changes provider auth routing, which needs maintainer awareness beyond ordinary CI.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body reports reviewed-head Linux/macOS validation plus a redacted real Cursor account app-auth run that returned finite plan usage, and the maintainer delta did not change that production probe path.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body reports reviewed-head Linux/macOS validation plus a redacted real Cursor account app-auth run that returned finite plan usage, and the maintainer delta did not change that production probe path.

Evidence reviewed

What I checked:

• AGENTS.md policy read: Read the full repository AGENTS.md and applied provider data-siloing, cookie-import, focused-validation, and changelog/release guidance while reviewing this PR. (AGENTS.md:1, 9f1a96c3a77b)
• Diff surface: The PR head changes 6 files with 147 additions and 10 deletions across Cursor provider auth, CLI source handling, Linux tests, docs, and CHANGELOG. (bdc9ae94a68d)
• Linux app-token path: The PR resolves Cursor's Linux state DB from an absolute XDG_CONFIG_HOME or falls back to ~/.config before reading cursorAuth/accessToken. (Sources/CodexBarCore/Providers/Cursor/CursorStatusProbe.swift:426, bdc9ae94a68d)
• macOS browser import remains gated: The browser-cookie import and CursorCookieImporter helper paths remain under os(macOS), while app-auth fallback remains available after cached/stored session handling. (Sources/CodexBarCore/Providers/Cursor/CursorStatusProbe.swift:974, bdc9ae94a68d)
• Prior source-mode blocker fixed: Cursor now advertises .web, the Linux CLI bypass no longer rejects Cursor web/manual-cookie mode when cookies are enabled, and Linux tests cover the descriptor/source-mode contract. (Sources/CodexBarCore/Providers/Cursor/CursorProviderDescriptor.swift:36, bdc9ae94a68d)
• Proof and maintainer context: The PR body reports Linux/macOS focused validation, all-shard and make-check validation, and a redacted live production Cursor app-auth run; an OWNER comment says the maintainer repair at bdc9ae9 added .web source support and Linux regression coverage. (bdc9ae94a68d)

Likely related people:

• steipete: Current-main blame and shortlog heavily route the Cursor provider, CLI source-mode helper, and recent PR repair commits to steipete; he also merged the earlier Cursor app-auth fallback PR and authored the latest hardening commits on this branch. (role: recent Cursor provider/auth contributor and PR repair owner; confidence: high; commits: e437044c32ba, b60a510e5f32, 80803fb50ee3; files: Sources/CodexBarCore/Providers/Cursor/CursorStatusProbe.swift, Sources/CodexBarCore/Providers/Cursor/CursorProviderDescriptor.swift, Sources/CodexBarCLI/CLIUsageCommand.swift)
• Jackie-Qin: Merged PR fix: use Cursor app auth as fallback #1295 shows Jackie-Qin authored the initial Cursor app-auth fallback, review-feedback, and precedence commits that this Linux extension builds on. (role: introduced Cursor app-auth fallback; confidence: medium; commits: 1b0e2f1a7828, f29ededc4460, 5d7c00bcd9c5; files: Sources/CodexBarCore/Providers/Cursor/CursorStatusProbe.swift, Tests/CodexBarTests/CursorStatusProbeTests.swift, docs/cursor.md)

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.

Review history (6 earlier review cycles)

• reviewed 2026-07-05T01:56:15.756Z sha aa1a10d :: needs real behavior proof before merge. :: [P1] Keep the Linux browser import order empty | [P2] Move the Linux Cursor tests into the Linux test target
• reviewed 2026-07-05T02:01:52.776Z sha 447df44 :: needs maintainer review before merge. :: none
• reviewed 2026-07-05T02:07:33.590Z sha 447df44 :: needs changes before merge. :: [P1] Import the Linux SQLite shim before enabling Cursor on Linux | [P1] Guard the Cursor Linux tests from non-Linux runs
• reviewed 2026-07-05T05:25:00.397Z sha f968dd9 :: needs maintainer review before merge. :: none
• reviewed 2026-07-05T05:37:19.649Z sha f968dd9 :: needs changes before merge. :: [P2] Make Cursor web source actually supported
• reviewed 2026-07-05T09:30:23.376Z sha bdc9ae9 :: needs maintainer review before merge. :: none

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aa1a10df5c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Keep CursorCookieImporter types available on Linux

When this file is compiled on Linux, the new outer #if os(macOS) || os(Linux) includes CursorStatusProbe, but this added macOS-only guard removes CursorCookieImporter; the unguarded helper signatures below still reference CursorCookieImporter.SessionInfo (scanBrowsers, scanImportedSessions, and fetchIfSessionAccepted), so the Linux CLI target cannot compile. Either provide a Linux-compatible SessionInfo/stub or wrap those helpers in the same macOS-only condition.

Useful? React with 👍 / 👎.

[DonnieFi]

Thanks for the review — pushed fixes in 447df44:

1. Wrapped the macOS-only browser session helpers (scanBrowsers, fetchIfSessionAccepted, etc.) behind os(macOS) so Linux no longer references CursorCookieImporter.
2. Switched non-macOS defaultBrowserCookieImportOrder to [] instead of Browser.defaultImportOrder.
3. Moved Linux coverage into TestsLinux/CursorLinuxTests.swift.
4. Added redacted Debian proof to the PR body.

@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 repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f968dd93a7

ℹ️ 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]

Add Cursor web source before unblocking Linux web mode

For Linux Cursor manual-cookie runs with --source web or source: "web", this exception now skips the macOS-only web-support error, but CursorProviderDescriptor still declares only .auto and .cli (Sources/CodexBarCore/Providers/Cursor/CursorProviderDescriptor.swift:36) and CLIHelpers.fetchProviderUsage rejects unsupported source modes before the strategy runs (Sources/CodexBarCLI/CLIHelpers.swift:191). The result is still Source 'web' is not supported for cursor instead of using the configured manual cookie; either add .web to Cursor's source modes or limit this Linux exception to modes the descriptor actually accepts.

Useful? React with 👍 / 👎.

[steipete]

@clawsweeper re-review

Maintainer repair pushed at bdc9ae94a68dd35df7f2302ea5f65b70c93fc9d6: Cursor now advertises the explicit .web source already supported by the Linux CLI bypass, with Linux regression coverage. Focused macOS and Linux tests, all 47 shards, make check, and AutoReview are clean.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[steipete]

Landed as 7807679 after maintainer repair and exact-head validation. The final change aligns Cursor's explicit web-source contract, adds Linux regression coverage, and preserves the existing macOS browser/WebKit behavior and credential order.

Proof: Linux ARM64 focused suite 7/7; macOS Cursor 38/38 and CLI entry 23/23; all 47 local shards; make check; AutoReview clean; ClawSweeper exact-head review with no actionable finding; all required exact-head GitHub checks green. The production app-auth path was also exercised against a real signed-in Cursor account with sensitive values omitted.

Thank you @DonnieFi!