Skip to content

Commit c86be38

Browse files
committed
docs: correct CLI-mode claim that one-shot commands never touch the daemon (#2183, #2167)
README.md:132, README.md:633, README.md:761, and docs/CONFIGURATION.md:203 said one-shot `cli` commands "never start or connect to the coordination daemon" / read "their own environment without starting the daemon". That was already contradicted a few lines above it (README.md:126 lists one-shot CLI commands among the processes that "share a crash-safe OS admission barrier" with the daemon) and by the code: main_local_cli_daemon_execute() (src/main.c) bootstraps a client connection to the shared per-user coordination daemon via main_client_bootstrap_with_upgrade(), spawning one (bootstrap.daemon_spawned) when none is running, before dispatching the tool call. Verified live: `cli --verbose list_projects` against an isolated HOME/CBM_CACHE_DIR/CBM_RUNTIME_DIR printed "hint: this command started a temporary CBM daemon", and its cbm-daemon.log showed daemon.start -> daemon.runtime_stopping (reason=last_committed_client_disconnected) -> daemon.lifetime_end, i.e. the daemon it spawned exited again once the CLI command's own connection closed. bootstrap_production_spawn() passes the calling process's `environ` straight to posix_spawn(), so a CLI invocation that starts the daemon also seeds that daemon's captured daemon-owned environment (CBM_DIAGNOSTICS, CBM_LOG_LEVEL, etc.) - it does not read "its own environment" independently as the docs claimed. Corrected all four passages to state the real behavior: CLI commands connect to the shared daemon (starting one if none is running) for the same admission barrier and per-project locks, hold a `cli_session` that is never registered with the background watcher, and - if their own connection is what started the daemon - that daemon exits again once the command's connection closes and no other session is attached. No opt-out env var or flag for an in-process/no-daemon CLI mode exists (grepped the whole tree), so none is documented. This is a pure documentation fix; no production behavior changed. Kept clear of PR #2348 (fix/issue-2167), which separately rewrites the watcher-scope paragraph at README.md:152/237/672 and docs/CONFIGURATION.md:88 for issue #2167's auto-sync-scope correction - none of the lines here overlap with that diff. Refs #2183, #2167 Signed-off-by: Martin Vogel <[email protected]>
1 parent 0f52d30 commit c86be38

2 files changed

Lines changed: 4 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ The native `install`, `update`, and `uninstall` commands are the deliberate exce
129129

130130
Package-manager setup (npm, PyPI, or Go) verifies and publishes a coherent private cached runtime set. Sidecars are replaced before the executable with per-file atomic renames; an interrupted multi-file publication is detected and repaired on the next launch rather than being described as one crash-atomic filesystem transaction. It does not replace the active native installation and therefore does not stop running CBM sessions. When that cached binary is executed, it still enters the same exact-build admission barrier. The shell and PowerShell installers invoke the verified candidate's native `install` command, so they do receive the full account-wide activation guarantee.
131131

132-
The ordinary `cli` mode is intentionally separate: it runs one command locally and never starts or connects to the coordination daemon, registers a daemon session, or starts watchers/UI. Its only shared state is the OS admission barrier plus per-project locks for graph mutations. While the command is running, a temporary monitor lets activation cancel that operation and its supervised worker safely; the monitor exits with the command and never becomes a standing daemon. See [CLI Mode](#cli-mode) for details.
132+
The ordinary `cli` mode runs one command locally, but it is not disconnected from the daemon above: it connects to the shared coordination daemon — starting one if none is already running — for that same admission barrier plus per-project locks on graph mutations. Its connection is a `cli_session`: it never registers with the background watcher and never starts a UI, and it holds the admission lease only for the command's lifetime. If the command's own connection is what started the daemon, that daemon exits again once the command closes and no other session is attached; if a daemon was already running, the command simply joins and leaves it exactly as found. While the command is running, a temporary monitor separately lets activation cancel that operation and its supervised worker safely; the monitor exits with the command and never becomes a standing daemon. See [CLI Mode](#cli-mode) for details.
133133

134134
### Graph Visualization UI
135135

@@ -630,7 +630,7 @@ no longer a suitable automatic global target.
630630

631631
## CLI Mode
632632

633-
Every MCP tool can be invoked as a local, one-shot command. CLI tools neither start nor connect to the coordination daemon and leave no standing process behind. They hold a crash-safe exact-build admission lease only for the command lifetime. `index_repository` is the only exception internally: it starts a temporary, exact-build supervised worker for the index, then stops that worker before the CLI command exits; the worker holds its own lease until exit.
633+
Every MCP tool can be invoked as a local, one-shot command. CLI tools connect to the shared coordination daemon — starting one if none is already running — to get a crash-safe exact-build admission lease for the command's lifetime; they never register with the background watcher, and a daemon a command had to start itself exits again once the command's connection closes and no other session is using it. `index_repository` is the only exception internally: it starts a temporary, exact-build supervised worker for the index, then stops that worker before the CLI command exits; the worker holds its own lease until exit.
634634

635635
Commands that mutate graph data use shared OS-backed, per-project locks. This serializes conflicting work from CLI and MCP sessions on the same project while allowing unrelated projects to proceed independently.
636636

@@ -785,7 +785,7 @@ is preserved. See [Index resource limits](docs/INDEX_RESOURCE_LIMITS.md).
785785
| `CBM_MEM_BUDGET_MB` | *(detected)* | Override the in-memory graph budget with an explicit cap in MiB, taking precedence over the `ram_fraction × total_RAM` default. Useful on bare-metal hosts without a cgroup limit, or to pin a budget *below* the cgroup limit so headroom is left for sibling processes. Must be a positive integer; it is clamped to detected total RAM (logged as `mem.budget.clamped`), and non-numeric or non-positive values are ignored with a warning (`mem.budget.env.invalid`). |
786786
| `CBM_DUMP_VERIFY_MIN_RATIO` | `0.5` | After indexing, compare persisted SQLite node count to the in-memory dump count. When persisted nodes fall below this fraction of committed nodes (and committed > 50), `index_repository` returns `status:"degraded"` instead of silent `indexed`. Range 0–1; set `0` to disable. Invalid values are ignored with a warning. |
787787

788-
Environment used by daemon-owned components—such as diagnostics, daemon logging, and process-wide indexing resource limits—is captured from the first daemon-backed session that starts the daemon. Later sessions join that process and cannot replace those values. To change them, close all daemon-backed sessions, update the relevant agent configurations consistently, and restart a session. `CBM_ALLOWED_ROOT` remains session-specific, a conflicting `CBM_CACHE_DIR` is rejected, and one-shot CLI commands read their own environment without starting the daemon.
788+
Environment used by daemon-owned components—such as diagnostics, daemon logging, and process-wide indexing resource limits—is captured from the first daemon-backed session that starts the daemon. Later sessions join that process and cannot replace those values. To change them, close all daemon-backed sessions, update the relevant agent configurations consistently, and restart a session. `CBM_ALLOWED_ROOT` remains session-specific, a conflicting `CBM_CACHE_DIR` is rejected, and a one-shot CLI command is not exempt from the rule above: it connects to the coordination daemon like any other session, starting one if none is running, so its own environment becomes the captured daemon-owned environment only when its invocation is the one that starts the daemon — joining an already-running daemon, it inherits that daemon's already-captured values instead.
789789

790790
```bash
791791
# Store indexes in a custom directory

‎docs/CONFIGURATION.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ options = "metadata,umask=22,fmask=11"
214214
or keep the cache on the Linux filesystem (the default `~/.cache/codebase-memory-mcp`),
215215
which is also much faster than a 9p-mounted Windows drive.
216216

217-
Environment used by daemon-owned components—such as diagnostics, daemon logging, and process-wide indexing resource limits—is captured from the first daemon-backed session that starts the daemon. Later sessions join the existing process and cannot replace those values. To change them, close every daemon-backed session, update the relevant agent configurations consistently, and restart a session. `CBM_ALLOWED_ROOT` remains session-specific, a conflicting `CBM_CACHE_DIR` is rejected, and one-shot CLI commands use their own current environment without starting the daemon.
217+
Environment used by daemon-owned components—such as diagnostics, daemon logging, and process-wide indexing resource limits—is captured from the first daemon-backed session that starts the daemon. Later sessions join the existing process and cannot replace those values. To change them, close every daemon-backed session, update the relevant agent configurations consistently, and restart a session. `CBM_ALLOWED_ROOT` remains session-specific, a conflicting `CBM_CACHE_DIR` is rejected, and a one-shot CLI command is not exempt from the rule above: it connects to the coordination daemon like any other session, starting one if none is running, so its own environment becomes the captured daemon-owned environment only when its invocation is the one that starts the daemon — joining an already-running daemon, it inherits that daemon's already-captured values instead.
218218

219219

220220
### Roots that are always refused

0 commit comments

Comments
 (0)