fix: symlink path resolution causing duplicate instances (#15482)

[snowstorm0182]

Description

• Add canonical() function to resolve symlinks before caching instances
• Prevents TUI freeze when working with symlinked directories
• Add comprehensive tests for symlink path handling
• Fixes Two server instances created when project path contains symlink, causing TUI to freeze on prompt #15482

Issue for this PR

Closes #15482

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

When OpenCode was opened from a directory that was a symlink (e.g., ~/ssd → /media/user/ssd_storage), it would create two separate server instances - one for the symlink path and one for the resolved real path. This caused the TUI to freeze when sending prompts because the UI was connected to one instance while operations were executing on a different instance.

The fix adds a canonical() function that resolves symlinks using fs.realpath() before using the directory as a cache key in Instance.provide(). This ensures symlink paths and their real paths always map to the same instance.

How did you verify your code works?

1. Created comprehensive test suite in test/project/instance-symlink.test.ts:
   • Test verifying symlink and real path use same instance
   • Test simulating the original bug scenario with session switching
2. All new tests pass
3. All existing test suites continue to pass (project, session, etc.)
4. Manually verified the fix by creating a symlink and testing the original reproduction steps

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

Hey! Your PR title Fix symlink path resolution causing duplicate instances (#15482) doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on the search results, here are potentially related PRs:

Related PRs:

1. fix(opencode): resolve symlinks to directories in project picker #10366 - fix(opencode): resolve symlinks to directories in project picker

   • Directly related: also addresses symlink resolution in the codebase

2. fix: prevent symlink escape in Filesystem.contains #6403 - fix: prevent symlink escape in Filesystem.contains

   • Related: handles symlink path safety concerns

3. fix: use full URL for file:// plugin deduplication #8758 - fix: use full URL for file:// plugin deduplication

   • Related: addresses deduplication logic similar to the caching mechanism in this PR

These PRs share the theme of symlink handling and deduplication/caching logic. PR #10366 in particular appears to be the closest match as it also deals with resolving symlinks in the project handling code.

[github-actions]

Thanks for updating your PR! It now meets our contributing guidelines. 👍