# What Is the Session Coordination Daemon and Its Admission Barrier in Codebase-Memory-MCP?

> Understand the session coordination daemon and its admission barrier in Codebase-Memory-MCP. Learn how this per-account singleton process ensures IPC and lifecycle management for build consistency.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: internals
- Published: 2026-07-28

---

**The session coordination daemon is a per-account singleton process in Codebase-Memory-MCP that manages IPC and lifecycle across all components, protected by a file-based admission barrier ensuring exact-build consistency across processes.**

The session coordination daemon serves as the central nervous system for Codebase-Memory-MCP (CBM), residing in `src/daemon/` and orchestrating all inter-process communication and resource sharing. This architecture ensures that MCP servers, CLI commands, background workers, and UI components operate under a unified lifecycle management system. Before any component can participate, it must pass through a strict admission barrier that validates build consistency and prevents version skew.

## Core Responsibilities of the Session Coordination Daemon

### Single Shared Instance Per User Account

The daemon operates as a **single shared instance per user account**, meaning all CBM processes—including MCP JSON-RPC servers, one-shot CLI commands, and background watchers—connect to this central coordinator for IPC and lifecycle management. According to the repository's README, the `daemon/` directory handles "*Per-account session coordination, IPC, lifecycle, shared jobs/watchers*"【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L663-L667】. This singleton pattern prevents resource contention and ensures serialized access to shared assets like the SQLite graph store.

### Process-Level Coordination and Crash Safety

Beyond simple coordination, the daemon provides **crash-safe, exclusive access** to critical resources through OS-level file locking mechanisms. When the daemon starts, it establishes a process-wide exclusive lock that persists for its entire lifespan, protecting shared log files and the graph database from concurrent modification or corruption during unexpected terminations.

## The Admission Barrier: Exact-Build Consistency

The **admission barrier** is a crash-safe mechanism that guarantees all active CBM processes run the exact same executable build, coordination ABI, and canonical cache root. As documented in the README, "*MCP servers, hooks, one-shot CLI commands, temporary index workers, and the daemon share a crash-safe OS admission barrier*; starting an ordinary conflicting process fails before doing work and records an explicit conflict"【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L119-L122】.

The barrier utilizes four distinct lock files defined in [`src/daemon/version_cohort.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/version_cohort.c):

- `cbm-version-cohort-admission-v1.lock` — Validates exact-build, cache root, and ABI compatibility
- `cbm-version-cohort-maintenance-v1.lock` — Protects long-running mutations
- `cbm-version-cohort-lifetime-v1.lock` — Holds the process-wide exclusive lock for the daemon's lifespan
- `cbm-version-cohort-daemon-v1.lock` — Indicates the daemon itself is active

When a process attempts to start, the `version_cohort_lock_until()` function attempts to acquire an exclusive (EX) lock on the admission file. If another process holds the lock with a different build fingerprint, the acquisition fails and the process aborts immediately, preventing version skew.

## Implementation Details and Source Code

### Daemon Initialization ([`src/daemon/daemon.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/daemon.c))

The main entry point for daemon mode resides in [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c), which delegates to [`src/daemon/daemon.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/daemon.c) when the `--daemon` flag is present. The function `cbm_daemon_start()` initializes the coordination layer and acquires the necessary lifetime locks.

```c
/* In src/main.c the daemon is launched if the `--daemon` flag is present */
int main(int argc, char **argv) {
    if (cbm_flag_present(argv, "--daemon")) {
        return cbm_daemon_start();   // src/daemon/daemon.c
    }
    /* … normal CLI execution … */
}

```

If the daemon cannot acquire its coordination locks, it invokes `main_coordination_cleanup_fail_stop` to perform a graceful shutdown with proper error reporting【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/src/main.c#L179-L186】.

### Lock Acquisition Logic ([`src/daemon/version_cohort.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/version_cohort.c))

The core admission logic lives in [`src/daemon/version_cohort.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/version_cohort.c), where `version_cohort_lock_until()` manages the file-based locks. This function attempts to obtain exclusive locks with a specified timeout, acting as the gatekeeper for the admission barrier.

```c
/* Called from many places (e.g., src/daemon/project_lock.c) */
static cbm_private_file_lock_status_t lock_admission(cbm_version_cohort_manager_t *mgr) {
    return version_cohort_lock_until(
        mgr,
        VERSION_COHORT_ADMISSION_FILE,
        CBM_PRIVATE_FILE_LOCK_EX,          // exclusive lock = admission barrier
        VERSION_COHORT_CLEANUP_TIMEOUT_MS);
}

```

When lock acquisition fails, the system calls `version_cohort_cleanup_fail_stop()`, which logs the error and terminates the process immediately to prevent inconsistent state:

```c
static _Noreturn void version_cohort_cleanup_fail_stop(const char *component) {
    cbm_log_error("daemon.forced_shutdown", "component", component,
                  "action", "coordination_cleanup");
    _exit(EXIT_FAILURE);
}

```

This forced shutdown mechanism appears in lines 18-31 of [`src/daemon/version_cohort.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/version_cohort.c)【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/src/daemon/version_cohort.c#L18-L31】.

### Client-Side Admission Checks

Even one-shot CLI commands that do not start the daemon must verify the admission barrier. The CLI implementation in [`src/cli/cli.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) calls `cbm_version_cohort_acquire_admission()` to ensure compatibility before executing operations.

```c
/* src/cli/cli.c – Admission check for one-shot commands */
if (!cbm_version_cohort_acquire_admission()) {
    fprintf(stderr, "error: exact-build admission failed; aborting.\n");
    exit(EXIT_FAILURE);
}

```

This check ensures that temporary workers and command-line tools maintain the same build consistency guarantees as the long-running daemon.

## Summary

- The **session coordination daemon** provides per-account singleton coordination for all CBM components, managing IPC, lifecycle, and shared resource access from `src/daemon/`.
- The **admission barrier** enforces exact-build consistency across all processes using file-based locks in [`src/daemon/version_cohort.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/version_cohort.c).
- Four distinct lock files manage admission, maintenance, lifetime, and daemon state to ensure crash-safe operation and prevent version skew.
- Both daemon and CLI modes must pass `version_cohort_lock_until()` checks, with failures triggering immediate termination via `version_cohort_cleanup_fail_stop()`.
- This architecture guarantees exclusive, crash-safe access to the SQLite graph store and other shared resources while maintaining strict build consistency.

## Frequently Asked Questions

### What happens if two different versions of Codebase-Memory-MCP try to run simultaneously?

The admission barrier blocks the second process. When `version_cohort_lock_until()` detects a build fingerprint mismatch on `cbm-version-cohort-admission-v1.lock`, it returns a failure status and the process aborts with an "exact-build admission failed" error before performing any work. This prevents data corruption from incompatible ABI versions.

### Can I run the daemon and CLI commands at the same time?

Yes, provided they are the exact same build. The daemon holds the lifetime and daemon locks, while CLI commands acquire temporary admission locks. Both validate against the same version cohort in [`src/daemon/version_cohort.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/version_cohort.c), ensuring compatibility while allowing concurrent operation of long-running services and one-shot tools.

### Where is the admission barrier logic implemented?

The barrier logic is primarily implemented in [`src/daemon/version_cohort.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/version_cohort.c), specifically in the `version_cohort_lock_until()` function. This file manages the four lock files that constitute the admission, maintenance, lifetime, and daemon barriers, providing the OS-level coordination primitives used throughout the codebase.

### What is the purpose of the maintenance lock file?

The `cbm-version-cohort-maintenance-v1.lock` file protects long-running mutations and maintenance operations from conflicting with other processes. While the admission lock ensures version consistency at startup, the maintenance lock provides additional serialization for background tasks like indexing or graph compaction, ensuring these operations complete atomically without interference.