Each Task has one ordered Task mail history, and a-stack keeps all of it. Only the current assignees of the Task can send mail, read mail or get back the receipt of a send. The Orchestrator must be assigned to the Task too. The Operator credential gives no mail access, except that the Operator's answer to a Needs you question is sent as Task mail, as described in The Operator's answer. A browser view credential can only read the Task mail of its own Session, as described in Browser reads.
Every mail command needs an Agent credential and --workspace ID --session ID. A credential file that names its Workspace and Session gives them (see Credential context). If you use a different state directory, add the same --state-dir to every command.
These examples use the Agents and the assigned Task from Workspaces, Sessions and Agents and Tasks and the Task graph.
a-stack mail send --as agent --credential-file "$worker_a_credential" \
--workspace "$workspace_id" --session "$session_id" --task "$task_id" \
--body 'Ready for review, @worker-b.' --mention worker-b \
--operation-id mail-review-1 --json
a-stack mail send --as agent --credential-file "$worker_a_credential" \
--workspace "$workspace_id" --session "$session_id" --task "$task_id" \
--body-file message.txt --operation-id mail-details-1 --json
a-stack mail read --as agent --credential-file "$worker_a_credential" \
--workspace "$workspace_id" --session "$session_id" --task "$task_id" \
--limit 100 --json
# Save data.cursor. Give it in the next read to continue this Task's history.
a-stack mail read --as agent --credential-file "$worker_a_credential" \
--workspace "$workspace_id" --session "$session_id" --task "$task_id" \
--cursor "$mail_cursor" --json
a-stack mail check --as agent --credential-file "$worker_a_credential" \
--workspace "$workspace_id" --session "$session_id" \
--cursor-file /private/worker-a/mail.json --json--body-file - reads the body from stdin. You cannot use it together with --body. A body must not be blank, must be valid UTF-8 and can be 65,536 bytes at most. For larger documents or results, use Task file references. a-stack rejects a body that is too long. It never cuts it. Mail counts toward the sender's write budget: about 127 sends of maximum size at once, then about 16 a minute. --mention NAME takes a name without @. You can repeat it.
Run a-stack mail wait --cursor-file /private/worker-a/mail.json with your Agent credential to wait for addressed mail. Use the same cursor file as mail check. A harness can run this command in a background tool and notify the Agent when it exits.
- By default, unread mentions of you, urgent mail, acknowledgement requests for you and Operator answers wake the wait. Other Agents’ status chatter does not.
--allwakes on any new mail on your assigned Tasks, but never your own mail. --cursor-file FILEis required; stdin (-) is not supported. The file may be missing. Wait never creates or advances it, and matching unread mail already present returns immediately. Runmail checkafterwards to read the mail and save your positions, then restart the wait while workers are active.--timeout DURATIONtakes a positive duration such as10mor1h; the default is30m.- Exit 0 prints JSON with
data.countanddata.tasks[], each withtask_idandcount, for matching messages on the returned page. This is a wake hint, not a complete inbox count. Exit 5 prints error codemail_wait_timeout. Restart after a timeout if workers are still active. A closed Session returnssession_closed; a revoked credential returnsunauthorized. Handle those errors instead of restarting blindly. - Wait uses existing Session and mail reads with
peek, so it does not re-arm notices, clear unread-mention waits or acknowledge mail. It holds scan positions only in memory. Polls start 5 seconds apart and back off to 30 seconds;rate_limitedcan request a longer delay throughretry_after_seconds. The timeout bounds those delays and network reads.
mail reply --message ID --body 'Your reply' --operation-id ID sends to the original message's Task in your authenticated Session. It is shared Task mail, not a private reply. The response includes the Task title and ID and says shared with all current assignees. You must still be assigned to that Task. A conflicting --task is rejected; body text cannot change the destination. --body-file works as with mail send.
The original sender is mentioned automatically if they are still an assignee. An Operator answer has no Agent sender to mention. Use --no-mention-sender to skip the automatic mention, or repeat --mention NAME to mention additional current assignees. Body mentions still apply. The same operation-ID and retry rules as mail send apply; retries keep the original receipt and resolved mentions even if the original sender leaves. Task titles in reply output reflect the current title.
Run mail recipients --task T to see the current assignees who can read a message and be mentioned, without sending anything. You must be assigned to T. This is a preview, not a reservation: the send checks membership again in its transaction. The Orchestrator receives mail only when assigned too.
Any current assignee can add --urgent to mail send or mail reply. Use it rarely: a stop request, a blocker or a contract change that the recipient must read before continuing. Mail retains priority: "normal" by default or priority: "urgent"; priority is part of retry identity and is never inferred from text. It changes scheduling, not authority or permissions.
Urgency needs installed, enabled and enrolled mail hooks. At eligible tool-result or prompt boundaries, they check urgent references without the normal 30-second delay. Each successful poll emits at most one fixed, body-free nudge. This does not interrupt a running tool or guarantee when the next boundary occurs. Herdr's one-pending-notice rule is unchanged; hookless Agents keep ordinary mail checks and notices.
New Operator Needs you answers are urgent automatically. Overdue acknowledgement reminders are urgent to hooks too, without changing the original message's priority or creating a new message. Reading a notice never acknowledges a message.
When a question blocks an Agent, send it with --ack-required, mention the assignee who must answer, and set the Task to Waiting with a reason naming that Agent. A mention is not proof of receipt.
Task reads include mail_waits: the oldest unread current mention per sender and recipient, with names, receipt time, elapsed minutes and stalled. Each response includes at most 100 groups, oldest first. “Unread” means the recipient has not made a successful own mail read since the message arrived; it does not mean every returned page was understood. The timestamp is per Agent, not a per-Task cursor. Browser reads, another Agent's reads and failed reads never update it. A successful own mail check, mail read or task handoff clears earlier waits without acknowledging them. Removal and rejoining do not revive old waits.
After 30 minutes the Now board, watch and notification status show Stalled. Mention notices describes the one extra notice after 10 minutes. Neither creates a Needs you question.
Use --ack-required on mail send or mail reply when a handoff needs an explicit response. By default every mentioned current assignee except the sender must acknowledge, including the automatic reply mention. Self-mentions and selecting yourself with --ack-from create no acknowledgement obligation. Repeat --ack-from NAME to select particular current assignees instead; these names also receive a mention. An empty recipient list is rejected. --ack-due 30m sets an optional deadline measured from the send. It accepts a positive Go duration, such as 30m or 2h, up to 2562047h47m16.854775807s; larger values are out of range; both acknowledgement options require --ack-required.
# Add the normal credential, Workspace and Session flags.
a-stack mail send --task "$task_id" --body 'Please confirm this handoff.' \
--ack-required --ack-from worker-b --ack-due 30m --operation-id handoff-ack-1
# worker-b acknowledges explicitly:
a-stack mail ack --message "$message_id" --operation-id handoff-ack-response-1Only a selected current recipient can acknowledge. The service records that Agent's ID and the time. Repeating an acknowledgement does not change its recorded time, even with a new operation ID. Reading, advancing a cursor, submitting a notice, another assignee's acknowledgement, replying, and finishing the Task never acknowledge on your behalf. An acknowledgement means the recipient explicitly accepted the message, not that the work succeeded. It grants no permission and never gates Task completion or opens Needs you.
Unassignment permanently withdraws outstanding obligations, even after the Agent rejoins. Closed Sessions allow retained reads and matching receipt recovery, but no new acknowledgements. Message reads include acks: recipient ID and current name, optional due_at, and either acked_at or withdrawn_at when resolved. The recipient ID is the acknowledgement actor; names are not authority.
mail check always includes the caller's own pending_acks, independently of mail cursors, even when tasks is empty. mail read and task handoff list pending obligations for that Task. These summaries hold at most 500 obligations, with more_acks: true when more exist. To inspect every obligation, page through mail read and inspect each message's acks. Acknowledging the listed requests also lets later pending requests appear in the next check. more and more_acks are separate: do not loop on more_acks expecting a mail cursor to consume it.
The Now board shows overdue counts as read-only text. With Herdr enabled, overdue obligations share the existing mention-notice path. Each obligation can submit at most one overdue reminder; known pre-submission failures may retry, while uncertain submissions are never retried automatically. Reminders contain no body and create neither new messages nor new acknowledgement requests. Acknowledging or withdrawing an obligation suppresses any reminder not yet submitted. Like other notices, a reminder already in the external input queue cannot be recalled.
All endpoints take authenticated POST JSON under /v1/mail/. They use the same instance, Host, Origin and strict JSON checks as the rest of the HTTP API. The context fields are workspace_id and session_id.
| Endpoint | Other request fields | data in the response |
|---|---|---|
send |
task_id, operation_id, body, optional priority (normal or urgent), mentions array of names, ack_required, ack_from array and ack_due duration |
A compact receipt: the message resource_id and body_ref, the sequence number in revision, and outcome: "sent" |
reply |
message_id, operation_id, body, optional priority, task_id, mentions, no_mention_sender, ack_required, ack_from and ack_due |
The send receipt plus task_id, task_title and audience |
ack |
message_id, operation_id |
A receipt with the message resource_id and outcome: "acknowledged" |
recipients |
task_id |
task_id, task_title, audience and recipients (Agent IDs and names) |
read |
task_id, optional cursor and limit |
task_id, messages, cursor, more, and total when nonzero |
check |
optional cursors map, after_task, task_limit, limit and peek (hooks and mail wait; does not re-arm notices) |
A tasks array of read pages, next_task when more Tasks follow, and more |
The hook-only urgent endpoint takes optional positions and after_task. It returns at most 100 assigned Tasks' body-free high-water marks, next_task, and an urgent boolean covering new urgent mail or overdue ACK reminders. Follow the continuation to complete a round. Only Agent credentials can use it. It changes no server state; normal mail checks and browser reads do not consume these marks.
Each message has priority, id, task_id, sequence, sender_id, sender_name, received_at, body and mention_ids. sender_name is the sender's current Agent name. mention_ids is the sorted list of the resolved Agent IDs. The sequence increases inside one Task. The service sets the sender and the UTC receipt time.
Mail does not change the Task's progress or the Task revision. A send raises the Session read revision, because the Task data has mail_count, the number of messages. Mail bodies never appear in Task details, Task history or browser snapshots.
The browser view credential can use read for any Task of its own Session, also a Task with no assignee. It gets the same messages, cursor and limits as an assignee. It cannot use send, reply, ack, recipients or check, and it gets forbidden for another Session. A browser read stores no read position, writes no receipt and makes no notice. The Operator CLI credential still has no mail access.
a-stack answer, and the answer box of the browser view, send the Operator's answer to a Task's Needs you question as Task mail. The message has sender_kind operator, sender_name Operator and an empty sender_id. It mentions every current assignee, so each gets a notice, and it reaches each Agent through mail check like other mail. The Operator cannot send any other mail, and still cannot read mail with the CLI.
A read does not remove or mark anything. If a Task has no cursor or an empty one, the read starts at the first message. This is also true for a new assignee or an assignee that rejoins.
A returned cursor points to the last message that the response actually contains. An empty page keeps the same position. more: true means that more retained messages follow that position. Cursors are opaque keyset positions for one Task. a-stack rejects a malformed cursor, a cursor of a different Task and a position that does not exist. If you lose a cursor, the next read starts again from the first message.
mail read and mail check return 100 messages by default. Use --limit with a value from 1 to 500. A response can hold 768 KiB of encoded data, which leaves space below the response limit of 1 MiB. So a page can contain fewer messages when they are large. A body of maximum size with JSON escapes and 500 resolved recipients fits in one response. A cursor never moves past a message that the response does not contain.
task handoff --task T shows a bounded mail excerpt. For an assignee, its JSON includes first_sequence, last_sequence, earlier_messages, total, cursor and more. Zero-valued ranges and earlier counts are omitted. The text says how many earlier messages are not shown. Continue after the excerpt with its cursor; read from the beginning without a cursor to recover earlier messages. Large messages can fill the byte budget before the tail ends, in which case more is true. A handoff changes no saved mail position and makes no acknowledgment.
mail check includes one notice_warning (reason and fix) when the caller's mention notices are unavailable or uncertain. An unresolved_uncertain count keeps earlier uncertain notices visible after a later successful submission. It uses retained notice states, the stored binding and last delivery diagnostic, not a new Herdr request. Mail still works. See Diagnostics.
mail check reads the caller's current Tasks in Task ID order. It reads 50 Tasks by default. Use --task-limit with a value from 1 to 100. The message limit and the size limit apply to the whole response.
more: true in the response means that more mail is waiting than the response holds: a Task's page has more: true, or next_task is set.
mail check --cursor-file FILE keeps your positions in a file that you own. Before fetching mail or printing a page, the check verifies that the cursor folder exists and is writable and that an existing cursor is a regular file. It then reads the file, fetches mail, writes the complete response to stdout, and only then saves the returned positions. A failed or short stdout write leaves the file unchanged. A crash before the save can replay the batch. Run the command again while the output has more: true. The service stores no read position; the file is yours.
A successful stdout write is not proof that a harness delivered its tool result or that an Agent understood it. This is an output checkpoint, not an acknowledgment. To replay history after a lost tool result, use a new cursor file or mail read without a cursor.
- The CLI creates the file if it is missing. It writes a temporary file with mode 0600, syncs it and renames it over the old one, so a crash never leaves half a file. The folder must exist.
- If two checks write the same file at once, the last write wins. The other check's mail then shows again in the next check. Nothing is lost.
- The file is a JSON object with Task cursors and reserved keys
identity,next_taskandpartial.identitybinds it to the database, Workspace, Session and Agent credential without storing the credential. A mismatched or older unbound file is refused. Use a new file to replay retained mail after upgrading or replacing a credential. The file can be 1 MiB at most. - The next check continues after the last scanned Task, even when that Task still has mail. At the end of a round it returns to the first Task.
partialkeepsmoretrue until an earlier partial Task can be revisited. For a fixed set of N assigned Tasks, a round takes at most N successful checks; continuous traffic on the first Task cannot starve the others. Changes to assignments start appearing by the next round. This bound assumes the same file, no manual--after-taskoverride and no competing writers. - With a cursor file, the output lists only the Tasks with new mail, and no
next_task."tasks": []means that this page has no new mail; keep checking ifmoreis true. - If the check rejects a saved cursor, for example after a database restore, delete the file. The next check starts again at the first message.
mail check checks a cursor only when it reads that Task, and it ignores the cursors of Tasks that you are no longer assigned to.
Without --cursor-file, every check starts again at the first message of every Task. It stops at the message limit, so on a busy Task you never see the newest mail, and each check shows old mail again. When more is true, the output then has a hint. --cursor-file - reads a cursor map from stdin and never writes anything; then merge the returned tasks[].cursor values into your map yourself, and follow next_task with --after-task.
A scan continuation belongs to one Session and one caller. Tasks that you were removed from in between do not appear. If you are assigned a new Task that comes earlier in the scan order, it appears in the next round. The server keeps no per-Task read positions. It retains only the Agent's latest successful own-read time for unread-mention warnings. Explicit acknowledgement obligations are separate from reading.
A mention name follows the Agent name rules: 1 to 64 ASCII letters, digits, underscores or hyphens, and it starts with a letter or digit.
In a body, a mention starts with @. The @ must be at the start of the text, after white space, or after opening punctuation such as an opening quote or <. The mention takes the full name, so @worker-b-extra never mentions worker-b. Email addresses do not mention anyone, also with a quoted local part. For example, person@worker-b.example and "person"@worker-b.example do not mention worker-b, but Ask "@worker-b" does.
The parser does not use Task membership. After parsing, each name from the body and from --mention must be a current assignee of the Task. Otherwise a-stack rejects the whole send. The error names each mention that is not an assignee and lists the current assignee names, for example mention target must be a current Task assignee: @ghost is not a current assignee of this Task; assignees: 02-worker, 03-worker; run mail recipients --task TASK_ID; write other names without @. It lists 20 names at most.
Names from the body and from --mention are counted once each. One message can mention 500 different recipients at most, so that the attribution in a response stays bounded. Repeated names do not use more places. a-stack stores the resolved Agent IDs. So if a name is used again later, old messages still point to the original Agent. A mention of yourself is stored with the state self and makes no notice.
When an Agent is unassigned from a Task, it loses read access, send access and receipt replay for that Task immediately. In the same transaction, a-stack suppresses that Agent's pending and submitting notices for the Task. If the Agent rejoins, it can read the full history again, including the messages from while it was away. Its suppressed notices stay suppressed. Messages that it sent stay in the history.
Finishing or cancelling a Task does not end its mail. A closed Session still allows authorized reads and the recovery of matching receipts within 30 days, but it rejects new mail.
Choose an operation ID before you send, and keep it. If a response is lost, or the service restarts, send the same unchanged request with the same ID. For 30 days it returns the original receipt, if the sender still has read access. A changed payload causes a conflict. After that, the same ID returns operation_expired, without sending again. The message and its history stay. Read the Task mail to establish the result before choosing a new operation ID; blindly changing the ID could send twice. After the Session is closed, a retry can still recover a committed send, but a send that was never committed stays rejected.
The body, the sequence number, the resolved mentions, any acknowledgement obligations and the compact receipt commit together. If a write fails, or the process crashes before the commit, none of them becomes visible. Reads, membership changes and closure run in order with sends, inside the SQLite transaction.
Schema version 4 adds two tables:
mail_messageshas one row per message, with a unique(task_id, sequence).mail_mentionshas one row per message and recipient, with a foreign key to the message. A trigger checks that the row names the message's Task. Each row is also a compact durable outbox entry for a notice. It contains no body.
Schema version 8 rebuilds mail_messages as a rowid table, so a long body is stored in the table page instead of an overflow page of its own. Before, a foreign key to the message ID and the Task ID needed a second unique index on (id, task_id); the trigger does that check with the primary key.
Schema version 9 rebuilds mail_messages with a sender_kind: agent, with the Agent in sender_id, or operator, with no sender_id, because the Operator is no Agent. Reads of an Operator message give sender_kind: "operator", an empty sender_id and the sender_name "Operator". Agent mail has no sender_kind in reads and reads the same as before.
A mention row has a notice state: pending, submitting, submitted, uncertain or suppressed, or self, which makes no notice. state_at records the time of the last state change. The pending index starts with the state, the recipient and the message. The membership index starts with the Task, the recipient, the state and the message.
Mail makes pending and self rows. An unassignment suppresses pending and submitting rows. The optional notice dispatcher does everything else outside the mail transactions: exact batches, runtime and binding checks, submission and recovery from uncertain outcomes.
suppressedis final, also when a submission is in progress or the Agent rejoins.- After a crash, rows that are still
submittingbecomeuncertain. a-stack never resends them automatically. - A closed Session pauses notices that were not sent. It does not delete the rows.
- A notice is generic. It contains no mail body, credential or private path.
- Even after a notice is submitted, the Agent's mail read is authorized separately.
Schema version 12 adds mail_acks, one compact row per message and selected recipient, and notice_ack_refs for exact reminder batches. It stores no extra body. The first start makes a pre-migration copy and checks foreign keys before committing; upgrading a schema-11 database creates no obligations for old messages. See Go back to an older version before restoring the copy with an older binary.
Schema version 13 adds the retained priority column and a partial index for urgent mail. Historical messages default to normal; existing overdue obligations can still produce an urgent hook reminder. Bodies remain single-copy.
go test ./internal/stack -run TestMailGrowth10000SingleCopyBodies -count=1 -v sends 10,000 synthetic 56-byte messages. Each message mentions three other assignees. One local run with the bundled SQLite 3.53.4 retained exactly 10,000 message rows with their bodies, 560,000 body bytes, 30,000 pending mention rows and 10,000 send receipts. Nothing was submitted. Each body is stored once, however many recipients it has.
| Storage | Before (bytes) | After (bytes) |
|---|---|---|
| Physical main database | 4,096 | 23,334,912 |
| WAL | 642,752 | 4,247,752 |
| SHM | 32,768 | 32,768 |
| Completed compact backup | 212,992 | 20,783,104 |
| Message table | 4,096 | 2,416,640 |
| Mention table | 4,096 | 5,365,760 |
| Mention membership index | 4,096 | 4,403,200 |
| Mention pending index | 4,096 | 3,080,192 |
| Message Task/sequence index | 4,096 | 962,560 |
| Message ID/Task index | 4,096 | 942,080 |
| Operation receipts | 4,096 | 3,428,352 |
The physical sizes include checkpoint and freelist effects. The object sizes come from dbstat on integrity-checked compact backups that SQLite made, read with Python's SQLite 3.54.0. No live database was copied.
The sends took 2,521.846 ms in total. The core send took 221 µs at p50 and 436 µs at p95. These fixture measurements do not include HTTP or the CLI, and they make no promise about production throughput or latency. For short bodies like these, the indexes, receipts and notice data use much more space than the bodies. History and operation IDs have no total retention limit in v1.
The mail tests use real SQLite and HTTP, CLI subprocesses and temporary state. They cover:
- Independent paging, and size limits with maximum bodies and recipients.
- Late join and rejoin, and credential replacement.
- Races with membership changes and closure, and concurrent sequence numbers.
- Migration rollback, and failed mention and receipt writes.
- An abrupt process exit after a mention insert, and the recovery after it.
The normal and race test suites, go vet ./... and the build all apply. Herdr delivery and physical power loss are not part of these tests.