Immutable OS-level process identity used to defend durable PID references
against PID reuse. A PID may be recycled for an unrelated process after its
original owner exits; the start marker makes that transition observable.
A PID a lean-ctx instance recorded for one of its services, with the
process identity recorded next to it when the record carries one (the
daemon identity file, the Cockpit launch record). A record without an
identity (a /health answer, a daemon PID file of an earlier release) is
gated by command line, executable, user and live identity only.
Classify a process command line as a lean-ctx background service, or
None for everything else — MCP stdio servers, hooks, command runners,
one-shot CLI calls and foreign programs. Pure, so the selection rules are
covered on every platform.
Of the recorded owned PIDs (daemon PID file, proxy /health on this
instance’s port, Cockpit launch record), the ones that still are lean-ctx
background services sweep includes. Command line, executable, user and
identity (the recorded one, where the record has it) gate every PID
again, so a stale record whose PID now belongs to an MCP server, a command
runner or a foreign process is never selected. Never this process or its
ancestors, never a process whose identity cannot be read.
lean-ctx background services of this user that no record of this
instance names (recorded): a foreground lean-ctx serve, a proxy on
another port, another data dir’s daemon, a duplicate from a start race.
The process-group id as a positive value for killpg(pgid, …) or
kill(-pgid, …), or why it may not be signalled: everything
signal_target refuses, plus the group this process belongs to.
The path a running lean-ctx image was installed under. An update or
dev-install replaces the binary while services keep running the old
image, and the OS then reports a different path for it: Linux
/proc/<pid>/exe reads …/lean-ctx (deleted), Windows reports the
rename-aside sidecar lean-ctx.old.exe or its parked form
lean-ctx.old-<pid>-<nanos>.exe (core::updater::windows_sidecar).
Exactly those shapes map back to lean-ctx/lean-ctx.exe; every other
path is returned unchanged.
True when pid runs as the same user as this process (effective uid on
Unix, token user SID on Windows). A record or a /health answer can name
any PID; a lifecycle command only ever acts on its own user’s processes,
also when it runs elevated. Unknown means false (fail closed).
Parse the text of a PID file (its first line, trimmed). Only a decimal
PID in 2..=i32::MAX is accepted; empty text, garbage, signs, zero,
PID 1 and overflowing values are refused, so a corrupt file can never
become a signal target.
What restart/config apply does about a proxy it stopped: start it
again with the arguments it ran with, unless the proxy autostart service
brought it back (autostart_restarted). Without this, restart left the
proxy down on Windows and wherever no autostart is installed (#2176
review). None when there is nothing to start. Pure.
Read a PID file. A missing file is None. A file whose content is not a
signalable PID (empty, garbage, negative, 0, 1, above i32::MAX) is
reported with a warning, removed as stale, and also None: such a value
must never reach kill(2), where 0 is the own process group and a
wrapped -1 is every process of the user.
The process a record written by that process itself names (the Cockpit
launch record), proven by the identity in the record rather than by a
command-line kind: this user, lean-ctx executable, same process as
recorded, never this process or its ancestors. None otherwise.
Two identities name the same process: the same creation marker and the
same installed executable, also when an update renamed the running image
in between (see installed_executable_path). Pure.
Stop selected services: graceful termination first, a kill for those
still running after a grace period. Every signal goes through
signal_same_process, so a PID the OS reused in between is left alone.
Stop the recorded lean-ctx background services (owned) that sweep
includes (see find_service_processes and stop_selected). Nothing
is ever selected by process name (#2176).
The warning stop/uninstall print and doctor shows for
find_unrecorded_services, or None when there are none:
(what is running, how to stop it). Pure; windows picks the hint.