Messaging and Inbox

Messaging and Inbox

Messaging is the durable foundation of Pizarra. A successful send receives a monotonic sequence and is written before delivery begins. A send that has not yet been confirmed delivered reports queued; the watchdog retries it.

Do NOT read queued as "the destination is unreachable". It covers four situations: an older message still pending for that team, the team being held, a real delivery failure, and - for every dial-in team - the ordinary path, because the acknowledgement that marks such a delivery arrives later on the reverse channel the host holds open. A dial-in destination is therefore reported queued on every message, including the ones that arrive instantly. The hub says which case it is in the reply's note, and clients should show that rather than infer a reason from the flag.

Direct messages

The selected Tiza configuration determines the sender identity:

TIZA_CONF=/etc/pizarra/agents/builder.conf \
  tiza reviewer "Please verify task 41 against the acceptance criteria."

Destination names and numeric team IDs are accepted:

tiza builder "Start the approved change."
tiza 2 "Review the attached result."

For multiline input, use a file or standard input:

tiza reviewer --file review-request.txt
printf '%s\n' "Line one" "Line two" | tiza reviewer --file -

Message files are capped at 256 KiB. The complete native JSON-line frame is capped at 1 MiB.

Several destinations at once

A destination may name more than one recipient, separated by commas. Elements may be teams, groups, @group or all, mixed freely:

tiza builder,reviewer "Both of you please look at this."
tiza builder, reviewer "Spaces around the commas are fine."
tiza @reviewers,builder "The group and one extra."

Spaces around the commas are absorbed, so the list survives being split by the shell. Until 1.1.41 it did not: tiza a, b msg arrived as the destination a, with the rest of the list swallowed into the message text, and the interactive console refused a list outright because it validated only one name before the hub ever saw the line. The feature worked over the wire and was unusable from both places a person actually types one.

Every element is resolved before anything is stored, so an unknown name refuses the entire send and names the element that failed. This matters: a partial broadcast that reported success would be indistinguishable from a complete one. Repeated names collapse to a single durable copy, and the sender is skipped, so naming yourself in a list does not echo the message back.

Group expansion honours that group's excluded members. A team named explicitly is not subject to any group's mute, because a muted member remains a member everywhere else.

Group and fleet fan-out

Send to every active, non-excluded member of a group:

tiza @release "The candidate is ready for independent checks."

A bare group name also works unless a team has the same name; a team wins that collision. The @group form is unambiguous.

Send one durable copy to every other team:

tiza all "Maintenance begins in ten minutes."

A broadcast expands into separate journal entries per destination. Delivery is not an all-or-nothing transaction; the response reports partial fan-out when some destinations cannot be resolved or accepted.

Journal before delivery

sequenceDiagram
    participant C as Client
    participant H as Hub
    participant J as Journal
    participant E as Endpoint
    C->>H: authenticated message
    H->>J: append and flush
    J-->>H: sequence is durable
    H->>E: deliver
    alt acknowledged
        E-->>H: sequence acknowledgement
        H-->>C: sent
    else unavailable
        H-->>C: queued
        H->>E: retry oldest pending
    end

Loading

This gives durable at-least-once transport. A remote daemon persists the last terminal sequence it injected, so a retry after a lost acknowledgement can be acknowledged without a second paste. Pizarra does not claim exactly-once execution of whatever the terminal program does after receiving the text.

Delivery envelope

The hub can wrap the message with current operational context:

• verified sender and destination;
• sequence and timestamp;
• project and standing instructions;
• team speciality, style, hierarchy, and administrators;
• open tasks and active workflow steps;
• application ownership;
• shared-file locations; and
• exact reply commands.

Header configuration changes presentation for the fleet, not identity or durable journal content.

Reading without consuming

Peek at unread messages:

tiza inbox --keep

Read unread messages and advance through the returned entries:

tiza inbox

Read history, including already acknowledged messages:

tiza inbox --all

pzweb deliberately separates Inbox from History. Looking at durable history must not silently mark unread work as handled; acknowledgement is explicit in the browser.

Human terminal console

Start the live console:

tiza chat

Examples inside chat:

builder: Implement the accepted change and report tests.
@release: Candidate ready; begin your assigned checks.
/send reviewer Inspect task 41
/msg reviewer
First line
Second line
.
/file tester /srv/checks/test-plan.txt

A line containing only . sends a composed message. /cancel abandons it. The console reconnects its watch from the last processed sequence and acknowledges batches only after rendering them.

Use tiza chat --plain for limited terminals or redirected input.

Live watch and gaps

The native watch stream replays visible events after a cursor and then becomes live. A scoped identity may skip global sequence numbers because traffic between other identities is intentionally hidden.

An explicit gap is different: replay history was unavailable, a bounded queue overflowed, a replay cap was reached, or the requested cursor was ahead of known history. Consumers must reload durable state instead of guessing what happened.

The browser feed projects durable messages only. It does not include every native system and task watch event.

Holds and recovery

An operator can keep delivery pending:

tiza hold builder on
tiza hold builder off
tiza fleet

When released, pending messages resume in order. A reliable endpoint activity report may also trigger a configured automatic hold; heuristic activity alarms do not silently stop delivery.

Unknown outcomes

A one-shot client retries only when connection failure happened before the request was written. Once a mutation was written, a lost or malformed reply is an unknown outcome.

Do not repeat the send immediately. Inspect inbox, history, tasks, or workflow state first. This prevents a lost response from becoming a duplicated privileged action.

For exact syntax see the CLI reference and Native Wire Protocol.