feat(platform): CBM_WORKERS env override for cbm_default_worker_count

[yangsec888]

What

Adds a single env-knob, CBM_WORKERS, that explicitly sets the
worker count returned by cbm_default_worker_count(). When unset,
behaviour is unchanged.

Why

In containerized deployments, cbm_default_worker_count(initial=true)
returns sysconf(_SC_NPROCESSORS_ONLN) (host-CPU count, not the
container's CPU quota). On a 1-vCPU pod scheduled onto a 16-core
node cbm spawns ~16 indexing workers, each with its own per-worker
buffers — the dominant OOMKill driver in container deployments
(see companion issue #363 for the broader cgroup-awareness ask).

A small env knob solves the immediate operator pain without taking
on the scope of full cgroup detection, and it follows the same
shape as the existing CBM_* env overrides: explicit override >
implicit detection.

Patch

src/foundation/system_info.c:

int cbm_default_worker_count(bool initial) {
    /* CBM_WORKERS env override (clamped to [1, CBM_WORKERS_MAX]).
     * Useful inside containers where sysconf(_SC_NPROCESSORS_ONLN)
     * reports host CPUs rather than the cgroup's effective CPU quota.
     * Same precedence shape as other CBM_* env overrides:
     * explicit override > implicit detection. */
    char buf[CBM_SZ_32];
    if (cbm_safe_getenv("CBM_WORKERS", buf, sizeof(buf), NULL) != NULL) {
        long n = strtol(buf, NULL, CBM_DECIMAL_BASE);
        if (n >= MIN_WORKERS && n <= CBM_WORKERS_MAX) {
            return (int)n;
        }
        cbm_log_warn("workers.env.invalid", "value", buf,
                     "fallback", "sysconf");
    }

    cbm_system_info_t info = cbm_system_info();
    // ... unchanged from today ...
}

CBM_WORKERS_MAX = 256 is added to the file-local enum; happy to
drop the upper clamp if you'd rather trust the operator, or move
the constant somewhere shared. cbm_safe_getenv, CBM_DECIMAL_BASE,
CBM_SZ_32, SKIP_ONE, MIN_WORKERS, and cbm_log_warn all
already exist (see src/foundation/platform.h, constants.h, and
log.h).

Tests

tests/test_platform.c gains three cases inside the existing
SUITE(platform):

1. platform_default_workers_env_override — CBM_WORKERS=4 is honored for both initial=true and initial=false.
2. platform_default_workers_env_invalid — 0, -1, 9999, and not-a-number all fall back to the sysconf-derived default (and emit workers.env.invalid at WARN).
3. platform_default_workers_env_unset — when unset, cbm_default_worker_count(true) == cbm_system_info().total_cores, preserving today's contract.

Docs

One-line addition to the Environment Variables table in
README.md:

CBM_WORKERS — Override the parallel-indexing worker count
returned by cbm_default_worker_count. Useful inside containers
where sysconf(_SC_NPROCESSORS_ONLN) reports host CPUs rather
than the cgroup's effective quota. Range 1–256; invalid values
are ignored with a warning.

Behaviour when unset

Identical to today. No deployment that doesn't set CBM_WORKERS
sees any difference.

Verification on my side

I have not run scripts/build.sh / scripts/test.sh /
scripts/lint.sh locally because the full ASan + UBSan setup
isn't installed on my machine. Happy to iterate quickly on any
CI feedback (lint, clang-tidy, cppcheck, format) — the patch is
small enough that a turnaround should be fast.

Related

• Companion issue Linux: cbm_system_info / cbm_default_worker_count don't respect cgroup CPU/memory limits #363 — full cgroup-aware detection (the broader
  ask this PR carves a smaller, lower-risk path out of).
• Other crash bugs that container-overspawn magnifies: Dump-phase crash on large TS monorepo (v0.6.1, darwin-arm64) — pipeline completes through semantic_edges then terminates abnormally before gbuf.dump #317, Silent index corruption after rapid kill/restart cycles #334,
  Segmentation fault (core dumped) #336, Segmentation fault at start of lsp_cross pass on repositories with 200+ files #340.
• Downstream context: filed while integrating CBM as a long-lived
  MCP-server process inside a 2 GiB Kubernetes pod. Backend pod's
  current workaround is a memory-limit bump from 2 GiB → 4 GiB to
  ride out the overspawn until this lands.