Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/*
* ipc.h — Authenticated local transport for the CBM daemon.
*
* Unix builds use owner-only Unix-domain sockets and advisory file locks.
* Windows builds use generation-random current-user named pipes plus
* handle-anchored private lock files in an owner-only runtime directory. All
* implementation details stay opaque so callers cannot accidentally bypass
* the transport checks.
*/
#ifndef CBM_DAEMON_IPC_H
#define CBM_DAEMON_IPC_H
#include "daemon/daemon.h"
#include "foundation/private_file_lock.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
typedef struct cbm_daemon_ipc_endpoint cbm_daemon_ipc_endpoint_t;
typedef struct cbm_daemon_ipc_listener cbm_daemon_ipc_listener_t;
typedef struct cbm_daemon_ipc_connection cbm_daemon_ipc_connection_t;
typedef struct cbm_daemon_ipc_startup_lock cbm_daemon_ipc_startup_lock_t;
typedef struct cbm_daemon_ipc_local_transition cbm_daemon_ipc_local_transition_t;
typedef struct cbm_daemon_ipc_participant_guard cbm_daemon_ipc_participant_guard_t;
typedef struct cbm_daemon_ipc_lifetime_reservation cbm_daemon_ipc_lifetime_reservation_t;
/* A receive wait with no wall-clock expiry. The wait remains interruptible by
* peer EOF and cbm_daemon_ipc_connection_interrupt(). This is intentionally a
* named sentinel rather than a very large finite timeout: authenticated MCP
* sessions routinely remain idle for days, and a long-running application
* request must not lose its control connection merely because no new frame is
* arriving. */
#define CBM_DAEMON_IPC_WAIT_FOREVER UINT32_MAX
/* Create one endpoint namespace for an exact 16-lowercase-hex instance key.
* POSIX addresses are deterministic; Windows resolves the current daemon
* generation through an owner-only nonce record. runtime_parent may be NULL
* to use the platform's secure local default. The returned runtime directory
* is an owner-only child of that parent. */
cbm_daemon_ipc_endpoint_t *cbm_daemon_ipc_endpoint_new(const char *instance_key,
const char *runtime_parent);
void cbm_daemon_ipc_endpoint_free(cbm_daemon_ipc_endpoint_t *endpoint);
const char *cbm_daemon_ipc_endpoint_address(const cbm_daemon_ipc_endpoint_t *endpoint);
const char *cbm_daemon_ipc_endpoint_runtime_dir(const cbm_daemon_ipc_endpoint_t *endpoint);
/* Duplicate the endpoint's already-validated owner-only runtime-directory
* handle for native lock files. Callers never reopen the path themselves. */
cbm_private_file_lock_status_t cbm_daemon_ipc_private_lock_directory_new(
const cbm_daemon_ipc_endpoint_t *endpoint, cbm_private_lock_directory_t **directory_out);
/* Listener and connection handles are non-inheritable. */
cbm_daemon_ipc_listener_t *cbm_daemon_ipc_listen(const cbm_daemon_ipc_endpoint_t *endpoint);
/* A daemon host may reserve endpoint ownership before constructing any
* stateful subsystem, then transfer that exact reservation into its listener.
* POSIX listener publication binds a private generation anchor, durably
* records the pending anchor identity through a recoverable deterministic
* temp link, hard-links the anchor into the stable socket name without
* overwrite, commits an anchor-bearing identity marker through the same
* protocol, and removes pending last. The anchor remains linked for the
* listener lifetime.
* listen_reserved consumes *reservation_io only on success and sets it to
* NULL; on failure the caller still owns it. A reservation is bound to the
* endpoint that created it and cannot be adopted by another endpoint. The
* daemon host must retain a participant guard before taking the reservation;
* the convenience listen() wrapper owns that guard automatically. */
int cbm_daemon_ipc_lifetime_reservation_try_acquire(
const cbm_daemon_ipc_endpoint_t *endpoint,
cbm_daemon_ipc_lifetime_reservation_t **reservation_out);
void cbm_daemon_ipc_lifetime_reservation_release(
cbm_daemon_ipc_lifetime_reservation_t *reservation);
cbm_daemon_ipc_listener_t *cbm_daemon_ipc_listen_reserved(
const cbm_daemon_ipc_endpoint_t *endpoint,
cbm_daemon_ipc_lifetime_reservation_t **reservation_io);
void cbm_daemon_ipc_listener_close(cbm_daemon_ipc_listener_t *listener);
/* Heartbeat for the daemon's long-lived runtime artifacts: refresh the held
* lifetime reservation, the listener's participant guard (if it owns one),
* external_guard (optional, a guard the caller retains beside this listener)
* and the published identity marker so an age-based temp cleaner never
* deletes them (#2178). Returns 1 when all were refreshed, 0 once any no
* longer names the file this listener owns (a lost lifetime file lets a peer
* start a second generation; a lost identity marker makes listener close
* leave the socket pair behind), and -1 when a still-valid file could not be
* refreshed (transient). Only the thread that closes the listener may call it
* while the listener is open. */
int cbm_daemon_ipc_listener_touch(cbm_daemon_ipc_listener_t *listener,
cbm_daemon_ipc_participant_guard_t *external_guard);
/* Create or validate one private current-user directory at an already
* canonical local path. Ancestors are handle-validated without mutation:
* POSIX permits only root/current-user owners and no group/other write (apart
* from a root-owned sticky parent selecting a trusted-owned child); Windows
* permits current user/SYSTEM/Administrators/TrustedInstaller and rejects
* untrusted mutation ACEs. The final directory is hardened to owner-only
* access. Symlink, reparse-point, foreign-owner, and unsafe filesystem states
* fail closed. This is the common trust boundary for the canonical account
* cache root as well as daemon-private artifacts. */
bool cbm_daemon_ipc_private_directory_secure(const char *directory_path);
/* Human-readable reason for this process's most recent private-namespace
* validation refusal (empty string when none). Diagnostic only — callers
* append it to their error messages; policy decisions never read it. */
const char *cbm_daemon_ipc_validation_detail(void);
/* #1717: advice, never a refusal. When cache_root lives on a network
* filesystem (Linux statfs: NFS, CIFS, SMB2, Lustre, GPFS), log one
* `daemon.cache_root_network_fs` warning per process pointing at local
* storage. Returns true only when this call emitted that warning. */
bool cbm_daemon_ipc_warn_if_network_cache_root(const char *cache_root);
#ifdef CBM_ENABLE_TEST_SEAMS
/* Report `magic` as the cache root's statfs f_type on every platform (active),
* or restore real detection; either way re-arm the once-per-process warning. */
void cbm_daemon_ipc_set_fs_magic_for_test(bool active, unsigned long magic);
#endif
/* This process's most recent listener-publication failure: the stage that
* refused, the errno the failing step reported (0 when the step reported
* none), and the artifact path it was operating on ("" when no path applies).
* Every `daemon.ipc.listen_failed` log line carries the same three fields.
* Reset at the start of each listen attempt. Returns false while no failure
* has been recorded. Diagnostic only: the daemon host copies it into its
* durable start-failure record so a waiting client can name the cause instead
* of burning its full startup deadline (#1828). */
enum {
CBM_DAEMON_IPC_LISTEN_FAILURE_STAGE_CAP = 32,
CBM_DAEMON_IPC_LISTEN_FAILURE_PATH_CAP = 4096
};
typedef struct {
char stage[CBM_DAEMON_IPC_LISTEN_FAILURE_STAGE_CAP];
int errno_value;
char path[CBM_DAEMON_IPC_LISTEN_FAILURE_PATH_CAP];
} cbm_daemon_ipc_listen_failure_t;
bool cbm_daemon_ipc_listen_failure_detail(cbm_daemon_ipc_listen_failure_t *out);
#ifdef CBM_ENABLE_TEST_SEAMS
/* #1537: seed the detail so a test can prove the CLI refusal surfaces it. */
void cbm_daemon_ipc_set_validation_detail_for_testing(const char *detail);
#ifdef _WIN32
/* #1705: run the daemon's directory-owner/ACE trust predicate against an
* arbitrary SID, so a test can assert THIS machine's built-in Administrator
* (RID-500) is trusted while a foreign S-1-5-21-*-500 is not. Returns false on
* any setup failure. Windows only. */
bool cbm_daemon_ipc_win_sid_trusted_for_testing(void *sid);
#endif
#ifndef _WIN32
/* #1830 seams (POSIX). Override the single-uid user-namespace overflow uid that
* ancestors may be owned by (active=false restores the real /proc-derived
* value); and expose the pure uid_map-parse and ancestor accept/refuse decision
* so they can be tested without a chown-able overflow-owned directory. */
void cbm_daemon_ipc_posix_set_ancestor_overflow_uid_for_test(bool active,
unsigned long overflow_uid);
/* #1717 seam (POSIX): report the directory at directory_path (matched by
* dev/ino) as owned by foreign_uid during the ancestor walk. False when the
* path is not a directory. Clear restores real ownership. */
bool cbm_daemon_ipc_posix_set_foreign_owned_dir_for_test(const char *directory_path,
unsigned long foreign_uid);
void cbm_daemon_ipc_posix_clear_foreign_owned_dir_for_test(void);
bool cbm_daemon_ipc_posix_uid_map_is_single_uid_for_test(const char *uid_map, unsigned long euid);
bool cbm_daemon_ipc_posix_ancestor_stat_ok_for_test(unsigned long owner, unsigned int mode,
unsigned long euid, bool overflow_active,
unsigned long overflow_uid);
/* #1687: treat every directory as on a WSL DrvFs mount so the remedy text in
* the private-directory refusal is testable off WSL. Diagnostic only. */
void cbm_daemon_ipc_posix_force_wsl_drvfs_for_test(bool force);
#if defined(__linux__)
/* Number of REAL overflow-uid derivations so far. The value is meaningless on
* its own; the point is that it must rise on every ancestor check, proving no
* cache has crept back in. */
unsigned cbm_daemon_ipc_posix_overflow_compute_count_for_test(void);
#endif
#endif
#endif
/* Create/validate an owner-only directory and securely open one regular
* owner-only append log within it. User-controlled path components may not be
* symlinks, junctions, or other reparse points; trusted root-owned macOS /tmp
* and /var aliases are normalized before validation. A file larger than
* rotate_cap_bytes is moved to <base_name>.1 before a new stream is opened.
* The caller owns the returned FILE and must fclose it. */
FILE *cbm_daemon_ipc_private_log_open(const char *directory_path, const char *base_name,
size_t rotate_cap_bytes);
/* Tri-state operations return 1 on success, 0 on timeout, and -1 on error.
* receive_frame also accepts CBM_DAEMON_IPC_WAIT_FOREVER. */
int cbm_daemon_ipc_accept(cbm_daemon_ipc_listener_t *listener, uint32_t timeout_ms,
cbm_daemon_ipc_connection_t **connection_out);
/* No-spawn endpoint liveness probe for binary activation safety. Returns
* 1 when a secure daemon endpoint is connected, pending, or busy; 0 only when
* it is absent; -1 when endpoint ownership or safety cannot be proven. A
* secure but refused Unix socket also fails closed as active because BSD may
* use ECONNREFUSED for a full listen queue.
* It never sends a protocol frame, so exact and conflicting builds are both
* reported as active. */
int cbm_daemon_ipc_endpoint_probe(const cbm_daemon_ipc_endpoint_t *endpoint, uint32_t timeout_ms);
/* Observe the daemon-generation lifetime reservation without spawning a
* daemon or retaining the reservation. Returns 1 while a host is constructing,
* listening, or closing the stable endpoint, 0 when the reservation is free,
* and -1 when ownership/safety cannot be proven. Stale cleanup holds both the
* startup lock and a temporary lifetime reservation; listener construction
* then transfers a lifetime reservation through listener teardown. */
int cbm_daemon_ipc_lifetime_reservation_probe(const cbm_daemon_ipc_endpoint_t *endpoint);
#ifndef _WIN32
/* Remove only a provably current-generation stale Unix socket identity. The
* caller must first observe an absent lifetime reservation and retain the
* matching startup lock for the complete call; the implementation rechecks
* both conditions. Stable deletion normally requires a committed marker whose
* named anchor and stable path are the same secure socket inode; pending alone
* may only complete that commit when both paths independently corroborate it.
* With both records absent, the exact owner-private two-name/two-link stable
* socket and anchor shape is also recoverable after immediate revalidation.
* A differing stable replacement is preserved while owned anchor/records are
* collected. Returns 1 when the stable endpoint is absent and all owned
* artifacts are absent or were removed, 0 when cleanup is refused for a live,
* legacy, unknown, or mismatched identity, and -1 for an invalid lock or
* unsafe/I/O state. This operation never connects to the endpoint. */
int cbm_daemon_ipc_stale_generation_cleanup(const cbm_daemon_ipc_endpoint_t *endpoint,
const cbm_daemon_ipc_startup_lock_t *startup_lock);
#endif
/* Migration-only observation of transport/startup primitives used by builds
* that predate version-cohort coordination. This never connects to the old
* endpoint and never claims a legacy primitive as ownership authority.
* Returns 1 when a legacy generation is present or starting, 0 when absent,
* and -1 when ownership/safety cannot be proven. */
int cbm_daemon_ipc_legacy_generation_probe(const cbm_daemon_ipc_endpoint_t *endpoint);
cbm_daemon_ipc_connection_t *cbm_daemon_ipc_connect(const cbm_daemon_ipc_endpoint_t *endpoint,
uint32_t timeout_ms);
void cbm_daemon_ipc_connection_close(cbm_daemon_ipc_connection_t *connection);
/* Bounded wait for the peer to consume everything already sent, by reading
* (and discarding) until peer EOF or the timeout. On POSIX this is a no-op:
* closing a stream socket leaves buffered data deliverable, so the final
* response survives an immediate close. On Windows named pipes, closing the
* server handle discards data the client has not yet read; a server that
* sends a final response and closes immediately races the client's decode.
* Peer EOF is proof of consumption because clients close only after reading
* their pending response. Callers close the connection afterwards. */
void cbm_daemon_ipc_connection_drain(cbm_daemon_ipc_connection_t *connection, uint32_t timeout_ms);
/* Interrupt pending I/O without freeing the connection object. This is
* idempotent and may be called from a supervisor thread; the connection's
* owning worker must still call connection_close after its I/O unwinds. */
void cbm_daemon_ipc_connection_interrupt(cbm_daemon_ipc_connection_t *connection);
/* Kernel-reported peer process ID for this established socket/pipe. Returns
* zero when the platform cannot provide an authenticated peer PID. The daemon
* uses this as the anchor for executable identity verification; protocol
* payloads are never trusted to declare their own process identity. */
uint64_t cbm_daemon_ipc_connection_peer_pid(const cbm_daemon_ipc_connection_t *connection);
/* send_frame uses a bounded internal write timeout. receive_frame returns a
* malloc-owned payload (NULL for an empty frame) through payload_out. */
bool cbm_daemon_ipc_send_frame(cbm_daemon_ipc_connection_t *connection,
cbm_daemon_frame_type_t type, uint16_t flags, const void *payload,
uint32_t length);
int cbm_daemon_ipc_receive_frame(cbm_daemon_ipc_connection_t *connection, uint32_t timeout_ms,
cbm_daemon_frame_t *frame_out, uint8_t **payload_out);
/* Nonblocking single-winner current-generation startup serialization. POSIX
* retains startup-v2 EX plus a SH claim on the frozen legacy startup file.
* Windows retains startup-v2 EX plus the validated frozen legacy mutex, but
* does not publish a generation or sentinel until prepare_handoff. This makes
* activation/install probes non-mutating. Returns 1 when acquired, 0 on a
* competing transition/legacy owner, and -1 on an unsafe or I/O state. */
int cbm_daemon_ipc_startup_lock_try_acquire(const cbm_daemon_ipc_endpoint_t *endpoint,
cbm_daemon_ipc_startup_lock_t **lock_out);
/* Activation-only no-spawn generation probe under the exact matching,
* retained, unprepared startup lock. It ignores the caller's own startup-v2
* and frozen-legacy startup claims, serially cleans a provable stale POSIX
* generation under a temporary lifetime reservation, and reports only a live
* daemon lifetime, remaining stable transport, or deterministic
* legacy/current sentinel.
* Returns 1 when active, 0 when authoritatively absent, and -1 when the lock,
* endpoint, transport, or ownership cannot be validated. */
int cbm_daemon_ipc_generation_probe_under_startup_lock(
const cbm_daemon_ipc_endpoint_t *endpoint, const cbm_daemon_ipc_startup_lock_t *startup_lock);
/* Prepare a serialized daemon handoff. POSIX validates/removes only a
* provably current-generation stale socket identity while retaining both
* startup-v2 EX and frozen-legacy SH. Windows creates/joins the authenticated
* current-participant group, publishes the generation, then releases only the
* legacy mutex. Both platforms retain startup-v2 and a temporary participant
* claim through child readiness. */
bool cbm_daemon_ipc_startup_lock_prepare_handoff(cbm_daemon_ipc_startup_lock_t *lock);
/* Retry-safe teardown. Success consumes and clears *lock_io. A native cleanup
* failure returns false and retains every unreleased claim in *lock_io; the
* caller must retry within a finite deadline or fail-stop its process. */
bool cbm_daemon_ipc_startup_lock_release(cbm_daemon_ipc_startup_lock_t **lock_io);
/* Join the current participant group while a daemon bootstrap parent retains
* its prepared startup lock. The child takes no startup-v2 claim of its own;
* it joins the parent's authenticated legacy-compatible group and retains the
* returned guard for its complete daemon lifetime. The endpoint must outlive
* the guard. Returns 1 when joined, 0 when no prepared group exists or a
* legacy transition won, and -1 on an unsafe/I/O state. Release is retry-safe
* where the platform exposes retryable teardown and consumes *guard_io only
* after the participant claim is completely gone. */
int cbm_daemon_ipc_participant_guard_try_join(const cbm_daemon_ipc_endpoint_t *endpoint,
cbm_daemon_ipc_participant_guard_t **guard_out);
bool cbm_daemon_ipc_participant_guard_release(cbm_daemon_ipc_participant_guard_t **guard_io);
/* Same heartbeat contract and 1/0/-1 result as cbm_daemon_ipc_listener_touch,
* for a guard the caller retains itself. */
int cbm_daemon_ipc_participant_guard_touch(const cbm_daemon_ipc_endpoint_t *endpoint,
cbm_daemon_ipc_participant_guard_t *guard);
/* Standalone CLI work joins the legacy-compatible current participant group
* without becoming a daemon client. Acquisition retains startup-v2 only for
* the seal/presence decision. Sealing also retains a participant claim:
* frozen-legacy SH on POSIX, or group-v1 SH plus one non-serving deterministic
* legacy-pipe sentinel on Windows. After the transition-aware presence check,
* begin_work commits the decision by releasing startup-v2 while keeping the
* participant claim through local work. Multiple local participants and a
* same-build modern daemon may then overlap, while a pre-cohort startup stays
* excluded. POSIX sealing also removes only a provably current-generation
* crash-left socket identity. Tri-state operations return 1 on success, 0
* when another transition or legacy/unknown generation won, and -1 on an
* unsafe/I/O state. The endpoint must outlive the transition. */
int cbm_daemon_ipc_local_transition_try_acquire(const cbm_daemon_ipc_endpoint_t *endpoint,
cbm_daemon_ipc_local_transition_t **transition_out);
int cbm_daemon_ipc_local_transition_seal_legacy(cbm_daemon_ipc_local_transition_t *transition);
/* Observe daemon lifetime only through a successfully sealed, matching,
* retained transition. Returns 1 while a daemon lifetime is active, 0 when
* its absence is authoritative under the transition, and -1 when the guard,
* endpoint, or underlying primitive cannot be verified. */
int cbm_daemon_ipc_local_transition_lifetime_probe(
const cbm_daemon_ipc_endpoint_t *endpoint, const cbm_daemon_ipc_local_transition_t *transition);
/* Commit the classified transition and begin standalone work. This releases
* startup-v2 but retains the participant claim. It is valid exactly once after
* sealing/presence classification. */
bool cbm_daemon_ipc_local_transition_begin_work(cbm_daemon_ipc_local_transition_t *transition);
/* Release ends protection after the caller has stopped all local work. On
* Windows teardown reacquires startup-v2 and the legacy mutex, releases group
* SH, closes this participant's sentinel last, then releases mutex and v2.
* Success consumes and clears *transition_io; a retryable native cleanup
* failure or startup-gate contention returns false and retains it. */
bool cbm_daemon_ipc_local_transition_release(cbm_daemon_ipc_local_transition_t **transition_io);
/* Nonblocking release: 1 consumes and clears *transition_io (also when already
* empty), 0 retains it while another startup owns a required gate, and -1
* retains it on an unsafe/native I/O failure. A NULL transition_io is invalid.
* Callers can give healthy contention its own wait policy without extending
* the deadline for repeated native cleanup failures. */
int cbm_daemon_ipc_local_transition_try_release(cbm_daemon_ipc_local_transition_t **transition_io);
#endif /* CBM_DAEMON_IPC_H */