When something does not happen

Every state on this page is one we have actually met. Where two causes are told apart, it is because mistaking one for the other has cost somebody an afternoon.

1. Start here

Almost every report is "I did a thing and nothing happened", and the useful first question is which of three places it stopped in.

The message never arrivedIt arrived and became no turnIt arrived, was handled, and correctly produced no turn
who decidedthe relaythe agent's gatethe agent's harness, below the model
is it an erroryesit is configurationno: this is success
what you seeoften a rejection when you sendnothing at allnothing in the channel, but a reaction
The third column is the one that gets misdiagnosed. Some messages, the skill doorbells, are supposed to be handled without a turn, so looking for a sentence records a pass as a failure. Check for a reaction before concluding anything. And if something has not happened within about a minute and a half, it is not coming: nothing in this service is slow, and "slow" almost always means dropped, not routed, or decided against.

2. Buzz Desktop will not connect

The relay is closed, and a key that is not a member is refused when it connects.

CauseHow to tellFix
not admitted yetnobody has added your key, and you have not claimed an invitationask the relay's owner to add you (Getting started, step two)
invitation expired or used upthe claim is refused, not the connectionask for a fresh one; they expire after three days by default
your machine cannot reach the service at allneither https://engram-buzz.pvelua.net/version nor https://engram.pvelua.net/api/version answers, and neither ever has from this machineask whoever invited you. During the private beta, reaching the service is part of enrolment, so your access has not been set up yet, or not for this machine
the service is down/version does not answer, but it did earlier from this same machinenothing to fix at your end

That last check is worth knowing by heart. /version answers without a credential, so it separates three things that look identical from outside: I cannot reach the service, the service is down, and my identity is wrong. The first two both look like no answer; what tells them apart is whether this machine has ever reached it. The first time you connect from a new machine, a timeout means your access, not the service.

3. I am connected and there is nothing here

Expected. Admission puts you on the relay and in no channel. Someone adds you to a channel, or you create one (Channels and projects, §2).

4. My message to an agent would not send

The relay refuses a message that addresses somebody who is not a member of that channel: mentioned pubkeys are not channel members. Add them to the channel, or address somebody who is in it. This is one of the few cases where the error is actually reported to you; most of the others are silent.

5. The agent is in the room and never answers anything

"Never answers anything" is different from "did not answer this". Two causes, both silent.

It was added in the wrong role. An identity added as Bot cannot be mentioned: an @ to it is stored as plain text, so nothing is ever delivered, and the relay reports nothing. Remove it and add it again as Member.

Its gate does not admit you. Every agent decides whose messages become a turn, and the decision is made inside the harness, after delivery: the relay accepts your message, and nothing answers. The ready-made agents are not set up to take turns from every member of the service, so you cannot count on them answering your own messages. That is how the service runs today, not a fault at your end and not something you can configure; Your agents explains it, and the direction it is going.

6. I revised a skill and nothing happened

In order of likelihood:

  1. Nothing in the channel is the correct outcome. The doorbell is handled below the model, so the receipt is a reaction: 📘 installed · 🗑️ removed · ⚠️ kept the last good copy · nothing if the feature is off for that agent. Look at the doorbell, not for a reply.
  2. You looked too early. A normal fetch takes about a second, but a rejected credential takes about 15 seconds to say so and an unreachable ENGRAM about 95 seconds. For those first 95 seconds a failure looks exactly like a healthy start. Wait until the signal is due, then look.
  3. The channel is not bound to the project, so no doorbell was sent. Change something and see whether any doorbell appears (§7).
  4. You revised a skill the agent is not assigned, or assigned in a different project. One assigned skill per agent per project; check which one the agent actually has.

See Skills for your agents, §4 for what each reaction means.

7. No doorbells arrive at all

A doorbell is a consequence of the binding between a channel and a project. If nothing ever arrives, check the binding first, before the agents and before permissions. In the project's Settings → Channels:

What the channel row saysWhat to do
Unavailable — not visible to the adapter, binder awaiting confirmationthe channel is private and the adapter is not in it. Add the adapter as a Member (Channels and projects)
key not proven beside the binderthe person who bound it has a bound but unproven key, which routes nothing. Prove it (Getting started, step three)
binder not in channelthe person who bound the channel is not a member of it. Add them, or bind it again as someone who is
Observed, binder in channelthe binding is healthy; press Test agents to check the rest of the chain

The quickest positive test: make a small, harmless change in the project and watch the channel. A doorbell within seconds proves the binding, the relay and the adapter in one step. No doorbell only says that something in that chain is not connected; the binding is the likeliest.

8. ENGRAM says "Buzz: couldn't deliver"

When a doorbell could not be delivered, the item it was about (a hand-off, a proposed addition) says so in ENGRAM, with the reason. Nothing is lost: the item is still waiting where you found it.

The reasonWhat it means, and what to do
not in this project's roomthe project has a bound channel, but the person or agent it was for is not a member. Add them to the channel
this project has no Buzz roomno routable channel serves the project. Bind one, or check that the binding is healthy (§7)
the adapter can't see the rooma private channel without the adapter in it. Add the adapter as a Member (Channels and projects)
your key isn't on this relaythe key ENGRAM has for that person is not admitted to the relay. They need admitting, or the key they use in Buzz Desktop is a different one from the key bound in ENGRAM
this hand-off names no projectthe hand-off was made without a project, so there is no room to ring. The receiver finds it in ENGRAM's Suggestions instead

A related badge, not signalled: no Chat Key, means the person has no chat key bound in ENGRAM at all, so there was nobody to address.

9. Approvals

Since ENGRAM v1.21.0, a project can approve a version of an article or skill (Skills for your agents, §7). The cases people meet:

What happensWhy, and what to do
I submitted, and the decider was never toldthe decider is not a member of the bound channel, so the request was not delivered; it is never sent privately instead. Add the decider to the channel. Meanwhile the item is listed as awaiting on the project's page, where the decider can act on it
there is no Submit for approval on a rowonly the item's author, the project's owner, an admin, a moderator or the decider may submit. Documents are never submitted, and an item must be in the project's library first
"This version is approved; revise it to submit again"a decision belongs to the version that was decided. Revise the item, and the new version can be submitted
"This item was revised since"the version you tried to decide is no longer the current one. Read the current version and decide that
"Only this project's decider approves or rejects"you are not the decider. It is the project's owner, or, when an agent owns the project, the person at the root of that agent's owners; never a moderator
the agent works from text newer than what was approvedexpected. Approval records a decision and gates nothing: agents always receive the current version. The row links to the approved version while the newer one is Draft

10. The agent cannot find something that is obviously there

An agent acts under its own account, not yours, and reads what it has been granted and nothing else. So "it cannot find my article" is usually about the agent's permissions, not search. Check that the agent is a member of the project, and that what you expect it to read is visible to the project rather than private to you.

An empty result is not proof that nothing is there. It is equally consistent with the agent not being allowed to see it, and from the agent's side the two look the same.

11. It answered when I was only talking about it

Expected: the relay reads @Name out of your message text and turns it into a real address. Writing "@BE Coder already looked at this" to a colleague wakes the coder. Drop the @ when you mean to refer to somebody rather than address them. Nothing downstream can tell addressed from mentioned, so the only control is how you write.

12. Two agents both answered, separately

Expected. One message addressed to two agents is two independent turns. They do not confer, and neither sees the other's reply as part of its own work. If you want one to hand work to another, that is what the orchestrator role is for.

13. My name shows on messages, but things are not attributed to my account

Your chat key is bound but possession was never proven. The name comes from the binding; the provable link comes from the proof. Finish it (Getting started, step three). It is the most common half-finished state in the whole flow, precisely because it looks finished.