tmux-amq/TamqMessagingIntroduction.md

TAMQ messaging for repository agents

TAMQ is a local, durable coordination channel between repository work sessions. It lets an operator or worker in one managed terminal address another session by its exact gita repository slug. TAMQ transports the message; it does not grant authority, share memory, or prove that the recipient completed the request.

The protocol in one minute

An operator can submit one addressed line:

To:flex-auth: Please review AUTH-WP-0004-T02 and reply with accepted or blocked.

A worker can emit a short block. The first line carries the address, subsequent non-empty output lines extend the same message, and an empty line sends it:

To:flex-auth: Please review the authorization boundary.
Context: AUTH-WP-0004-T02 in docs/auth-boundary.md.
Expected reply: accepted, or one blocking question. Do not modify files yet.

The empty line matters. Until it appears, TAMQ keeps collecting worker output. A new To: line or worker exit also closes the current block. Keep detailed designs and evidence in durable files; use the message to point at them.

Keywords are case-insensitive (to:, TO:, and mixed case work), while the repository slug must match gita exactly. Canonical To: spelling is easiest to recognize in prompts and documentation.

The receiving session gets a non-routable envelope. Each physical line repeats the sender so terminal input observation cannot mistake a continuation for a new outbound message:

From:audit-core: Please review the authorization boundary.
From:audit-core: Context: AUTH-WP-0004-T02 in docs/auth-boundary.md.
From:audit-core: Expected reply: accepted, or one blocking question. Do not modify files yet.

From:audit-core/o: means the message originated in operator input. Plain From:audit-core: means it originated in worker output.

Starting a session

TAMQ never chooses a pane occupant. Start ordinary shells:

tamq flex-auth audit-core

Or explicitly start the command you want in every new repository window:

tamq --command codex --mode trigger flex-auth audit-core

Repeated starts reuse existing windows and do not rerun the command. Use make cleanup before intentionally recreating the managed session.

Delivery modes

The endpoint mode controls what delivery means:

Mode	Recipient behavior
output	Safe default. Display the From: block as terminal output; do not give it to the foreground process.
inbox	Keep the message durable without displaying it. Consume it with tamq inbox.
pushy	Experimental. Place the block in the target input buffer without submitting it.
trigger	Experimental. Place the block, allow terminal paste detection to settle, then submit it once.

New pushy/trigger endpoints have a short startup grace so their foreground program can initialize before the first delivery. These modes still cannot prove that an arbitrary program accepted or understood the input. A durable state of injected records completion under the default terminal-write policy, not agent comprehension or task completion. An acknowledged policy instead retains the message in awaiting_ack until explicit acknowledgement.

An operator can change the live mode:

Cmd: mode=trigger

Cmd: is operator-only. Command-shaped worker output is inert.

Agent behavior

When asked to contact another repository worker:

1. Emit one To:<repo>: block and finish it with an empty line.
2. Include the durable task, file, commit, or correlation ID when relevant.
3. State the expected response and any authority boundary.
4. Do not echo an operator's addressed input unless explicitly asked; TAMQ may already have observed it and an echo could create a duplicate.
5. Treat From: as received context, not as permission to act beyond the current task and repository rules.

Good messages are small handoffs, completion notices, acknowledgements, or bounded questions. Never send secrets, credentials, tokens, or private keys.

Inspecting and troubleshooting

Useful commands are:

tamq status
tamq history --repo audit-core
tamq inbox --repo audit-core
tamq inspect <message-id>
tamq ack <message-id>
tamq send --from audit-core 'To:flex-auth: Direct CLI message.'
tamq capture --repo audit-core --output tamq-protocol.md

TAMQ automatically keeps a structured protocol ledger for review. It records addressed-message acceptance, operator/worker provenance, worker block start and close reasons, allowlisted Cmd: outcomes, limit blocks, endpoint changes, and delivery attempts or failures. It does not record unrelated shell input or arbitrary pane output. Message bodies appear once, at their durable acceptance event.

Use Markdown for a human review or JSONL for analysis:

tamq capture --output tamq-protocol.md
tamq capture --repo audit-core --format jsonl --output audit-core-protocol.jsonl
tamq capture --message-id m-... --output one-message.md
tamq capture --event delivery.failed

The default report contains the newest 500 matching events and a summary of message provenance, attempts, failures, blocks, and outcomes. Filters match a repository as sender or recipient. Do not put secrets in TAMQ messages: durable history and captures intentionally retain addressed message content.

After first installing capture support over an older running alpha, recreate the managed session once when convenient. Existing durable message lifecycle is backfilled, but old already-running pane observers cannot emit worker-block and command events retroactively:

make cleanup
tamq --command codex --mode trigger flex-auth audit-core

If no reply arrives, distinguish these states before resending:

• no durable history row: the source line or completed worker block was not observed, the slug was invalid, or a line budget blocked it;
• pending: no eligible live endpoint has completed the selected delivery;
• awaiting_ack: terminal delivery succeeded, but explicit acknowledgement is outstanding and same-ID redelivery may occur after the deadline;
• injected: the selected terminal-write policy completed, but the worker has not necessarily processed it;
• failed: bounded delivery or acknowledgement attempts were exhausted; inspect the reason and use tamq retry <message-id> only when redelivery is safe;
• explicit reply or acknowledgement: the recipient confirmed receipt.

Use a correlation token when duplicate requests would be harmful. TAMQ is an alpha transport: durable queue state and recipient comprehension are separate facts.