[codex] Structure workspace file system errors

[juliusmarminge]

Summary

• replace synthetic read failures with structured path-escape, non-file, and binary-file errors
• preserve real causes and operation paths at each filesystem I/O boundary
• bracket file handles so close runs after success, semantic failure, I/O failure, or interruption

Validation

• vp test apps/server/src/workspace/WorkspaceFileSystem.test.ts
• vp check
• vp run typecheck

---

Note

Medium Risk
Changes the wire shape and message text for multiple workspace RPC error paths; clients that relied on old embedded platform strings or query text in messages need to use failure and optional fields instead.

Overview
Workspace file I/O now returns a union of tagged errors (WorkspaceFileSystemOperationError, path escape, not-a-file, binary) with workspaceRoot, resolvedPath, and per-step operation labels. readFile uses acquireUseRelease so file handles close on success, semantic failure, I/O error, or interruption.

WebSocket RPC maps workspace/search/browse/file errors through helpers that populate failure codes and request context on ProjectSearchEntriesError, ProjectListEntriesError, ProjectReadFileError, ProjectWriteFileError, and FilesystemBrowseError. User-facing message strings are derived from cwd/paths only—search queries and file contents are omitted from payloads and messages; raw cause remains for debugging.

Contracts add optional structured fields with custom constructors for new call sites and decode compatibility for legacy message-only errors during rolling upgrades. Tests assert structured RPC shapes and that sensitive tokens do not appear in error text.

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

Note

Structure workspace file system RPC errors with typed, sanitized error classes

• Replaces generic string-based error messages across workspace file system RPCs with discriminated error classes (WorkspaceFileSystemOperationError, WorkspaceFilePathEscapeError, WorkspacePathNotFileError, WorkspaceBinaryFileError) defined in WorkspaceFileSystem.ts.
• Extends RPC error contracts in project.ts and filesystem.ts with optional structured fields (cwd, relativePath, failure classification, operation stage) and custom constructors that derive sanitized messages.
• Updates ws.ts handlers for projectsSearchEntries, projectsListEntries, projectsReadFile, projectsWriteFile, and filesystemBrowse to populate these structured error types, removing the legacyPlatformFailureDescription helper.
• Ensures sensitive data is not leaked: raw query strings are replaced with query length, and binary file contents are never included in errors.
• Legacy message-only error payloads remain decodable for rolling upgrade compatibility.

^{Macroscope summarized d2e1471.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0e03b654-f278-44c6-b371-0b62970bab37

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-workspace-filesystem-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

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

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: RPC reads missing error cause
  • Added workspaceFileReadCompatibilityDetail() to map each WorkspaceFileSystemError tag to its legacy user-visible description, replacing the broken cause.cause access that produced 'undefined' for the three new error types lacking a cause property.

Or push these changes by commenting:

@cursor push 8dd7e5a105

Preview (8dd7e5a105)

diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -170,6 +170,23 @@
   }
 }
 
+function workspaceFileReadCompatibilityDetail(
+  error: WorkspaceFileSystem.WorkspaceFileSystemError,
+): string {
+  switch (error._tag) {
+    case "WorkspaceFileSystemOperationError":
+      return legacyPlatformFailureDescription(error.cause);
+    case "WorkspaceFilePathEscapeError":
+      return "Workspace file path resolves outside the project root.";
+    case "WorkspacePathNotFileError":
+      return "Workspace path is not a file.";
+    case "WorkspaceBinaryFileError":
+      return "Binary files cannot be previewed as text.";
+    default:
+      return unexpectedCompatibilityError(error);
+  }
+}
+
 function projectSetupScriptCompatibilityDetail(
   error: ProjectSetupScriptRunner.ProjectSetupScriptRunnerError,
 ): string {
@@ -1288,7 +1305,7 @@
               Effect.mapError((cause) => {
                 const message = isWorkspacePathOutsideRootError(cause)
                   ? "Workspace file path must stay within the project root."
-                  : `Failed to read workspace file: ${legacyPlatformFailureDescription(cause.cause)}`;
+                  : `Failed to read workspace file: ${workspaceFileReadCompatibilityDetail(cause)}`;
                 return new ProjectReadFileError({ message, cause });
               }),
             ),

_{You can send follow-ups to the cloud agent here.}

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

[macroscopeapp]

Effect service review — 1 finding. The refactor splits WorkspaceFileSystemError into four classes, three of which intentionally carry no cause. The sole production consumer (apps/server/src/ws.ts:1291, the projects.readFile RPC handler) still builds its user-facing message from cause.cause, which is now undefined for those errors — surfacing "Failed to read workspace file: undefined" to the UI for not-a-file, binary-file, and symlink-escape cases. See inline comment.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Approved

This PR restructures workspace file system error handling to use structured fields instead of generic messages, improving debuggability and security (avoids leaking sensitive data like query contents). No runtime behavior changes - only error reporting format is affected, with backwards compatibility maintained.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate d2e1471