Troubleshooting

Grouped by what you see. Several of these name something unrelated to the real problem, which is why they are written down.

The agent is up but nobody can reach it

[reach] cloudflared could not start (… No such file or directory)
[register] SKIPPED - nothing to publish (reach mode 'cloudflared(failed)', no 'myUrl')

The binary named in reach.bin is missing. No tunnel means no public URL, so registration is skipped — the agent is healthy and simply not listed. Put the binary where reach.bin points.

A quick tunnel’s hostname changes on every restart; the registry is updated each time, but anything holding the old URL needs the new one.

“Licence is not currently valid” and the licence is fine

Almost always the wrong working directory. The identity comes from env-file, which is read from the current folder. Start a component from its own licensed folder.

Same cause: an agent started before its router. Order is router, then agent, then workspace.

A turn returns instantly and does nothing

A couple of seconds, a small response, nothing in the wrapper’s log. The mission never ran. In order of likelihood:

1. The engine was re-sealed without --file, unbinding the wrapper
2. The wrapper’s harness-root is empty — nothing to navigate
3. The agent binary predates the sealed-mission feature — it logs -> process instead of runs ONE mission (sealed): <name>

“may not post to session”

[external] '<subject>' may not post to session 'ext-s-…'

A cached session outlives a policy change, a re-seal, or a restart, and does not self-heal. Retire the entry under <HEIA_DIR>/peer-sessions/ and the next call mints a fresh one.

The door answers your own question back to you

{"ok":true,"accepted":"response"}

The caller and the door share a HEIA_DIR. The caller’s “expecting a reply” record and the door’s inbox are the same file, so your question lands on your own expectation. Give each its own store.

“REFUSED to register router session … default-deny”

The router approved it and the agent refused. The sha512(email) subject has no inbound rule on the serving agent:

./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule "${SUB},<agent>,inbound,allow"

“not permitted to act on behalf of that subject”

The vouch was sealed for the email but the turn binds to sha512(email). Seal the hash.

Restarting one agent stops another

Some builds match agents by process name, so restart from a runner folder also stops the workspace agent. Read the output to tell which you have — a folder-scoped restart names what it left alone:

left alone: agent belonging to another folder (1987, 2001, …)

“Text file busy” when replacing a binary

cp cannot overwrite a running executable. Worse, a script that ignores the error goes on to print a success line built from the unchanged file — so the swap looks done and is not.

Stage a copy beside it and mv over the path, which replaces the directory entry rather than writing into the open file. Then verify the hash changed on disk rather than trusting the message.

A merge or ingest that says it finished, and did not

manifest.json is written when concatenation ends, before the index build. A store with no terms.idx, centroids.bin or ivf-vectors.bin is unfinished whatever the manifest says.

If it vanished mid-build, check for the kernel:

sudo dmesg -T | tail -30      # look for: Out of memory: Killed process … (hexaeight-engin)

A merge needs roughly twice the shard total in RAM and on disk. A group needs neither — prefer it.

An edited card still returns the old text

chunks.jsonl is append-only. --memory-refresh adds new chunks and leaves the old ones retrievable, so a search can still return pre-edit text after a refresh that reported success.

Rebuild the memory, or import under a fresh name.

Also check which copy you edited: a memory’s manifest.json records the source path it was ingested from. Editing a copy elsewhere changes nothing.

Reading logs

Read the tail, or the whole file. Do not grep for the keyword you expect: the line that explains a failure usually sits next to the one you searched for, and filtering hides it.