fix: setup and first-run pain points (closes #67)

[fazleelahhee]

Closes #67. Lands the four most actionable items from the bundle in one
PR (per Raj's triage); leaving #2's full download-timeout work for a
separate follow-up since it touches the slow path and warrants its own
discussion of retry/backoff strategy.

Fixes in this PR

1. Drop --changed-only from the post-commit hook template —
   indexer/git_hooks.py. The flag was removed from cce index but
   the hook template still referenced it, so every commit silently
   errored. cce index (no flag) already does incremental indexing.

2. Persistent fastembed cache + .incomplete sweep —
   indexer/embedder.py. Three folded problems:

   • Default cache moves from \$TMPDIR/fastembed_cache to
     \$XDG_CACHE_HOME/fastembed (or ~/.cache/fastembed) — survives
     WSL's systemd-tmpfiles /tmp wipe.
   • New CCE_FASTEMBED_CACHE_PATH env var (priority over
     FASTEMBED_CACHE_PATH) for users isolating CCE's cache.
   • _sweep_incomplete_downloads() at Embedder init removes any
     *.incomplete blobs from a stalled huggingface_hub download so
     one flaky network event can't crash every subsequent run with
     NO_SUCHFILE.
   • Error message now points at the cache dir and suggests rm -rf
     recovery.

3. TCP liveness probe in hook scripts —
   memory/hook_installer.py. POSIX adds a bash /dev/tcp probe;
   Windows adds a PowerShell TcpClient probe. A stale serve.port
   no longer wastes 1-2s/curl call.

4. Empty-index MCP returns a status response instead of blocking —
   integration/mcp_server.py. First context_search on an empty
   index used to silently run a full reindex and only respond when it
   finished. Now kicks the index off as a background task and returns
   an immediate status line.

Deferred to a follow-up

• feat(memory): claude-mem feature parity — series of 5 PRs #2 from the issue — full download timeout/retry on
  huggingface_hub. This PR addresses the sticky part of that
  failure (the .incomplete cleanup means one stall no longer
  poisons every future run) but bounding the download itself with
  retry/backoff is a separate change.

Tests

• test_git_hooks.py +1 case
• test_embedder.py +6 cases (cache dir precedence, sweep behaviour)
• test_hook_installer.py +2 cases (POSIX + Windows probe present
  before any curl)
• tests/integration/test_mcp_empty_index.py (new, 3 cases)

Verification

• pytest -n 4 → 887 passed, 1 skipped, 0 failed
• ruff check on every changed file → clean

Test plan

• Fresh WSL: rm -rf ~/.cache/fastembed; cce serve — model lands
  in ~/.cache/fastembed, survives reboot
• Mid-download ^C, restart cce serve — .incomplete gets
  swept, download retries cleanly
• cce serve, kill with -9, time a hook event — under 100ms
  instead of 1-2s
• cce serve --project-dir /tmp/empty then context_search over
  MCP — returns "Index is empty, indexing started" immediately
  instead of blocking
• cce init && git commit --allow-empty — post-commit runs
  cce index cleanly with no errors in 2>&1 capture

[Copilot]

Pull request overview

This PR addresses several setup/first-run pain points (issue #67) by fixing broken git hook templates, making fastembed’s cache persistent and self-healing, reducing hook latency when the server port is stale, and ensuring MCP context_search on an empty index returns immediately with a status message while indexing runs in the background.

Changes:

• Update git hook templates to call cce index without the removed --changed-only flag.
• Add persistent fastembed cache resolution + .incomplete cleanup and improve load error messaging.
• Add TCP liveness probes to hook scripts and make MCP empty-index searches non-blocking via background indexing.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/context_engine/indexer/git_hooks.py	Removes --changed-only from hook script template.
src/context_engine/indexer/embedder.py	Adds persistent cache dir resolution, sweeps *.incomplete, passes cache_dir to fastembed, improves error message.
src/context_engine/memory/hook_installer.py	Adds POSIX/Windows TCP liveness probes before curl.
src/context_engine/integration/mcp_server.py	Changes lazy indexing to run in background and returns a status response when index is empty.
tests/indexer/test_git_hooks.py	Adds regression test ensuring hooks don’t reference --changed-only.
tests/indexer/test_embedder.py	Adds tests for cache-dir precedence and .incomplete sweeping behavior.
tests/memory/test_hook_installer.py	Adds tests asserting TCP probe exists and runs before curl.
tests/integration/test_mcp_empty_index.py	Adds integration coverage for empty-index MCP behavior and _ensure_indexed() return value.
.github/workflows/ci.yml	Pins FASTEMBED_CACHE_PATH so cache warming and tests share the same directory.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rajkumarsakthivel]

LGTM. All 4 actionable items from #67 landed.

Hook template fix, persistent cache with .incomplete sweep, TCP liveness probe (both POSIX and Windows), and non-blocking empty-index response. Download timeout deferred to a follow-up is the right call. Good test coverage.