Module daemon 

Enums

DaemonStop

What stop_daemon found for the active data dir.

Functions

cleanup_daemon_files

Cleanup PID file and IPC endpoint on shutdown.

daemon_addr

daemon_pid_path

daemon_status

init_foreground_daemon

Initialize the foreground-daemon process. Commits the XDG layout pin (and drains a residual ~/.lean-ctx) before the daemon writes anything, so this long-running, possibly launchd/systemd-autostarted writer can never re-collapse config/data/state/cache onto a stray legacy dir (GL #623). The MCP server pins on its own start; the daemon is the other independent entry point (e.g. serve --_foreground-daemon), so it must heal too. heal() is idempotent and cheap — a no-op once pinned and when no residual dir exists.

is_daemon_running

Fast check on the hot path (every MCP request): the recorded PID is alive and, when the daemon recorded its identity, still that process. A PID file of an earlier release has no identity; verified_daemon also checks the command line.

is_foreground_daemon

Whether this process is the long-lived foreground daemon.

mark_foreground_daemon

Mark this process as the foreground daemon. Called once at daemon init.

not_running_message

The line serve --stop and daemon stop print, and exit 1 after, when no daemon runs for the active data dir. Names the dir so that a caller with a scratch LEAN_CTX_DATA_DIR sees which instance it asked about.

owned_service_pids

PIDs of the background services this instance (data dir) recorded: the daemon PID file, the proxy that answers /health on the configured port, and the Cockpit launch record. Nothing else is ever a stop candidate — MCP stdio servers, lean-ctx -c runners, hooks and other instances’ services have no record here (#2176).

read_daemon_pid

The PID in daemon.pid. Empty, garbage, 0, negative or overflowing content is warned about and the stale file removed; it never becomes a signal target (ipc::process::read_pid_file).

read_daemon_record

The recorded daemon: the PID from daemon.pid and, when the identity file names the same PID, the identity recorded at start. A PID file of an earlier release has no identity; it is gated by command line only.

restore_stopped_proxy

Start a proxy that restart/config apply stopped again when no autostart service brought it back (#2176 review #4): detached, with the arguments it ran with, by the installed binary. None when there was nothing to restore; otherwise the PID or the spawn error.

running_daemon_pid

The PID of the running daemon as daemon status reports it: this process when it is the foreground daemon daemon.pid names, otherwise verified_daemon. The process sweep behind verified_daemon excludes its own PID, so the daemon answering its own /v1/local/daemon found no daemon (running: false) while lean-ctx daemon status saw it.

start_daemon

start_daemon_with_binary

Source installs launch the verified installed copy, preserving the caller’s CWD.

stop_daemon

Stop the daemon of the active data dir (LEAN_CTX_DATA_DIR, else the default under HOME), resolved only through that dir’s PID file, identity file and socket — never through a default path, a process name or a service name. The autostart service is stopped too, but only when it runs exactly this daemon’s PID (5 Nov 2026: systemctl --user stop by unit name stopped the user’s real daemon from a scratch data dir).

stop_owned_services

Stop this instance’s recorded background services that sweep includes (see owned_service_pids); every PID is gated again by command line, user and process identity in ipc::process::stop_services.

unrecorded_services

lean-ctx background services of this user that this instance has no record of. Listed by stop, uninstall and doctor, never stopped (owner decision 02.11.).

unrecorded_services_warning

The two lines stop/uninstall/doctor print for unrecorded_services — what still runs, and how to stop it — or None.

verified_daemon

The PID of the recorded daemon when it really is this user’s lean-ctx daemon: command line serve --_foreground-daemon, lean-ctx executable, same user, and the recorded identity where there is one. Slower than is_daemon_running (reads the command line); for doctor and stop.