Module pins 

Pinned sessions come back after the daemon restarts.

The pin book (<config dir>/daemon-pins.json) is the set of pinned journals for this profile. It is written through, never by a timer: the actor calls PinBook (as the host’s PinSink) when the pin changes, when a pinned session moves to a new journal, and when a pinned session is ended on purpose. A daemon stop, reload or crash leaves it alone, and the next cold start continues every entry that is not live and pins it (restore_all). SYNAPS_DAEMON_RESTORE_PINS=0 starts without that.

The file lives in the config dir, not the run dir: older binaries unlink run-dir json they cannot parse, and the run dir may be tmpfs. Entries are parsed one at a time, so one bad (or newer) entry never loses the rest; an entry this build can’t read is written back untouched, and a file from a newer schema version is read-only here.

Structs

PinBook

The pin book of one config dir. Every change is a locked read-modify-write (<file>.lock), so the daemon and a CLI clearing an entry never lose each other’s writes.

PinEntry

One pinned journal. Never carries SessionConfig or settings.

Enums

Restored

Outcome of one restore, for logs and daemon pin.

Constants

FILE_VERSION

HELD_RECHECK

A journal held by an exiting process gets this long, once.

MAX_ATTEMPTS

Restore attempts the daemon did not live through before an entry is given up as a crash loop (marked failed, not retried).

PINS_FILE

RESTORE_CREATE_TIMEOUT

One restore’s create budget (MCP servers, extensions).

RESTORE_ENV

0/false/off/no: start the daemon without restoring pins.

STATE_FAILED

STATE_WAITING

Functions

live_for

The live session for a journal, if this daemon holds it (a lock placeholder does not count).

offline

Entries that are not live in this daemon: what listings show as waiting / failed / not restored yet.

pin_offline

daemon pin for a journal that is not live here: --off drops its entry, on restores it now (a fresh try: the crash marker is reset). None when the book has no such entry.

resolve_entry

daemon pin <ID|NAME> against the book: exact journal id, a unique name, or a unique journal-id prefix of at least super::close::MIN_PREFIX_LEN characters.

restore_all

Cold start: restore every entry not already live, one at a time (so the crash marker names the one entry in flight), after the daemon is ready. Holds the idle exit while it runs.

restore_enabled

SYNAPS_DAEMON_RESTORE_PINS is not off.

restore_one

Continue one entry into this daemon, pinned (synaps --attach --continue <id>’s create). Never steals a held journal; the attempt marker is on disk before create, so a daemon that dies inside it does not try again forever.