feat(index): add opt-in index resource profiles

Six independent keys are an honest interface and a poor default. An operator
who only wants indexing to stay within reason has to learn all six, choose a
value for each, and keep them consistent as the machine changes.

Add index_resource_profile, accepting off, balanced or strict. Balanced
guards the host: it lets an index use what the machine can spare and stops a
runaway worker before the host is exhausted. Strict holds indexing to the
daemon's own budget, so a repository that needs more fails fast and
attributed instead of finishing at the host's expense. Any individual key,
including an explicit off, replaces that dimension of the selected profile,
so a profile is a baseline rather than a lock.

The balanced worker ceiling is derived from detected host memory instead of
being tabled. Large-repository indexing peaks in the tens of gigabytes, so
any round number low enough to feel safe would reject repositories that index
successfully today. When host memory cannot be read, balanced falls back to a
fixed floor.

Profiles also bound directory count, entry count, traversal depth and
discovery time. These have no individual keys for the same reason as the
storage internals: they are only meaningful inside a composed decision. The
resolved profile travels through the same trusted worker contract as the
individual limits, so every entry point enforces the same decision.

That contract now also carries the resolved profile and the override mask, so
the shell fixture standing in for the supervisor sends both.

The coverage that proves a forged policy cannot fork a second job asserts
that an explicit request joins the auto-index job already running for the
same root, and that assertion found the join broken on Windows. A project
root reaches the daemon through the platform canonicalizer, which answers in
backslash form there, while every tool handler normalizes the separators of
the path it canonicalizes. One directory therefore had two spellings, and
they met in comparisons that are exact: whether an index request may join the
running job, and whether a watch is still live for that root. Both were
wrong on Windows, in opposite directions, so aligning either one alone moved
the failure rather than removing it. The session context now stores the
normalized spelling, and the daemon canonicalizes project roots through a
single function that normalizes on the way out.

Only the storage side is directly assertable off Windows, since separators
are folded on every platform; the watch-liveness side is held by the existing
watcher-ownership tests, which is where the second half of this surfaced.

Signed-off-by: 刘冲 <mail@liuchong.dev>

Author: liuchong

README.md

@@ -728,6 +728,7 @@ codebase-memory-mcp config set auto_index true           # auto-index on session
 codebase-memory-mcp config set auto_index_limit 50000    # max files for auto-index
 codebase-memory-mcp config set auto_watch false          # don't register background git watcher (default: true)
 codebase-memory-mcp config set watcher_enabled false     # stop the watcher thread entirely (default: true)
+codebase-memory-mcp config set index_resource_profile balanced # opt-in composed resource limits
 codebase-memory-mcp config set index_max_files 250000    # optional per-index source-file limit
 codebase-memory-mcp config set index_max_source_mb 16384 # optional per-index source-size limit
 codebase-memory-mcp config set index_max_rss_mb 8192     # optional worker-tree current RSS limit
@@ -737,10 +738,13 @@ codebase-memory-mcp config set index_min_free_disk_mb 4096 # optional free-space
 codebase-memory-mcp config reset auto_index              # reset to default
 ```
 
-The six index resource settings default to `off`. Exceeding one fails the
-complete index attempt rather than publishing a partial graph; an existing
-serving index is preserved. Storage probes also fail closed when an enabled
-measurement cannot be completed. See
+`index_resource_profile` defaults to `off` and accepts `off`, `balanced`, or
+`strict`. The six individual resource settings also default to `off`; an
+explicit value, including `off`, replaces that dimension of a selected
+profile. Exceeding an effective limit fails the complete index attempt rather
+than publishing a partial graph, and an existing serving index is preserved.
+Storage probes also fail closed when an enabled measurement cannot be
+completed. See
 [Index resource limits](docs/INDEX_RESOURCE_LIMITS.md).
 
 ### Environment Variables

docs/CONFIGURATION.md

@@ -89,6 +89,7 @@ Current keys:
 | `auto_index_limit` | `50000` | Maximum file count allowed for automatic indexing of a new project. |
 | `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). |
 | `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. |
+| `index_resource_profile` | `off` | Composed index resource baseline: `off`, `balanced`, or `strict`. |
 | `index_max_files` | `off` | Optional maximum number of accepted source files in one discovery run. |
 | `index_max_source_mb` | `off` | Optional maximum accepted source size in MiB in one discovery run. |
 | `index_max_rss_mb` | `off` | Optional maximum current RSS in MiB for the complete contained index-worker process tree (`64..1048576`). |
@@ -122,8 +123,12 @@ Current keys:
 > `auto_index` still runs, and `index_repository` stays available for manual
 > reindexing.
 
-The six index resource settings are independent and disabled by default.
-They apply to explicit indexing, automatic indexing, and watcher re-indexing,
+The profile and all six individual resource settings are disabled by default.
+An individual stored value replaces its profile dimension; storing `off`
+disables only that dimension. Profile-only limits also bound traversed
+directories, directory entries, depth, discovery time, final database size,
+staging size, and task temporary size. Effective limits apply to explicit
+indexing, automatic indexing, and watcher re-indexing,
 but not to `cross-repo-intelligence`, which does not scan or publish repository
 source indexes. Equality is allowed; exceeding a setting fails the complete
 index request and preserves any previously serving database. Worker RSS covers

docs/INDEX_RESOURCE_LIMITS.md

@@ -4,6 +4,51 @@ Index resource limits are optional operator controls for repositories whose
 discovery breadth or worker runtime is not known in advance. They are disabled
 by default so existing large-repository workloads retain their current behavior.
 
+## Resource profiles
+
+`index_resource_profile` accepts `off`, `balanced`, or `strict` and defaults to
+`off`. A profile supplies a baseline; each explicitly stored individual
+resource key then replaces its dimension. An explicit `off` disables only that
+dimension.
+
+| Dimension | `balanced` | `strict` |
+|---|---:|---:|
+| Accepted files | 500,000 | 100,000 |
+| Traversed directories | 250,000 | 20,000 |
+| Directory entries | 2,000,000 | 500,000 |
+| Directory depth | 128 | 64 |
+| Accepted source | 65,536 MiB | 4,096 MiB |
+| Discovery duration | 1,800 seconds | 30 seconds |
+| Worker duration | 7,200 seconds | 3,600 seconds |
+| Final database | 65,536 MiB | 16,384 MiB |
+| Staging artifacts | 81,920 MiB | 20,480 MiB |
+| Task temporary artifacts | 98,304 MiB | 24,576 MiB |
+| Projected cache | 131,072 MiB | 32,768 MiB |
+| Free-disk reserve | 4,096 MiB | 4,096 MiB |
+
+The two profiles answer different questions about worker memory, so their RSS
+ceilings are derived rather than tabled.
+
+Balanced protects the host. Its ceiling is 80% of detected host memory, which
+leaves an index free to use everything this machine can spare and still stops a
+runaway worker before the host is exhausted. A fixed number is deliberately not
+used here: large-repository indexing peaks in the tens of gigabytes, so any
+round ceiling low enough to feel safe would reject repositories that index
+successfully with the profile off. When host memory cannot be read, balanced
+falls back to the higher of twice the worker soft budget or 8,192 MiB.
+
+Strict protects the budget. Its ceiling is the lower of the worker soft budget
+and 8,192 MiB, which is the point of the profile: a repository that needs more
+memory than the daemon budgets for itself fails fast with an attributed
+`rss_bytes` violation instead of completing at the host's expense. On a large
+repository this is expected to fail, and the failure names the limit and the
+observed value so the operator can choose `balanced`, raise
+`index_max_rss_mb`, or leave the profile `off`.
+
+Both derived values are held inside the same 64 to 1,048,576 MiB range that
+`index_max_rss_mb` accepts, and detected host memory can lower but never raise
+an explicitly configured `index_max_rss_mb`.
+
 ## Discovery settings
 
 | Key | Default | Accepted value | Protects |
@@ -63,6 +108,12 @@ rules, filename and suffix filters, language detection, and the existing
 per-file size rule. `index_max_source_mb` sums the filesystem sizes of that same
 accepted set.
 
+Profile directory counting includes the request root and each non-skipped
+directory admitted for traversal. Entry counting happens before ignore,
+language, and file-size filtering. Root depth is zero. The monotonic discovery
+deadline is checked before opening a directory and before processing each
+entry. Equality is allowed for every dimension.
+
 Equality is allowed. The first file or byte that makes an observed value greater
 than its limit stops discovery. CBM discards the partial file list and does not
 publish a partial graph as a complete index.

scripts/test-runtime.sh

@@ -109,10 +109,13 @@ _cbm_test_runtime_daemon() {
 # worker in argv; a worker that finds no complete policy refuses to start rather
 # than index unbounded. A shell test that spawns `cli --index-worker` itself
 # stands in for the supervisor and owes the worker the same object. Mirrors
-# cbm_mcp_index_policy_add_to_args: every key in cbm_index_policy_key_at, and
-# nothing else.
+# cbm_mcp_index_policy_add_to_args: the resolved profile, the override mask
+# that says which keys the operator set by hand, every key in
+# cbm_index_policy_key_at, and nothing else.
 cbm_test_index_worker_policy_json() {
-    printf '%s' '"_cbm_index_policy":{"index_max_files":"off","index_max_source_mb":"off"'
+    printf '%s' '"_cbm_index_policy":{"index_resource_profile":"off"'
+    printf '%s' ',"_cbm_index_override_mask":0'
+    printf '%s' ',"index_max_files":"off","index_max_source_mb":"off"'
     printf '%s' ',"index_max_rss_mb":"off","index_max_duration_seconds":"off"'
     printf '%s' ',"index_cache_max_mb":"off","index_min_free_disk_mb":"off"}'
 }

src/cli/cli.c

@@ -21,6 +21,7 @@
 #include "foundation/platform.h"
 #include "foundation/constants.h"
 #include "foundation/log.h"
+#include "foundation/mem.h"
 #include "foundation/sha256.h"
 #include "cli/client_adapter.h"
 #include "mcp/mcp.h" // cbm_mcp_tool_input_schema — CLI flag parser + per-tool --help
@@ -7016,13 +7017,19 @@ bool cbm_config_load_index_policy(cbm_config_t *cfg, cbm_index_resource_policy_t
         return false;
     }
     cbm_index_policy_init(policy);
+    const char *profile = cbm_config_get(cfg, CBM_INDEX_CONFIG_RESOURCE_PROFILE, "off");
+    if (!cbm_index_policy_set_profile(policy, profile, error, error_size)) {
+        return false;
+    }
     for (size_t index = 0; index < cbm_index_policy_key_count(); index++) {
         const char *key = cbm_index_policy_key_at(index);
-        const char *value = cbm_config_get(cfg, key, cbm_index_policy_default_value(key));
-        if (!cbm_index_policy_set(policy, key, value, error, error_size)) {
+        const char *value = cbm_config_get(cfg, key, NULL);
+        if (value && !cbm_index_policy_set(policy, key, value, error, error_size)) {
             return false;
         }
     }
+    cbm_system_info_t system = cbm_system_info();
+    cbm_index_policy_finalize(policy, (uint64_t)system.total_ram, (uint64_t)cbm_mem_budget());
     return true;
 }
 
@@ -7050,6 +7057,7 @@ static const config_key_def_t CONFIG_KEYS[] = {
     {CBM_CONFIG_UI_LANG, "auto", "Pin graph UI language: en, zh, or auto"},
     {CBM_CONFIG_UI_ENABLED, "false", "Serve the graph UI on a loopback HTTP port"},
     {CBM_CONFIG_UI_PORT, "9749", "Port for the graph UI listener when enabled"},
+    {CBM_INDEX_CONFIG_RESOURCE_PROFILE, "off", "Index resource profile: off, balanced, or strict"},
     {CBM_INDEX_CONFIG_MAX_FILES, "off", "Max accepted source files per index, or off"},
     {CBM_INDEX_CONFIG_MAX_SOURCE_MB, "off", "Max accepted source MiB per index, or off"},
     {CBM_INDEX_CONFIG_MAX_RSS_MB, "off", "Max worker process-tree RSS MiB, or off"},
@@ -7083,19 +7091,17 @@ static bool config_key_is_ui(const char *key) {
 }
 
 static bool config_key_is_index_policy(const char *key) {
-    for (size_t index = 0; key && index < cbm_index_policy_key_count(); index++) {
-        if (strcmp(key, cbm_index_policy_key_at(index)) == 0) {
-            return true;
-        }
-    }
-    return false;
+    return cbm_index_policy_is_config_key(key);
 }
 
 static int config_index_policy_write(cbm_config_t *config, const char *key, const char *value) {
     cbm_index_resource_policy_t candidate;
     cbm_index_policy_init(&candidate);
     char error[CLI_BUF_256];
-    if (!cbm_index_policy_set(&candidate, key, value, error, sizeof(error))) {
+    bool valid = strcmp(key, CBM_INDEX_CONFIG_RESOURCE_PROFILE) == 0
+                     ? cbm_index_policy_set_profile(&candidate, value, error, sizeof(error))
+                     : cbm_index_policy_set(&candidate, key, value, error, sizeof(error));
+    if (!valid) {
         (void)fprintf(stderr, "error: %s\n", error);
         return CLI_ERR;
     }

src/daemon/application.c

@@ -1999,9 +1999,32 @@ static bool application_index_args_add_policy(cbm_daemon_application_t *applicat
         cbm_log_error("daemon.index.policy", "error", error);
         return false;
     }
+    cbm_system_info_t system = cbm_system_info();
+    cbm_index_policy_finalize(&policy, (uint64_t)system.total_ram,
+                              application ? (uint64_t)application->worker_memory_budget_bytes : 0);
     return cbm_mcp_index_policy_add_to_args(document, root, &policy);
 }
 
+static char *application_index_args_replace_policy(cbm_daemon_application_t *application,
+                                                   const char *args_json) {
+    yyjson_doc *source = args_json ? yyjson_read(args_json, strlen(args_json), 0) : NULL;
+    yyjson_mut_doc *document = source ? yyjson_doc_mut_copy(source, NULL) : NULL;
+    yyjson_doc_free(source);
+    yyjson_mut_val *root = document ? yyjson_mut_doc_get_root(document) : NULL;
+    if (!root || !yyjson_mut_is_obj(root)) {
+        yyjson_mut_doc_free(document);
+        return NULL;
+    }
+    while (yyjson_mut_obj_get(root, "_cbm_index_policy")) {
+        (void)yyjson_mut_obj_remove_key(root, "_cbm_index_policy");
+    }
+    char *rewritten = application_index_args_add_policy(application, document, root)
+                          ? yyjson_mut_write(document, 0, NULL)
+                          : NULL;
+    yyjson_mut_doc_free(document);
+    return rewritten;
+}
+
 static char *application_auto_index_args(cbm_daemon_application_t *application,
                                          const char *root_path) {
     yyjson_mut_doc *document = yyjson_mut_doc_new(NULL);
@@ -2286,14 +2309,19 @@ static char *application_index_execute(void *context, const char *root_path,
     if (!session || !root_path || !args_json) {
         return NULL;
     }
-    char *project_key = application_index_project_key(root_path, args_json);
+    char *trusted_args = application_index_args_replace_policy(session->application, args_json);
+    if (!trusted_args) {
+        return cbm_mcp_text_result("failed to resolve daemon index resource policy", true);
+    }
+    char *project_key = application_index_project_key(root_path, trusted_args);
     if (!project_key) {
+        free(trusted_args);
         return cbm_mcp_text_result("failed to derive index project identity", true);
     }
     application_job_subscribe_status_t subscribe_status = APPLICATION_JOB_SUBSCRIBE_UNAVAILABLE;
     cbm_daemon_application_job_t *job = NULL;
     for (;;) {
-        job = application_job_subscribe(session->application, project_key, root_path, args_json,
+        job = application_job_subscribe(session->application, project_key, root_path, trusted_args,
                                         &subscribe_status);
         if (job || (subscribe_status != APPLICATION_JOB_SUBSCRIBE_BUSY &&
                     subscribe_status != APPLICATION_JOB_SUBSCRIBE_CANCELLING)) {
@@ -2312,11 +2340,13 @@ static char *application_index_execute(void *context, const char *root_path,
         cbm_mutex_unlock(&session->application->mutex);
         if (queued_cancelled) {
             free(project_key);
+            free(trusted_args);
             return cbm_mcp_text_result("index operation cancelled for this session", true);
         }
         cbm_usleep(APPLICATION_JOB_POLL_US);
     }
     free(project_key);
+    free(trusted_args);
     if (!job) {
         const char *message = "daemon index coordinator is stopping or unavailable";
         if (subscribe_status == APPLICATION_JOB_SUBSCRIBE_OPTIONS_CONFLICT) {
@@ -2430,7 +2460,8 @@ static cbm_daemon_runtime_application_status_t application_set_context(
     char canonical_allowed[APPLICATION_PATH_CAP] = {0};
     bool canonical = cbm_canonical_path(root, canonical_root, sizeof(canonical_root));
     if (canonical && allowed_present) {
-        canonical = cbm_canonical_path(allowed, canonical_allowed, sizeof(canonical_allowed));
+        canonical =
+            cbm_canonical_path(allowed, canonical_allowed, sizeof(canonical_allowed));
     }
     canonical = canonical && application_canonical_directory_exists(canonical_root);
     bool set =