[FEATURE]: Define native and identity path contracts across client/server boundaries

[romanilyin]

Feature hasn't been suggested before

• I have verified this feature request is not a duplicate of an existing proposal.

Describe the enhancement you want to request

OpenCode passes path strings between Desktop, the SDK, the server, SQLite, and filesystem caches, but those values have different jobs:

• a path usable by the current server process;
• a stable comparison/storage identity;
• a user-facing display path.

Mixing those concepts causes recurring failures:

• Desktop v1.16.0 converts WSL /mnt/c/... workspace to Windows C:\... path and breaks file/session list #30895 and Desktop App sends UNC paths to WSL-hosted server, breaking all bash tool calls [WORKAROUND ✅ ] #19473: Windows/UNC paths reach a WSL server and are resolved under its cwd;
• Windows: Sessions not showing in opencode desktop UI due to inconsistent path separator (/ vs \) #31597 and fix(session): Windows session directory filters treat slash-equivalent paths as different #28038: slash-equivalent Windows paths can split session matching. fix(session): normalize session directory filters across path variants #28040 already targets that narrow case and should not be duplicated;
• Desktop fails to show sessions when project is opened through a symlink path #30260: symlink display paths and resolved physical paths need a separate identity rule.

I propose a staged approach:

1. Validate request directory hints at the HTTP boundary before instance lookup.
2. Keep native filesystem paths separate from lexical comparison keys and realpath/cache identity.
3. Add versioned keys only where exact string matching or persistence needs them.
4. Handle database/App migration and explicit Windows/WSL bridging in later PRs.

I maintain the MIT package @romanilyin/canonicalpath and can keep it behind a small OpenCode wrapper. I already have a narrow first-stage branch with no database or Desktop migration.

Would the maintainers accept this staged contract, and would they prefer the MIT package, an in-tree implementation, or a smaller server-local wrapper first?

[romanilyin]

I have prepared a small first-stage branch for the server-side boundary fix:

https://github.com/romanilyin/opencode/tree/directory-boundary

This first stage uses @romanilyin/canonicalpath behind a server-local OpenCode wrapper. It only validates request directory hints before instance lookup and keeps the existing relative-path, empty-query, and raw-header fallback behavior.

It does not include SQLite/App/session identity migration, symlink/realpath identity changes, or automatic Windows/WSL path translation.

If maintainers prefer, I can adapt this first PR to use an in-tree implementation instead, or move the wrapper into core later if a shared path contract is the desired direction.

Unless there is an objection, I plan to open this as a narrow PR1 for review.