feat(desktop): add native macOS usage status bar

[donbeave]

Summary

Completes the jackin❯ Desktop — agent usage macOS status bar roadmap program. Operators get one native status item per detected provider, a limits-only Agent Usage glance popover, and a Capsule-parity Usage window, all driven by Rust-owned provider data and presentation.

What ships

• One menu-bar item per detected Codex, Claude, Amp, Grok, z.ai, Kimi, or MiniMax account, with provider icon, selected-account quota glance, honest unavailable/refreshing/stale states, and Amp Free Daily semantics.
• Left-click opens the provider tab; right-click exposes Open Usage Window, Refresh, and Quit. Provider headers open a resizable Usage window focused on that provider.
• The Agent Usage popover includes Overview/provider tabs, quota windows, reset countdowns, run-out projections, quota-bound balances, multi-account selection, and one shared Refresh action.
• Capsule and Desktop consume one Rust-owned limits presentation, preserving provider order, bucket order, labels, degradation, and quota meaning without Swift-side synthesis.
• Claude credentials can resolve through the macOS Keychain with scoped caching and serialized off-main access; Codex, MiniMax, z.ai, Amp, and Grok decoders reflect current provider contracts.
• macOS 14/15 material fallbacks and macOS 26 Liquid Glass chrome remain isolated behind the native fallback layer. Architecture and parity harnesses enforce display-only Swift and limits-only output.
• Operator, contributor, roadmap, research, release-readiness, and install-proof documentation now describe the completed program and its remaining public-activation boundary.

Behavior changes

• jackin❯ Desktop now auto-detects enabled providers instead of presenting one configurable aggregate status item or a Settings surface.
• Usage surfaces show subscription and quota limits only. Token prices, cost estimates, spend histories, and usage trends remain excluded.
• Release validation provisions every required tool and passes without secrets; public activation remains unavailable until authorized Apple signing/notarization and publishing actions exist.

What this addresses

• Completes plans 001–009 and 011 of the jackin❯ Desktop — agent usage macOS status bar roadmap item.
• Replaces duplicated Swift usage interpretation with a single Rust presentation contract shared by Capsule, FFI, the status bar, popover, and Usage window.
• Retires the prior native macOS usage-menu-bar program as superseded history and reconciles its operator documentation with the shipped design.

Hard rule: limits only

Every jackin❯ usage surface presents provider-supplied subscription or quota bounds only. Token unit prices, session-cost estimates, aggregate-spend rankings, and historical usage or spend trends are forbidden; the architecture harnesses enforce this boundary.

Not included

• Public notarized release and Homebrew tap activation. Plan 010 is rejected because Apple signing/notarization authority is absent and release/publish/tap-merge actions were outside the authorized execution boundary.
• Amp paid-plan monthly display semantics remain deferred pending an authenticated provider capture.

Verify locally

Checkout

Paste this first to bypass the tirith paste scanner for the rest of the session:

export TIRITH=0

Then paste the checkout block:

jackin-dev pr sync 827
cd "$(jackin-dev pr path 827)/jackin"
source "$(jackin-dev pr path 827)/env.sh"
which jackin

jackin-dev pr sync clones or refreshes the PR checkout, checks out the PR's real head branch, builds the local jackin binary, copies live config into the PR bundle, creates empty PR-scoped state, writes env.sh, builds and exports a local JACKIN_CAPSULE_BIN when the changed workspace package is in the jackin-capsule dependency closure, and auto-builds the PR construct image when the changed files require it. After source "$(jackin-dev pr path 827)/env.sh", echo "$JACKIN_CAPSULE_BIN" is set only when the PR requires a local capsule, and echo "$JACKIN_CONSTRUCT_IMAGE" is set only for PRs whose diff requires a local construct image.

Static checks

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings

Rust and Desktop tests

cargo xtask ci --fast
cargo xtask desktop test

The aggregate gate covers workspace correctness, while the Desktop gate exercises provider/FFI behavior and the native architecture, status-item, and parity harnesses.

Docs checks

(
  cd docs
  bun install --frozen-lockfile
  bun run build
  cargo xtask docs repo-links
  cargo xtask roadmap audit
  bunx tsc --noEmit
  bun test
)

User smoke — jackin❯ Desktop

Apple Silicon macOS with full Xcode preferred; Command Line Tools can run the repository harness lane.

mise install
cargo xtask desktop build --version 0.6.0 --build 1
cargo xtask desktop verify
cargo xtask desktop run

After launch:

• Confirm one status item appears for each detected supported provider and no item appears for unavailable providers.
• Left-click each item and confirm its provider tab opens; select Overview and provider tabs, switch accounts where available, and run Refresh.
• Right-click an item and confirm exactly Open Usage Window, Refresh, and Quit appear.
• Open the Usage window from the context menu and a provider header; confirm provider focus, row order, quota values, reset countdowns, and degradation states match the Capsule usage dialog.
• Confirm no Settings surface, token-price copy, cost estimate, history, trend, sparkline, donut, or spend ranking appears.

Quit after the smoke:

osascript -e 'quit app "Jackin Desktop"' 2>/dev/null || killall JackinDesktop 2>/dev/null || true

jackin-capsule smoke

jackin load the-architect . --debug

Inside the container, verify:

• Row 0 status bar is visible: jackin❯ [<agent-name>]
• Agent TUI starts and renders correctly below the status bar.
• The default Control+backslash shortcut opens the command palette.
• Open the usage dialog and confirm provider labels, bucket ordering, quota strings, reset countdowns, and degradation copy match jackin❯ Desktop for the same account snapshot.
• After refresh, run jackin usage <instance-or-container> verify --debug from the prepared checkout and record whether every provider row passes.

Documentation

(
  cd docs
  bun install --frozen-lockfile
  bun run dev
)

Vite serves at http://localhost:3000/. Pages to walk:

http://localhost:3000/guides/macos-usage-menu-bar/
UPDATED operator guide. Confirm installation boundary, local build flow, credentials, per-provider status items, popover interactions, Usage window, multi-account behavior, and privacy wording.

http://localhost:3000/reference/adrs/adr-011-native-macos-usage-menu-bar/
UPDATED ADR. Confirm the Rust-owned presentation and display-only Swift contract reflects the shipped multi-item design.

http://localhost:3000/roadmap/native-macos-usage-menu-bar/
UPDATED prior-program record. Confirm it is clearly superseded by the completed jackin❯ Desktop program and no longer presents stale implementation work.

http://localhost:3000/roadmap/
UPDATED roadmap overview. Confirm the native macOS usage-menu-bar item appears in the completed section.

Migration notes

None. jackin❯ Desktop remains pre-release; public notarized distribution is not activated by this pull request.