Skip to content

Commit 72a2c0b

Browse files
authored
Merge pull request #2348 from DeusData/fix/issue-2167
fix(watcher): show watch state in index_status, correct auto-sync docs (#2167)
2 parents a96064c + 72edfce commit 72a2c0b

10 files changed

Lines changed: 525 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,8 @@ codebase-memory-mcp config set auto_index true
151151

152152
When enabled, new projects are indexed automatically on first connection. Previously-indexed projects are registered with the background watcher for ongoing git-based change detection. Configurable file limit: `config set auto_index_limit 50000`.
153153

154+
The watcher follows MCP sessions: it watches the project each open MCP session is rooted in (the client's working directory) and stops when the last session for that project closes. A repository indexed with `cli index_repository`, or indexed from a session rooted somewhere else, is not watched — re-run `index_repository` after changing it. `index_status` reports this in its `watch` object: `watched`, and either the poll cadence and last scan time or the `reason` it is not watched.
155+
154156
Watcher registration is controlled separately by `auto_watch` (default `true`). Set `config set auto_watch false` to keep a session from registering its project with the background watcher — useful when working across many projects and you want each session contained to explicit indexing.
155157

156158
To turn the watcher off entirely, set `config set watcher_enabled false` (default `true`): the background poll thread never starts and no project is registered, while `auto_index` and manual `index_repository` keep working. Unlike `auto_watch` — which is consulted per session — `watcher_enabled` is read once when the background daemon starts, so run `codebase-memory-mcp daemon stop` after changing it; reconnecting your MCP client alone will not restart the daemon. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#2-cli-managed-runtime-settings).
@@ -246,7 +248,7 @@ The install script placed beside the binary is **reported, not deleted** — uni
246248

247249
### Distribution & operation
248250
- **Native runtime set, zero infrastructure services**: SQLite-backed, persists to `~/.cache/codebase-memory-mcp/`
249-
- **Auto-sync**: Background watcher detects file changes and re-indexes automatically
251+
- **Auto-sync**: Background watcher detects file changes in the project an MCP session is working in and re-indexes it automatically (other indexed repos: re-run `index_repository`)
250252
- **Route nodes**: REST endpoints are first-class graph entities
251253
- **CLI mode**: `codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'`
252254
- **Available on**: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, `go install`
@@ -681,7 +683,7 @@ JSON arguments can also be piped on stdin, for tools that take arguments. A tool
681683

682684
| Tool | Description |
683685
|------|-------------|
684-
| `index_repository` | Index a repository into the graph. Auto-sync keeps it fresh after that. Waits for the whole index by default; pass `async: true` to start it in the daemon and return at once, then poll with `status: true` (see below). |
686+
| `index_repository` | Index a repository into the graph. Auto-sync keeps it fresh only while it is the project of an open MCP session; repos indexed from the CLI or from another project's session need a re-run (`index_status` shows `watch`). Waits for the whole index by default; pass `async: true` to start it in the daemon and return at once, then poll with `status: true` (see below). |
685687
| `list_projects` | List all indexed projects with node/edge counts. |
686688
| `delete_project` | Remove a project and all its graph data. |
687689
| `index_status` | Check indexing status of a project. |

‎docs/CONFIGURATION.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,11 +88,17 @@ Current keys:
8888
| `auto_index` | `false` | Automatically index new projects when an MCP session starts. |
8989
| `auto_index_limit` | `50000` | Maximum file count allowed for automatic indexing of a new project. |
9090
| `auto_watch` | `true` | Register the session's project with the background git watcher on connect. Set `false` to keep a session from registering its project (the watcher still runs for other projects). |
91-
| `watcher_enabled` | `true` | Master switch for the background watcher subsystem. Set `false` to stop the watcher from starting at all — no poll thread and no project registration. Reindex manually with `index_repository` when disabled. |
91+
| `watcher_enabled` | `true` | Master switch for the background watcher subsystem. Set `false` to stop the watcher from starting at all — no poll thread and no project registration. Reindex manually with `index_repository` when disabled. Only an open MCP session's own project is ever watched; `index_status` reports the current state in its `watch` object. |
9292
| `watch_non_git` | `false` | Also poll project roots that are **not git repositories**. By default the watcher only follows git projects, so a project indexed from a plain directory is never refreshed after its first index — reindex it manually with `index_repository`. Set `true` to poll such roots on the same adaptive cadence with a file-tree scan: the indexer's own discovery walk (same skip lists, `.gitignore` and `.cbmignore` rules) hashed over each file's path, size and mtime. Any change reindexes once; paths the indexer skips (including cbm's own `.codebase-memory/` output) never trigger. The first poll after the daemon starts reindexes each such project once, since nothing records which tree state the index holds. The scan walks the whole tree every poll, so it costs more than git polling on very large trees. Read once when the daemon starts, like `watcher_enabled`. |
9393
| `index_max_files` | `off` | Optional maximum number of accepted source files in one discovery run. |
9494
| `index_max_source_mb` | `off` | Optional maximum accepted source size in MiB in one discovery run. |
9595

96+
For a watched project, `index_status` names the polling method in `watch.strategy`:
97+
`git` (HEAD and dirty-state polling), `tree` (a non-git root polled by the
98+
`watch_non_git` file-tree scan), `none` (a non-git root that is registered but never
99+
polled, the default for a plain directory) or `pending` (registered; the first poll
100+
has not run yet).
101+
96102
> **`watcher_enabled` vs `auto_watch`.** `watcher_enabled` controls whether the
97103
> watcher *subsystem* starts at all (the background poll thread). `auto_watch` is
98104
> narrower: it only controls whether a connecting session registers *its own*

‎docs/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -728,7 +728,7 @@ <h3>Infrastructure-as-code indexing</h3>
728728
</div>
729729
<div class="feature">
730730
<h3>Auto-sync</h3>
731-
<p>A background watcher detects changes and re-indexes incrementally. No manual reindex after editing files.</p>
731+
<p>A background watcher detects changes in the project your MCP session is working in and re-indexes it incrementally. No manual reindex after editing files there.</p>
732732
</div>
733733
<div class="feature">
734734
<h3>Team-shared graph artifact</h3>

‎src/daemon/application.c‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -565,6 +565,57 @@ static void application_refresh_watch_locked(cbm_daemon_application_session_t *s
565565
session->watch = watch;
566566
}
567567

568+
static const char *application_watch_strategy_name(cbm_watcher_strategy_t strategy) {
569+
switch (strategy) {
570+
case CBM_WATCHER_STRATEGY_GIT:
571+
return "git";
572+
case CBM_WATCHER_STRATEGY_TREE:
573+
return "tree";
574+
case CBM_WATCHER_STRATEGY_NONE:
575+
return "none";
576+
default:
577+
return "pending";
578+
}
579+
}
580+
581+
/* index_status watch visibility (#2167). The physical watcher is the truth for
582+
* "watched"; the reasons explain the documented scope: only an MCP session's
583+
* own project is watched, and only while that session is open. Takes the
584+
* application mutex and the watcher lock one after the other, never nested. */
585+
static void application_watch_status(void *context, const char *project,
586+
cbm_mcp_watch_status_t *out) {
587+
cbm_daemon_application_session_t *session = context;
588+
cbm_daemon_application_t *application = session ? session->application : NULL;
589+
if (!application || !application->watcher) {
590+
out->reason = "watcher_disabled";
591+
return;
592+
}
593+
cbm_watcher_project_info_t info;
594+
if (cbm_watcher_project_info(application->watcher, project, &info)) {
595+
out->watched = true;
596+
out->strategy = application_watch_strategy_name(info.strategy);
597+
out->poll_interval_ms = info.poll_interval_ms;
598+
out->last_scan_unix_s = info.last_scan_unix_s;
599+
return;
600+
}
601+
const char *session_project = cbm_mcp_server_session_project(session->mcp);
602+
if (!session_project || strcmp(session_project, project) != 0) {
603+
out->reason = "not_session_project";
604+
return;
605+
}
606+
if (application->config &&
607+
!cbm_config_get_bool(application->config, CBM_CONFIG_AUTO_WATCH, true)) {
608+
out->reason = "auto_watch_off";
609+
return;
610+
}
611+
/* Only MCP sessions run background initialization; a one-shot CLI command
612+
* never holds a watch across calls. */
613+
cbm_mutex_lock(&application->mutex);
614+
bool mcp_session = session->background_eligible;
615+
cbm_mutex_unlock(&application->mutex);
616+
out->reason = mcp_session ? "not_registered" : "cli_session";
617+
}
618+
568619
static void application_refresh_watch(cbm_daemon_application_session_t *session) {
569620
if (!session || !session->application) {
570621
return;
@@ -2798,6 +2849,7 @@ static cbm_daemon_runtime_application_session_t *application_session_open(
27982849
}
27992850
cbm_mcp_server_set_background_tasks(session->mcp, false);
28002851
cbm_mcp_server_set_config(session->mcp, application->config);
2852+
cbm_mcp_server_set_watch_status_provider(session->mcp, application_watch_status, session);
28012853
cbm_mcp_server_set_index_executor(session->mcp, application_index_execute, session);
28022854
cbm_mcp_server_set_index_status_provider(session->mcp, application_index_status, session);
28032855
cbm_mcp_server_set_project_mutation_guard(session->mcp, application_session_mutation_begin,

‎src/mcp/mcp.c‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -749,8 +749,9 @@ static const tool_def_t TOOLS[] = {
749749
"\"project\"]}"},
750750

751751
{"index_status",
752-
"Project readiness, counts, root, and coverage gaps. diagnostics adds coverage rows; verbose "
753-
"adds Git paths. Best-effort only; verify cited paths with check_index_coverage.",
752+
"Project readiness, counts, root, watch state, and coverage gaps. diagnostics adds coverage "
753+
"rows; verbose adds Git paths. Best-effort only; verify cited paths with "
754+
"check_index_coverage.",
754755
"{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
755756
"\"verbose\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Add worktree/"
756757
"shadow Git paths for index-location debugging.\"},"
@@ -1409,7 +1410,8 @@ static const int SUPPORTED_VERSION_COUNT =
14091410
static const char MCP_SERVER_INSTRUCTIONS[] =
14101411
"Graph first: search_graph for symbols, trace_path for relationships, get_code_snippet for "
14111412
"source, query_graph for multi-hop, and get_architecture for overview. Use search_code/grep "
1412-
"for literals or coverage gaps. Indexes auto-refresh. Check cited-path coverage; paginate.";
1413+
"for literals or coverage gaps. The session project's index auto-refreshes; re-index others. "
1414+
"Check cited-path coverage; paginate.";
14131415

14141416
static const char MCP_ANALYSIS_SERVER_INSTRUCTIONS[] =
14151417
"analysis tool profile: read-only graph work via search_graph, trace_path, "
@@ -1791,6 +1793,9 @@ struct cbm_mcp_server {
17911793
bool background_tasks; /* per-server update/auto-index work enabled */
17921794
struct cbm_watcher *watcher; /* external watcher ref (not owned) */
17931795
struct cbm_config *config; /* external config ref (not owned) */
1796+
/* index_status watch visibility (#2167) */
1797+
cbm_mcp_watch_status_fn watch_status_fn;
1798+
void *watch_status_context;
17941799
cbm_mcp_index_executor_fn index_executor;
17951800
void *index_executor_context;
17961801
cbm_mcp_index_status_fn index_status_provider; /* #2144; NULL outside the daemon */
@@ -1878,6 +1883,14 @@ void cbm_mcp_server_set_watcher(cbm_mcp_server_t *srv, struct cbm_watcher *w) {
18781883
}
18791884
}
18801885

1886+
void cbm_mcp_server_set_watch_status_provider(cbm_mcp_server_t *srv, cbm_mcp_watch_status_fn fn,
1887+
void *context) {
1888+
if (srv) {
1889+
srv->watch_status_fn = fn;
1890+
srv->watch_status_context = context;
1891+
}
1892+
}
1893+
18811894
void cbm_mcp_server_set_config(cbm_mcp_server_t *srv, struct cbm_config *cfg) {
18821895
if (srv) {
18831896
srv->config = cfg;
@@ -6896,6 +6909,40 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
68966909
return result;
68976910
}
68986911

6912+
/* index_status "watch" object (#2167): is this project kept fresh by the
6913+
* background watcher right now, and if not, why. Auto-sync covers the active
6914+
* MCP session's project only; anything else needs index_repository again. */
6915+
static void add_watch_status_json(cbm_mcp_server_t *srv, yyjson_mut_doc *doc, yyjson_mut_val *root,
6916+
const char *project) {
6917+
cbm_mcp_watch_status_t status = {0};
6918+
if (srv->watch_status_fn) {
6919+
srv->watch_status_fn(srv->watch_status_context, project, &status);
6920+
} else {
6921+
status.reason = "no_watcher";
6922+
}
6923+
yyjson_mut_val *watch = yyjson_mut_obj(doc);
6924+
yyjson_mut_obj_add_bool(doc, watch, "watched", status.watched);
6925+
if (status.watched) {
6926+
yyjson_mut_obj_add_str(doc, watch, "strategy", status.strategy ? status.strategy : "");
6927+
yyjson_mut_obj_add_int(doc, watch, "poll_interval_ms", status.poll_interval_ms);
6928+
if (status.last_scan_unix_s > 0) {
6929+
char when[CBM_SZ_32];
6930+
time_t t = (time_t)status.last_scan_unix_s;
6931+
struct tm tm;
6932+
cbm_gmtime_r(&t, &tm);
6933+
if (strftime(when, sizeof(when), "%Y-%m-%dT%H:%M:%SZ", &tm) > 0) {
6934+
yyjson_mut_obj_add_strcpy(doc, watch, "last_scan_at", when);
6935+
}
6936+
}
6937+
} else {
6938+
yyjson_mut_obj_add_str(doc, watch, "reason", status.reason ? status.reason : "unknown");
6939+
yyjson_mut_obj_add_str(doc, watch, "hint",
6940+
"Auto-sync watches only the active MCP session's project; "
6941+
"re-run index_repository to refresh this index.");
6942+
}
6943+
yyjson_mut_obj_add_val(doc, root, "watch", watch);
6944+
}
6945+
68996946
static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
69006947
char *project = get_project_arg(args);
69016948
cbm_store_t *store = resolve_store(srv, project);
@@ -6967,6 +7014,7 @@ static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
69677014
doc, root, "hint",
69687015
"Project is empty. Re-run index_repository(repo_path=...) to populate.");
69697016
}
7017+
add_watch_status_json(srv, doc, root, project);
69707018
} else {
69717019
yyjson_mut_obj_add_str(doc, root, "status", "no_project");
69727020
}

‎src/mcp/mcp.h‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,22 @@ void cbm_mcp_server_free(cbm_mcp_server_t *srv);
179179
/* Set external watcher reference (for auto-index registration). Not owned. */
180180
void cbm_mcp_server_set_watcher(cbm_mcp_server_t *srv, struct cbm_watcher *w);
181181

182+
/* Watch visibility for index_status (#2167). The daemon, which owns the one
183+
* background watcher, answers whether `project` is currently watched. All
184+
* strings are static. A server without a provider runs no watcher at all and
185+
* reports watched=false with reason "no_watcher". */
186+
typedef struct {
187+
bool watched;
188+
const char *reason; /* why not watched (set when !watched) */
189+
const char *strategy; /* "pending" | "git" | "tree" | "none" (set when watched) */
190+
int poll_interval_ms; /* current adaptive cadence (when watched) */
191+
int64_t last_scan_unix_s; /* last completed scan, wall clock; 0 = none yet */
192+
} cbm_mcp_watch_status_t;
193+
typedef void (*cbm_mcp_watch_status_fn)(void *context, const char *project,
194+
cbm_mcp_watch_status_t *out);
195+
void cbm_mcp_server_set_watch_status_provider(cbm_mcp_server_t *srv, cbm_mcp_watch_status_fn fn,
196+
void *context);
197+
182198
/* Set external config store reference (for auto_index setting). Not owned. */
183199
void cbm_mcp_server_set_config(cbm_mcp_server_t *srv, struct cbm_config *cfg);
184200

‎src/watcher/watcher.c‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,12 @@ typedef struct {
9999
* from `rev-parse --show-cdup`. Porcelain paths are repository-relative, so
100100
* the signature needs this to stat them. Resolved once at baseline. */
101101
char repo_cdup[CBM_SZ_4K];
102+
/* Published status for cbm_watcher_project_info (#2167). The poll path
103+
* writes these while index_status reads them from a session thread, so
104+
* they are atomics: the diagnostic read is never a data race. */
105+
atomic_int status_strategy; /* cbm_watcher_strategy_t */
106+
atomic_int status_interval_ms; /* mirrors interval_ms */
107+
_Atomic int64_t status_last_scan_s; /* wall-clock seconds; 0 = none yet */
102108
} project_state_t;
103109

104110
/* ── Watcher struct ─────────────────────────────────────────────── */
@@ -922,6 +928,9 @@ static project_state_t *state_new(const char *name, const char *root_path) {
922928
}
923929
atomic_init(&s->registered, true);
924930
s->interval_ms = POLL_BASE_MS;
931+
atomic_init(&s->status_strategy, CBM_WATCHER_STRATEGY_PENDING);
932+
atomic_init(&s->status_interval_ms, POLL_BASE_MS);
933+
atomic_init(&s->status_last_scan_s, 0);
925934
return s;
926935
}
927936

@@ -1262,6 +1271,25 @@ int cbm_watcher_index_failure_count(cbm_watcher_t *w, const char *project_name)
12621271
return failures;
12631272
}
12641273

1274+
bool cbm_watcher_project_info(cbm_watcher_t *w, const char *project_name,
1275+
cbm_watcher_project_info_t *out) {
1276+
if (out) {
1277+
memset(out, 0, sizeof(*out));
1278+
}
1279+
if (!w || !project_name || !out) {
1280+
return false;
1281+
}
1282+
cbm_mutex_lock(&w->projects_lock);
1283+
project_state_t *s = cbm_ht_get(w->projects, project_name);
1284+
if (s) {
1285+
out->strategy = (cbm_watcher_strategy_t)atomic_load(&s->status_strategy);
1286+
out->poll_interval_ms = atomic_load(&s->status_interval_ms);
1287+
out->last_scan_unix_s = atomic_load(&s->status_last_scan_s);
1288+
}
1289+
cbm_mutex_unlock(&w->projects_lock);
1290+
return s != NULL;
1291+
}
1292+
12651293
int cbm_watcher_watch_count(cbm_watcher_t *w) {
12661294
if (!w) {
12671295
return 0;
@@ -1274,13 +1302,31 @@ int cbm_watcher_watch_count(cbm_watcher_t *w) {
12741302

12751303
/* ── Single poll cycle ──────────────────────────────────────────── */
12761304

1305+
/* Publish what index_status reports: the strategy, the current cadence and,
1306+
* when a check just completed, the wall-clock time of that scan. A non-git
1307+
* root is "tree" when watch_non_git polls it (#1948), else "none". */
1308+
static void publish_status(project_state_t *s, bool scanned) {
1309+
cbm_watcher_strategy_t strategy = CBM_WATCHER_STRATEGY_NONE;
1310+
if (s->is_git) {
1311+
strategy = CBM_WATCHER_STRATEGY_GIT;
1312+
} else if (s->tree_poll) {
1313+
strategy = CBM_WATCHER_STRATEGY_TREE;
1314+
}
1315+
atomic_store(&s->status_strategy, strategy);
1316+
atomic_store(&s->status_interval_ms, s->interval_ms);
1317+
if (scanned) {
1318+
atomic_store(&s->status_last_scan_s, (int64_t)time(NULL));
1319+
}
1320+
}
1321+
12771322
/* Init baseline for a project: check if git, get HEAD, count files */
12781323
static bool init_baseline(cbm_watcher_t *w, project_state_t *s) {
12791324
struct stat st;
12801325
if (stat(s->root_path, &st) != 0) {
12811326
cbm_log_warn("watcher.root_gone", "project", s->project_name, "path", s->root_path);
12821327
s->baseline_done = true;
12831328
s->is_git = false;
1329+
publish_status(s, false);
12841330
return true;
12851331
}
12861332

@@ -1358,6 +1404,7 @@ static bool init_baseline(cbm_watcher_t *w, project_state_t *s) {
13581404
}
13591405

13601406
s->next_poll_ns = now_ns() + ((int64_t)s->interval_ms * US_PER_MS);
1407+
publish_status(s, true);
13611408
return true;
13621409
}
13631410

@@ -1524,6 +1571,7 @@ static void commit_baselines(cbm_watcher_t *w, project_state_t *s) {
15241571
if (git_file_count(w, s, &file_count) == WATCHER_GIT_OK) {
15251572
s->file_count = file_count;
15261573
s->interval_ms = cbm_watcher_poll_interval_ms(s->file_count);
1574+
publish_status(s, false);
15271575
}
15281576
}
15291577

@@ -1595,6 +1643,7 @@ static void poll_project(const char *key, void *val, void *ud) {
15951643
if (!check_changes(ctx->w, s, &changed)) {
15961644
return;
15971645
}
1646+
publish_status(s, true);
15981647
if (!changed) {
15991648
s->next_poll_ns = ctx->now + ((int64_t)s->interval_ms * US_PER_MS);
16001649
return;

0 commit comments

Comments
 (0)