stateloom-on-eury

name

stateloom-on-eury

description

Use when a state machine or board must be modelled, drawn, validated or generated into code on Eury — and when asking "what does the loom run here", "is stateloom up", "quel port", "the canvas is frozen", "the board never moves", "MCP 401", "how do I open the board from ilex". Also use when deciding at which ALTITUDE to model a session — a meaning board a human and an agent can converse with, versus a mechanics board that measures the agent loop — and before generating either. Covers the containerised deployment, its memory ceiling, its boot behaviour, the two-layer rule, and what a transcript can and cannot tell you.

The loom on Eury

Four processes in one container image behind one port, holding .smdf.json state machines that an agent edits over MCP and a human edits in a browser — the same document, live, both directions. Deployed 2026-08-16, replacing a hand-rolled three-terminal stack.

   http://127.0.0.1:4598        loopback — agents on Eury, curl
   http://100.88.23.103:4598    tailnet  — ilex · ginkgo · larix · tilia · abies
        └─ gateway :8080
             ├── /socket.io/*  → hub    :4599   sequencer, never writes disk
             ├── /mcp          → mcp    :4600   your door, bearer-token guarded
             └── everything    → canvas :4598   the human's board

Documents live in /home/gmusic/salix/repos/stateloom-surface/looms/, which is the container's /data — the only readable/writable root. Address them the way the server sees them: /data/<name>.smdf.json. A host path is refused, not followed.

Chronicle episodes are mounted, not copied

Episode 333 is a second document root at /data/ep333, served from where it lives so there is one file and no divergence. A board there is addressed /data/ep333/salix/<name>.smdf.json.

The write boundary is the filesystem's, not a convention: the loom runs as gmusic, so it writes salix/ — this account's drop lane — and only reads the mia-owned boards beside it. DROP-ONLY enforced rather than recalled. Mount another episode by adding a volume next to the existing one in .stateloom/docker-compose.yml; never by copying documents into looms/.

An agent is handed this door with:

claude --mcp-config /home/gmusic/.mcp.stateloom.json

That file lives in $HOME (mode 600) and not in any repository on purpose — the episodes tree has a remote, and a bearer token committed there is a token published. Regenerate it after a rotation with the episode's etc/stateloom-mcp-config.sh, which reads the live token from .stateloom/.env and carries none itself.

It is already running

Nothing to start. restart: unless-stopped on all four containers plus docker.service enabled means the loom returns by itself after a reboot or a crash. Check before you act:

curl -sS http://127.0.0.1:4598/healthz
# {"ok":true,"gateway":true,"upstreams":{"canvas":true,"hub":true,"mcp":true}}

If that answers, do not run docker up, do not "restart to be safe" — the hub holds every peer's live room. Only if healthz fails:

cd /home/gmusic/salix/repos/stateloom-surface
docker compose -p stateloom -f .stateloom/docker-compose.yml --env-file .stateloom/.env up -d

Use docker compose directly, never npm run up. That npm script calls stateloom docker up, which regenerates .stateloom/docker-compose.yml and silently drops both local edits: the tailnet port mapping and the memory ceilings below. If someone runs it, restore both and re-apply with the command above.

Memory ceiling — why it is there

Eury runs 31Gi with both swapfiles saturated. An unbounded container competes with the agent fleet for the last free gigabyte, and the OOM killer picks whichever victim is cheapest — usually somebody's live session, not the runaway.

service	cap	measured idle	swap
hub	256m	~19 MiB	denied
mcp	256m	~30 MiB	denied
canvas	512m	~42 MiB	denied
gateway	256m	~14 MiB	denied

memswap_limit == mem_limit denies swap entirely: the container fails loudly inside its own cgroup instead of dragging the host down. Total hard ceiling 1.25 GiB, ~8% used at rest. Raise a cap with STATELOOM_MEM / STATELOOM_MEM_CANVAS in .stateloom/.env — never by removing the limit.

docker stats --no-stream $(docker ps -q -f name=stateloom)

What you can do with it

Register the MCP server from /home/gmusic/salix/repos/etc/mcp-config-stateloom.json (HTTP + bearer, port 4598 — 4597 was the retired stack). Recover it any time:

npx -y @miadi/stateloom-skills@latest docker mcp-config

want	do
build / edit a machine	create_state_machine, add_state, add_event, add_transition, remove_state
switch board	set_project_file /data/<name>.smdf.json — server path, never a host path
check it holds	validate_definition — V001–V014
draw it	render_diagram → PNG, SVG, Mermaid, ASCII
generate code	generate_code → Python / TypeScript
write a spec	generate_rispec → a RISE markdown document
give the human a board	http://100.88.23.103:4598/?doc=/data/<name>.smdf.json

?doc= is per-viewer — measured: fetching it returns 200 and leaves /api/config's projectFile unchanged, so two people handed two links do not repoint each other's board.

The nine @miadi/stateloom-skills skills are installed in stateloom-surface/.claude/skills/ — stateloom-design, -codegen, -render, -rispec, -live-loop, -setup, -service, -tailnet, -docker. Read those for depth; this file is only what is true on this host.

Two layers, never merged

A board is built at one of two altitudes, and handing someone the wrong one is the failure this section exists to prevent.

	meaning	mechanics
states	CURRENT REALITY → Action step N → DESIRED OUTCOME	Deliberating, Executing, Composing, AwaitingHuman
events	tension_established, owner_consented, moment_of_truth	Call_Bash, TurnEnded, ToolReturned
answers	what was the work becoming, and what moved it	what the loop did, and how much of it
engine	an LLM read pass, then the human corrects it on the canvas	session-to-smdf.py, mechanically
reads	the human's turns, the commit bodies, the issue text	the raw JSONL
file	<name>.smdf.json	<name>-mechanics.smdf.json

A mechanical extractor cannot produce a meaning board, and no amount of fixing will change that. The tool sequence Read · Edit · Bash · Bash implements "raise the contrast floor" and "delete the feature" identically. Intent was never encoded in tool names, so it cannot be recovered from them — and a diagram whose shape is the same for every session on this host carries no information about any session.

The meaning board's cheap, accurate input is not the raw transcript. In order: the human's turns (a few hundred lines, the whole intent spine), the commit bodies and issue text for whatever repo was touched — which usually already contain the state names nearly verbatim — and only then the assistant's text-only turns. Never the tool calls.

Then the human drags a state name on the canvas and the agent sees it change. That bidirectionality is the loom's entire reason to exist, and a board generated from tool names has nothing in it a human would want to rename.

Model the meaning board on WitnessedCapture (/data/ep333/pane-capture-witnessed.smdf.json) — the house pattern, a structural tension chart wearing a state machine's clothes, with condition guards on the transitions that need a human's word.

The mechanics layer — what it is honestly for

~/.agents/skills/stateloom-on-eury/session-to-smdf.py \
    ~/.claude/projects/<project>/<session-id>.jsonl \
    --name MySession --namespace Miadi.SessionMechanics \
    -o <episode>/salix/my-session-mechanics.smdf.json

Several transcripts may be passed in chronological order; each file boundary emits an explicit TranscriptBoundary event rather than flowing one file's last state into the next file's first — a fork seam is a discontinuity, and drawing it as continuous invents transitions.

States are the agent's operating mode, events are its calls, and every transition carries its observed count. What that is good for: volume, distribution, and where a loop actually spent itself. What it is not: an account of the work.

Read the counts before believing them. Every state on a mechanics board is an inference this script makes, not a label the transcript carries — so a state name can be wrong even when the arithmetic is right. Two that were, and were fixed:

• Thinking-only records were counted as Answered → AwaitingHuman, which made "waiting for the human" the largest state on the board while the agent was thinking. Thinking is now Thought → Deliberating, and AwaitingHuman is entered only at a real turn boundary.
• stop_hook_summary fires once per turn and means nothing happened. Reading it as a hook fire turned the turn count into a false finding about friction. Constrained is now entered only when a record actually carries hookErrors or preventedContinuation.

Built and standing: /data/ep333/salix/ava002-mechanics.smdf.json — five transcripts of the compositions-jamai lane (where the ATELIER fork ran; tmux rise-ava002, session 38c66d28), 13,692 lines → 19 states, 35 events, 128 transitions, validator clean. Top states: Deliberating 1400, Executing 1311, Composing 616, Interpreting 248, AwaitingHuman 215. There is no Constrained state — across all 13,692 lines, zero records carried hookErrors or preventedContinuation.

A board names the lane it measured, and no other. That one says nothing about /workspace/repos/miadisabelle/gmtermux/: those sessions ran under another identity on another host, and no transcript for them exists on Eury. A transcript-based engine cannot reach a day it has no transcript for — say that, rather than modelling something adjacent and letting the filename imply otherwise.

See creative-session-fork for how such a fork is made.

Traps, each one paid for

Symptom	Cause	Move
Board renders, never moves	something re-pointed the canvas off same-origin	curl /api/config must say "bridgeUrl":"/"
Skills look refreshed, aren't	the installer keeps existing files	re-run with --force
npx @miadi/stateloom-skills runs an old version	it resolved the local node_modules copy	pin it: @latest or an explicit version
Tailnet mapping / memory caps vanished	someone ran stateloom docker up	restore both edits in the compose, re-apply
MCP 401 with the right-looking token	container re-minted it	docker mcp-config, update the config file
Two editors, neither sees the other	a host-native loom shares looms/	one loom per directory — never both
Canvas link opens the wrong board	STATELOOM_CANVAS_URL unset	it is set to the tailnet origin; keep it that way
render_diagram → EACCES	it writes beside the document, and the episode root is mia-owned	pass path into the writable lane: /data/ep333/salix/<name>.<ext> — reading someone's board does not grant writing next to it

Logs before guessing:

docker compose -p stateloom -f /home/gmusic/salix/repos/stateloom-surface/.stateloom/docker-compose.yml logs --tail 50 <hub|mcp|canvas|gateway>

Where the old shape went

hub-up.sh, mcp-http-up.sh, canvas-up.sh and canvas.mjs in stateloom-surface/ are the Aug-4 stack and no longer describe anything that runs. Upstream ships their function as the stateloom-service, -tailnet and -docker skills. Originals, the pre-upgrade document and the retired panes' final scrollback: stateloom-surface/.stateloom-legacy-2026-08-16/; tarball at salix/repos/stateloom-surface.BACKUP-2026-08-16.tgz.