presence: Bulletin-Driven Terminal Presence#

Renders bounded, focus-gated terminal presence from bulletin ancestor claims.

This module deliberately provides a single render cycle rather than a DECSET 1004 watcher: a background terminal reader could steal keystrokes from the shell. Callers must supply focus state explicitly, so unknown focus safely renders a steady tint.

Manual/window override integration is intentionally an activation gap: this primitive does not inspect or supersede either existing override mechanism.

Render bounded, focus-gated terminal presence from bulletin ancestor claims.

This module deliberately provides a single render cycle rather than a DECSET 1004 watcher: a background terminal reader could steal keystrokes from the shell. Callers must supply focus state explicitly, so unknown focus safely renders a steady tint.

Manual/window override integration is intentionally an activation gap. This primitive does not inspect or supersede either existing override mechanism.

irix.presence.CLAIM_TINT = '#182C20'#

Dark-mode presence tints – kept as hardcoded literals (not palette-resolved, a known disconnect noted during research but not changed here to avoid perturbing the pinned dark rendering; see light_claim_tint/light_pulse_tint for the light pair, which IS resolved from the palette).

class irix.presence.Claim(identity: str, path: Path)#

An active bulletin identity and the absolute path it claims.

irix.presence.light_claim_tint() → str#

Return the light-mode steady presence tint.

Resolved FROM the palette (jade-sheet2) rather than hardcoded, unlike the dark pair – see the module-level CLAIM_TINT/PULSE_TINT comment. Picked for perceptual-role equivalence with the dark pair: sheet2 is the same near-neutral background-wash rung CLAIM_TINT occupies in the dark palette (a quiet, steady ambient marker), and contrast_ratio(light_claim_tint(), light_pulse_tint()) (~1.72) lands within 0.01 of contrast_ratio(CLAIM_TINT, PULSE_TINT) (~1.72) – the dark pair’s own distinguishability, reproduced almost exactly.

irix.presence.light_pulse_tint() → str#

Return the light-mode pulse-peak presence tint.

Resolved FROM the palette (jade-line1) – the “line” rung is the more saturated tier PULSE_TINT occupies (relative to CLAIM_TINT) in the dark palette. See light_claim_tint for the contrast-ratio verification.

irix.presence.light_pulse_tints() → tuple[str, ...]#

Return the light-mode pulse-cycle tints, eased between claim and pulse.

irix.presence.parse_claims(text: str) → list[Claim]#

Extract identity plus the leading absolute where: path from bulletin text.

Relative, home-abbreviated, and malformed paths are excluded because a renderer cannot safely decide their ancestry without guessing at another agent’s context.

irix.presence.ancestor_claim(directory: str | Path, claims: Iterable[Claim], own_identity: str = '') → Claim | None#

Return another claim whose path is an ancestor of directory, if any.

irix.presence.bulletin_claim(directory: str | Path, bulletin_path: str | Path = PosixPath('/home/robbd/ai/bulletin.md'), own_identity: str = '') → Claim | None#

Read a bulletin and find a safe ancestor claim, degrading inertly on errors.

irix.presence.osc11(hex_color: str) → str#

Build an OSC-11 terminal-background sequence without selecting an output device.

Delegates to the same format term.emit_osc11 uses (de-duplication) while staying deliberately device-agnostic: unlike term.emit_osc11 and term.write_tty_bytes, this module never chooses /dev/tty vs stdout on its own (see the module docstring) – render_presence’s writer parameter already has a sensible default (sys.stdout.write) and a background terminal reader is explicitly out of scope here, so unifying device selection too would fight this module’s own design rather than serve it.

irix.presence.render_presence(directory: str | Path, bulletin_path: str | Path = PosixPath('/home/robbd/ai/bulletin.md'), focus: bool | None = None, own_identity: str = '', writer: Callable[[str], object] | None = None, sleeper: Callable[[float], object] | None = None, delay: float = 0.08, mode: str = 'dark') → bool#

Render exactly one safe presence result and return whether a claim matched.

focus=True emits one eased, finite cycle. False and None use one steady tint; the latter deliberately treats unavailable focus telemetry as unknown rather than attempting to discover it from terminal input.

Parameters:

  • directory – Directory to check for an ancestor bulletin claim.

  • bulletin_path – Path to the bulletin markdown file.

  • focus – True for the eased pulse cycle, False/None for a steady tint.

  • own_identity – Bulletin identity to exclude from ancestor matching.

  • writer – Sink for each emitted OSC-11 sequence. Defaults to sys.stdout.write.

  • sleeper – Sleep function between pulse frames. Defaults to time.sleep.

  • delay – Seconds between pulse frames.

  • mode – 'dark' (default) or 'light' – selects the tint pair.

irix.presence.main(*vargs: str) → None#

Render one presence state from explicit arguments and exit.