Module registry 

Structs

DaemonPaths

Files the synaps daemon keeps under registry_dir() (0700). One daemon per profile: daemon.{sock,lock,json,pid} or daemon-<P>.{…}.

SessionEndpoint

Owns a bound, published generation and its captured runtime directory. A timestamp/hash collision fails binding without replacing the prior socket. Unix lock-contention leftovers are repaired on the next successful scan; Windows card cleanup under contention requires retry or own-PID reload sweep. No asynchronous task can bind after this guard is dropped.

SessionRegistration

Constants

REGISTRATION_KIND

Discriminator written into every registration so the registry can tell its own files from other *.json sharing the run dir (daemon.json, tooling drops). Files missing it (older binaries) are treated as sessions.

Functions

daemon_paths

Daemon file paths for a profile, under registry_dir().

daemon_paths_in

Same, rooted at an explicit dir (tests; --socket overrides only .sock).

find_session_registration

Resolve a query to a registration. Resolution order:

list_active_sessions

Read all registration files, prune stale ones (dead PID), return live set.

register_session

Write {session_id}.json atomically (tmp + rename). Chmod 0600 on Unix.

registry_dir

Returns the session runtime directory, creating it mode 0700 if needed.

sanitize_session_id

Sanitize a session ID for safe use in filenames and socket paths. Rejects path separators, .., and non-printable characters. Returns the sanitized string (replaces unsafe chars with _).

socket_path_for_session

Returns the legacy Unix socket path for a session. Active endpoint clients must read SessionRegistration::socket_path: new endpoints use bounded generation names, not this pre-publication helper. Sockets live in the registry dir — $SYNAPS_RUNTIME_DIR when set (e.g. /run/user/<uid>/synaps), otherwise $SYNAPS_BASE_DIR/run (default ~/.synaps-cli/run/) — which is user-owned and mode 0700, avoiding /tmp symlink squatting and TOCTOU races.

sweep_stale_registrations

Remove registrations that no running session can own and return how many were removed. Always: an owner pid that no longer exists. With own_pid (the daemon, at startup): also registrations naming that pid, which can only be leftovers. A reload re-execs the same pid without running any session’s shutdown, and the new image has not registered anything yet when it sweeps.

unregister_owned

Remove reg’s registration and socket, but only while the file on disk is still this exact registration (same owner pid, start time and socket).

unregister_session

Operator removal by ID (not owner-scoped). No runtime teardown uses this. Remove only a valid matching registration. Best-effort — never panics. Also removes the socket file at socket_path if it exists.

update_session_name

Rewrite {session_id}.json with a new name (rename / saveas). The rest of the record (socket, pid, started_at) is kept. Errors when there is no registration to update.