feat(auth): separate environment administration permissions

[juliusmarminge]

Provider setup, settings changes and server maintenance all shared orchestration:operate. Parts of Connections also required access administration to configure an environment. A workspace operator could not be granted these capabilities independently.

Adds three scopes:

• settings:write for environment settings and keybindings.
• providers:manage for provider configuration, sign-in, installation, updates and reset credits.
• environment:maintain for server updates, process signals, resource collector recovery and host power controls.

Settings patches require permission for every domain they change, including settings:write for model pricing overrides. Web, desktop and mobile use the selected environment's grant for controls and check it again before writes. Shared settings sync includes only writable environments. Access and relay administration remain separate, and local preferences stay editable.

New Standard and Administrative grants include these scopes. Existing paired clients keep their grants and must pair again to receive the new permissions. Reconnecting does not expand access.

Validation: 93 focused web tests and the mobile TypeScript check passed. Targeted formatting and diff checks passed. RPC tests cover individual settings/provider grants, mixed patches and denied maintenance actions.

Pairing controls, captured from this layer’s base and head with the same viewport and default selection:

Before	After

Model: GPT-6. Harness: Codex.

Note

Add settings:write, providers:manage, and environment:maintain auth scopes

• Introduces three new environment scopes in auth.ts and wires them into the server RPC authorization map in RpcAuthorization.ts, replacing the overloaded orchestration:operate for settings writes, provider management, and environment maintenance operations.
• Adds synchronous scope-reader helpers in both web (session.ts) and mobile (session.ts) session state, returning false for failed, unauthenticated, or scope-less sessions.
• Gates UI controls across settings, provider management, diagnostics, cloud links, connections, keybindings, and usage screens on the appropriate new scope; unauthorized callbacks return without dispatching mutations.
• Updates shared settings sync in useSettings.ts to check per-patch required scopes via the new requiredScopesForServerSettingsPatch helper, skipping writes to environments that lack the needed grants.
• Updates server websocket layer in ws.ts to support requiring multiple scopes per RPC call, so mixed settings patches can demand both settings:write and providers:manage.
• Risk: existing pairings and sessions created before this change will not include the new scopes; the server falls back to orchestration:operate for serverUpdateScope when auth.serverUpdateScope is absent, but other operations (provider management, settings writes, environment maintenance) now require the new scopes explicitly — clients or pairings that previously relied on orchestration:operate for these actions will be denied until re-paired. See remote-access.md.

^{Macroscope summarized 4cde5f6.}

---

Note

High Risk
Changes authentication scope boundaries and RPC enforcement across server, web, desktop, and mobile; existing pairings keep old grants until re-paired.

Overview
Splits environment administration out of orchestration:operate into settings:write, providers:manage, and environment:maintain, and wires server RPC/HTTP authorization plus Standard vs Administrative grant bundles to those scopes. serverUpdateSettings now requires every scope implied by the patch (via requiredScopesForServerSettingsPatch), and the auth descriptor advertises serverUpdateScope for self-update checks.

Clients add useEnvironmentScope / readEnvironmentScope and use them to disable or block provider updates, reset credits, server updates, T3 Connect reconcile, pairing delegation, keybindings, and Connections access UI when the grant is missing—often re-checking immediately before writes. Mobile auto-settle shared settings waits on session resolution, picks the first writable reference, still shows read-only values, and fans edits only to writable environments.

Project scripts treat keybinding as optional on save so script-only edits do not overwrite shortcuts changed elsewhere; explicit shortcut changes still require settings:write. Pairing link creation is limited to scopes the current session holds, and “revoke others” stays enabled when the client list is unknown.

^{Reviewed by Cursor Bugbot for commit 4cde5f6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	13.6 KiB	—	15.1 KiB	✅
Codex	Thread snapshot wire	—	7.0 KiB	—	7.3 KiB	✅
Codex	Live turn WebSocket wire	—	6.6 KiB	—	7.8 KiB	✅
Codex	Live turn WebSocket decoded	—	57.1 KiB	—	66.4 KiB	✅
Codex	Live turn messages	—	10	—	21	✅
Claude	Total thread wire	—	13.5 KiB	—	15.1 KiB	✅
Claude	Thread snapshot wire	—	7.0 KiB	—	7.3 KiB	✅
Claude	Live turn WebSocket wire	—	6.5 KiB	—	7.8 KiB	✅
Claude	Live turn WebSocket decoded	—	57.8 KiB	—	66.4 KiB	✅
Claude	Live turn messages	—	9	—	21	✅

Baseline: unavailable · PR result: 4cde5f6 · Source CI: failure

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[cursor]

Stale Bugbot comment from a previous run.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a broad authentication and authorization capability change that alters RPC enforcement, pairing defaults, and production behavior across server, web, and mobile clients. Existing unresolved Medium findings also concern keybinding cleanup and environment-specific shortcut dispatch, so the change warrants human review.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit 7355eae. Configure here.}

[macroscopeapp]

🟡 Medium chat/ChatHeader.tsx:424

The scripts menu displays shortcuts from activeThreadEnvironmentId, but the active chat keydown handler resolves script commands from the primary environment's keybindings, so shortcuts shown for a secondary environment do not run the displayed script and a primary-environment shortcut may run instead. Update the handler to resolve bindings for activeThreadEnvironmentId (or otherwise use the same environment-specific bindings as the menu).

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/chat/ChatHeader.tsx around line 424:

The scripts menu displays shortcuts from `activeThreadEnvironmentId`, but the active chat keydown handler resolves script commands from the primary environment's `keybindings`, so shortcuts shown for a secondary environment do not run the displayed script and a primary-environment shortcut may run instead. Update the handler to resolve bindings for `activeThreadEnvironmentId` (or otherwise use the same environment-specific bindings as the menu).