feat(auth): separate environment administration permissions

[juliusmarminge]

Settings changes, provider setup, and host maintenance shared task-operation access, so they could not be granted independently. Add:

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

Mixed settings patches require every affected domain, including settings access for pricing overrides. Provider fallback uses effective enabled instances, honors explicit overrides, and preserves the stored model preference when an instance is disabled. Access and relay administration retain their own scopes.

Controls that change environment state wait for an initial grant and use the target environment's permissions on web, desktop, and mobile. Open dialogs react to revocation; retained callbacks recheck after confirmations and async preparation. Shared project edits check every member before the first write, while scripts and single-checkout removal use that checkout's grant. Settings sync targets connected, writable environments.

Thread actions, composer sends, approvals, queued work, and uploads check orchestration:operate at dispatch. RPCs that launch an editor on the environment's host require that scope independently of settings access. The desktop's client-local Open action and SSH editor links remain available. Local drafts, navigation, copying, and device preferences remain usable; Live Activities configures only environments with relay:write.

Web editor and thread/project dispatch guards return EnvironmentAuthorizationError with the required orchestration:operate scope. Shortcut-write denials carry settings:write. Mobile attachment commands use the same typed task-access denial, as do new-task checks before preparing attachments and again before dispatch. These error types preserve the existing denial messages and expose the required scope to callers.

Project scripts save and resolve shortcuts on their own environment; global app shortcut resolution stays with the primary environment. Action re-creation and t3.json imports preserve retained shortcuts unless an authorized explicit edit changes them. Standard and Administrative presets include the new scopes; existing credentials keep their recorded grants.

The earlier fixture/settings run passed 132 tests. The typed-denial follow-up passed all seven editor/orchestration tests, including assertions for the error class and required scope. The integrated web typecheck passed at 6a9376f5; server, desktop, and mobile scoped typechecks passed in earlier stack verification.

Before the mobile error-type change, four of six focused cases failed their typed-denial assertions and two passed; all six passed afterward. Those six passed again within the 28 mobile cases at the integrated a685c585 revision, where web and mobile typechecks passed. The four mobile files changed for this follow-up passed lint without warnings and passed formatting.

Real-client checks at 82749030 confirmed that restricted web settings leave a device preference editable while shared settings stay denied and explain the missing permission on keyboard focus. The iOS composer kept local text editable and displayed the task-access denial. These checks preceded the web and mobile error-type follow-ups.

Earlier-revision pairing UI:

Before	After

Earlier browser E2E used a shortcut configured only on a second environment: it appeared without running before the fix, then ran that environment's script exactly once afterward. These captures predate final integration:

Before: displayed shortcut does not run	After: script runs in its own environment

The browser pass at 6a9376f5 used the same restricted grant and draft as the baseline at 8ff45db4. Enter preserved the draft and composer focus without starting a turn; task scripts, host-editor RPCs, Git writes, and new-terminal creation were unavailable. The baseline provider-status timeout toast is unrelated to these scope fixes.

Before: restricted connection still offers actions	After: denied actions preserve the local draft

Settings verification at 82749030: a device preference was changed and restored while the shared setting stayed unavailable and explained its missing permission.

The iOS check at the same revision retained a locally typed draft and showed why sending was unavailable. This capture precedes the mobile error-type and Git-form completion follow-ups.

Onboarding imports now require orchestration:operate on the selected environment. The controls follow grant changes, and retained callbacks recheck access before importing projects or thread history. Scanning, local selection, and Skip remain available under the tested read-only grant.

Real browser verification compared 78c9ad7f with b053bc01, using the same test backend at 78c9ad7f and the same four scopes: orchestration:read, filesystem:read, terminal:read, and relay:read. Before, clicking Import for the single scanned fixture ended with “Could not import thread history.” After, Import is disabled with a permission explanation. Manual selection toggled off and on while Import stayed disabled, and clicking Skip left onboarding for a local draft.

Before: Import appears available	After: Import explains the missing permission

The seven import component cases went from six failures and one pass before the fix to seven passes. At the integrated b053bc01 revision, 165 web tests and web/mobile typechecks passed. Revocation during asynchronous work was covered by component tests; the browser pass covered the read-only controls, selection, and Skip flow.

Model: GPT 6 Astra. Harness: Codex.

Note

Split environment administration into settings:write, providers:manage, and environment:maintain scopes

• Adds three new environment scopes to the contract and includes them in AuthStandardClientScopes; the server advertises environment:maintain via an optional serverUpdateScope field on ServerAuthDescriptor
• Replaces broad orchestration:operate requirements in RPC_REQUIRED_SCOPES with operation-specific scopes for provider management, environment maintenance, settings writes, keybinding writes, provider reads, telemetry retries, process signaling, and host power reporting
• The serverUpdateSettings WebSocket handler now derives required scopes from the patch via requiredScopesForServerSettingsPatch, so mixed settings+provider patches require both settings:write and providers:manage
• Web and mobile UI components (composer, thread lists, settings panels, diagnostics, cloud-link controller, attachment queues, outbox drain) gate controls and re-check scopes at action time using new useEnvironmentScope/readEnvironmentScope helpers
• Risk: RpcAuthorization.ts narrows every previously broad-orchestration:operate RPC; any out-of-tree client or existing session that relied on the single scope for settings/provider/maintenance operations will now receive authorization errors unless its grant includes the new specific scopes. Older servers that omit serverUpdateScope still accept orchestration:operate for updates, but upgraded servers must include environment:maintain in the grant.

^{Macroscope summarized 5d802e8.}

---

Note

Medium Risk
Broad mobile permission enforcement on thread/outbox/attachment paths; incorrect scope checks could block legitimate operators or leave stale callbacks active until re-checked.

Overview
Mobile now honors per-environment OAuth scopes instead of treating every connected environment as fully writable.

Session helpers (readEnvironmentScope, useEnvironmentScope, useEnvironmentsWithScope) drive UI and background workers from each target’s grant, including cached scopes during refresh.

Task control (orchestration:operate) gates thread list mutations, swipe actions, composer send/stop, approvals, user-input replies, new-task start, attachment mint/upload/delete, and outbox drain—often with re-checks after async steps or retained callbacks so revoked access cannot slip through.

Settings and relay use separate scopes: auto-settle sync picks the first writable reference (settings:write), disables controls when read-only, and Live Activity linking only re-links environments with relay:write via canConfigureEnvironment. Provider reset credits require providers:manage.

Server-side tests/assertions align with AuthStandardClientScopes / AuthAdministrativeScopes, auth policy exposes serverUpdateScope, and host power reporting RPC maps to environment:maintain.

^{Reviewed by Cursor Bugbot for commit c93d49b. 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.6 KiB	—	15.1 KiB	✅
Claude	Thread snapshot wire	—	7.0 KiB	—	7.3 KiB	✅
Claude	Live turn WebSocket wire	—	6.6 KiB	—	7.8 KiB	✅
Claude	Live turn WebSocket decoded	—	57.9 KiB	—	66.4 KiB	✅
Claude	Live turn messages	—	10	—	21	✅

Baseline: unavailable · PR result: 5d802e8 · Source CI: success

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 PR introduces a broad environment-permission model with new authorization scopes, changed pairing defaults, and enforcement across server, web, and mobile workflows. Its security sensitivity and substantial runtime blast radius require human review.

Not approved because:

• Per-review cost limit exceeded (workspace setting). Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings, or comment @macroscope-app review this PR to bypass the limit and review now. 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.}