Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

Merge main into PR 882 preserving provider and Claude error distinctions

review22c362605ceb
diff --cc CLAUDE.md
index a2ffbfdbc,113399c0e..2e4930da2
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -3001,8 -3110,11 +3110,13 @@@ command-bearing opens; this does not ad
that host (cache eviction still runs against the FULL target list, so switching between two SSH
projects doesn't throw each host's cache away).
+- **Grok billing failures** retain per-view HTTP status or a safe timeout/network/invalid-response category in `ProviderUsage.diagnostics`. The default view still runs after a credits failure; recovered limits keep their diagnostic. Only two successful empty views imply no quota. Never include raw exceptions, URLs or response bodies, or refresh/write credentials. Desktop and Server share the core reader and popover; provider-only errors must keep the pill visible.
+
+ - **Usage failure readouts** — an empty Claude snapshot with `status: error` says "Could not
+ read usage." in both the single-account and multi-account popovers, including beside healthy
+ provider rows. Nonempty snapshots retain their last-known bars on error; no error-specific
+ authentication advice is inferred from the status.
+
- **Remote usage** (SSH hosts, `src/core/usage/remote-claude-usage.ts`) — the source behind the
SSH scope above. v1 excluded remote accounts, which left a user whose Claude only ever runs on a
server staring at an empty indicator while the host had perfectly good numbers.
diff --cc CONTRIBUTING.md
index f59796480,929065f3a..cfff60764
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@@ -623,10 -649,50 +649,52 @@@ terminal opens keep their existing iden
for every control verb. Legacy mobile/SSH callers must present this instance’s node token for
command-bearing opens; this does not add a human-confirm dialog or change mobile transport APIs.
+Grok billing diagnostics must keep HTTP codes and safe failure categories per billing view. Never send raw error messages, URLs or response bodies to the UI; credentials remain read-only. A failed view is not proof that there is no quota, even when the other view responds.
+
+ ## User-owned agent settings
+
+ Claude/Gemini settings must go through the guarded transactions in
+ `src/core/agents/hooks/{settings-file,remote-settings-file}.ts`. Confirmed absence or a successfully read empty/whitespace file may start from `{}`;
+ malformed, non-object and unreadable files must survive unchanged.
+ Keep unrelated settings and foreign hook handlers. Stage writes, serialize nodeterm writers,
+ and compare the original bytes again before publishing; never use `cat … || echo '{}'` or a
+ catch-all read fallback. Local and SSH symlinked profiles update and lock the resolved target without replacing
+ the link; recheck resolution before publishing. SSH uses plain readlink and cd -P (no GNU -f),
+ and refuses dangling/cyclic links and newline paths. A conflicting/stale lock skips installation
+ with a diagnostic naming the lock and safe manual recovery; do not steal it from another process. These locks
+ coordinate nodeterm, not external editors, so do not claim a filesystem-wide compare-and-swap.
+ **Creating an agent node is not proof it started.** Control opens retain their launch command
+ until delivery is acknowledged, and report `queued` while it is held. A successful terminal send
+ proves delivery only; never describe it as a healthy/running agent without agent evidence.
+ Desktop launches (automatic and Run now) use the echo-verified command writer, not `sendText`.
+ Keep unsubmitted UI intent durable through shell settle/unmount. New intent carries `attempted:false`;
+ Desktop and Server save `attempted:true` before input. Never-attempted warm `--after` launches may
+ proceed after shell verification; attempted/legacy-unknown intent requires Run now. Only confirmed
+ submission clears intent. Desktop open replies use `createControlOpenBatch` for queued accounting;
+ protect that contract and concurrent submission with behavior tests, never source-text pins.
+ Relay queued/restored launches and Run now are refused until a scoped durable claim API exists.
+ A new relay UI initialCommand may run once on a fresh PTY through the verified writer, without
+ workspace writes or pendingLaunch creation. Consume its transient attempt before shell settle;
+ never retry it on remount or serialize it as durable intent.
+ Never round-trip a relay workspace load into save: the load can contain only one shared project,
+ while save replaces the entire host index. A pre-input parked-project deferral keeps intent
+ never-attempted; it must not poison the writer or trigger a retry timer.
+ Held Desktop launches retain their attached transport even offscreen with tmux (large fan-outs cost
+ memory). Server deferred delivery is one-shot: a failed probe/send needs explicit recovery.
+
## Testing
+ **Screenshot paste has one route per gesture.** On macOS, Cmd+V saves/uploads a file and
+ pastes its path; Ctrl+V belongs to the foreground program. A node's configured agent is not
+ proof of foreground clipboard-image support. Keep shell/SSH/Server file routing and capture
+ suppression of accompanying text; do not synthesize Ctrl+V or try both routes without a
+ capability and receipt protocol. The shortcuts panel documents this distinction (#712).
+
+ The titlebar's scroll viewport owns its `no-drag` region. Do not add `app-region: no-drag`
+ to tabs or their descendants: Electron can subtract their off-screen rectangles from the
+ wordmark's drag area. `scripts/tabbar-drag.test.ts` checks native hit testing with isolated
+ Electron/Xvfb on Linux; macOS traffic lights and actual window movement still need device checks.
+
`npm test` must pass, and `npm run typecheck` is the fastest gate.
Beyond that, one habit is worth more than any other here:
diff --cc src/renderer/components/UsageIndicator.grok.test.tsx
index 0edb8b496,000000000..17841e62d
mode 100644,000000..100644
--- a/src/renderer/components/UsageIndicator.grok.test.tsx
+++ b/src/renderer/components/UsageIndicator.grok.test.tsx
@@@ -1,102 -1,0 +1,110 @@@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DEFAULT_SETTINGS, type ClaudeUsage, type ProviderUsage, type UsageLimit } from '@shared/types'
+import { useSettings } from '../state/settings'
+import { UsageIndicator } from './UsageIndicator'
+
+const limit: UsageLimit = {
+ kind: 'session', group: 'session', usedPercent: 37, severity: null,
+ resetsAt: null, windowMinutes: 300, scopeLabel: null, isActive: false
+}
+const snapshot = (status: ClaudeUsage['status'], limits: UsageLimit[] = []): ClaudeUsage => ({
+ status, limits, session: null, weekly: null, email: null, updatedAt: 0
+})
+
+let host: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS, usagePercentMode: 'remaining' } })
+})
+
+afterEach(() => {
+ act(() => root.unmount())
+ host.remove()
+ useSettings.setState({ settings: DEFAULT_SETTINGS })
+ vi.unstubAllGlobals()
+})
+
+async function open(system: ClaudeUsage, providers: ProviderUsage[] = []) {
+ vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+ // No credentials, network, or running sessions: exercise the real component using bridge snapshots.
+ vi.stubGlobal('nodeTerminal', { usage: {
+ fetch: async () => system,
+ providers: async () => providers,
+ onUpdate: () => () => {}
+ } })
+ await act(async () => root.render(<UsageIndicator />))
+ await act(async () => host.querySelector('.usage-indicator')!.dispatchEvent(
+ new MouseEvent('mouseover', { bubbles: true })
+ ))
+}
+
+describe('Grok billing diagnostics in the usage popover', () => {
+ it.each([
+ [{ reason: 'http', httpStatus: 401 }, 'Grok authentication failed (HTTP 401)'],
+ [{ reason: 'http', httpStatus: 403 }, 'Grok authentication failed (HTTP 403)'],
+ [{ reason: 'http', httpStatus: 429 }, 'Usage request rate limited (HTTP 429)'],
+ [{ reason: 'http', httpStatus: 503 }, 'Grok returned HTTP 503'],
+ [{ reason: 'http', httpStatus: 418 }, 'Usage request failed (HTTP 418)'],
+ [{ reason: 'network' }, 'Could not reach Grok'],
+ [{ reason: 'timeout' }, 'Usage request timed out'],
+ [{ reason: 'invalid-response' }, 'Usage response could not be read']
+ ] as const)('shows a safe, specific reason for %j', async (diagnostic, message) => {
+ await open(snapshot('unavailable'), [{ provider: 'grok', account: null,
+ status: 'error', limits: [], updatedAt: 0, diagnostics: [{ view: 'credits', ...diagnostic }] }])
+ expect(host.querySelector('.usage-indicator')?.textContent).toContain('⚠')
+ const text = host.querySelector('.usage-account')?.textContent
+ expect(text).toContain('Credits view: ' + message)
+ expect(text).not.toContain('expired')
+ expect(text).not.toContain('No usage data.')
+ })
++ it.each(['unavailable', 'error'] as const)('keeps Claude %s distinct from a Grok failure', async (status) => {
++ await open(snapshot(status), [{ provider: 'grok', account: null,
++ status: 'error', limits: [], updatedAt: 0, diagnostics: [{ view: 'credits', reason: 'network' }] }])
++ const body = host.querySelector('.usage-popover__body')!
++ expect(body.textContent).toContain('Credits view: Could not reach Grok')
++ expect(body.textContent).not.toContain('No usage data.')
++ expect(body.textContent?.includes('Could not read usage.')).toBe(status === 'error')
++ })
+ it('shows recovered limits alongside the failed view', async () => {
+ await open(snapshot('unavailable'), [{ provider: 'grok', account: null,
+ status: 'ok', limits: [limit], updatedAt: 0, diagnostics: [
+ { view: 'credits', reason: 'network' }
+ ] }])
+ expect(host.querySelectorAll('.usage-row')).toHaveLength(1)
+ expect(host.querySelector('.usage-account')?.textContent).toContain('Credits view: Could not reach Grok')
+ })
+ it('keeps distinct reasons from both views visible', async () => {
+ await open(snapshot('unavailable'), [{ provider: 'grok', account: null,
+ status: 'error', limits: [], updatedAt: 0, diagnostics: [
+ { view: 'credits', reason: 'http', httpStatus: 401 },
+ { view: 'default', reason: 'timeout' }
+ ] }])
+ const text = host.querySelector('.usage-account')?.textContent
+ expect(text).toContain('Credits view: Grok authentication failed (HTTP 401)')
+ expect(text).toContain('Default view: Usage request timed out')
+ })
+ it('respects the hidden-provider setting even on failure', async () => {
+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS, hiddenUsageProviders: ['grok'] } })
+ vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+ vi.stubGlobal('nodeTerminal', { usage: {
+ fetch: async () => snapshot('unavailable'),
+ providers: async () => [{ provider: 'grok', status: 'error', limits: [],
+ diagnostics: [{ view: 'credits', reason: 'network' }] }],
+ onUpdate: () => () => {}
+ } })
+ await act(async () => root.render(<UsageIndicator />))
+ expect(host.querySelector('.usage-indicator')).toBeNull()
+ })
+ it('supports older snapshots without diagnostics', async () => {
+ await open(snapshot('unavailable'), [{ provider: 'grok', account: null,
+ status: 'error', limits: [], updatedAt: 0 }])
+ expect(host.querySelector('.usage-account')?.textContent).toContain('Could not read usage.')
+ })
+})
diff --cc src/renderer/components/UsageIndicator.tsx
index 5abda29dd,bbf9643e8..c8333888a
--- a/src/renderer/components/UsageIndicator.tsx
+++ b/src/renderer/components/UsageIndicator.tsx
@@@ -404,8 -499,7 +505,9 @@@ export function UsageIndicator(
const status = claudeUsage?.status ?? visibleRemote[0]?.usage.status ?? 'unavailable'
const hasData = limits.length > 0 || enabled.length > 0
const fetching = refreshing
- const isError = status === 'error'
+ const providerError = visibleProviders.some((p) => p.status === 'error')
- const isError = status === 'error' || providerError
++ const claudeError = status === 'error'
++ const isError = claudeError || providerError
// The pill leads with whatever is closest to biting, so a scoped model cap that is nearly
// exhausted can't hide behind a comfortable 5h window. Considers every enabled provider, not
// just Claude, so an exhausted Codex window drives the bar too.
@@@ -532,13 -628,19 +636,19 @@@
<>
{/* Claude's rows are bare when it is the only provider; once others share the
panel they need a heading of their own to stay attributable. */}
- {enabled.length > 0 && limits.length > 0 && (
- {enabled.length > 0 && (limits.length > 0 || isError) && (
++ {enabled.length > 0 && (limits.length > 0 || claudeError) && (
<div className="usage-account__label">Claude</div>
)}
{limits.map((l) => (
<LimitRow key={limitKey(l)} limit={l} mode={percentMode} />
))}
- {!hasData && !providerError && <div className="usage-popover__empty">No usage data.</div>}
+ {/* Another provider's data must not hide a failed Claude read. Keep any
+ last-known Claude bars instead of replacing them with the empty state. */}
- {(!hasData || (isError && limits.length === 0)) && (
++ {((!hasData && !providerError) || (claudeError && limits.length === 0)) && (
+ <div className="usage-popover__empty">
- {isError ? 'Could not read usage.' : 'No usage data.'}
++ {claudeError ? 'Could not read usage.' : 'No usage data.'}
+ </div>
+ )}
{claudeUsage?.email && (
<div className="usage-account">
<div className="usage-account__label">Claude Account</div>