Summary

Describe the problem and fix in 2–5 bullets:

• Problem: When the Edit tool tries to open a file outside the workspace root, SafeOpenError throws with code "invalid-path" and message "path escapes root". Consumers cannot distinguish this from other invalid-path cases (hardlinks, symlinks, non-files) and often fall back to a misleading "File not found" message.
• Why it matters: Users see "File not found" when the real cause is "file is outside workspace", making debugging confusing.
• What changed: Added a new "outside-workspace" error code to SafeOpenErrorCode. All path-escapes-root checks in openFileWithinRoot / writeFileWithinRoot now use this code. Consumers (pi-tools.read.ts, browser/paths.ts, media/server.ts) handle it with specific, accurate messages.
• What did NOT change (scope boundary): Other "invalid-path" uses (hardlinks, symlinks, non-files) remain unchanged. readLocalFileSafely is unaffected (no root boundary check).

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related write tool rejects paths outside workspace root (e.g. Obsidian vault) #28427, [Bug]: tools.fs.workspaceOnly=false does not allow write/read/edit outside workspace (sandbox off) #28763, Edit/Write tools restricted to workspace root even with tools.fs.workspaceOnly=false #29612

User-visible / Behavior Changes

• Edit/Write tools now report "file is outside workspace root" or "File is outside {scopeLabel}" instead of "File not found" or "Invalid path" when targeting a file outside the workspace.
• Media server returns 400 "file is outside workspace root" instead of 400 "invalid path" for outside-workspace requests.
• Sandbox FS errors for outside-workspace paths report EACCES instead of rethrowing a raw SafeOpenError.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS Darwin 24.0.0
• Runtime/container: Node.js via pnpm
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Create a workspace directory and a file outside it
2. Call openFileWithinRoot with a relative path that escapes the root (e.g. ../outside/file.txt)
3. Observe the error code and message

Expected

• SafeOpenError with code "outside-workspace" and message "file is outside workspace root"

Actual

• Previously: SafeOpenError with code "invalid-path" and message "path escapes root"

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

pnpm vitest run src/infra/fs-safe.test.ts — all 11 tests pass, including updated traversal expectations ("outside-workspace").

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: pnpm build, pnpm tsgo, pnpm lint, pnpm vitest run src/infra/fs-safe.test.ts all pass
• Edge cases checked: read traversal, write traversal, symlink escape (via existing tests)
• What you did not verify: Windows CI (no Windows environment available locally), end-to-end Edit tool UX in the CLI

Compatibility / Migration

• Backward compatible? No — code that matches err.code === "invalid-path" for path-escapes-root will no longer trigger; they need to also check "outside-workspace".
• Config/env changes? No
• Migration needed? No — consumers in this repo are updated in this PR. External consumers of the plugin-sdk SafeOpenErrorCode type will get a compile error if they have exhaustive switches, which is the desired behavior.

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert this commit; change "outside-workspace" back to "invalid-path" with "path escapes root" message
• Files/config to restore: src/infra/fs-safe.ts, src/agents/pi-tools.read.ts, src/browser/paths.ts, src/media/server.ts, src/infra/fs-safe.test.ts
• Known bad symptoms reviewers should watch for: Any consumer that matches only "invalid-path" for workspace boundary errors would silently miss the new code and fall through to a generic handler

Risks and Mitigations

• Risk: External plugin-sdk consumers with exhaustive SafeOpenErrorCode switches get a compile error
  • Mitigation: This is intentional — the new type variant forces them to handle the case explicitly. The .d.ts is auto-generated from source.