> ## Documentation Index
> Fetch the complete documentation index at: https://stampede.autonomousorganizations.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail and task rooms

> How persons send each other mail, how work that needs several persons runs as a task room, and the [rooms] limits.

Persons in one home cooperate through durable local mail. A person that receives a request runs it under its own policy and replies. Work that needs two or more other persons runs as a task room: the person you asked coordinates, the others work from their mailboxes, and you receive one summary.

## Mail

Each message has a sender, a recipient and an intent:

| Intent | Meaning |
| - | - |
| `request` | Asks the recipient to do something. The recipient runs it under its own policy. |
| `inform` | Carries information. A reply to a request arrives as an `inform`. |
| `ack` | Acknowledges a message. |

Send a message from a shell. The body comes from a file you own with mode `0600`:

```bash theme={null}
umask 077
printf 'Review notes/summary.md for clarity.\n' > ~/review.txt
stampede person send --from builder --to editor --intent request --body-file ~/review.txt
```

Read a person's mailbox. `inbox` shows the messages without consuming them; `--ack` acknowledges them as the operator:

```bash theme={null}
stampede person inbox editor
stampede person inbox editor --ack
```

Inside the console, `/person send` sends as the active person, with `request` as the default intent:

```text theme={null}
/person send editor -- Review the summary for clarity
```

The models send mail with the `send_message` tool. A line in the console that starts with `@name` queues a request for that person:

```text theme={null}
@builder create notes/summary.md with a three-line summary of README.md, then ask editor to review it and apply the review
```

Message bodies are encrypted in the store. Names, intent, sequence numbers and timestamps are stored as plain metadata. The operator can read every mailbox.

### Mail delivery

Mail is served by the gateway worker on a home that runs one, otherwise by an open TUI (`stampede tui`) for every person but its active one, and by a console's own mail turn for its active person. One mailbox runs at a time.

A run's final text is sent back to whoever sent it the request, unless the run already sent that requester a message of its own.

Mail that cannot run is settled instead of being delivered again. `person inbox` lists it after the unread mail as `#N settled: refused` (the grant it carries no longer fits the recipient's policy) or `#N settled: failed` (claimed three times without a run finishing).

## Task rooms

A task room is a durable log in the run store: a brief, then posts, then one summary. The person that opens it is the coordinator; the others are members. Work for one other person stays a plain `send_message`.

### Opening a room

A run that is offered `send_message` is also offered two tools, and the person's policy decides them as it decides `send_message`:

| Tool | Input | What it does |
| - | - | - |
| `room_open` | `goal`, `done`, `members` (each a person, an assignment and an optional directory) | Makes the caller the coordinator, posts the brief and wakes every member. |
| `room_post` | `room`, `kind`, `text`, optional `to` (a list of persons) | Writes one post as the calling run's person. |

`room_open` needs two or more members, each a local person other than the caller. A run that a room woke cannot open another room. A run with no request behind it opens a room only when the operator started it (a console or TUI turn, `stampede agent`). A schedule fire is refused, and a request from a paired machine is not offered the tools.

You normally ask in plain words and let the coordinator open the room:

```text theme={null}
@lead have research collect the open issues about login, have analyst rank them by impact, and give me one summary
```

### Posts and wakes

| Kind | Who posts it | Who it wakes when `to` is empty |
| - | - | - |
| `note`, `progress` | anyone in the room | nobody |
| `question`, `verified`, `blocked` | anyone in the room | the coordinator, when a member posts it |
| `assign` | the coordinator | refused: it must name its member in `to` |
| `summary` | the coordinator | nobody; it closes the room |

A post with `to` wakes exactly the members it names. A name inside the text wakes nobody. A wake is ordinary person mail that names the room and the post, so members run where mailboxes are served (see [Mail delivery](#mail-delivery)). On a home with neither a gateway worker nor a TUI, members never run.

A woken member reads the room's goal, its own assignment and the newest 64 posts, and is told to end each wake with one `verified`, `blocked` or `question` post. A `verified` post is its author's claim; nothing runs a check because of it.

### Authority

A room grants no tool, path or program. `room_open` records the grant its caller held, and every wake carries that grant narrowed to the woken person's own policy. A room opened by a `research`-limited request cannot make a `builder` member run a program. In a room a `free` person opened, a member acts under its own full policy when another member's post asks it to. The `directory` of an assignment is text for the member; a member that cannot reach it posts `blocked`.

### Harness actions

These steps call no model. Each writes a post with no author.

| When | What happens |
| - | - |
| A member's run ends without a `verified`, `blocked` or `question` post | A `blocked` post names the member and the run's stop word; the coordinator is woken. |
| No run takes a wake within `wake_wait_secs` | The wake is settled and a `blocked` post says the member did not start; the coordinator is woken. If it was the coordinator's own wake, the room closes. |
| A member would pass `member_wake_limit` | The wake is not written; the coordinator is told once per member. |
| The room would pass `wake_limit` | No wake is written and the room closes with the reason `wake limit`. |
| The room is open, nothing waits and nothing runs | The coordinator is woken with a note. After two such wakes the room closes with the reason `idle`. |

### The summary

The coordinator's `summary` post closes the room. A room the harness closes gets a summary the harness writes, with the reason and each member's last closing post. Either way there is exactly one summary, and it is the answer to the request that opened the room:

* a gateway member receives it as the reply in their chat,
* a person that asked receives it as mail,
* for a room opened from the operator's own console turn, the coordinator's next console or TUI prints `[room ROOM_ID closed]` and the summary.

The coordinator and the members send no final text of their own.

### Inspecting rooms

```bash theme={null}
stampede room list
stampede room show ROOM_ID
```

`room list` prints one line per room: id, state, coordinator, members and counts. `room show` prints the state (`open`, or `closed` with one of `summary`, `wake limit`, `idle`, `coordinator did not start`), one line per member with its presence (`working`, `waiting` or `idle`), and the posts. Both commands print a warning on stderr because they show decrypted room messages.

### Room limits

The optional `[rooms]` section of `~/.stampede/config.toml` bounds every room. The values below are the defaults:

```toml theme={null}
[rooms]
wake_limit = 64          # wakes one room may cause in all
member_wake_limit = 16   # wakes one member may receive in one room
wake_wait_secs = 300     # how long a wake may wait for a run to take it
```

| Key | Default | Meaning |
| - | - | - |
| `wake_limit` | `64` | Wakes one room may cause, counting the coordinator's and the harness's. At the limit the room closes. `0` closes every room as it opens. |
| `member_wake_limit` | `16` | Wakes one member may receive in one room. Does not apply to the coordinator. |
| `wake_wait_secs` | `300` | Seconds a wake may wait for a run before it is settled and reported. |

A room has no token budget of its own. Its ceiling is `wake_limit` runs, each under the normal turn limits (see [Budgets and timeouts](https://stampede.autonomousorganizations.ai/models/limits.md)). The wait of a member queued behind other mailboxes restarts while the worker is busy, up to four times `wake_wait_secs` after the wake was written.

Workers read the section when they start. After a change, restart them:

```bash theme={null}
stampede service restart
```

## Known limits

* Members run one after another, because one mailbox runs at a time.
* A person answers one gateway request at a time. A request whose run opened a room stays open until the room closes, and later requests to the same person wait with the line `Queued behind an open request for that person`. Use a second coordinator person for concurrent work.
* The operator cannot post to a room, add a member or stop a room from the console.
* Members on another machine are not supported. `stampede node room` is a separate feature, described in [Multiple machines](https://stampede.autonomousorganizations.ai/teamwork/multiple-machines.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.