Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

fix(watcher): pace re-indexes by the cost of the last successful run

Shane McCarron5c54201ef8ed
diff --git a/src/watcher/watcher.c b/src/watcher/watcher.c
index ac7c47b7f..cef4fd482 100644
--- a/src/watcher/watcher.c
+++ b/src/watcher/watcher.c
@@ -154,6 +154,16 @@ struct cbm_watcher {
* daemon log names the stuck project instead of only repeating the warning. */
#define INDEX_FAIL_SUSTAINED 10
+/* Success cooldown (#2835): after a successful re-index the next poll waits
+ * at least INDEX_COOLDOWN_FACTOR x the index's own duration, counted from when
+ * the index finished, so the watcher spends at most ~1/(K+1) of wall time
+ * indexing one project — a 5-minute rebuild idles 15 minutes. Sub-second
+ * indexes stay at the plain cadence. The ceiling bounds staleness after one
+ * pathological run; it is NOT INDEX_FAIL_CEILING_MS (5 min), which would cut
+ * the cooldown of any rebuild over 100 s below K x its duration. */
+#define INDEX_COOLDOWN_FACTOR 3
+#define INDEX_COOLDOWN_CEILING_MS 1800000 /* 30 min */
+
/* Stale-root pruning (#286): a watched project whose root directory stays
* missing is pruned — its cached DB is deleted and the watch entry removed.
* Deletion is destructive (the DB can hold user-authored data such as the
@@ -204,6 +214,20 @@ int cbm_watcher_index_backoff_ms(int interval_ms, int consecutive_failures) {
return (int)(delay < interval_ms ? interval_ms : delay);
}
+int cbm_watcher_success_delay_ms(int interval_ms, int64_t index_elapsed_ms) {
+ if (interval_ms < 0) {
+ interval_ms = 0;
+ }
+ if (index_elapsed_ms <= 0) {
+ return interval_ms;
+ }
+ /* Divide instead of multiply so a huge elapsed cannot overflow. */
+ int64_t cooldown = index_elapsed_ms > INDEX_COOLDOWN_CEILING_MS / INDEX_COOLDOWN_FACTOR
+ ? INDEX_COOLDOWN_CEILING_MS
+ : index_elapsed_ms * INDEX_COOLDOWN_FACTOR;
+ return (int)(cooldown > interval_ms ? cooldown : interval_ms);
+}
+
int cbm_watcher_poll_interval_ms(int file_count) {
int ms = POLL_BASE_MS + ((file_count / POLL_FILE_STEP) * CBM_MSEC_PER_SEC);
if (ms > POLL_MAX_MS) {
@@ -1693,12 +1717,22 @@ static void poll_project(const char *key, void *val, void *ud) {
}
cbm_log_info("watcher.changed", "project", s->project_name, "strategy",
s->is_git ? "git" : "tree");
+ int delay_ms = -1; /* < 0: use the failure-backoff cadence below */
+ int64_t anchor_ns = ctx->now; /* success re-anchors to when the index finished */
if (ctx->w->index_fn) {
+ int64_t index_start = now_ns();
int rc = ctx->w->index_fn(s->project_name, s->root_path, ctx->w->user_data);
if (rc == 0) {
ctx->reindexed++;
s->index_failures = 0;
commit_baselines(ctx->w, s);
+ anchor_ns = now_ns();
+ delay_ms =
+ cbm_watcher_success_delay_ms(s->interval_ms, (anchor_ns - index_start) / US_PER_MS);
+ if (delay_ms > s->interval_ms) {
+ cbm_log_info("watcher.cooldown", "project", s->project_name, "delay_ms",
+ itoa_buf(delay_ms));
+ }
} else if (rc > 0) {
/* Busy-skip: baseline stays uncommitted, next poll retries. */
cbm_log_info("watcher.index.retry", "project", s->project_name);
@@ -1721,10 +1755,12 @@ static void poll_project(const char *key, void *val, void *ud) {
}
}
- /* Failures back off; success and busy-skip keep the adaptive cadence. */
- s->next_poll_ns =
- ctx->now +
- ((int64_t)cbm_watcher_index_backoff_ms(s->interval_ms, s->index_failures) * US_PER_MS);
+ /* Success pays back the index's cost; failures back off; busy-skip keeps
+ * the adaptive cadence. */
+ if (delay_ms < 0) {
+ delay_ms = cbm_watcher_index_backoff_ms(s->interval_ms, s->index_failures);
+ }
+ s->next_poll_ns = anchor_ns + ((int64_t)delay_ms * US_PER_MS);
}
/* Callback to snapshot project state pointers into an array. */
diff --git a/src/watcher/watcher.h b/src/watcher/watcher.h
index 2986cb57d..eb7e92915 100644
--- a/src/watcher/watcher.h
+++ b/src/watcher/watcher.h
@@ -195,6 +195,15 @@ int cbm_watcher_poll_interval_ms(int file_count);
* Negative inputs are treated as zero. */
int cbm_watcher_index_backoff_ms(int interval_ms, int consecutive_failures);
+/* Return the delay (ms) before the next poll after a SUCCESSFUL re-index that
+ * took `index_elapsed_ms`: max(interval_ms, INDEX_COOLDOWN_FACTOR (3) x
+ * index_elapsed_ms), with the cooldown term capped at INDEX_COOLDOWN_CEILING_MS
+ * (30 min). The caller counts it from when the index finished, so the watcher
+ * spends at most ~1/4 of wall time indexing a project; sub-second indexes keep
+ * `interval_ms`.
+ * Never below `interval_ms`; overflow-safe; negative inputs act as zero. */
+int cbm_watcher_success_delay_ms(int interval_ms, int64_t index_elapsed_ms);
+
/* Classify a stat() errno observed on a watched project root: returns true
* only for values that mean the root itself is gone (ENOENT, ENOTDIR) and
* may count toward stale-root pruning (#286). Any other failure (EACCES,
diff --git a/tests/test_watcher.c b/tests/test_watcher.c
index 8be483ca8..c2796e3a6 100644
--- a/tests/test_watcher.c
+++ b/tests/test_watcher.c
@@ -2260,6 +2260,124 @@ TEST(watcher_sustained_failure_logs_once_issue2015) {
PASS();
}
+/* ── Success cooldown (#2835) ─────────────────────────────────────── */
+
+TEST(success_delay_fast_index_keeps_interval) {
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, 0), 5000);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, 1), 5000);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, 1666), 5000); /* 3x < interval */
+ ASSERT_EQ(cbm_watcher_success_delay_ms(60000, 20000), 60000);
+ PASS();
+}
+
+TEST(success_delay_slow_index_scales_by_factor) {
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, 1667), 5001);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, 10000), 30000);
+ /* 5-minute rebuild → next poll 15 min after it finishes. */
+ ASSERT_EQ(cbm_watcher_success_delay_ms(60000, 300000), 900000);
+ PASS();
+}
+
+TEST(success_delay_clamped_and_degenerate) {
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, 600000), 1800000);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, 600001), 1800000);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, INT64_MAX), 1800000);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, -1), 5000);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(5000, INT64_MIN), 5000);
+ ASSERT_EQ(cbm_watcher_success_delay_ms(-1, 0), 0);
+ /* Never below the caller's own cadence, even above the ceiling. */
+ ASSERT_EQ(cbm_watcher_success_delay_ms(INT_MAX, INT64_MAX), INT_MAX);
+ PASS();
+}
+
+TEST(success_delay_is_monotonic) {
+ int previous = cbm_watcher_success_delay_ms(5000, 0);
+ for (int64_t e = 0; e <= 2000000; e += 997) {
+ int delay = cbm_watcher_success_delay_ms(5000, e);
+ ASSERT_TRUE(delay >= previous);
+ ASSERT_TRUE(delay >= 5000 && delay <= 1800000);
+ previous = delay;
+ }
+ PASS();
+}
+
+/* Wire-up: the cooldown must be measured around the real index_fn call. An
+ * instant callback keeps the plain cadence (no cooldown line); a callback
+ * slower than interval/3 (5000/3 ms) extends it and logs once. */
+static int cooldown_log_hits = 0;
+static void cooldown_log_sink(const char *line) {
+ if (line && strstr(line, "watcher.cooldown") != NULL) {
+ cooldown_log_hits++;
+ }
+}
+static int slow_index_sleep_ms = 0;
+static int slow_index_calls = 0;
+static int slow_index_callback(const char *name, const char *path, void *ud) {
+ (void)name;
+ (void)path;
+ (void)ud;
+ slow_index_calls++;
+ if (slow_index_sleep_ms > 0) {
+ cbm_usleep((unsigned)slow_index_sleep_ms * 1000U);
+ }
+ return 0;
+}
+
+TEST(watcher_success_cooldown_measures_index_issue2835) {
+ char tmpdir[256];
+ snprintf(tmpdir, sizeof(tmpdir), "/tmp/cbm_watcher_cool_XXXXXX");
+ if (!cbm_mkdtemp(tmpdir))
+ FAIL("cbm_mkdtemp failed");
+ if (wt_git(tmpdir, "init -q") != 0) {
+ th_rmtree(tmpdir);
+ FAIL("git init failed");
+ }
+ char p[300];
+ th_write_file(wt_path(p, sizeof(p), tmpdir, "file.txt"), "hello\n");
+ wt_git(tmpdir, "add file.txt");
+ wt_git(tmpdir, "commit -q -m init");
+
+ cbm_store_t *store = cbm_store_open_memory();
+ cbm_watcher_t *w = cbm_watcher_new(store, slow_index_callback, NULL);
+ cbm_watcher_watch(w, "cool-repo", tmpdir);
+ slow_index_calls = 0;
+ slow_index_sleep_ms = 0;
+ cbm_watcher_poll_once(w); /* baseline */
+
+ CBMLogLevel old_level = cbm_log_get_level();
+ cbm_log_set_level(CBM_LOG_INFO);
+ cooldown_log_hits = 0;
+ cbm_log_set_sink(cooldown_log_sink);
+
+ /* Instant index: no cooldown. Loop on the attempt count (a transient git
+ * probe failure makes a poll a no-op, see the sustained-failure test). */
+ th_append_file(wt_path(p, sizeof(p), tmpdir, "file.txt"), "a\n");
+ while (slow_index_calls < 1) {
+ cbm_watcher_touch(w, "cool-repo");
+ cbm_watcher_poll_once(w);
+ }
+ int fast_hits = cooldown_log_hits;
+
+ /* 1.8 s index → 3 x 1800 = 5400 ms > 5000 ms interval: cooldown. */
+ slow_index_sleep_ms = 1800;
+ th_append_file(wt_path(p, sizeof(p), tmpdir, "file.txt"), "b\n");
+ while (slow_index_calls < 2) {
+ cbm_watcher_touch(w, "cool-repo");
+ cbm_watcher_poll_once(w);
+ }
+
+ cbm_log_set_sink(NULL);
+ cbm_log_set_level(old_level);
+
+ ASSERT_EQ(fast_hits, 0);
+ ASSERT_EQ(cooldown_log_hits, 1);
+
+ cbm_watcher_free(w);
+ cbm_store_close(store);
+ th_rmtree(tmpdir);
+ PASS();
+}
+
TEST(watcher_index_failure_count_unknown_project) {
cbm_store_t *store = cbm_store_open_memory();
cbm_watcher_t *w = cbm_watcher_new(store, index_callback, NULL);
@@ -4043,6 +4161,11 @@ SUITE(watcher) {
RUN_TEST(index_backoff_never_schedules_sooner_than_the_interval);
RUN_TEST(watcher_index_failure_streak_increments_and_resets_issue2015);
RUN_TEST(watcher_index_failure_backoff_gates_repolling_issue2015);
+ RUN_TEST(success_delay_fast_index_keeps_interval);
+ RUN_TEST(success_delay_slow_index_scales_by_factor);
+ RUN_TEST(success_delay_clamped_and_degenerate);
+ RUN_TEST(success_delay_is_monotonic);
+ RUN_TEST(watcher_success_cooldown_measures_index_issue2835);
RUN_TEST(watcher_sustained_failure_logs_once_issue2015);
RUN_TEST(watcher_index_failure_count_unknown_project);
RUN_TEST(watcher_project_info_publishes_scan_issue2167);