feat(auth): separate filesystem read and write permissions

[juliusmarminge]

Direct workspace reads and edits shared task permissions, while local diffs required review:write. Add filesystem:read for browsing, searching, previews, and local diffs, and filesystem:write for edits and saved plans. Both remain in the Standard preset; new grants retire review:write while old credentials remain decodable.

Host workspace/media URLs require file-read access when minted. Web, desktop, and mobile menus wait for a known grant from the source environment, then recheck after native selection and URL minting. Copying paths or URLs, uploaded attachments, and local or external media keep their existing behavior. Explicit asset refresh retains server authorization during grant loading.

Revocation hides cached search results and stops pending autosaves. Unsaved edits survive closing and reopening previews, React effect replay, and grant changes; an older editor's completed write cannot clear a newer draft's pending state. Typed project paths still work with task permission alone, while directory browsing requires file access. Mobile Review explains denied local-diff access instead of reporting an empty worktree.

Existing credentials keep their recorded scopes and need a fresh grant to add filesystem access. These scopes govern direct client actions; they do not sandbox providers or terminal commands.

Earlier focused media, search, save, and Review suites passed with coverage for initial grant loading, revocation during async work, draft recovery, and unaffected nonhost media. Web, mobile, and shared scoped typechecks passed during stack verification. The media below records those earlier client checks.

An existing race in the highlighting test fixture left frame callbacks running after its global stubs were removed, causing a cancelAnimationFrame exception in CI. The fixture now tracks and cancels pending frame handles after worker termination and before restoring globals. Controlled callback ordering reproduced the failure with the old fixture and passed with the fix; all seven tests using real workers passed at the integrated a685c585 revision. Web and mobile typechecks passed there. Lint for the integrated follow-up files reported zero errors and 24 existing warnings; formatting passed.

Earlier-revision pairing UI:

Before	After

Earlier iPhone E2E used the same dirty worktree with file access granted and denied. These captures predate final integration:

Before: missing permission reported as an empty worktree	After: access denial explained

Model: GPT 6 Astra. Harness: Codex.

---

Note

High Risk
Changes authentication scope requirements and authorization for file reads, writes, diffs, and asset URLs across server and all clients; misconfiguration or stale grants can block core workspace features.

Overview
Introduces filesystem:read and filesystem:write as first-class OAuth grant scopes and wires them through server RPC authorization, replacing orchestration/review scopes for direct host file operations and local diff preview. review:write is retired for new token requests; host workspace/media asset minting now requires filesystem:read, while attachments keep existing rules.

Web, mobile, and desktop clients gate browsing, file trees, previews, composer path search, asset URLs, media menus, and git/worktree review sections on resolveFilesystemReadAccess, showing loading/denial states instead of firing unauthorized queries or leaking cached host diffs. Losing filesystem:write stops autosave and keeps unsaved drafts across closed previews until write access returns; plan save and file editor UI reflect read-only mode.

Pairing/token flows and CLI scope flags now use the unified AuthGrantScope set; server tests cover scoped WS file read/write and asset URL behavior.

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

Note

Separate filesystem read and write scopes across server, web, and mobile

• Adds shared resolveFilesystemReadAccess resolver in filesystem.ts that distinguishes pending, denied, and granted states from catalog, connection, and session data
• Reassigns RPC methods in RpcAuthorization.ts from orchestration:read/review-write to filesystem:read/filesystem:write; assetsCreateUrl in ws.ts now requires filesystem:read for workspace-file and media-file resources
• Gates host-file queries, asset URLs, path/content search, file previews, diff panels, command-palette browsing, and media actions on resolved read access across web and mobile; denied or pending access shows loading or error states instead of querying the host
• Adds unsaved-draft retention in fileSaveCoordinator.ts and useFileSaveCoordinator.ts: writes are skipped when filesystem:write is revoked, drafts stay pending, and auto-recover once write access returns
• Updates CLI scope flag in authScopes.ts and pairing settings in ConnectionsSettings.tsx to offer filesystem:read/filesystem:write instead of review-write
• Risk: RPC_REQUIRED_SCOPES reassignment removes review-write; existing sessions or pairing tokens that relied on review-write for file/diff access must now be granted filesystem:read or filesystem:write

^{Macroscope summarized 7d9a81c.}

Summary by CodeRabbit

• New Features
  • Added separate file-read and file-write permissions for workspace access.
  • File browsing, searching, previews, diffs, media actions, and project-file loading now respect file-read access.
  • Workspace editing and saving require file-write access; unavailable files are shown as read-only or blocked.
  • Added clearer loading and access-error states across mobile and web experiences.
  • Preserved unsaved drafts when access changes or saving is temporarily unavailable.
  • Updated connection permission presets to include appropriate file-access permissions.
• Documentation
  • Documented the new file-access permissions and their effects.
• Bug Fixes
  • Prevented misleading empty review-diff messages when errors occur.

[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.5 KiB	—	15.1 KiB	✅
Codex	Thread snapshot wire	—	7.1 KiB	—	7.3 KiB	✅
Codex	Live turn WebSocket wire	—	6.5 KiB	—	7.8 KiB	✅
Codex	Live turn WebSocket decoded	—	56.3 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.1 KiB	—	7.3 KiB	✅
Claude	Live turn WebSocket wire	—	6.5 KiB	—	7.8 KiB	✅
Claude	Live turn WebSocket decoded	—	57.0 KiB	—	66.4 KiB	✅
Claude	Live turn messages	—	9	—	21	✅

Baseline: unavailable · PR result: 4200bbe · 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.9 KiB
• Claude decoded thread snapshot: 114.7 KiB

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

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a broad authentication and filesystem-permission change spanning server authorization and web/mobile file operations, including new default grants and revocation behavior. The security boundary and changed product defaults require human review.

Not approved because:

• Per-PR 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]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.