feat(config): add ignore_worktrees to skip linked git worktrees

[vitalNohj]

Problem

Agent workflows increasingly use git worktree add to run several branches of the same repo side by side. Every worktree is discovered as its own project, so the cache accumulates a near-duplicate graph per worktree and project pickers get noisy. Today there is no way to say "index the main checkout, leave the worktrees alone".

Change

Adds an opt-in ignore_worktrees config key. When enabled, a linked worktree is left alone across every indexing entry point:

• auto-index on connect skips it (logged as autoindex.skip with reason=linked_worktree)
• the daemon's background auto-index skips it
• explicit index_repository refuses with an actionable message naming both ways forward
• hook-augment guidance stops telling the agent to run index_repository in a directory where it would only be refused

The explicit call keeps an escape hatch — index_worktree=true indexes a worktree regardless of the setting, so the key never becomes a dead end:

repo_path is a linked git worktree and ignore_worktrees is enabled. Pass
index_worktree=true to index it anyway, or run:
codebase-memory-mcp config set ignore_worktrees false

Default is false, so nothing changes for existing users unless they opt in.

Detection

cbm_git_is_linked_worktree() is git plumbing only, no subprocess — it runs on every session start, so shelling out the way cbm_git_context_resolve() does was not an option.

<path>/.git must be a regular file holding a gitdir: pointer and that gitdir must contain a commondir file.

That second condition is the important one: a submodule's .git is also a gitlink file, so a naive "is .git a regular file?" check misclassifies every submodule as a worktree. A submodule's gitdir (<super>/.git/modules/<name>) has no commondir entry, which separates the two cleanly. The main checkout of a repo that has worktrees is never affected.

Tests

tests/test_git_context.c — detection truth table: linked worktree true; the main checkout of that same repo false; a submodule false; a plain non-git dir false.

tests/test_mcp.c — the config gate on explicit index_repository: worktree refused, main checkout not refused, and index_worktree=true escaping the gate.

Both follow the existing fixture patterns in those files (th_mktempdir/th_rmtree, SKIP_PLATFORM on Windows, graceful skip when git is unavailable).

Verification

• scripts/build.sh — clean
• scripts/test.sh — 6661 passed, 0 failed (116 suites)
• make -f Makefile.cbm security — all 8 layers pass
• clang-format (repo-wide lint-format) and cppcheck — clean; clang-tidy reports 0 findings on the added lines
• manually verified end-to-end against the built binary: refusal on a worktree, normal indexing on the main checkout, index_worktree=true override, and unchanged default-off behaviour

Docs

docs/CONFIGURATION.md gets a table row plus a section covering motivation, the enable command, all three behaviours, and the submodule/main-checkout caveat. README.md gets a short paragraph next to auto_watch.

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

[DeusData]

Thank you for the focused ignore_worktrees configuration contribution. This adds public configuration and changes repository-discovery behavior, so I have routed it to 0.11.0-rc with normal priority for a full behavior review. The community queue is currently full, and detailed feedback may take a little time.

[DeusData]

@vitalNohj — the behavior review is done, and the answer is accepted: both surfaces ship — the ignore_worktrees config key and the index_worktree per-call override — once the rework below lands. Your detection design carried the decision: the commondir marker is the right discriminator (submodule-safe, since submodule gitdirs never carry it), the fail-open posture on any probe failure is exactly correct, and default-off is verifiably bit-for-bit today's behaviour.

Context you deserve on why this needed a maintainer decision at all: there is a parked direction (see #573) where worktrees eventually get a cheap view keyed by the git common dir rather than nothing. Your key is opt-in-off, so it forecloses none of that — and your commondir plumbing is genuinely reusable for that family-identity work later. But "skip worktrees on purpose" and "worktrees get an overlay" are opposite product answers to the same pain, so shipping yours ahead of that decision was a call, not a formality. It is now made, in your favour.

The rework map — one item is invisible and load-bearing:

1. CONFIG_KEYS row (the invisible one). Since 0.10.0: two silent empty-result paths — tree format returns {} over MCP (default), and config get returns empty for all keys but auto_index #1522/Installer/updater scope and safety: no per-client selector, destructive update step before an interactive prompt, hidden ui_enabled, brittle legacy-marker cleanup #1558, that table in src/cli/cli.c (:6837) is the config set allowlist — config_key_lookup rejects unknown keys (:6997). Your PR predates this, patches the old printf blocks, and adds no row — so on current main every enable command your own docs and refusal message suggest would error unknown config key. Add {CBM_CONFIG_IGNORE_WORKTREES, "false", "<help text>"} with the default mirroring your runtime reader, per the table's keep-in-sync comment. Nothing will fail a test if you miss this — the Installer/updater scope and safety: no per-client selector, destructive update step before an interactive prompt, hidden ui_enabled, brittle legacy-marker cleanup #1558 pin covers only the UI keys — which is precisely why it leads this list.
2. Rebase: conflicts in README, CONFIGURATION.md and the rewritten config region of cli.c; the other nine files auto-merge.
3. The default-off pin: a test asserting that with the key unset, a linked worktree still indexes exactly as today — the regression class we guard hardest. Your explicit-gate probe with its positive control and override-escape is good; this is the missing direction.
4. If you can: cover the auto-index path (your _for_testing wrapper hardcodes false, so the new branch is currently unreachable from the test hook), swap the hardcoded /tmp for th_mktempdir as your body describes, and let fixture failures SKIP rather than PASS.

The one red CI leg on your final SHA (test_daemon_ipc.c:2248, Windows) is a timeout-decided test on a loaded runner, mechanism-unrelated to your diff — it is now on our flake ledger, and a rebase re-runs everything anyway.

Take your time; the acceptance does not expire. This is a first contribution built the way we wish more were.

[DeusData]

@vitalNohj, thank you, sincerely. You took a rework map with one invisible, untested trap at the top of it and came back with every item done, plus the tests we only asked for "if you can". I'm sorry, too: this landed on 09-23 and we didn't notice for two days. That's on us, not on you.

What we checked on 0d2f840c, item by item against the map:

1. CONFIG_KEYS row: present in src/cli/cli.c with default false, mirroring the runtime reader. It's pinned by your new cli_ignore_worktrees_config_key_is_discoverable, so the enable command your docs and refusal message suggest now works.
2. Rebase: the branch merges cleanly with today's main.
3. Default-off pin: mcp_ignore_worktrees_default_off_still_indexes_worktree covers the direction that was missing. We also checked the code: all four call sites (explicit call, in-process auto-index, daemon auto-index, hook guidance) short-circuit on the config read before any filesystem probe. With the key unset, today's behaviour is untouched.
4. Auto-index coverage, th_mktempdir, SKIP-not-PASS: all done. Your two auto-index tests drive the real initialize path with the count hook as the observable, which is exactly the shape we'd have asked for.

We also re-read the detector: the commondir discriminator, relative-pointer resolution, and fail-open on every probe failure. We confirmed the new read goes through cbm_fopen, that the change adds no raw allocation sites to src/, and that nothing in the diff goes beyond the feature.

Two optional wording nits, entirely up to you and fine to leave:

• The one-line help text and the docs table row say "when indexing automatically", but the key also refuses explicit index_repository calls. The section below the table already explains that, so something like "Skip linked git worktrees when indexing (explicit calls need index_worktree=true)" would make the one-liner match.
• The explicit default-off test asserts "not refused" rather than a successful index. The auto-index default-off test already covers the positive side, so this is only a note.

We'll run a fresh CI pass against current main and merge from there. Thank you again. This is a contribution built the way we wish more were, and it's already noted for the worktree-family work in #573.