Fix file links failing to open across git worktrees

[yaacovcorcos]

Problem

Clicking a file link in chat (e.g. a bare reference like kanbanDispatch.ts) could fail to open with a misleading "no such file" error even though the file plainly exists in the workspace. Two independent root causes combined to produce this:

1. Git worktree duplicates. The filesystem-walk index descended into linked git worktrees, so one logical file was indexed several times — the real checkout plus a copy under each .codex-worktrees/* worktree. The bare/partial-reference resolver saw multiple matches, treated the reference as ambiguous, and gave up; the read then surfaced the raw realpath ENOENT for the literal (non-existent) path the user never typed. The duplicates also inflated the index toward its 25k-entry cap, silently truncating it.
2. Dishonest ambiguity. On a genuine ambiguity the resolver returned null, which the reader reported as ENOENT — a "file not found" message for a file that exists.

Fix (server-only)

• Prune linked git worktree subtrees from the index walk. A linked worktree records its .git as a regular file pointer (vs. a primary repo's .git directory) — the reliable discriminator — so the walk stops at that boundary. .git entries are skipped whether file or directory. The worktree/skip predicates are extracted into shared helpers used by both the index build and the direct disk scan.
• Structured resolution. resolveWorkspaceFileBySuffix now returns resolved | ambiguous | unresolved instead of string | null. It resolves only on a single distinct match and reports the competing paths on a true ambiguity — it never silently guesses between two different files that happen to share a basename.
• Truncation fallback. When the cached index is truncated (and therefore an unreliable source of truth), the resolver re-scans the tree directly with a bounded BFS for a trustworthy candidate set.
• Honest error. A genuinely ambiguous reference now returns an actionable message listing the competing files and asking for a fuller path, instead of a false ENOENT. This reuses the existing WorkspaceFileSystemError tag, so no contract or client change is required.

Why not "rank and pick the best match"

Deliberately avoided: silently choosing one of several distinct real files with the same basename would open the wrong file and hide the ambiguity. Reporting it is correct and predictable; the worktree pruning removes the false duplicates that caused the vast majority of these collisions in the first place.

Tests

Added coverage in workspaceEntries.test.ts and WorkspaceFileSystem.test.ts:

• Linked git worktree subtrees are pruned from the index.
• Unique bare basename and unique partial tail → resolved.
• Basename matching multiple real files → ambiguous (sorted matches).
• No match → unresolved.
• Worktree-duplicate scenario resolves to the real file end-to-end.
• Truncated index triggers a direct disk re-scan.
• The reader surfaces an honest ambiguity message (asserts it names the competing files and does not contain "ENOENT").

Verification

bun fmt, bun lint, bun typecheck (9/9 packages), and the full apps/server Vitest suite (2370 passing) are green.

🤖 Generated with Claude Code