Module retire 

retire — decommission a wire identity you’re done with, reversibly.

The daemon supervisor keeps a daemon alive for every real identity (one with a private.key) so it can still receive mail — so an idle throwaway identity’s daemon can’t just be killed: the supervisor respawns it within one poll. “Retiring” writes a durable .retired marker that makes the supervisor treat the home as ineligible (it kills the child and never respawns — see daemon_supervisor::supervisor_eligible), then stops the running daemon directly.

Reversible by construction: the marker is the ONLY state change. The home, identity keypair, relay slot, and pull cursor are all kept, so revive (remove the marker) brings the identity back intact and it drains any mail that arrived while retired (relay slots never expire; mail is retained).

is_retired is a pure existence check so a torn write can never flip an identity back to “not retired”. CLI-only: an agent must not retire another identity’s daemon unsupervised (mirrors wire nuke).

Structs

RetiredMarker

Constants

MARKER_SCHEMA

Functions

current_home

The session home THIS process resolves for itself (honoring WIRE_HOME / session-key). Used to guarantee we never retire the current identity — compared by canonical home path, since resolve_session_key() is None on a bare terminal. None if it can’t be resolved (caller must fail closed).

has_pending_inbound

True iff the home has any pending inbound pair request awaiting wire accept (state/wire/pending-inbound-pairs/*.json). Such a home has 0 pinned peers but is NOT idle — a peer is actively trying to reach it — so the bulk sweep must never retire it.

identity_age_s

Seconds since this identity was created — the mtime of config/wire/private.key, written exactly once at keygen and never rewritten. This is the honest “how old is this throwaway” signal: unlike daemon.pid (which resets to now on every supervisor respawn) or last_sync.json (which a running daemon refreshes every heartbeat), the key’s mtime tracks the identity’s actual age, so a freshly-created sibling session is never swept. None if no key (not a real identity).

is_current

True iff home is the current process’s own identity home.

is_retired

Pure existence check — never parses the body, so a partial write can’t read as “not retired”. The supervisor eligibility filter keys on this.

marker_path

<home>/state/wire/retired.json.

read_marker

Best-effort read of the marker body for display. A parse error is treated as retired-with-unknown-details (fail closed), never as not-retired.

resolve_target

Resolve <handle|fingerprint|key> to exactly one local session, box-wide over list_sessions(). Many idle homes never claimed a handle, so the key (by-key dir name) and fingerprint are also accepted. Errors on zero or multiple matches — never guesses.

retire_session

Retire a session home: write the marker FIRST (so the supervisor won’t respawn), then stop its daemon via the injected stop fn. Returns the pid that was stopped, if any. Idempotent — re-retiring just rewrites the marker.

revive_session

Bring a retired identity back: remove the marker; the supervisor respawns its daemon on the next poll. No-op if not retired.

stop_daemon_graceful_then_force

Stop a daemon by pid, graceful then force. Mirrors the wire upgrade fix: a bare SIGTERM / taskkill /PID (no /F) is a no-op for a headless daemon on Windows, so escalate to SIGKILL / /F if it’s still alive after a grace.