Module running 

The machine-wide map of capsules that are currently running: one record per session, at ~/.murmur/running/<session_id>.json. An agent session writes its record once its A2A door is bound and names the door in url; a script capsule binds no door, writes its record when its session starts, and holds "url": null.

A record is a hint, never a truth. Nothing can guarantee it is removed — a SIGKILLed capsule writes no farewell — so a reader never trusts one. verify puts three layers between a record and the claim that a session is live, and each is insufficient alone:

1. The pid is alive. Necessary, nowhere near sufficient.
2. The process’s start time matches the recorded one. Pids are reused, so without this a record can name an unrelated process that happens to hold the number now.
3. The door answers and identifies itself. A live pid proves neither that the process is the capsule nor that it can still respond, so the agent card is fetched and the sessionId of its capsule extension compared. A record with no door has no third layer: layers 1 and 2 decide it alone.

Reading prunes a record only on evidence: layer 1 finding no process, or layer 2 reading a start time that differs from the recorded one, which means the pid was reused. That is the only reaper there is, and it is enough because the record is a hint. A reading that could not be taken is not evidence. A live pid whose start time cannot be read is ProcessState::Unverified: kept, reported as unreachable, and never signalled. A record that passes 1 and 2 and fails 3 is kept too: it names a process that is alive, perhaps suspended, and unlinking it would throw away the only handle to a running capsule because it was slow to answer.

The record names the process and stores nothing from the environment. A session declaring network.authentication also records every door token it minted: the operator token, which is how the host tools call its door, and one per declared credential, which mur token hands out. Layer 3 reads the session id off the extended card with the operator token. The record is the only place a token is written: mur run prints none. The directory is 0700 and each record 0600, because the set of records is a map of reachable capsules, and of the tokens that drive them, to anything on the machine that can read it.

A session whose manifest declares control: also holds <session_id>.control beside its record: the control token, at the same mode, written before the record and removed with it. It is the only place the token exists outside the process, and it is useless once the process is gone, because the key that verifies it was never written anywhere.

Structs

ControlTokenGuard

One session’s control token file, written for exactly as long as the session runs.

ProcessIdentity

A process named so that a recycled pid is never mistaken for it: its pid, and its start time as process_start_token reads it.

RecordListing

What list_reporting read, and what it removed on the way past.

RecordScan

What one pass over a running directory found.

RunningGuard

One session’s record, written for exactly as long as the session runs.

RunningRecord

Which process holds one running session, and where its door is when it has one.

Enums

Liveness

What all three layers say about a record.

ProcessState

What layers 1 and 2 say about the process a record names.

SignalOutcome

What sending one signal to a record’s process did.

Functions

control_token_path

~/.murmur/running/<session_id>.control: where a session declaring control: keeps its control token for as long as it runs.

has_controlling_terminal

Whether the calling process has a controlling terminal, which is what decides outlives_launcher: a capsule attached to a terminal dies with that window.

identity_state

Layers 1 and 2 for any process named by pid and start time, record or not.

list

Every record that parses, most recent session first.

list_reporting

list, also naming the unreadable files it removed and the older-mur records it left, for a reader that reports its pruning.

process_start_token

Layer 2’s reading: an opaque, platform-local token for when pid’s process started.

process_state

Layers 1 and 2: the pid is alive, and the process holding it is the one that wrote the record.

prune

Unlink one record, and its control token file if it has one. For a Liveness::Gone reading only.

record_location

~/.murmur/running/<session_id>.json, the record a running session is listed by, resolved as running_dir_location resolves the directory: nothing is created.

running_dir

~/.murmur/running, created if missing and held at 0700, inside a ~/.murmur held at 0700.

running_dir_location

~/.murmur/running, resolved from HOME without creating or re-moding anything.

scan

Every .json entry of dir, read and parsed, with nothing created, re-moded or removed.

signal_kill

SIGKILL the process a record names, if it is still that process.

signal_kill_process

SIGKILL the process identity names, and that process alone, never its group, if it is still that process.

signal_term

SIGTERM the process a record names, if it is still that process.

signal_term_process

SIGTERM the process identity names, if it is still that process.

verify

All three layers, door probe included.