Add fswatch-based kubeconfig monitoring

[mrf]

Add fswatch-based kubeconfig monitoring for comprehensive context switch detection

Implements issue kubectx-timeout-1904: Add file system monitoring using fswatch to detect kubectl context switches made outside the shell wrapper.

This enables detection of context switches from ANY tool including:

• IDE plugins (VSCode Kubernetes, IntelliJ IDEA, etc.)
• GUI tools (Lens, K9s, etc.)
• Direct kubectx commands
• Manual kubeconfig file edits

Key Features:

• Uses fswatch with FSEvents API on macOS for efficient, low-overhead monitoring
• Monitors ~/.kube/config (or $KUBECONFIG path) for modifications
• Detects actual context changes and records activity to reset timeout
• Graceful degradation when fswatch not available (daemon continues normally)
• Runs in separate goroutine alongside periodic timeout checker
• Automatic restart on fswatch process failures
• 500ms debounce to handle transient file writes

Implementation:

• internal/watcher.go: Core watcher implementation with FSEvents integration
• internal/watcher_test.go: Comprehensive test suite (unit tests pass)
• internal/daemon.go: Integrated watcher into daemon lifecycle
• docs/fswatch-monitoring.md: Complete documentation with troubleshooting guide

Documentation Updates:

• README.md: Added fswatch installation and usage sections
• CHANGELOG.md: Documented new feature
• CONTRIBUTING.md: Added kubectl requirement for running tests
• examples/README.md: Added fswatch installation step

Testing:

• Build: Success
• Core watcher unit tests: All pass
• Integration with daemon: Verified
• Graceful degradation: Tested and working

Note: fswatch is optional - daemon works perfectly without it using shell wrapper detection alone.

🤖 Generated with Claude Code

Description

Beads Issue

Closes: kubectx-timeout-XXX

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test coverage improvement

Testing

Unit Tests

• Unit tests added for new/changed code
• All unit tests pass locally
• Code coverage meets minimum threshold (80% overall, 90% core logic)

Integration Tests

• Integration tests added if cross-component changes
• All integration tests pass locally

Manual Testing

• Manual testing performed (describe below)

Manual Testing Details:

Code Quality Checklist

Required (Must Pass)

• Code formatted with gofmt and goimports
• All linter checks pass (golangci-lint run ./...)
• No security issues (gosec ./...)
• Self-review performed (read through your own code)
• No commented-out code blocks
• Git commit messages are clear and descriptive

Code Review Standards

• Functions have single, clear responsibility
• All errors properly handled (no swallowed errors)
• Public APIs have godoc comments
• Complex logic has explanatory comments
• No hardcoded credentials or secrets
• File operations use appropriate permissions
• Input validation for external inputs
• Race conditions handled with proper locking

Documentation

• README.md updated (if user-facing changes)
• Configuration documentation updated (if config changes)
• API documentation updated (if API changes)
• Comments added for complex/non-obvious code

Security Considerations

• No security implications
• Input validation added/modified
• Authentication/authorization changes
• Credential handling changes
• File permission changes
• Command execution changes

Security Review Details:

Performance Considerations

• No performance implications
• Performance improved
• Performance impact acceptable (explain below)

Performance Details:

Breaking Changes

• No breaking changes
• Breaking changes documented above

Screenshots / Logs

[Paste relevant terminal output or logs here]

Reviewer Notes

---

Pre-Review Checklist (for submitter)

Before requesting review, verify:

• All CI checks pass
• Branch is up to date with main
• No merge conflicts
• PR description is clear and complete
• All checklist items above are addressed

---

Review Priority:

• Standard review (48h turnaround)
• Urgent review needed (explain why below)

Senior Review Required: (auto-detected by changes)

• Security-sensitive changes
• Architecture changes
• Performance-critical code
• High-risk areas (launchd, kubectl execution, state management)