saphan message
Sends and reads messages between coordinating agent sessions, the 'heads' holding the master, scribe or advisor role.
Sends and reads messages between coordinating agent sessions, the "heads" holding the master, scribe or advisor role. A reader is a seat (a machine and identity pair), not a session, so a restarted session keeps its read state; several heads sharing one seat can keep separate read state with --track. The seat is worked out from this process's environment and the machine registry; a seat that does not resolve is refused before anything is read or written. In a workspace bound to a gateway (saphan bridge init --gateway) every message is pushed to the gateway under this machine's certificate and every read fetches first; otherwise nothing is fetched, messages are written locally, and the output says so. Seats with any other role (such as executor, review or design) are refused: they report through their run's return instead.
saphan message list
Fetches from the gateway, then prints this seat's unread messages (no acknowledgement from this seat), newest first; messages addressed to a track are listed only with --track. If the fetch fails, the last fetched state is printed marked STALE and the command exits non-zero.
| flag | type | default | what it does |
|---|---|---|---|
--track | string | The track (a named line of work) this head holds, so unread state is kept per seat and track; declared on the gateway on first use, and a declaration is never released or expired. |
saphan message read
Prints one message and records this seat's acknowledgement in the same act; reading it again writes nothing. Only a recipient can acknowledge a message; anyone else can view it with message show.
| flag | type | default | what it does |
|---|---|---|---|
--track | string | Record the acknowledgement for this head only, leaving the message unread for other heads on the same seat. |
saphan message reply
Sends one answer to a message; the recipient and conversation are taken from the original, never typed. Only a recipient can reply, and exactly one of --body or --body-file is required.
| flag | type | default | what it does |
|---|---|---|---|
--body | string | The reply text. | |
--body-file | string | Read the reply text from this file; an empty file is refused. | |
--measured | string | nothing — every sentence in this message is claimed, not measured | Say which parts of the body were measured rather than claimed; by default everything in it is marked as claimed. |
--resolution | string | done | done (the default), partial (progress reported, an answer still owed) or refused. |
--track | string | Reply as this head (seat and track). |
saphan message send
Sends one message to a seat (machine/identity), to every active holder of a head role (role:<role>), or to every head that declared a track (track:<slug>). Recipients are resolved and fixed when the message is sent; a seat or head that appears later is not a recipient, and an unknown seat, a role other than master, scribe or advisor, or a track no head declared is refused with nothing written. Exactly one of --body or --body-file is required.
| flag | type | default | what it does |
|---|---|---|---|
--body | string | The message text. | |
--body-file | string | Read the message text from this file; an empty file is refused. | |
--measured | string | nothing — every sentence in this message is claimed, not measured | Say which parts of the body were measured rather than claimed; by default everything in it is marked as claimed. |
--reply | string | optional | Whether an answer is required (it stays open in the recipient's tray until answered), optional (the default) or none. |
--salience | string | normal | Mark the message normal (the default) or high. |
--subject | string | The name of the conversation this message opens; derived from the clock when omitted. | |
--to | string | The recipient: machine/identity, role:<role> or track:<slug>. | |
--track | string | Declare this head's own track first, so replies can be addressed back to it. |
saphan message show
Prints one message and, for each recipient fixed at sending, when it was seen, acknowledged and answered. Writes nothing; the sender sees every recipient's row, a recipient sees its own.
| flag | type | default | what it does |
|---|---|---|---|
--track | string | View the message as this head (seat and track). |
saphan message watch
Waits until an unread message for this seat arrives (or exits at once if one is already waiting), then exits with one line naming it; run it as a background task and start it again after each exit. It needs a gateway: in an unbound workspace it refuses. It acknowledges nothing and writes nothing, holding one HTTPS request to the gateway while it waits. Any non-zero exit (an unbound workspace, an unreachable gateway, a refused certificate) means it is not watching.
| flag | type | default | what it does |
|---|---|---|---|
--track | string | Wake only for messages this head owes, never for another head's; the track must already be declared with message list --track, or the watch refuses with message-track-not-declared. |
Global options apply to every command — see Every command.