feat(sync): worktree index mismatch detection — doctor check + MCP banner (closes #66 phase-4)

[Wolfvin]

Closes #66 (phase 4 only — phases 1, 2, 3, 5 remain open for other workers).

What

Add git worktree ↔ CodeLens index mismatch detection. When a user runs CodeLens inside a git worktree that does not have its own .codelens/ index, CodeLens's workspace auto-detection silently walks up and loads the main checkout's index — which was built from a different branch. Every subsequent query / trace / dataflow / taint answer is then grounded in the wrong file set, with no warning to the user or the agent.

Why

Issue #66 Phase 4 explicitly calls for this:

Worktree mismatch detection — detect git worktree nested inside main checkout. Walk-up resolves .codelens/ to parent main checkout (different branch). Warning in codelens status + banner on every MCP read tool response. Suggest codelens init -i in worktree.

This is a real correctness bug. A worktree user gets stale data with no indication anything is wrong.

How

New module scripts/sync/worktree.py with three public functions:

• detect_worktree_index_mismatch(project_root) → structured record
• format_worktree_warning(mismatch) → multi-line CLI warning
• format_worktree_banner(mismatch) → single-line MCP banner

The detector shells out to git rev-parse --show-toplevel and git rev-parse --git-common-dir (max 2 subprocess calls per probe, 5s timeout each, never raises). Returns 5 reason codes:

Reason	Mismatch	Meaning
not_a_git_repo	False	git not installed, or workspace not under git
not_a_worktree	False	main checkout, no worktree concerns
worktree_has_own_index	False	worktree with its own .codelens/ (correct setup)
no_index_found	False	worktree, but no .codelens/ anywhere up the tree
worktree_uses_main_index	True	MISMATCH — worktree reading main's index

Wiring

codelens doctor — new check workspace.worktree_index_mismatch (status=warning on mismatch). Runs BEFORE _check_codelens_writable because the writable check creates .codelens/ as a side effect of probing write permissions, which would mask the mismatch.

MCP server — read-tool responses get a top-level _worktree_warning field when a mismatch is detected:

{
  "content": [...],
  "isError": false,
  "_worktree_warning": {
    "banner": "⚠️ WORKTREE INDEX MISMATCH: ...",
    "mismatch": { "mismatch": true, "reason": "worktree_uses_main_index", ... }
  }
}

Mutating commands (scan, init) skip the banner — they're the user's remediation path. The mismatch verdict is cached per workspace for the server's lifetime (probed once, reused). Cache is invalidated when scan runs (the user may have just run codelens init -i to fix the mismatch).

Why a top-level field, not a content prepend: Prepending text to the content array would corrupt the JSON payload agents parse out of the response. A top-level field keeps the JSON intact while still surfacing the warning prominently.

Critical implementation detail: early-probe

The mismatch detection runs BEFORE _execute_command, not after. Why: read commands like list / query trigger ensure_codelens_dir(workspace) as a side effect of loading the registry, which creates .codelens/ in the worktree. If we probed after execution, the worktree would appear to have its own index and the mismatch would never fire. Probing early caches the pre-execution state so the banner reflects what the user actually configured.

Tests

30 new tests across 3 files (all green):

• tests/test_worktree.py (19 tests) — detector + formatters, covers all 5 reason codes plus robustness (None input, file path, empty string, subdirectory of worktree).
• tests/test_doctor.py (6 new tests in TestWorktreeMismatchCheck class) — doctor integration, including an ordering test that enforces "mismatch check runs BEFORE writable check".
• tests/test_mcp_hooks.py (5 new tests in TestWorktreeBannerAttachment class) — MCP integration, including cache-once-per-workspace and detection-never-breaks-tool-call contracts.

Test results

1404 passed, 76 skipped, 1 failed in 61.22s

The 1 failure is pre-existing and unrelated to this PR:

FAILED tests/test_codelensignore.py::TestBackwardCompat::test_actual_target_dir_is_ignored

This test was failing on origin/main before this branch was created.

Files

File	Change
scripts/sync/__init__.py	New — package marker with docstring
scripts/sync/worktree.py	New — detector + formatters (330 lines)
scripts/commands/doctor.py	Modified — added _check_worktree_mismatch, reordered _run_all_checks
scripts/mcp_server.py	Modified — added _worktree_mismatch_cache, _get_worktree_mismatch, _attach_worktree_banner; wired into _handle_tools_call (read tools only)
tests/test_worktree.py	New — 19 tests
tests/test_doctor.py	Modified — added TestWorktreeMismatchCheck class (6 tests)
tests/test_mcp_hooks.py	Modified — added TestWorktreeBannerAttachment class (5 tests)
CHANGELOG.md	Updated — added [8.2.0] section for issue #66 Phase 4

Acceptance criteria (from issue #66)

• Phase 4: worktree mismatch warning appears in codelens doctor output
• Phase 4: banner attached to every MCP read tool response (as _worktree_warning field)
• Phase 4: suggests codelens init -i in the worktree to build its own index

Out of scope (other phases of issue #66)

• Phase 1: Per-file staleness banner (scripts/sync/pending.py)
• Phase 2: Connect-time catch-up
• Phase 3: Native file watcher (FSEvents/inotify/ReadDirectoryChangesW)
• Phase 5: Anonymous opt-in telemetry

These phases remain open for other workers — the issue is not closed by this PR.

Findings

While implementing this, I noticed that _check_codelens_writable in doctor.py creates .codelens/ as a side effect of probing write permissions. This is intentional (it's the only way to verify write access), but it means any doctor check that depends on the pre-doctor state of .codelens/ must run BEFORE the writable check. The _check_worktree_mismatch check does this correctly, but future checks should be aware of this ordering constraint. I've added a comment in _run_all_checks documenting it.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud