[Feature]: Centralize cross-platform path identity

[Baziar]

Problem statement

One physical project can appear through symlinks, macOS /var aliases, Windows
8.3 names, drive-case variants, junctions, or UNC paths. Comparing path strings
can duplicate a project or weaken a containment check.

Proposed solution

Current foundation

• Git worktree fingerprints with content fallback;
• targeted macOS alias and repository-local symlink tests;
• containment checks for reports, adoption metadata, agent outputs, and archives;
• portable relative paths in public artifacts;
• workspace-contract resolution for deletion tombstones and overlapping Graph
  labels that refer to one contained physical artifact.

Remaining work

Define one shared utility and contract for three different concepts:

1. display path;
2. portable artifact path;
3. filesystem identity and containment boundary.

Replace remaining raw-string identity checks only after classifying which of the
three meanings each call site needs.

Acceptance criteria

• The three path roles and result types are documented and versioned.
• Git scope uses repository-relative Git evidence, not absolute equality.
• /var aliases, Windows long/8.3 names, drive case, separators, and UNC have fixtures.
• POSIX symlink and Windows junction/reparse escapes are rejected.
• Planned non-existent targets bind safely to their nearest existing ancestor.
• Registry, Doctor, Graph, and cache identity agree on one logical project.
• Persisted public artifacts contain no machine-specific canonical identity.
• Linux, macOS, and Windows native tests pass.

Completion evidence

Publish the call-site inventory, native OS fixture results, and cache migration or
invalidation decision. No new test may assert physical identity with raw string
equality.

Suggested starting points:

• packages/cli/src/utils/artifact-path-compat.ts
• packages/cli/src/utils/workspace-project-paths.ts
• packages/cli/src/__tests__/artifact-path-compat.test.ts
• packages/cli/src/__tests__/workspace-project-paths.test.ts

Alternatives considered

The following alternatives or adjacent concerns are intentionally outside this issue:

• universally lowercasing paths;
• exposing inode/device numbers as portable identity;
• changing existing public path fields without a versioned migration.

Expected impact

Users see one logical project across aliases and operating systems, while
containment checks stop depending on unsafe textual path equality.

[github-actions]

Hey @Baziar — welcome to Workspai! 👋

Thanks for taking the time to open your first issue. Clear reports and focused ideas help us make Workspai more useful for developers and AI tools working across real software workspaces.

A maintainer will review the scope and labels. If you would like to work on this issue yourself, leave a comment and we’ll help you find the relevant contracts, code, and tests.

Glad to have you here.