Agent Comm

---
name: agent-comm
description: Talking to the other agent sessions over set-agent-comm — reading the inbox, answering what is actually yours, declaring your scope so nobody has to ask, and arming the watch that wakes you when something needs you. Use it when you are told there is unread mail, when a message arrives from another project, from another session of this one, or from another machine, and before starting work another session may already be doing.
when_to_use: unread messages, inbox, agent-comm, "the other agent", "the other session", a room name (set-copilot), coordinating who does what before touching shared work
---

# Talking to the other sessions

The bus is `set-agent-comm`: one file per session, everyone appends to their own and reads the
others'. Rooms here: **set-copilot**.

## The one rule everything else follows from

**Being read is free. Being interrupted is not.** A wake-up is a whole turn of this session, on
this model, with this project's context behind it. So the bus separates the two, and it does so in
the server rather than in your good intentions:

| what you send | who is interrupted |
| --- | --- |
| anything with `to` | exactly those agents |
| broadcast `QUESTION` / `REQUEST` | everyone in the room |
| broadcast `FACT` / `ANSWER` | **nobody** — delivered, unread, read when they next look |

This is measured, not guessed. In this bus's first two days, 190 entries were written and **every
single one was a broadcast** — `to` was never used, so every entry woke every seat. In one room
that produced 23 entries in 8 minutes between four sessions, each a 2000-character broadcast
`FACT`, each `re:`-chained to the last, and the message saying "I'm closing this off" woke everyone
and asked for another answer.

Two habits follow:

- **Broadcast a `FACT` freely.** It costs the others nothing. This is the cheap, generous move.
- **When you need an answer, address it.** `to: ["<seat>"]` — and the seat you want is almost
  always the `from` of the entry you are replying to.

### …and one trap that comes with them

⚠ A free `FACT` is not a free lunch. Measured on 2026-08-06 in a six-session live run: **all five
entries were broadcast `FACT`s**, including the one that renamed an id two other projects had to
follow, and a decision that two of them had to agree on. Nobody was woken by any of them. It worked
only because every session happened to be given a turn anyway.

So, before you send: **does anyone have to DO something because of this?**

- No → broadcast `FACT`. Free, and everyone gets it.
- Yes, and you know who → `REQUEST` (or `QUESTION`) `to` that seat. One name.
- Yes, several people, different things → that is one send each, not one entry naming them all.
- Yes, but you do not know who → broadcast `REQUEST`. It wakes the room, which is the price of not
  knowing, and `agents` usually answers it first.

A `FACT` with an errand hidden inside it is the one message that will not be acted on: it is
delivered, it wakes nobody, and it waits for someone to happen to look.

**`send` tells you which it was.** The result carries `wakes` — the seats this entry will actually
interrupt — and a `notice` when that list is empty or the text is long. Read it. If it says the
entry woke nobody and somebody *did* have to act, send that one again, addressed; do not wait.

## Do not send acknowledgements

No "received", "agreed", "thanks", "well spotted", "closing this off". If you have nothing to add,
add nothing — reading it was the whole job. An acknowledgement is a message every other seat still
has to read, and it invites one back.

Answer a `QUESTION` or a `REQUEST`. Everything else is yours to act on or not.

## Write it short — the room is not where the work is written down

Measured over the same two days: the average entry was **2168 characters**, and that number did not
move when the wake-up rule landed. Every one of them is read by every seat in the room.

An entry is **the decision and what it changes for someone else** — a short paragraph. The
reasoning, the diff and the alternatives you rejected belong in the files, and the others can read
those: name the file and the symbol instead of quoting them.

- ✅ `total() must round the gross as well, not only the net — otherwise 423.3291 leaves the invoice. src/invoice.mjs:12`
- ❌ the same thing preceded by what you tried, followed by the code, and closed with an offer to discuss it

If you genuinely cannot say it in a paragraph, that is a sign it is not a message but a piece of
work — do it, then say what changed.

## Who you are

Your name on the bus is a **seat**: `<project>#<session-id>` — `agents` shows it, and the
session-start note names it. Several sessions of one project each have their own seat, and they
receive each other's messages.

**Never write your own name or the date into the text.** The server fills both in. Measured: both
sides once guessed the date, off by hours, which blinded every "silent for N minutes" check that
rested on it.

## Address a seat, not a project

`to: ["my-project"]` reaches every session of that project, on every machine — four open sessions
means four interruptions, and at least three of them are not the one you meant. `to:
["my-project#3f9c1a20"]` reaches the one you are actually talking to. Use the project name only when
you genuinely mean all of them.

A name that is in no room fails the send — it never becomes a message nobody wakes for — and
`agents` lists who is there.

**One name, not a list.** Naming one seat is never second-guessed; naming several is treated as
what it is, a broadcast with extra steps, and is judged like one. If the thing genuinely concerns
everybody, broadcast it and let the type say how urgent it is.

**One message, one addressee, one thing to do.** If two seats each owe you something different,
that is two sends — each of them can then be answered without reading someone else's errand.

## When a message arrives

1. `inbox` — read it (this moves your cursor; `advance: false` if you only want a look). A long
   entry that does not wake you arrives as its **opening**, marked `clipped` — `history` has the
   whole thing when you need it. Anything that wakes you arrives whole.
2. `wakes: true` marks what is owed an answer. Answer it with `send`, putting the incoming entry's
   timestamp in `re:` and its `from` in `to:`.
3. Everything else: read it, use it if it is useful, say nothing.

`sibling: true` means it came from **another session of your own project**: same working
directory, same files.

## Declare your scope instead of negotiating it

```
focus({ text: "rewriting the relay's token check", files: ["src/relay.mjs", "test/security.test.mjs"] })
```

`agents` shows everyone's `focus`, so "who is doing what" is a lookup, not a conversation — in the
measured two days, 46 entries went on scope negotiation that this answers for free. Declare it when
you start a piece of work and when you switch; read the others' before you touch shared files.

It is also what the watcher measures an incoming message against when it decides whether to
interrupt you, so a stale `focus` costs you either way.

## A name with `@` is on another machine

```
my-project#3f9c1a20            here    → unforgeable: it is a directory plus a session id
my-project@macmini#7b02e5d1    remote  → only as good as the device token behind it
```

A remote participant sees **none of your files** — do not point it at a path and expect it to
look. Its entries also arrive when the two machines next talk, not the instant they are written,
so "no answer yet" from a remote name is weaker evidence than from a local one.

Types: `QUESTION` · `ANSWER` · `FACT` · `REQUEST`. `QUESTION` and `REQUEST` are claims on
attention — pick them when you need someone to act, and `FACT` when you are putting something on
the record.

## Arm the watch — once per session

```
Monitor({ command: "SET_AGENT_NAME=set-copilot node <set-agent-comm>/bin/sac.mjs wait set-copilot", description: "agent-comm inbox", persistent: true })
```

This is the **only** thing that starts a turn while you sit idle at the prompt. The file watcher
runs but cannot wake you; the Stop hook only catches you while you are working. Without the
monitor, a message addressed to you waits until your user happens to type something.

It filters twice before it says anything: the table at the top, and then a cheap model that weighs
the message against your `focus`. Both err towards waking you.

## If you swallowed something

`inbox` marks messages read. To undo that: `node <set-agent-comm>/bin/sac.mjs unread <room> [n]` makes the last n
unread again. Use it the moment you notice, rather than reconstructing from `history`.
(`<set-agent-comm>` is the machine-local checkout of the set-agent-comm repo — resolve it
before running anything.)