Module proc_tree 

Processes above this one, each named by its pid and its start time, so a pid the kernel has since handed to another process is not taken for the one that was recorded. Read from /proc on Linux and libproc and sysctl on macOS; elsewhere every list is empty and nothing is alive.

Structs

Proc

One process: its pid, when it started (clock ticks after boot), and its name at the time it was read.

Functions

above

The processes above pid, nearest first, up to and including pid 1: in a container that may be the harness itself.

alive

Whether p still runs: the same pid with the same start, and not a zombie waiting to be reaped.

ancestors

The processes above this one, nearest first. Walked once: a process does not move in the tree, and a hook asks for its ancestors from several places in one call.

argv

The command-line words of pid.

boot

This boot, so a process recorded before a reboot or on another machine never matches one here.

calling_shell

The shell that ran the process whose ancestors are chain: past any wrappers, the outermost of the shells nested directly above it, so a script that starts a fresh sh -c per line is still one shell. None when a program other than a shell ran it.

cast_shell

The shell a cast binds to. Ancestors whose resolved executable is mine are this program, whatever argv0 said, and they do not end the walk. A Python process that launched it does not end the walk either. The outermost nested shell is then the one calling_shell would take. None when some other program, an agent runner or the session is the first program above this process.

cwd

The working directory of pid.

editor_above

Whether an editor or an agent is still above this process. Linux also accepts the runner named by the file the process is running, so a node that is only hosting an editor still counts.

environ

The environment pid was started with. A program it runs can set its own variables, but cannot change what its parent was started with.

exe

The executable path of pid.

exe_runner

The runner pid is, from the file the kernel runs it from, never from the name it gives itself. An installed runtime such as node ([runtime_of_file]) is the runner whose script it runs, that script’s path resolved on disk and judged as a runner file is. The script’s path comes from the process’s own arguments, so only a runtime the person installed is believed about it.

hook_runner

The runner that spawned this ljos hook itself, or why none did: the parent must be an installed runner (exe_runner), with no shell or interpreter between them but the sh -c the runner runs its hook command in ([hook_shell]). That runner must not run inside a tool call, which a runner above it, a tool call’s variables in the environment it was started with, or the guard’s tool-call record ([confirm_runner]) would show. Only such a hook’s prompt is the person’s. An environment that cannot be read hides the stamp, so it is refused.

is_editor_name

Whether name is an editor or an agent. A path uses its file name.

is_ljos_exe

Whether path is the ljos executable. The resolved file name stays ljos when argv0 is a link or another name.

note_tool_call

Record the tool call whose guard hook this is. The runner is runner, the process that spawned the hook. The hook’s own start time is the watermark: a process started later, in this session or cgroup, is the tool call even after it detaches.

of

The process pid names now.

own_home

The home this user’s passwd entry names. A tool call sets HOME for whatever it starts, but cannot change this.

placed_runner

The installed runner above this process, checked against the tool-call record ([confirm_runner]). Shells and wrappers are stepped over. The first other program that is not an installed runner ends the walk, so a copy named like a runner cannot hide behind a real one further up.

runner

The program that ran the process whose ancestors are chain, read up to the session ([ends_the_walk]), which is never the program: the nearest harness ([crate::is_harness_process]), so a uv, npx or node that only started the hook and exits with it does not outrank the harness above it; else the nearest one that is neither a shell nor a wrapper, which keeps a harness that runs as plain node; else the outermost of the shells and wrappers below the session. None when the session ran the process itself.

runner_above

The nearest process above this one that is a runner by the file the kernel runs it from (exe_runner), and which runner it is.

seal_unreadable_tool_call

Remember that a tool-call record could not be written. A later read then fails closed: a missing record means no tool call, and a failed write must not look like that. A tool call may have happened and its evidence could not be taken. Later reads fail closed instead of looking like a quiet runtime.

started_by_runner

The process the nearest runner on this process’s chain started: the shell it opened for a tool call, or this process when the runner ran it directly. None when the chain reaches the person’s session or the top without a runner.

token

p as one word that names it on this machine and boot.

token_alive

Whether the process a token names still runs here.