Runtime files and discovery

Development reference · View source

This section describes where hosts publish themselves. Most people never need it.

Supervising --serve. runyte --serve runs the host in the foreground, for direct supervision or diagnostics. Runyte also uses it internally when attaching to a missing session or restarting one.

Once startup begins, a foreground --serve watches the process that launched it and exits when that process exits.
Linux uses a stable process descriptor when the kernel provides one, and macOS a process event queue, so PID reuse cannot transfer that ownership. If the kernel denies stable observation, Runyte falls back to checking the PID; Linux also detects an unreaped zombie then.
Unix cannot identify an original parent that vanished before Runyte started executing. A service manager launching --serve should therefore keep and stop the Runyte process directly.
Hosts detached internally by Runyte are independent of the launcher and keep serving after it returns.
Detached startup carries the already-resolved workspace identity, so the child never rediscovers a project its parent resolved.

Endpoints.

Endpoint metadata and the Unix-domain socket prefer a valid owner-only $XDG_RUNTIME_DIR, falling back to the workspace state root, with owner-only permissions.
A private user-wide cache registry makes both locations listable. XDG-backed hosts also publish a runtime copy, so a missing or unusable cache does not prevent discovery.
Dead registrations are removed while listing, and stale sockets are recovered when a new host starts.
Graceful retirement also removes the host’s empty private endpoint directory.

The owner-wide inventory exists so an explicit --include-hidden can find hosts started in other isolated Runyte environments.

Each host publishes an owner-private row below non-disposable account state: ~/.local/state/runyte/all-hosts/<boot> on Linux, ~/Library/Application Support/Runyte/all-hosts/<boot> on macOS. The home directory comes from the operating-system account database, not $HOME.
The final directory is keyed by the kernel’s boot identity, so machines sharing a home never overwrite or inspect each other’s PIDs and sockets, and a new boot inherits no stale process identity. This stable, account-owned parent cannot be pre-claimed by another user in the system temporary directory.
If the account home or boot identity cannot be resolved, publishing a new host and explicit hidden-session operations fail with an error rather than using an incomplete inventory.
Ordinary discovery, identity locking, attaching to a running host, and ordinary listing never read or depend on it. Broad listing reads the current environment’s history for display but never rewrites it from hosts found elsewhere.
Scans accept only private, non-symlinked records whose workspace identity, endpoint metadata, live process, and responsive socket agree where process visibility allows. A responsive endpoint is kept when a PID namespace hides its process; one that cannot be observed conclusively is left out without being removed.