Skip to content

fix(mcp): two CODEGRAPH_DIR indexes of one project each get their own daemon - #3301

Open
Ahaeflig wants to merge 1 commit into
colbymchenry:mainfrom
Ahaeflig:fix/daemon-index-namespaces
Open

Ahaeflig wants to merge 1 commit into
colbymchenry:mainfrom
Ahaeflig:fix/daemon-index-namespaces

Conversation

@Ahaeflig

@Ahaeflig Ahaeflig commented Nov 15, 2026 •

Copy link
Copy Markdown

What it changes for you

  • codegraph index stops only its own index's daemon. A rebuild first stops the daemon of the index it rebuilds. When that index has no daemon, main falls back to the registry record named after the project root, and stops whatever daemon wrote it, which can be the daemon of another index of the project. Now it stops only a daemon known to serve the index it rebuilds.
  • codegraph daemon reaches every index. Two indexes of one project shared one registry record on main, so the list showed one daemon and Stop all stopped one. Now each index's daemon has its own record, and the list, the picker and Stop all reach each of them.
  • Two indexes no longer meet at one daemon. On Windows, and wherever a project's socket path is too long or its filesystem can't hold a socket, both indexes met at one daemon, which answered both from its own index. The version check doesn't catch that when both are the same release. That includes a project on a Windows drive under WSL: after CODEGRAPH_DIR=.codegraph-wsl codegraph init, which the WSL + Windows shared working tree on /mnt causes CodeGraph disk I/O error unless CODEGRAPH_DIR is split manually #995 message asks for, sessions of .codegraph-wsl were answered by the daemon of .codegraph.

The problem

This is the daemon change you asked to have split out of #2331.

CODEGRAPH_DIR lets one project hold more than one index; a project that keeps one index per CodeGraph build has several. Each index runs its own daemon, but part of how a daemon is found is keyed by the project root alone:

  • the Windows named pipe (\\.\pipe\codegraph-<hash of root>);
  • the temp-directory socket a POSIX daemon falls back to when the in-project path is too long or its filesystem can't hold a socket (codegraph-<hash of root>.sock);
  • the registry record behind codegraph daemon (~/.codegraph/daemons/<hash of root>.json).

The lock and the in-project socket (<index dir>/daemon.sock) were already per index.

What changes

Every pipe and fallback socket name changes. The named pipe, the fallback socket and the registry record of every index, the default .codegraph included, are named after the index's own canonical directory instead of the root. The lock and the in-project socket keep their paths, so wherever the in-project socket is used, which is most projects on macOS and Linux, a daemon is found where it always was. Names don't depend on which index is the project's default, which can change while daemons run: on a Windows drive under WSL, creating .codegraph-wsl makes it the default while a .codegraph daemon still serves. Every spelling of a root or an index directory still lands on one name. Only these hashes and comparisons fold case; the lock, the writer lock and the in-project socket keep the root's own spelling.

A session joins only its index's daemon. When the index's lock names a daemon, a launcher joins a daemon on a candidate socket only if its hello names that pid. It never sends a session to a socket path read from a file. Each time a session looks for its daemon, it looks under the names of the index its root resolves to then, as its lock, the daemon it spawns and its in-process fallback do. So a session on a Windows drive under WSL that started before .codegraph-wsl existed joins that index's daemon once its own daemon is gone, as it did on main.

After an upgrade. A daemon of an older release is still found through its index's daemon.pid and replaced, as it has been since #2335; that is how the #2278 pipe rename was handled too. A daemon of the same version from before the rename (a dev build, a fork) isn't older, so nothing replaces it. A launcher that finds no daemon on its candidates now also tries that daemon's name, the pipe or fallback socket named after the root, and joins the daemon there only if its hello names the pid in this index's own lock. A daemon of another index under that name is left alone.

After a downgrade. A session of an older release looks for the daemon under the old names. Where the in-project socket is used, it finds a daemon of this release there and serves itself in-process at once, as with any newer daemon. On Windows and on the fallback socket it finds nothing, spawns a daemon that can't take the lock, waits about 6 s, and then serves the session in-process, reads only. That is the cost of the rename. An older release's codegraph daemon also prunes a record that fails its hello under the name it works out from the record's root, not the file it read. So when a record this release wrote for another index of the project fails its hello while its pid is alive (a pid reused after an unclean exit, or a daemon busy for more than a second), the older release deletes the record its own daemon of that project filed under the root, and keeps the stale one. That daemon keeps serving its sessions, but neither release lists it until it restarts.

Registry records. A record now names its index directory, and list, stop, Stop all and the picker act on that directory, not on the reader's CODEGRAPH_DIR. A record an older release wrote names only its root. Its index is worked out from the record: an in-project socket path gives it, and otherwise it is the root's data directory whose daemon.pid names that daemon. When neither shows it, the record is still listed but never taken for one index's daemon, so codegraph index doesn't reach it. The picker and Stop all stop it by its pid, once its hello proves the pid is still that daemon (#1553). A record that fails its hello is pruned by the file it was read from, and only while that file still holds that record. Picker rows are keyed by record file, so two rows never share a value. A daemon removes the record it wrote when it stops, whichever index its root resolves to by then.

Cleanup. A replacement that has to kill an older daemon, and every replacement on Windows, where the stop is TerminateProcess, now also removes what that daemon named after the root: its registry record, and on POSIX the fallback socket its lock names, while nothing listens on it. The same cleanup runs when codegraph daemon stops a daemon or codegraph unlock clears a stale lock. A record goes only when it names the stopped daemon's pid and socket, so a live daemon that got a reused pid keeps its record.

codegraph daemon. "(current project)" marks, and pre-selects, only the row of the reader's own index. The picker's hints and notes, and the plain list printed when output isn't a terminal, name the index beside the root when it isn't the project's default or when two daemons serve one root. Other rows read as before.

stopDaemonAt and the cleanup behind every stop, including the cleanup's writer-slot claim, take the index directory they act on. When that directory is gone, deleted while its daemon ran, the cleanup claims nothing, since no lock is left there to fence, and leaves it gone: on a Windows drive under WSL, an empty .codegraph-wsl made again would be the project's default index. The older-daemon handover still takes over the writer slot of the reader's own index, the only index a handover concerns.

What I ran

Linux x64 (WSL2), Node 24.19.0, on main at f72c9d2:

  • Full suite (npx vitest run, with the native kernel staged and CODEGRAPH_KERNEL_EXPECT=1): 11,114 passed, 2 expected failures, 58 skipped (platform-gated), 0 failed.
  • The daemon test files, every daemon-*.test.ts plus mcp-daemon, index-daemon-rebuild, writer-lock, mcp-writer-lock, cli-unlock and wal-heal (20 files): 234 passed, 7 skipped (platform-gated).
  • Mutation testing: 37 mutants of this change, each compiled into dist/ and run against the daemon test files that cover it. 36 fail at least one test. The one left drops the check that an in-project socket named in an older release's record lies under that record's root, a check no record an older release writes fails.

daemon-index-namespace.test.ts (45 tests) covers:

  • every index's pipe, fallback socket and record named after its own directory, the default included, with the platform switched to win32 and linux; names that stay put when the index WSL picks by default changes; one name for every spelling of a root, and a symlinked root;
  • the lock keeping the root's case with the platform switched to win32, and a stale lock there cleared without a lowercased directory being made;
  • records: pruned by their own file, and not once that file holds another record; a daemon's deregistration leaving a successor's record; a stale lock's cleanup leaving the record of a live daemon that reused its pid; the index a record names read from the record alone, whatever the reader's CODEGRAPH_DIR;
  • stops: another index cleaned under that index's writer slot, and its record removed, not the reader's; a daemon found only through its record stopped and its record removed; a socket that refuses a connection, or never settles one, counted as in use; a daemon whose index directory was deleted stopped without the directory being made again, which on a WSL drive leaves the default to the index that is left;
  • records an older release filed under the root: their index worked out from the socket or a lock that names their pid and socket, never the reader's; never stopped by pid unless the pid still answers as that daemon;
  • with a stand-in for an older release's daemon (a fixture process): stopDaemonAt for an index without a daemon never stops it, from either reader; picking its row in the real picker stops only it; Stop all stops one of unknown index by its pid, and clears its record and socket when it has to kill it; clearing another index's stale lock leaves the socket it listens on; and a replacement that has to kill it leaves no record, socket or lock, for the default index and another;
  • the picker's current row and its first selection, the index named in hints, notes and the plain list (by running codegraph daemon);
  • sessions of the built CLI: two daemons when the index WSL picks by default changes under a running daemon; a session from before that change joining the new index's daemon once its own daemon goes; joining a same-version daemon from before the rename under the root's name, while the default index's session starts its own; and a planted daemon.pid naming a socket elsewhere, with a process that isn't the lock's daemon on the index's own fallback socket, neither of which receives a byte.

By hand, in a throwaway home and temp directory, against main, this PR as first posted, and this PR now:

  • A WSL project on a Windows drive (paths forced to count as one): a .codegraph session, then CODEGRAPH_DIR=.codegraph-wsl codegraph init and a session of .codegraph-wsl. On main the second session was answered by the .codegraph daemon; now it gets a daemon of its own, and each daemon holds only its own database.
  • The same project, with a path long enough for the fallback socket: a .codegraph session, then CODEGRAPH_DIR=.codegraph-wsl codegraph init, then the session's daemon stopped. On main the session joined the .codegraph-wsl daemon 1.2 s later. As first posted it never joined again and served the session in-process: without auto-sync while a .codegraph-wsl daemon it never looked for held the writer slot, and with a 4 s daemon idle timeout it started such a daemon five times in 40 s while calls waited up to 5.2 s. Now it joins 1.8 s later, and one daemon starts.
  • An index directory deleted while its daemon runs, then Stop all: as first posted, the stop made the directory again, empty, and on a WSL drive, where .codegraph-wsl existing makes it the default, the next session found no index. On main and now the directory stays deleted, and the session finds the code in .codegraph.
  • A daemon built from main serving .codegraph-a on the fallback socket named after the root: a session of this branch for .codegraph-a joins it and answers in 0.4 s (the first version took 6.3 s and served the session in-process), and a session for the default index starts its own daemon instead of joining it.
  • A daemon of this branch for .codegraph-a on its fallback socket, and a session of main for .codegraph-a: answered after 6.4 s, in-process, reads only, the downgrade cost above.
  • A daemon built from main serving .codegraph-a, and a record this branch wrote for .codegraph-b whose pid a live process now has: main's codegraph daemon deleted the live daemon's record and listed nothing the second time it ran, the downgrade note above; this branch's pruned only the stale record and kept listing the daemon.
  • A daemon.pid written by someone else, naming pid 1 and a socket elsewhere that answers as pid 1: no session connects to it; the session serves itself in-process.
  • codegraph index on the default index and on .codegraph-b, neither with a daemon of its own, while a daemon built from main served .codegraph-a: on main and in the first version that daemon was signalled to stop; now it keeps running, with its socket and record in place.
  • An older daemon that ignores SIGTERM, replaced by force: its record and its fallback socket stayed; now nothing is left.

Not run: native Windows and macOS. The Windows names are exercised only by switching process.platform, so the named pipes and the TerminateProcess cleanup weren't run on Windows itself, and the tests that run a daemon process or a session are POSIX-only.

🤖 Generated with Claude Code

… daemon

A daemon's rendezvous was keyed by the project root alone: the Windows named
pipe, the temp-directory socket a long or socket-less project path falls back
to, and the registry record behind `codegraph daemon`. Two indexes of one
project, kept apart with CODEGRAPH_DIR, therefore met at one daemon, which
answered both from its own index. Their registry records overwrote each
other, so the list showed one daemon and stop --all stopped one, and
`codegraph index` on an index without a daemon stopped whichever daemon had
filed the root's record.

Every index's pipe, fallback socket and registry record is now named after
its own canonical directory, the default index included, so no name depends
on which index is the default: on a Windows drive under WSL that changes
while daemons run. The lock and the in-project socket keep their paths, and
only the hashes and comparisons fold case.

A launcher never connects to a socket path read from a file. Each attempt
looks under the names of the index its root resolves to at that moment, so
a session joins a new default index's daemon once its own daemon is gone.
When the index's lock names a daemon, a candidate's hello must name that
pid. A daemon of the same version from before the rename is looked for
under the root's own pipe or fallback socket, and joined only when its hello
names the pid in this index's lock; an older release's daemon is found and
replaced through its lock, as before.

A record names its index directory, and list, stop, stop --all and the
picker act on it, not on the reader's CODEGRAPH_DIR. An older release's
record gets its index from its in-project socket or from the lock naming its
daemon; one that shows neither is listed but never taken for one index's
daemon, and is stopped by its pid only once its hello proves it. Records are
pruned by the file they were read from, and removed only while they name the
stopped daemon's pid and socket, so a successor or a daemon that reused a pid
keeps its record. Replacing or clearing an older daemon also removes the
record and fallback socket it named after the root, the socket only while
nothing answers on it. A cleanup whose index directory is gone claims
nothing and leaves it gone.

`codegraph daemon` marks only the reader's own index as the current project,
and names an index beside its root when it isn't the project's default or
when two daemons serve one root.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Ahaeflig
Ahaeflig force-pushed the fix/daemon-index-namespaces branch from a2d627d to 02a415c Compare November 15, 2026 21:36

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant