test(core): normalize .git/HEAD watcher events on macOS

[LeXwDeX]

Why

The Core watcher test deterministically receives an add event for .git/HEAD on macOS while asserting a change event. Linux CI passes, but the platform-specific FSEvents classification leaves the full local Core suite red and makes watcher regressions harder to distinguish from backend event vocabulary differences.

What to build

Define and enforce the watcher contract for an existing Git HEAD update across supported watcher backends. Normalize backend-specific event classification at the owning boundary when necessary, while preserving meaningful create, change, and delete semantics for consumers.

Reproduction evidence

• Run bun test test/filesystem/watcher.test.ts from packages/core on macOS.
• Watcher > publishes .git/HEAD events expects change but receives add.
• The failure reproduced in the full Core suite and an isolated rerun.
• The failing test predates graphagent-v1.0.36 and is outside the 1.0.37-dev.1 release diff.

Acceptance criteria

• The .git/HEAD update contract is explicitly documented by the test.
• The watcher emits the same contract-level event on macOS and Linux for the same existing-file transition.
• Create and delete behavior remains distinguishable and covered.
• The watcher test and full Core suite pass repeatedly on macOS and Linux.

Blocked by

None - can start immediately.

[LeXwDeX]

SpecGit delivery branch: feat/473-git-head-watcher (draft pull request #484).

[LeXwDeX]

Delivered by PR #486 (merged into dev 2026-09-01, Closes #473) after draft PR #484 was superseded by the branch-naming-compliant test/git-head-watcher lane. Auto-close did not fire because the merge target was dev, not the default branch. Promoted to main via PR #518.