fix(web): show attempted paths in file preview errors

[maria-rcks]

file previews now show a safe read failure, the attempted path, and workspace-folder guidance. the client retains structured error context and older servers retain their public fallback message. raw platform causes stay private.

closes #14491.

verified through the real web client: the missing devices.md link shows the attempted normalized path and Files guidance; docs/README.md's ./user/install.md still opens document-relatively. blacksmith passed 40 existing file-preview tests, web typecheck and scoped lint. final head be13522 preserves the captured candidate web source and includes main's ci repair.

before is the historical pre-change 3b0093d capture. after and the 7.53 second recording use the merged candidate with corrected "Workspace folder:" copy. workspace names, surrounding state and crops differ. native mobile, desktop shell, permission failures, inaccessible workspaces and older-server runtime compatibility remain unverified.

updated with gpt-6.1-sol via codex in t3 code.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 30dbf7ab-dac5-4cd9-9be1-d1478f26057a

📥 Commits

Reviewing files that changed from the base of the PR and between 17c0878 and be13522.

📒 Files selected for processing (5)

• apps/web/src/components/files/FilePreviewPanel.test.ts
• apps/web/src/components/files/FilePreviewPanel.tsx
• apps/web/src/components/files/filePreviewMode.ts
• apps/web/src/components/files/projectFilesQueryState.test.tsx
• apps/web/src/components/files/projectFilesQueryState.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

The file query state now preserves structured read errors. The file preview uses those details to show failure-specific messages, the attempted path, and working-directory guidance when available.

Changes

File preview read errors

Layer / File(s)	Summary
Preserve structured read errors apps/web/src/components/files/projectFilesQueryState.ts, apps/web/src/components/files/projectFilesQueryState.test.tsx	The query state exposes a typed readError and derives isNotFile from its failure value. Tests cover successful reads, directory paths, and other read failures.
Format and display read errors apps/web/src/components/files/filePreviewMode.ts, apps/web/src/components/files/FilePreviewPanel.tsx, apps/web/src/components/files/FilePreviewPanel.test.ts	Known failure types map to specific messages, with a separate message for workspace-root realpath failures. The preview can show the attempted path and working-directory guidance. Tests cover the message mappings and legacy error text.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to be135

File-preview errors now show the attempted path and a clearer reason. No merge-blocking risk was found. Real provider and UI behavior were not verified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to be135

The preview displays diagnostics already available to the connected client without adding file access or executable rendering. No material security regression was identified in the inspected changes, but live provider and client behavior remains unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — The existing read boundary supports workspace-relative files and absolute host paths accessible to the server process. Absolute host reads already bypass workspace containment. This PR changes diagnostic visibility in the selected web preview, not that authority.

Security Findings and Attack Paths

• inferred — No newly introduced execution or unauthorized disclosure path was established in the inspected change. Resolved and operation paths become visible on screen, but the existing server response already carried them to the same connected client. This conclusion does not establish safety for unverified production contexts.

Trust Boundaries and Controls

• observed — The WebSocket route authenticates the connection and provides authorization using session scopes. File reads retain the existing orchestration-read scope requirement. Workspace-relative resolution checks real paths and rejects escapes; absolute host reads remain a separate, pre-existing capability.

🚥 Pre-merge checks | ✅ 3 | ❓ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	For #14491, the web query retains structured ProjectReadFileError data, and the preview shows the attempted path, maps known failure codes to safe explanations, and gives workspace-relative path gui…	Evidence is needed to determine whether the native mobile preview consumes the shared read-file contract. If it does, its handling must be assessed against #14491; if it does not, no mobile change is required.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The query-state, preview-rendering, error-message, and test changes all support #14491. The available change summary shows no unrelated changes.
Title check	✅ Passed	The title clearly identifies the main change: showing attempted paths in file-preview errors.
Description check	✅ Passed	The description explains the problem and change, links the issue, reports focused verification and limitations, and includes before/after UI evidence. It does not state explicit maintainer approval or…

Full details: Linked Issues check

Explanation

For #14491, the web query retains structured ProjectReadFileError data, and the preview shows the attempted path, maps known failure codes to safe explanations, and gives workspace-relative path guidance. Tests cover failure messages and legacy fallback behavior. Desktop uses the web preview, so these changes apply there. The PR says the native mobile preview is unchanged, but the available evidence does not establish whether it consumes the same read-file contract. The issue requires consistent handling for any such mobile consumer.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[macroscopeapp]

Approvability

Verdict: Approved at be13522

Macroscope's review found this PR approvable — The PR is a focused file-preview error-reporting fix: it preserves existing read failures, presents sanitized messages, and shows the attempted path and workspace context only when a read fails. Successful previews and normal file-query behavior remain unchanged, with focused tests covering the new handling.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate be13522