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

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:

• 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)

The main entry point for daemon mode resides in src/main.c, which delegates to 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.

/* 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)

The core admission logic lives in 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.

/* 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:

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【/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 calls cbm_version_cohort_acquire_admission() to ensure compatibility before executing operations.

/* 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.
• 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}