@mcsherrylabs/pi-meerkat 0.7.0 → 0.8.0

package/README.md

@@ -5,28 +5,92 @@ Meerkat tools plus every tool dynamically discovered from the private
 `@mcsherrylabs/evolver-mcp@0.15.0` child. The released upstream baseline is 65 tools, so healthy
 discovery currently returns 72. The count is a comparison baseline, not a routing allowlist.
 
-**Version 0.7.0 introduces this facade.** Version 0.6.0 is the previous Pi/local-signing package
-and does **not** contain it. Use the explicit version below, not an unversioned `npx` command or
-an assumption about npm `latest`. Source/packed acceptance, publication, and verification of an
-installed published release are separate milestones.
+**Version 0.8.0 adds the zero-required-parameter installer.** Version 0.7.0 introduced the
+facade but required an existing node, registry, identity and key. Version 0.6.0 is the old
+Pi/local-signing package. Always use an exact published version, not npm `latest`.
 
-## Install from npm
+## Install the complete experience
 
-Run this in the same environment where Claude Code (or another MCP client) runs. Node 22 is
-the verified runtime. Installation downloads the package and its exact released dependency;
-it does not provision or start a node:
+Prerequisites in the environment where your MCP harness runs:
+
+- Node.js **22 or newer**, with `npm` and `npx` on `PATH`.
+- A reachable Docker Engine and **Docker Compose v2** (`docker version`, `docker compose version`).
+  A normal local engine or a separately hosted Docker daemon/context both work. Existing Docker
+  authentication/TLS settings are respected; no new credentials are requested for public images.
+- An MCP harness with stdio support. The installer prints registration JSON; it does not edit
+  the harness or silently replace an existing registration.
+
+### 1. Install
 
 ```bash
-npm install --prefix "$HOME/.local/share/meerkat-mcp/0.7.0" \
-  --no-audit --no-fund @mcsherrylabs/pi-meerkat@0.7.0
-export PATH="$HOME/.local/share/meerkat-mcp/0.7.0/node_modules/.bin:$PATH"
+npx --yes @mcsherrylabs/pi-meerkat@0.8.0 install
 ```
 
-The installed facade resolves and launches its actual dependency's `evolver-mcp` bin
-(`dist/cli.js`). It does not use a sibling source checkout, global executable, or unversioned
-runtime download. Installation under the home directory persists across rig recreation.
+No identity, key, endpoint, registry, chain ID, channel, port, GID, path, environment variables
+or paid model service is required. This creates an **independent private local chain** and
+starts its owned consensus node, separate processing node and Meerkat registry/content/inbox services. It does **not** join the
+shared devnet, claim from its faucet, inspect unrelated keys, or change another deployment.
+The first install downloads public pinned artifacts and builds three wrapper images, so
+allow time for Docker/npm downloads. Failed preflight/build/readiness exits nonzero with a reason.
+
+### 2. Register one server
+
+Use the one `registration.mcpServers.meerkat` entry printed by installation. For Claude Code,
+if you do not already have a registration named `meerkat`, the equivalent command is:
+
+```bash
+claude mcp add --scope user --transport stdio meerkat -- \
+  npx --yes @mcsherrylabs/pi-meerkat@0.8.0 serve
+```
 
-## Configure an existing node once
+Do not remove or replace an unrelated `meerkat` registration. Choose a different harness
+registration name for this entry if necessary; its underlying saved deployment remains the same.
+Other MCP clients can add the printed stdio JSON entry directly. Do **not** register an Evolver
+child separately. Restart the harness connection, inspect its tools, and begin with
+`meerkat_summary`, `meerkat_services`, `meerkat_inbox` and `evolver_chain_height`.
+
+`serve` finds the installer's saved state automatically; there is no `--config` or environment
+ceremony. The public package launcher is pinned and survives npm-cache cleanup. Each client
+gets its **own facade and exact Evolver child/session/store** inside the owned runtime container,
+connected through Docker exec stdio. Node/content/registry HTTP stays on the private owned
+Docker network, with **no host-published ports**, so a separate Docker daemon needs neither
+host-path sharing nor a public read port.
+Stdout carries MCP protocol only. Closing the connection or signalling the launcher awaits the
+exact remote facade and its private child, not the shared registry or another client's session.
+
+### Resume and ownership
+
+Run the **same install command** again to resume the same installation. Names, identity/key
+references, internal service ports, daemon identity, real genesis/node binding and ownership are saved
+privately under the operator's XDG state directory (or normal home state directory). Services
+use separately owned Docker volumes for consensus data, processing-node data, public genesis,
+registry/app state, subscriptions and announcer state. Consensus and consumer-paced processing
+are separate roles required by the released node. The follower receives only the **public** chain
+specification, never the consensus node's private volume. The released Evolver bootstrap alone
+creates/loads announcer signing keys; the facade,
+installer and output carry only references. No key bytes are copied to the harness.
+
+Rerun does not initialize subscriptions again, regenerate genesis, rotate keys, change authority,
+force-claim/unclaim, adopt another daemon's resources or recover an owner lock. A missing valued
+volume, conflicting ownership, changed daemon/binding, interrupted initializer or stale owner lock
+refuses explicitly and retains state for operator inspection. There is no automatic reset,
+force recovery, Docker prune, broad restart or harness-registration mutation. `serve` never
+creates or restarts services. An intentional **install** invocation may start its own stopped
+services; unrelated services are never touched. Automatic cross-version migration is not provided:
+resume with the saved pinned version.
+
+The installer enables the complete registry/read/announce experience, not every optional upstream
+capability. Generic Evolver subscription-control and other optional capability tools can remain
+unconfigured and refuse clearly; no Docker socket or private node-control API is exposed to the
+registry/facade. The real tool catalog baseline is 65 upstream + 7 local, **not a promise that each
+optional capability is configured**.
+
+## Advanced: attach an existing node
+
+If you already operate a node, registry and keys, you may install this exact package normally
+and use `meerkat-mcp setup` instead. This is an alternative to the automatic installer, not a
+prerequisite for it. Keep your installed package on a persistent user-owned PATH, not an
+npm-cache-internal pathname.
 
 Setup records **references**, not key bytes. Select an existing node endpoint, separate content
 endpoint, identity, existing key file, registry read origin, explicit genesis/chain ID and node ID,
@@ -70,24 +134,12 @@ Pi adapter, or separately managed child is required. Direct launch uses the same
 meerkat-mcp --config "$MEERKAT_CONFIG"
 ```
 
-### Register in Claude Code
-
-From the environment where Claude Code runs, register the installed facade with the same
-absolute config path used for setup:
-
-```bash
-claude mcp add --scope user --transport stdio meerkat -- \
-  "$(command -v node)" \
-  "$HOME/.local/share/meerkat-mcp/0.7.0/node_modules/@mcsherrylabs/pi-meerkat/dist/mcp-cli.js" \
-  --config "$MEERKAT_CONFIG"
-```
-
-`--scope user` makes this operator registration available across your projects. Use
-`--scope local` instead to restrict the initial test to the current project. Start a fresh
-Claude Code session and run `/mcp` to inspect the connection and its tools. Do not register the
-private Evolver child separately. Begin with `meerkat_summary`, a small `meerkat_services`
-query, `meerkat_inbox`, and the upstream read-only `evolver_chain_height`; do not approve
-announcement/sign/submit calls until you deliberately choose to exercise a write.
+For advanced attach, register the exact persistent installed entrypoint/config returned by
+setup; do not point a client at an npm-cache-internal file. The automatic installer's pinned
+`serve` registration above is the recommended route for a virgin harness. In Claude Code,
+`--scope user` makes the operator registration available across projects; `--scope local`
+limits it to the current project. Start a fresh session and use `/mcp` to inspect the connection.
+Do not approve announcement/sign/submit calls until you deliberately choose to exercise a write.
 
 The stdio connection uses stdout exclusively for MCP messages. Diagnostics go to stderr. The
 operator-selected node/content/trust/identity/key/channel inputs are captured at facade startup;

package/dist/installer/committee-init.sh

@@ -0,0 +1,117 @@
+#!/bin/sh
+# node entrypoint: host keys + genesis on first boot, then exec the node.
+#
+# On FIRST boot it generates this node's key material ON THE HOST (never in the
+# image or the repo), renders a one-node genesis committee from the derived public
+# keys, and persists everything into the /data volume. On every subsequent boot it
+# REUSES the same keys + genesis so the chain continues — the genesis committee must
+# stay byte-stable or the chain identity diverges.
+#
+# Two secrets, handled identically (spec 101 — both are host-only secrets):
+#   - Ed25519 node-identity key  -> ce.evolver.node.private-key (EVOLVER_PRIVATE_KEY)
+#   - BLS consensus key (IKM)    -> ce.evolver.node.bls-secret   (EVOLVER_BLS_SEED)
+# Their public keys go into genesis (public-key / bls-public-key).
+set -eu
+
+# Deliberately NOT derived from the app name. This id is written into the genesis
+# file on the volume at FIRST BOOT, so changing it on an existing chain would launch
+# the node under a name absent from its own genesis. Keeping it neutral means
+# `npm run rename` never has to touch this file and cannot leave a previous project's
+# name behind — the template used to default to `tmplnode0`, so every app built from
+# it had a node introducing itself by the TEMPLATE's name, in its logs and in its
+# published deployment artifact.
+NODE_ID="${NODE_ID:-node0}"
+KEYS=/data/keys
+GENESIS=/data/genesis.gen.conf
+ED_KEY="$KEYS/ed25519.key"     # base64 PKCS#8 Ed25519 private
+BLS_KEY="$KEYS/bls.key"        # base64 BLS IKM (>=32 bytes)
+
+if [ -f "$ED_KEY" ] || [ -f "$BLS_KEY" ] || [ -f "$GENESIS" ]; then
+  [ -s "$ED_KEY" ] && [ -s "$BLS_KEY" ] && [ -s "$GENESIS" ] || {
+    echo '[node-init] incomplete owned keys/genesis; refusing regeneration' >&2; exit 1;
+  }
+fi
+if [ ! -f "$ED_KEY" ]; then
+  echo "[node-init] first boot: generating host key material for '$NODE_ID'"
+  mkdir -p "$KEYS"; chmod 700 "$KEYS"
+
+  # Ed25519 identity keypair — PKCS#8 private + X.509 public, base64 DER.
+  tmp="$(mktemp)"
+  openssl genpkey -algorithm ed25519 -outform DER -out "$tmp" 2>/dev/null
+  ED_PRIV="$(base64 -w0 < "$tmp")"
+  ED_PUB="$(openssl pkey -inform DER -in "$tmp" -pubout -outform DER 2>/dev/null | base64 -w0)"
+  rm -f "$tmp"
+
+  # BLS consensus keypair — random IKM + derived pubkey, via the evolver keygen.
+  BLS_OUT="$(java -cp "/opt/evolver/lib/*" ce.evolver.crypto.keys.BLSKeyGenerator)"
+  BLS_SECRET="$(echo "$BLS_OUT" | awk '/^bls-secret:/{print $2}')"
+  BLS_PUB="$(echo "$BLS_OUT" | awk '/^bls-public-key:/{print $2}')"
+
+  if [ -z "$ED_PRIV" ] || [ -z "$ED_PUB" ] || [ -z "$BLS_SECRET" ] || [ -z "$BLS_PUB" ]; then
+    echo "[node-init] FATAL: key generation produced empty output" >&2
+    exit 1
+  fi
+
+  # Persist secrets — host-only, mode 600.
+  printf '%s' "$ED_PRIV"    > "$ED_KEY";  chmod 600 "$ED_KEY"
+  printf '%s' "$BLS_SECRET"  > "$BLS_KEY"; chmod 600 "$BLS_KEY"
+
+  # Render the chain spec (089): committee PUBLIC keys + the chain-wide consensus
+  # parameters. This exact file is published verbatim to every follower / app node
+  # (102 follower-join: the genesis file IS the chain, byte-identical everywhere) and
+  # its canonical hash is pinned as the genesis block id (ce.evolver.genesis-file in
+  # node.conf). 103: the host is the ROUTABLE public address — followers dial the
+  # committee at exactly this host:port. Chain-wide params live HERE, not in node.conf,
+  # so joiners inherit them automatically — quiescence especially (FR-019: a joiner
+  # with different quiescence would time out the deliberately-lingering leader).
+  PUBLIC_HOST="${PUBLIC_HOST:-localhost}"
+  cat > "$GENESIS" <<EOF
+ce.evolver.genesis.nodes = [
+  {
+    node-id        = "$NODE_ID"
+    host           = "$PUBLIC_HOST"
+    port           = 7000
+    public-key     = "$ED_PUB"
+    bls-public-key = "$BLS_PUB"
+    quorum-weight  = 1000
+  }
+]
+
+ce.evolver.consensus {
+  n-nodes                   = 1
+  block-time-ms             = 600
+  round-timeout-ms          = 1500
+  block-reward-tokens       = 10000   # generous dev reward: the faucet (5000/identity) is funded from the FIRST blocks, even under quiescence
+  snapshot-interval-blocks  = 0       # single-node: no snapshot cadence; joiners sync from block 0
+  identity-sponsorship-cost = 100
+
+  # Low idle disk-write: after 3 empty blocks the leader lingers on a 5-MINUTE heartbeat
+  # instead of the 600ms cadence (#31: idle-heartbeat-ms > block-time-ms activates quiescence);
+  # wake-on-work (node-local, always on) still proposes immediately on incoming txs.
+  # CHAIN-WIDE — identical on every node by construction.
+  quiescence {
+    idle-heartbeat-ms       = 300000
+    idle-after-empty-rounds = 3
+  }
+}
+EOF
+  echo "[node-init] generated keys (secrets in $KEYS, mode 600) + chain spec (host=$PUBLIC_HOST)"
+  echo "[node-init] PUBLISH the chain spec (public keys + chain-wide config): docker compose cp node:/data/genesis.gen.conf ."
+else
+  echo "[node-init] existing keys found in $KEYS — reusing (chain continues)"
+fi
+
+# Secrets reach the node via env (HOCON ${?...} substitution in node.conf).
+EVOLVER_PRIVATE_KEY="$(cat "$ED_KEY")";  export EVOLVER_PRIVATE_KEY
+EVOLVER_BLS_SEED="$(cat "$BLS_KEY")";    export EVOLVER_BLS_SEED
+mkdir -p /data/chain
+
+echo "[node-init] launching evolver node '$NODE_ID'"
+if [ -f /public-genesis/genesis.conf ]; then
+  cmp -s "$GENESIS" /public-genesis/genesis.conf || { echo '[node-init] public genesis differs; refusing replacement' >&2; exit 1; }
+else
+  cp "$GENESIS" /public-genesis/genesis.pending
+  chmod 640 /public-genesis/genesis.pending
+  mv /public-genesis/genesis.pending /public-genesis/genesis.conf
+fi
+exec /opt/evolver/bin/evolver -Dconfig.file=/config/node.conf "$NODE_ID"

package/dist/installer/committee.conf

@@ -0,0 +1,102 @@
+# Single-node full-quorum, quiescent. The chain spec (committee with this
+# node's generated public keys + ALL chain-wide consensus params, incl. quiescence) is
+# rendered at first boot by node-init.sh into /data/genesis.gen.conf and included
+# here — this file holds only NODE-LOCAL config. Secrets arrive via env (never in this
+# file).
+include file("/data/genesis.gen.conf")
+
+# 089 chain-spec pin: the canonical hash of the genesis file IS the chain's genesis
+# block id. Joiners set this to their verbatim copy — any drift refuses to boot.
+ce.evolver.genesis-file = "/data/genesis.gen.conf"
+
+ce.evolver.node {
+  private-key = ${?EVOLVER_PRIVATE_KEY}   # Ed25519 PKCS#8 (host secret, from node-init.sh)
+  bls-secret  = ${?EVOLVER_BLS_SEED}      # BLS IKM       (host secret, from node-init.sh)
+}
+
+evolver.peer-discovery {
+  # What this node ADVERTISES about ITSELF to peers — not somewhere it connects to.
+  # This chain is standalone (one node, its own genesis, no seeds) so nothing reads
+  # these; localhost is used because the alternative is advertising an address that
+  # is not this node. They named devnet.mcsherrylabs.com purely because this config
+  # was copied from that deployment. Joining a real chain means setting them to the
+  # ROUTABLE p2p transport (raw TCP mTLS :7000) and HTTPS API your peers can dial.
+  # 163 — `host:port`, no scheme: the transport is raw TCP + mTLS and never was a URL.
+  transport-address       = "committee:7000"
+  # No `peer-url`: this chain is one node, so nothing fetches content from it, and the
+  # plain-HTTP :8440 above could not serve a peer anyway — a content fetch carries the
+  # caller's client certificate and needs the node's OWN TLS listener. Joining a real
+  # chain means setting `transport-address` to the routable :7000 and `peer-url` to this
+  # node's https listener (never a reverse proxy: it presents no client certificate).
+  gossip-interval-seconds = 60
+}
+
+# Chain-wide consensus params (n-nodes, block-time, quiescence, ...) come from the
+# included chain spec — do NOT set them here, they must stay byte-identical on every
+# node. Only node-local knobs below.
+ce.evolver.consensus {
+  validate-chain-on-startup = false
+
+  # Reactivity (node-local, always on since #28): on incoming work the leader proposes
+  # IMMEDIATELY rather than waiting out the (5-minute) idle heartbeat — tx latency stays
+  # sub-second despite slow idle.
+  wake-on-work {
+    forward-watermark = 16
+  }
+}
+
+data.base       = "/data/chain"
+state.snapshots = "snapshots"
+# PLAIN HTTP on 8440 for everything that TALKS to this node, deliberately. The HTTPS
+# listener presents the node's IDENTITY certificate — self-signed, and valid for ~13
+# MINUTES, because it is a peer authentication credential and not a web certificate. No
+# browser can be made happy with that: an exception you click through expires before you
+# finish reading the page. Tolerating it in code means NODE_TLS_REJECT_UNAUTHORIZED=0,
+# which disables verification PROCESS-WIDE for every host — a bad habit to ship in a
+# template.
+#
+# TLS on 8441 for PEERS, because the content cache needs somewhere mTLS to live: its peer
+# route identifies callers by client certificate and the node refuses to start content
+# without a TLS listener. Before evolver v0.16.0 those were the same listener, so
+# "hold documents" and "put every client on an unpinnable certificate" were one decision.
+# They are not, and this is what that separation looks like in a deployment.
+http.port       = 8440
+# ⚠️ REQUIRED since evolver #131: the plain API listener now defaults to 127.0.0.1. The app
+# container reaches this node over the CONTAINER NETWORK, which is not loopback from the
+# node's point of view — without this line the app gets connection refused and the node
+# logs nothing unusual. "0.0.0.0" is what this deployment effectively had before.
+http.bind-host  = "0.0.0.0"
+https.port      = 8441
+evolver.grpc.port = 9000
+
+# 139 — CONTENT, so a detail document announced on this chain can actually be fetched.
+#
+# `bind-host` is what lets a SIBLING CONTAINER reach the publish/read route: it is
+# authorized by what can reach it, and the default (loopback) means "inside this node's
+# container and nowhere else". 0.0.0.0 here says: this compose project's network is the
+# boundary. It holds because the port below is published to 127.0.0.1 only.
+ce.evolver.content {
+  enabled   = true
+  http-port = 8450
+  bind-host = "0.0.0.0"
+}
+
+chainDb {
+  datasource {
+    driver                    = "org.hsqldb.jdbc.JDBCDriver"
+    user                      = "sa"
+    pass                      = ""
+    maxPoolSize               = 5
+    connectionProperties      = ""
+    cachePrepStmts            = true
+    prepStmtCacheSize         = 250
+    prepStmtCacheSqlLimit     = 2048
+    connectionTimeout         = 5000
+    useServerPrepStmts        = false
+    transactionIsolationLevel = "TRANSACTION_READ_COMMITTED"
+  }
+  viewCachesSize  = 50
+  useShutdownHook = false
+  freeBlobsEarly  = false
+}
+ce.evolver.execution.enabled = false

package/dist/installer/node-join.sh

@@ -0,0 +1,228 @@
+#!/bin/sh
+# Claim-then-boot (evolver feature 102) for an explicitly managed follower.
+# Static config is baked into the candidate image. The separately initialized subscription
+# directory is mounted read-only; the installer provisions/persists APP_NODE_ID before boot.
+# Ordinary entry never initializes subscription preferences or adopts existing valued state.
+#
+# FIRST boot: generate this node's keys LOCALLY (they never leave this volume),
+# faucet-claim its identity on devnet (the committee node sponsors and funds it — no
+# admin secret exists anywhere in this deployment), persist the result. EVERY boot:
+# source it and start as a non-genesis follower, syncing the chain from block 0.
+set -eu
+
+# Same read-only guard on normal boot and the owned-fixture preflight. It NEVER initializes,
+# rewrites or merges a declaration; canonical fragment validation belongs to the shared SDK.
+require_subscriptions() {
+  if [ ! -r "$1/channels.conf" ] ||
+     [ "$(cat "$1/channels.conf.initialized" 2>/dev/null || true)" != "evolver-subscriptions-v1" ]; then
+    echo "[node-join] FATAL: initialized subscription declaration missing; refusing to reseed"
+    return 1
+  fi
+}
+if [ "${1:-}" = "--check-subscriptions" ]; then
+  : "${2:?owned subscription directory required}"
+  require_subscriptions "$2"
+  exit $?
+fi
+require_subscriptions /subscriptions
+
+: "${DEVNET_API:?DEVNET_API required (the faucet base url, e.g. https://devnet.mcsherrylabs.com)}"
+
+# ⚠️ CHECKED HERE, not left to HOCON. `preferred-url` is a REQUIRED substitution in the
+# node config, so an unset value fails with
+#   ConfigException$UnresolvedSubstitution: Could not resolve substitution to a value
+# and a stack trace that says nothing about what an operator must do. Required is the
+# right choice — an unroutable default is what made this node dial its own loopback and
+# stop forwarding submits — but the refusal has to be readable.
+# NOTE: meerkat's version of this script FATALs here unless EVOLVER_TRANSPORT_ADDRESS is set. That is
+# an ANNOUNCER's requirement — its channel has a DA group, so other nodes must be able to dial it
+# to flood bodies to it. A reader has no such need and must advertise nothing, so the guard is
+# deliberately absent rather than satisfied with a made-up value.
+
+
+KEYS=/data/keys
+CLAIM="$KEYS/claim.env"
+ID_FILE="$KEYS/node-id"
+mkdir -p "$KEYS"
+chmod 700 "$KEYS"
+
+# The node id is chosen ONCE and persisted, because it is an on-chain name: re-deriving
+# it on a later boot would claim a SECOND identity and abandon the first.
+if [ -f "$ID_FILE" ]; then
+  NODE_ID="$(cat "$ID_FILE")"
+  echo "[node-join] reusing node id '$NODE_ID' (chain state continues)"
+else
+  if [ -n "${APP_NODE_ID:-}" ]; then
+    NODE_ID="$APP_NODE_ID"
+  else
+    # Identity names are ^[A-Za-z0-9]{1,50}$ — no hyphens, dots or underscores — so the
+    # app name is stripped to what a node id may contain (the same rule as
+    # scripts/versions.mjs identityPrefix), and a random suffix keeps a shared chain
+    # collision-free: a fixed name would come back `exists` with keys nobody holds.
+    BASE="$(printf '%s' "${APP_NAME:-app}" | tr -cd '[:alnum:]' | cut -c1-40)"
+    [ -n "$BASE" ] || BASE=app
+    NODE_ID="${BASE}node$(tr -cd '0-9' < /dev/urandom | head -c 6)"
+  fi
+  printf '%s' "$NODE_ID" > "$ID_FILE"
+  echo "[node-join] node id '$NODE_ID' chosen and persisted"
+fi
+
+: "${APP_NODE_ID:?managed deployment requires its saved explicit node id}"
+if [ "$NODE_ID" != "$APP_NODE_ID" ]; then
+  echo "[node-join] FATAL: saved node id differs from managed binding; refusing to claim or boot"
+  exit 1
+fi
+
+if [ ! -f "$CLAIM" ]; then
+  # A CLAIM WHOSE CONFIRMATION TIMED OUT MUST NOT BE RE-SENT BLIND.
+  #
+  # Observed on the live devnet: the faucet answered
+  # `504 {"error":"confirmation_timeout","message":"Transaction submitted but block
+  # confirmation timed out"}` — submitted, outcome UNKNOWN — the container exited, and
+  # the next boot found the id file but no claim file and claimed AGAIN. That is the one
+  # move that cannot be undone: the client persists its keypair only on success, so the
+  # first attempt's keys are gone, and if that attempt committed the name now belongs to
+  # keys nobody holds. The retry then either takes a name with a fresh keypair (and the
+  # first identity is abandoned) or comes back `exists`, after which the node fails every
+  # peer handshake with `Signature does not match` — the 103 failure verbatim.
+  #
+  # So the outcome is settled by READING, exactly as the app settles a submit: if the
+  # name is on chain and we hold no keys for it, stop and say so. The name cannot be
+  # reclaimed, so this is terminal by nature and the operator needs a different one.
+  # ASK, AND DISTINGUISH "NO" FROM "COULD NOT ASK".
+  #
+  # `wget | grep -q '"balance"'` is false for BOTH "the name is free" and "the faucet
+  # is unreachable", and on this path the second must not be read as the first: the
+  # whole point is to avoid claiming a name that may already be bound to keys nobody
+  # holds. So the identity route is asked with the exit status kept, and only a body
+  # that says `not_found` counts as free.
+  #   0 with "balance"    -> taken
+  #   0 with "not_found"  -> free
+  #   anything else       -> could not tell, which is not a licence to claim
+  # ⚠️ THE STATUS LINE, NOT THE EXIT CODE. `/api/identity/<name>` answers 404 for a name
+  # that is FREE — the commonest case — and `wget -qO-` reports any 404 as exit 8 with no
+  # body, so keying on the exit code classified "free" as "cannot ask" and refused to
+  # claim anything at all. Caught by the local rig, where every name is free.
+  #
+  # `-S` prints the response line even for an error status (GNU wget 1.25 in this image),
+  # so the three answers are distinguishable:
+  #   200 + "balance"  -> taken
+  #   404              -> free
+  #   anything else    -> could not ask, which is NOT a licence to claim
+  id_state() {
+    # `|| true` IS LOAD-BEARING, and it is the second layer of the same trap. Keying on
+    # the status line instead of the exit code is necessary but not sufficient: under
+    # `set -e` the ASSIGNMENT inherits wget's exit status, so a 404 killed this function
+    # before the case could run — the caller saw an empty answer and the script exited 8.
+    _resp="$(wget --timeout=5 --tries=1 -S -qO- "$DEVNET_API/api/identity/$1" 2>&1)" || true
+    case "$_resp" in
+      *"200 OK"*'"balance"'*) echo taken ;;
+      *"200 OK"*)             echo taken ;;
+      *"404"*)                echo free ;;
+      *)                      echo unreachable ;;
+    esac
+  }
+  state="$(id_state "$NODE_ID")"
+  if [ "$state" = unreachable ]; then
+    echo "[node-join] FATAL: cannot reach $DEVNET_API to ask whether '$NODE_ID' is already"
+    echo "[node-join]   claimed. Refusing to claim blind: if that name is already bound to keys"
+    echo "[node-join]   this deployment does not hold, claiming it again destroys the name."
+    exit 1
+  fi
+  if [ "$state" = taken ]; then
+    echo "[node-join] FATAL: identity '$NODE_ID' already exists on chain, and this"
+    echo "[node-join]   deployment holds no keys for it ($CLAIM is absent). A previous"
+    echo "[node-join]   claim committed after its confirmation timed out, and its keys"
+    echo "[node-join]   were never persisted — nothing here can authenticate as that name."
+    echo "[node-join]   Set APP_NODE_ID to an unused name (an identity name cannot be reused)."
+    exit 1
+  fi
+  echo "[node-join] first boot: claiming identity '$NODE_ID' via $DEVNET_API"
+  java -cp "/opt/evolver/lib/*" ce.evolver.tools.IdentityClaimClient \
+    --target="$DEVNET_API" --node-id="$NODE_ID" --out="$CLAIM" \
+    --timeout="${CLAIM_TIMEOUT:-180}" || CLAIM_RC=$?
+  if [ ! -f "$CLAIM" ]; then
+    # OUR attempt's outcome is now the unknown one, and asking ONCE is not enough: a
+    # `504 confirmation_timeout` means the transaction was submitted, and it can commit
+    # minutes later (its TTL is +50 rounds, and on a quiescent chain rounds are slow).
+    # Asking immediately and printing "the name is still free" was wrong while the claim
+    # was in flight — and with `restart: unless-stopped` the next boot would claim the
+    # same name AGAIN with fresh keys, which is how a name gets bound to keys nobody
+    # holds. So watch it for a bounded window before saying anything.
+    echo "[node-join] the claim for '$NODE_ID' did not confirm (exit ${CLAIM_RC:-?}) —"
+    echo "[node-join]   outcome UNKNOWN. Watching for up to ${CLAIM_WATCH_SECS:-300}s to see"
+    echo "[node-join]   whether it commits; nothing is resent."
+    _waited=0
+    _final=free
+    while [ "$_waited" -lt "${CLAIM_WATCH_SECS:-300}" ]; do
+      _s="$(id_state "$NODE_ID")"
+      if [ "$_s" = taken ]; then _final=taken; break; fi
+      sleep 10
+      _waited=$((_waited + 10))
+    done
+    if [ "$_final" = taken ]; then
+      echo "[node-join] FATAL: the claim for '$NODE_ID' COMMITTED after its confirmation"
+      echo "[node-join]   timed out, and its keys were never persisted (evolver#86)."
+      echo "[node-join]   Set APP_NODE_ID to an unused name and start again — an identity"
+      echo "[node-join]   name cannot be reused."
+    else
+      echo "[node-join] '$NODE_ID' is still not on chain after ${_waited}s, so the claim"
+      echo "[node-join]   did not commit and the name remains free; a restart may retry it."
+    fi
+    exit 1
+  fi
+  chmod 600 "$CLAIM"
+  echo "[node-join] claim committed — keys persisted (mode 600)"
+fi
+
+# EVOLVER_PRIVATE_KEY / EVOLVER_NODE_PUBLIC_KEY / EVOLVER_BLS_SEED
+set -a
+. "$CLAIM"
+set +a
+
+mkdir -p /data/chain
+# Config-only directory is mounted read-only into this node. Only the shared SDK controller
+# writes it. Ordinary boot NEVER merges environment/module defaults or initializes a missing file.
+# SDK initialization is an explicit fresh-resource command; its marker survives an empty set.
+# Already required before any identity/claim effects at entry.
+# Keep keys/chain private: no agent/container writes this node's database or fragment.
+chmod 700 /data/chain
+
+# ── WHICH PEERS THIS NODE DIALS ───────────────────────────────────────────
+#
+# ONE list rendered as BOTH keys, because they are one decision: `preferred-peers` says
+# who, `allowed-outbound` says how many, and the pin is strict only while the two agree
+# (node.conf says why). Computed here rather than written in node.conf for the same
+# reason the channel list is — so the two halves cannot drift apart.
+#
+# The upstream is always dialled. EVOLVER_DA_PEERS adds the DA members this deployment
+# must reach to PULL bodies for the channels declared above; without a slot for them,
+# `ChannelOverlay.peers()` is empty for those channels and nothing is ever fetched.
+_peers="${EVOLVER_UPSTREAM_NODE_ID}"
+# EVOLVER_DA_PEERS, comma-separated, deduplicated against the upstream. The comment above has
+# promised this since the file was written and the code never did it — so a deployment that set
+# it got silence, and the only way to pin a second peer was to smuggle a comma into
+# EVOLVER_UPSTREAM_NODE_ID, which works here only by accident of raw substitution and breaks the
+# dedupe and the count in the sibling stacks that DO implement this. Same shape as
+# evolver-llm/docker-compose.devnet.yml.
+for _p in $(printf '%s' "${EVOLVER_DA_PEERS:-}" | tr ',' ' '); do
+  if [ -n "$_p" ] && [ "$_p" != "${EVOLVER_UPSTREAM_NODE_ID}" ]; then
+    _peers="$_peers, $_p"
+  fi
+done
+_outbound="${EVOLVER_ALLOWED_OUTBOUND:-16}"
+echo "[node-join] pinning ${_peers} as the seed; allowing ${_outbound} outbound so discovery can happen"
+{
+  # The seed is PINNED so there is always a way back to the chain. `allowed-outbound` is
+  # deliberately LARGER than that one entry: the pin is strict only while the two are equal, and a
+  # strict pin would stop this node dialling anything it discovers. Once it has peers it learns its
+  # own distance to the committee and forwards transactions along that path like any other node.
+  printf 'evolver.peer-discovery.preferred-peers  = [ %s ]
+' "$_peers"
+  printf 'evolver.peer-discovery.allowed-outbound = %s
+'     "$_outbound"
+} > /data/chain/peers.conf
+
+echo "[node-join] launching follower '$NODE_ID' — syncing devnet from block 0"
+exec /opt/evolver/bin/evolver -Dconfig.file=/config/node.conf "$NODE_ID"
+