Module msg 

Messages between sessions: <store>/messages.jsonl, one line per borg tell or borg ask, from a session on any harness (or the engineer’s terminal) to the sessions on this machine (local, written local@<node>), every session of the collective on every member’s machine (collective, or its synonym all, written all as it always was), one session on one node (<session>@<node>), or the engineer (engineer[:<email>]): an Address, parsed in one place. Local first: a local line never leaves this machine (borg-mesh lines.rs travels keeps it here), and a drone named on the command line is this machine’s when one here matches; a colleague’s session is reached by its node, by collective, or as the sender of what a reply answers. A 0.4.0 reader parses local@<node> as the session local of that node, which no session is: it reaches nobody there. Plain lines, each naming its node, so the mesh can union them like the other synced logs; on one machine they need no mesh. A borg pause, borg resume or a remote borg no is a message too, of a privileged Kind that counts only under an admitted role (steer.rs).

A drone named on the command line (a designation as borg top shows it, or a session id prefix) is resolved to its session id when the message is sent: designations (“Two of Five”) shift as sessions start and end and differ per node, a session id does not. A line’s by, name and harness are its sender’s claims; only its node is checked (borg-mesh lines.rs travels), so a session is addressed with its node, and a reply goes to the (node, by) pair of what it answers (address): a by that names a local session from another node never routes a reply here.

Delivery (deliver): a recipient’s next prompt or tool call, where its harness takes context there (harness Caps), shows each message once, as labelled peer data with the command that answers it, never as the user’s words, never to its sender. At most PER_EVENT messages and EVENT_CHARS of their lines per event, newest first; the rest stay unclaimed for the next event. A broadcast reaches the sessions that were running when it was sent (as steer.rs applies). A delivery is claimed by creating <store>/messages/seen/<session>/<id> exclusively, so hooks running at once show it once. Nothing sent: the hook costs one failed stat; a log unchanged since the session’s last look, a read of its SCANNED stamp more. A prompt whose context the harness drops ("context": false) and a subagent’s event (agent_id) show nothing: the messages wait for the session itself.

Every line is checked on read (Message::well_formed): the log syncs from every member, and its fields reach prompts, a shell command and terminals. Text is redacted (notes.rs redact) and cut before it is hashed into the id. One message per sender and recipient per RATE_MS. Bounded on write: a line past TTL_MS goes, and at most the KEEP newest stay, byte for byte as they were.

Structs

Message

One line of messages.jsonl.

Sender

Who sends a message.

Shows

How one event shows its messages: to whom, on which harness, under which steering roles.

Enums

Address

Whom a message is for, as its to says it (parse; Display writes it back).

Kind

What a message does. Tell and Ask are conversation; Pause, Resume and Veto steer their recipient and count only under an admitted role (steer.rs). A line of any other kind does not parse.

NoSteer

Why this node’s steer would not count on another node: borg-mesh steer.rs check on its own key.

SendError

Why a message was not sent.

Constants

ALL

Every session of the collective on every member’s machine (Address::All): the command word, a synonym of COLLECTIVE, and how a line writes it.

ASK

A message that asks for a reply.

COLLECTIVE

The command word for every session of the collective (Address::All, written all).

ENGINEER

The engineer’s terminal as sender and address: engineer:<git user.email>, or this alone.

EVENT_CHARS

The most characters of message lines one prompt or tool call shows, as a live check reads of the turn (hook.rs LIVE_WORK_CHARS): about three full texts. The first message always fits.

FILE

The log, in the collective’s store.

FLAGS

borg tell and borg ask’s flags (completions.rs).

INBOX_FLAGS

borg inbox’s flags.

KEEP

The most lines the log keeps: the newest.

LOCAL

The command word for the sessions on this machine (Address::Local, written local@<node>).

NAME

The longest sender name a label shows, as steer.rs NAME_MAX.

PER_EVENT

The most messages one prompt or tool call shows: one conscience block (hook.rs MAX_PENDING).

RATE_MS

One message per sender and recipient this often: a third of presence’s IDLE_MS.

SKEW_MS

How far ahead of this clock a message may be and still count (clock skew between members).

STEER_FLAGS

borg pause and borg resume’s flags.

TELL

A message that informs.

TEXT

What a message keeps of its text: at most this many characters, plus an ellipsis when cut (as steer.rs TEXT_MAX).

TTL_MS

A message is conversation: shown and kept for a week.

USAGE

Functions

deliver

The hook’s call after everything else answered (out): at a prompt or tool call where the harness takes context, the messages for the event’s session not shown yet join the answer’s context, each once. A block (decision) answers the event alone, a prompt sent with "context": false (opencode during a stop) drops what borg answers, and a subagent’s event (agent_id: Claude gives its context to the subagent) is not the session’s: the messages wait. At most PER_EVENT and EVENT_CHARS (capped), newest first; the rest wait, and the session’s SCANNED stamp is not written while any does. started: the session’s start (presence.rs); None still delivers messages to the session but no broadcast.

for_session

The conversation of msgs (tells and asks; a steer is deliver’s alone) for session of the node here (started at started) at now, oldest first.

forget_session

Removes the delivery claims of one session (its presence record was pruned).

fresh

Whether m counts at now: not past TTL_MS, not further ahead than SKEW_MS.

is_engineer

Whether the address or sender a is the engineer: engineer or engineer:<email>.

is_id

Whether s is a message id as id_of writes it.

main

borg tell|ask|pause|resume|inbox ….

node

This node as a message names it: the member key borg-mesh publishes (node_pub_path), which the mesh checks a message’s node against before it carries it, else (no mesh yet) the stats.rs node.

node_pub_path

<store>/mesh/node.pub: where borg-mesh publishes this node’s member key (its identity.rs public_path is this).

path

read

Every well-formed message of the store, in file order: unparsable, newer and forged lines skipped.

render

The block of messages, with the reminder of what they are.

seen_by

Every id shown, with the sessions (as file names) it was shown to (top.rs, borg-web).

seen_path

Where the shown-once claims live, one directory per session (a watch on it sees deliveries).

send

Sends m from the store home at now: refused when every reader would drop it or its sender sent one to the same recipient within RATE_MS (a steer is never rate limited: a pause is answered by a resume). The write keeps the log bounded (bound). A steer from this node is admitted first, as Role::Local (steer.rs), so a reader that sees its line sees it count.

sender

The sender: from, else the calling session (caller), else the engineer.

steer_right

Whether a steer from me counts on another node: under the role the held membership gives it, admin or steer (steer.rs Role::of_member), as each receiver checks at admission. The document is read unverified: the mesh verified it when it saved it, and every receiver checks again, so this only spares the sender a false report.

unread

How many of msgs (as read gives them) are for session of this node here (started at started) and not shown to it yet: what its next prompts or tool calls would show.