perf(skills): cache standard user sources with live invalidation

[limityan]

Why

Skill discovery currently reparses process-level user sources on every query even though project and remote sources already need request-scoped freshness. This adds repeated filesystem and frontmatter work without improving correctness.

The design follows established competitor behavior: OpenCode exposes Skill metadata and loads content on demand, Claude Code discovers edits without restart, and Codex watches Skill roots and invalidates its cache. BitFun keeps the current turn stable and refreshes the next query.

References:

• https://opencode.ai/docs/skills
• https://code.claude.com/docs/en/slash-commands
• https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md

What changed

• Cache only workspace-independent standard user Skill roots across Claude Code, Codex, OpenCode, Agents, and BitFun conventions.
• Keep local project roots, remote project roots, and OpenCode configured skills.paths request-scoped so workspace precedence and configured-path semantics remain correct.
• Add versioned, single-flight invalidation with bounded stability retries; incomplete, symlink/reparse-backed, or unhealthy scans fail open to uncached discovery instead of publishing stale snapshots.
• Extend the shared file-watch service with backend health signals, full watcher rebuild, directory replacement rebinding, semantic build/target directory support, and serialized watch lifecycle updates.
• Keep the native watcher on an OS-owned thread while delivering frontend events through a bounded runtime-owned queue, so short-lived CLI runtimes can exit without losing long-lived desktop emitter ordering.
• Collapse recursive parent registrations over nested roots and preserve existing Skill precedence/deduplication behavior.
• Document the delivered source-freshness boundary in the OpenCode compatibility architecture notes.

User-visible behavior

• Repeated Skill queries avoid reparsing unchanged standard user sources.
• Adding, editing, removing, renaming, or replacing a watched user Skill source is visible on the next Skill query.
• Linked/reparse-backed standard Skills remain discoverable and are conservatively rescanned because their external targets are not guaranteed to be covered by the parent watcher.
• The active turn is never mutated in place.
• Watcher or scan uncertainty trades performance for correctness by rescanning.

Non-goals

• Plugin Host Runtime or plugin execution
• LSP support
• plugin marketplace/cache discovery
• URL/downloaded Skill sources
• changing project, remote-workspace, or configured-path ownership

Validation

• cargo test --locked -p bitfun-services-integrations --no-default-features --features file-watch --lib (7 passed)
• cargo test --locked -p bitfun-services-integrations --features file-watch --test file_watch_contracts (9 passed)
• cargo test --locked -p bitfun-core --features product-full source_cache::tests (7 passed)
• cargo test --locked -p bitfun-core --features product-full local_skill_scan_tests (5 passed)
• cargo test -p bitfun-core --lib configured_skill_tests (9 passed)
• cargo test --locked -p bitfun-cli --test exec_cli_contracts (15 passed)
• cargo check --locked -p bitfun-core --no-default-features
• cargo check --locked -p bitfun-core --features product-full
• pnpm run check:repo-hygiene
• pnpm run check:core-boundaries
• git diff --check gcwing/main...HEAD

Review notes

CI exposed that activating process-lifetime Skill watching made short-lived CLI processes wait on a never-ending Tokio blocking task after terminal events had already been emitted. The watcher receiver now belongs to a named OS thread; ordered frontend emission belongs to a bounded queue on the active runtime.

Independent adversarial review also found and closed watcher rebuild/registration races plus linked-source freshness gaps. Standard symlink/reparse-backed Skill directories and semantic files remain readable but make the snapshot uncacheable, avoiding stale metadata or invocation policy without adding a canonical-target watch graph. Final review reported no remaining PR-added P0/P1/P2 findings.

macOS CI then exposed that FSEvents reports canonical /private/var/... paths for /var/... registrations. The shared service now retains the native backend identity only for matching and projects events back into the caller's registered namespace. Rebuilds refresh that identity, and canonical-equivalent roots use deterministic precedence.

A second independent adversarial review verified the rebuild and overlapping-root fixes and reported no remaining PR-added P0/P1/P2 findings.