@mcsherrylabs/evolver-mcp 0.8.3 → 0.8.4

package/deploy/config/genesis.devnet.conf

@@ -0,0 +1,92 @@
+# devnet genesis — the committee, plus SEED NODES (170).
+#
+# ⚠️ THIS FILE IS THE CHAIN'S IDENTITY. Its canonical hash is the genesis block id, so any edit
+# here produces a DIFFERENT CHAIN. Every node must hold a byte-identical copy; a node with an
+# older one does not disagree politely, it cannot join at all.
+#
+# ── Why the seed entries exist (170, issue #121) ────────────────────────────────────────────
+# A node starting with an empty volume can only learn a peer's ADDRESS from this file, and can
+# only VERIFY a peer whose key is already in its chain state — which, before it has synced, is
+# also only this file. Both roads lead here. Before 170 this file named one node, the committee,
+# whose `allowed-inbound` is deliberately full, so a newcomer could reach nothing it was able to
+# trust and nothing it was able to trust would accept it. No configuration could fix that.
+#
+# A `quorum-weight = 0` entry is present-and-trusted WITHOUT being on the committee: it is seeded
+# as an identity, its Ed25519 key becomes verifiable, and its address becomes dialable — while
+# `seedGenesis` keeps it out of the quorum store and leader rotation filters it out of the
+# proposer set. That is the whole mechanism; no new key, no new trust path.
+#
+# ⚠️ The two front nodes keep the names they already had. They were NOT in genesis before, so a
+# chain rebuild would have reassigned their names and invalidated every pin across the estate and
+# the published installer. Pinning them here makes the names stable by construction.
+ce.evolver.genesis.nodes = [
+  # ── the committee ──────────────────────────────────────────────────────────────────────────
+  {
+    node-id        = "devnet1-node0"
+    host           = "devnet.mcsherrylabs.com"
+    port           = 7000
+    public-key     = "MCowBQYDK2VwAyEAxTC3mipBz3Ae6nkUzORWLAco21eX3iSSC+QEUSbJMCs="
+    bls-public-key = "rCrpHeLH85ECkow6A58I54fjvtCmOHfdm1llPrish+aD49l32sBciyYAzytRxwak"
+    quorum-weight  = 1000
+  },
+
+  # ── seed nodes: weight 0, so present and trusted but never voting, never leading ───────────
+  #
+  # ⚠️ Keys are the ones these two nodes ALREADY hold, read from their own /status. Their host
+  # secrets are untouched and stay where they are — only the public halves appear here.
+  {
+    node-id        = "evolvermeerkatnode920080"
+    host           = "65.21.255.224"
+    port           = 7100
+    public-key     = "MCowBQYDK2VwAyEAvDNSSDsSYRHfvFCOcl/Fba89VnBrkLzYBy28xqjg8Zg="
+    bls-public-key = "iJZMbE+J+TnNnHpYxk2lQDJipTvvUg0qCQNVJViTfoatqZkqazLCZbUmSP4W26Vj"
+    quorum-weight  = 0
+  },
+  {
+    node-id        = "schednode2"
+    host           = "65.21.255.224"
+    port           = 7200
+    public-key     = "MCowBQYDK2VwAyEAvUOp3fA1nTjv546jme0n14wYDVjHshLL3I7XpQxQ8V4="
+    bls-public-key = "ht3U8qRoQtKIU0NUbuuwx/ni4iF+rcAs2dJgxDOcf+YOs+brlSKSnC2XBFBp1rR1"
+    quorum-weight  = 0
+  },
+
+  # ⚠️ devnet-seed-3 IS NEVER DEPLOYED, ON PURPOSE, AND MUST STAY THAT WAY. A list of seeds is
+  # only worth having if a dead entry is walked past rather than waited on, and a seed that is
+  # permanently absent tests that on every single join instead of on the one afternoon somebody
+  # remembers to stop a live one. Its private key material was generated in a throwaway container
+  # and destroyed with it — nobody can bring this node up, which is the point. `.invalid` is
+  # reserved by RFC 2606 and can never resolve, so the attempt fails fast instead of hanging.
+  # If you are reading this because something reports it unreachable: that is the test passing.
+  {
+    node-id        = "devnet-seed-3"
+    host           = "devnet-seed-3.invalid"
+    port           = 7300
+    public-key     = "MCowBQYDK2VwAyEAHY2onS4+fZss0VZaT84AMcQQugILPagvBm3PFDE5cYY="
+    bls-public-key = "oO91EyEt4jvpP3XuuNiT+6F/9djCjAqgs/+e7eI64eGz9iRCcHT5HY17coLLKfsk"
+    quorum-weight  = 0
+  }
+]
+
+ce.evolver.consensus {
+  # ⚠️ ONE voting node. This is the committee size, not the number of genesis entries — the three
+  # seed entries above carry weight 0 and are not counted (NodeBootstrap derives the consensus
+  # cluster size with the same `quorumWeight > 0` filter the quorum store and leader rotation
+  # already use; before 170 it counted every entry, which would have put the relay threshold
+  # beyond anything a one-member committee could reach).
+  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
+  }
+}

package/deploy/config/node-join.sh

@@ -0,0 +1,270 @@
+#!/bin/sh
+# Claim-then-boot (evolver feature 102), the pattern from the evolver repo's
+# deployments/group-chat/app-node-init.sh, made publishable: nothing is bind-mounted and
+# the node id is derived rather than required, so this artifact runs in an empty
+# directory with no arguments.
+#
+# 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
+
+: "${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
+
+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 -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
+# ⚠️ THE AGENT WRITES HERE TOO, as uid 1000, not as this node's uid (10001). Without o+rwx on
+# the directory the agent gets EACCES creating the file at all. The Docker socket already grants
+# equivalent access (docker exec), so this does not widen the effective boundary.
+chmod o+rwx /data/chain
+
+# ── WHICH CHANNELS THIS NODE DECLARES ─────────────────────────────────────
+#
+# ONE decision, in ONE place, keyed on the SAME switch the app uses. The node config
+# `include required`s this file, so if the write below ever fails the node refuses to
+# start instead of quietly declaring nothing (HOCON ignores an absent optional include,
+# and a node that declares no channels retains no bodies, streams nothing and delivers
+# nothing — while logging nothing unusual).
+#
+# The registry's channel is declared IFF a registry is deployed here. Declaring it
+# otherwise wedges this node's apply on the first transaction written to a channel it is
+# not a DA member of: nothing stores the body, nothing can pull it, and apply is
+# forward-only (evolver#83).
+# ⚠️ A SUBSCRIPTION IS HOW THIS COMPONENT GAINS A CAPABILITY, not a configuration detail. Each
+# ledger declared here is something the component can then process, index and act on — the set grows
+# as its owner's interests do.
+#
+# The precondition is not optional: this node must be able to OBTAIN the bodies. A channel with a DA
+# policy serves them from its DA group, so this node needs a live connection to a member — otherwise
+# apply blocks on the first body it cannot fetch, PERMANENTLY, because apply is forward-only
+# (evolver#83). For `ce.meerkat.announcements` that group is `evolvermeerkatA286174reg`, whose only
+# member is `appnode046550` — which this node discovers and dials.
+#
+# ⚠️ THIS LIST IS MERGED, NEVER REPLACED. `meerkat_add_channel` writes the same file when the
+# agent subscribes to something, so the file is the union of two writers: this deployment's
+# channel, which is a property of the deployment, and whatever the agent has since subscribed
+# to, which is a property of its work. A boot that rewrote the list from EVOLVER_CHANNEL alone
+# would silently revoke every capability the agent had gained — including the reply channel it
+# is waiting on — and the agent has no way to notice: the file it wrote is simply gone.
+#
+# ⚠️ AND IT IS WRITTEN tmp-THEN-RENAME, chmod 666. Two uids write this one file, and a plain
+# `>` redirect must open the EXISTING file for writing: whichever of them creates it owns a
+# 0644 the other then cannot truncate, for as long as the file lives. That is not theoretical —
+# it wedged a node in a restart loop (`cannot create /data/chain/channels.conf: Permission
+# denied`), and because `include required` makes the node refuse to start rather than declare
+# nothing, the whole stack came down with it. `mv` needs write on the DIRECTORY, which the
+# o+rwx above grants both, so the rename lands whoever owns the old file; the 666 then lets
+# the agent's direct `writeFileSync` land too.
+# ⚠️ THE MCP CONSUMES NO CHANNEL STREAM, so the node declares NO channel by default
+# (`EVOLVER_CHANNEL` defaults empty). The `include required` of `channels.conf` in node.conf still
+# needs the file to EXIST, so an empty list is written below rather than the file being omitted.
+_ch="${EVOLVER_CHANNEL:-}"
+_conf=/data/chain/channels.conf
+_existing=""
+if [ -f "$_conf" ]; then
+  # the HOCON this file ever contains is one list on one line, written by this script or by
+  # pi-meerkat's formatHocon — strip to the bare comma-separated ids.
+  _existing=$(sed -n 's/.*\[\(.*\)\].*/\1/p' "$_conf" | tr -d ' "')
+fi
+_merged="$_ch"
+for _c in $(echo "$_existing" | tr ',' ' '); do
+  [ -n "$_c" ] || continue
+  [ "$_c" = "$_ch" ] && continue
+  _merged="$_merged,$_c"
+done
+# An empty channel set becomes `[]`, not `[""]` — the node declares no subscribed channel, which
+# is correct for a reader that owns no channel stream.
+if [ -z "$_merged" ] || [ -z "${_merged##*,}" ]; then
+  _body="[]"
+else
+  _body="[ $(echo "$_merged" | sed 's/,/", "/g; s/^/"/; s/$/"/') ]"
+fi
+echo "[node-join] declaring channels: $_merged"
+printf 'ce.evolver.subscribed-channels = %s\n' "$_body" > "$_conf.node.tmp"
+chmod 666 "$_conf.node.tmp"
+mv -f "$_conf.node.tmp" "$_conf"
+
+# ── 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"
+

package/deploy/config/node.conf

@@ -0,0 +1,277 @@
+# This node: a NON-GENESIS FOLLOWER on devnet. Chain-wide params come from the genesis
+# spec — never set them here, they must stay byte-identical on every node. Only
+# node-local knobs below.
+include file("/config/genesis.devnet.conf")
+
+# 089 chain-spec pin: the canonical hash of the genesis file IS the genesis block id.
+# Any drift refuses to boot rather than forking quietly.
+ce.evolver.genesis-file = "/config/genesis.devnet.conf"
+
+# This node's OWN identity, from the first-boot faucet claim (node-join.sh). REQUIRED
+# substitutions (no `?`): a node booting with missing keys must fail fast, not later and
+# obscurely at the first TLS handshake.
+ce.evolver.node {
+  private-key = ${EVOLVER_PRIVATE_KEY}      # Ed25519 PKCS#8 base64
+  public-key  = ${EVOLVER_NODE_PUBLIC_KEY}  # Ed25519 X.509 base64
+  bls-secret  = ${EVOLVER_BLS_SEED}         # BLS IKM base64
+  port        = ${EVOLVER_NODE_PORT}        # p2p transport (raw TCP, mTLS)
+}
+
+evolver.peer-discovery {
+  # THIS NODE ADVERTISES NOTHING, AND MUST NOT. `preferred-url` is the address this node
+  # gossips as its OWN (`""` = feature off), and a joined app node behind Docker HAS no
+  # routable p2p address: its 7000 is container-local and deliberately unpublished. So
+  # advertising one means every node on the chain records `<us> -> https://127.0.0.1:7000`
+  # and then dials its own loopback.
+  #
+  # Observed on devnet, and it is worse than noise: this node CONNECTED TO ITSELF, logged
+  # `Peer connected: <self>`, sent its own SyncManager `BlockRangeRequest(4841,4845)`, and
+  # TipGossip then reported `rotating to <self> (failed=devnet1-node0)` followed by
+  # `stalled (upstream=none)`. After that its submits were never forwarded and every write
+  # timed out. The table also keeps the dead: `evolvertemplateappnode965813 at
+  # 127.0.0.1:7000` from an earlier deployment was still being dialled hours later.
+  # ADVERTISED AGAIN, and ⚠️ ONLY BECAUSE IT IS NOW REAL. This was `""` because the node
+  # had been advertising `https://127.0.0.1:7000`: every peer that read the discovery
+  # table dialled its OWN loopback, so this node connected to itself, sent its own
+  # SyncManager block requests, reported `candidates=<self>` / `stalled (upstream=none)`
+  # and stopped forwarding submits. An unroutable value reinstates that exactly — which
+  # is why `EVOLVER_TRANSPORT_ADDRESS` is REQUIRED here rather than defaulted, and why the
+  # command suite refuses a loopback value.
+  # ⚠️ EMPTY, DELIBERATELY. This node is a READER behind NAT: it has no routable p2p address.
+  # Advertising one is not merely useless, it is harmful — devnet recorded a node that advertised
+  # an unroutable address CONNECTING TO ITSELF, sending its own sync requests, reporting
+  # `stalled (upstream=none)`, and leaving dead entries other nodes dialled for hours.
+  #
+  # It costs this node nothing: advertising is how others DIAL YOU, and nothing needs to. Writing
+  # still works — this node dials OUT, discovers the network, learns its distance to the committee
+  # and forwards transactions along that path. Being undialable only stops bodies being flooded TO
+  # it, which is a DA member's concern and not a reader's.
+  transport-address       = ""
+  peer-url                = ""
+  gossip-interval-seconds = 60
+
+  # 16 INBOUND, not 0. The 141 leaf recipe (`in=0`) is right for an app node that only
+  # talks upstream — and wrong here: the registry's channel requires announcers' nodes to
+  # reach THIS node so their flooded bodies can be attested (research D2). Each announcer
+  # holds one inbound slot, so 16 is the number of concurrent announcer nodes supported.
+  # Generous on both sides so DISCOVERY actually happens. The seed below is pinned so the node
+  # always has a way back to the chain, but `allowed-outbound` is deliberately LARGER than the
+  # pinned list — the pin is strict only while the two are equal, and a strict pin here would mean
+  # this node never dials anything it discovers.
+  allowed-inbound         = 16
+  # `allowed-outbound` and `preferred-peers` are DELIBERATELY ABSENT HERE — node-join.sh renders
+  # both into peers.conf so the two cannot drift apart in two files.
+  #
+  # ⚠️ THIS COMMENT USED TO CLAIM THE PIN IS STRICT. It is NOT, and the difference matters to
+  # anyone reasoning about what this node will dial. It said `|preferred| == allowed-outbound`
+  # holds "by construction"; node-join.sh renders ONE pinned seed and an outbound budget of 16,
+  # so 1 != 16 and the pin is deliberately LOOSE. That is the intended design — a follower has to
+  # dial what it discovers or it is a leaf — but the old wording described the opposite property
+  # and named the incidents (a dead address from a torn-down deployment still being dialled, this
+  # node dialling its own loopback) that a strict pin was supposed to prevent. Those are the COST
+  # of the loose pin, not evidence against it: the seed guarantees a way back to the chain, and
+  # discovery does the rest. Which is what keeps a shared chain's discovery table out of the
+  # dial queue — it keeps the dead (an address from a torn-down deployment was still
+  # being dialled hours later) and once made this node dial its own loopback. Raising
+  # the budget without naming a peer would silently unpin it; naming a peer without
+  # raising the budget could never reach it. One list, both keys, no drift.
+  #
+  # ⚠️ THIS USED TO BE `out=1`, copied verbatim from the 141 LEAF recipe, and it decided
+  # WHICH CHANNELS THIS NODE COULD READ — silently. `ChannelOverlay.peers(ledgerId)` is
+  # the channel's DA group ∩ connected, so with the one slot spent on the upstream every
+  # channel whose DA member is somebody else resolved to an EMPTY pull set: the node
+  # records the miss, sends no request, and says so at DEBUG only (evolver#89). A node
+  # reading a channel it does not itself serve needs the upstream AND one reachable DA
+  # member per such channel, so a fixed 1 is only ever right for a node that reads
+  # nothing but its own.
+}
+
+ce.evolver.consensus {
+  validate-chain-on-startup = false
+  wake-on-work { forward-watermark = 16 }
+}
+
+# PROCESSING MODE — off by default, and THE REASON THIS DEPLOYMENT EXISTS once your app
+# reads a channel.
+#
+# `/api/channel/next` is a SINGLE-CONSUMER, FORWARD-ONLY cursor: two readers do not
+# error, they silently split the stream and the message is unrecoverable. So an app that
+# consumes an ordered channel must drain a node NOBODY ELSE drains — which means a node
+# of its own. It cannot share a public one, and a single-node chain (devnet today) IS the
+# committee, so that node is not a processing node and serves no stream at all.
+#
+# And the committee's node must never be put in this mode: processing mode DEFERS apply
+# and paces it from the app's polling, so a committee node in processing mode would
+# couple consensus progress to an HTTP poller. Ordering is its job; give the app its own.
+#
+# Turning it on changes what committed reads MEAN here — they answer "as of MY cursor".
+# Measured in this family (evolver-scheduler): right after a successful faucet claim a
+# quorum node reported `{"balance":5000}` for an identity while a processing node
+# reported `{"error":"not_found"}` for the same one. An app in that mode needs to know
+# which of its questions are "has the chain agreed?" (ask a quorum node) and which are
+# "what have I processed?" (ask this one).
+#
+# ON, because this app owns a channel (`announcements`) and reads its ordered stream —
+# steps 5-7 of src/app.ts. BOTH lines are needed and neither works alone: a node in
+# processing mode with no channels declared has nothing to offer, and a node that
+# declares channels without execution stores bodies it never streams.
+#
+# The channel must be named HERE as well as claimed on chain. A processing node stores
+# bodies only for the channels it lists, so an undeclared channel's message is applied
+# in the slice and never offered — the write looks fine and the stream stays silent,
+# which is the failure the app's step 7 names explicitly.
+# ⚠️ OFF. This is a READER, and processing mode is what a node running an APP turns on.
+#
+# In processing mode apply is DEFERRED and paced by the app polling /api/channel/next, so
+# committed reads answer "as of MY cursor" rather than "as of the chain". With no channels
+# declared and no consumer draining — which is exactly this node — the cursor never advances and
+# NOTHING IS EVER APPLIED: the node syncs every block and still answers `not_found` for an identity
+# the chain committed. Observed here: its own identity, committed at block 7225 and verified on
+# chain, was unknown to it at height 7231.
+#
+# ⚠️ ON, NOW THAT SOMETHING DRAINS THIS NODE. The rule is not "readers off, apps on" — it is that
+# processing mode paces apply from whatever drains /api/channel/next, so it is correct exactly when
+# there IS a drainer and catastrophic when there is not (with none, this node synced every block and
+# still answered `not_found` for an identity it had itself committed).
+#
+# The meerkat registry beside it is that drainer. Its polling is what advances apply, so the agent's
+# reads stay correct — as of that cursor, which is what a component reading its own processed state
+# means by correct.
+ce.evolver.execution.enabled = ${?EVOLVER_EXECUTION_ENABLED}
+# ⚠️ THE CHANNEL LIST IS GENERATED BY node-join.sh, and `include required` means this node
+# REFUSES TO START if the fragment is missing rather than silently declaring nothing.
+#
+# It cannot be written here, because WHICH channels this node declares depends on whether
+# a registry is deployed beside it — and declaring one that is not wanted is not harmless:
+#
+#   the registry's channel is declared by the node so it can STORE and ATTEST bodies
+#   (`onBody` drops a flooded body for an undeclared channel, and a body it never stored
+#   is one it cannot attest — at m=1 that stops the registry rather than degrading it);
+#
+#   but a node that declares a channel it is NOT a DA member of STALLS at every transaction
+#   on that channel. `channelSubscribes` is false, so it stores no body, and nothing can be
+#   pulled either (the DA group's members are identities, not this node's peers), so the
+#   position answers `body-pending` and the cursor sits ON it — applied state, and every
+#   committed read, frozen at the block before it.
+#
+#   ⚠️ NOT a permanent wedge of the NODE, and evolver#83 was corrected on exactly this
+#   point: the runner advances the cursor atomically with the apply and the body lookup
+#   happens afterwards, so a CONSUMER that asks for `index + 1` walks past and the skipped
+#   transaction is still applied in the slice. What is permanent is the LOSS of that
+#   message. So the stall lasts as long as the consumer retries the same position — which
+#   the SDK's `drainChannel` does, correctly, for at-most-once delivery — and it is
+#   reachable by anyone willing to spend 10 credits on an id-only write to an unclaimed
+#   name. Declaring only what this deployment participates in avoids the whole question.
+#
+# In demo mode this node is not in the registry channel's DA group — nothing here claimed
+# it — so declaring it was exactly that hazard. The switch is PROCESSOR_HTTP_PORT (named
+# REGISTRY_HTTP_PORT before meerkat v0.6.0), the same one the app uses to decide it is a
+# service, so the two cannot disagree.
+include required(file("/data/chain/channels.conf"))
+# `required` for the same reason: an absent optional include is IGNORED, and a node
+# that silently fell back to the 64/64 defaults would dial the discovery table.
+include required(file("/data/chain/peers.conf"))
+
+# ── THE LOCAL ROUTES THIS DEPLOYMENT OPENS TO ITS OWN CONTAINERS ────────────
+#
+# The agent and the registry run BESIDE this node, each in its own container on this compose
+# project's network. These routes carry no token and no client certificate — reaching the address
+# IS the authorization — so the node binds them to loopback unless told otherwise, and loopback
+# inside this container is reachable by nothing else in the stack.
+#
+# `bind-host = 0.0.0.0` here means: THIS COMPOSE NETWORK IS THE BOUNDARY. That claim holds only
+# because none of these ports appear under `ports:` in docker-compose.yml and the stack does not
+# use host networking. Publish one, or run with `--network host`, and the claim is simply false.
+#
+# ⚠️ `ce.evolver.login` is deliberately NOT here and cannot be: that route signs as any identity
+# this host holds a signer for, which on this node is the node's own. Setting `bind-host` under
+# that namespace fails the boot rather than being ignored.
+
+# 145 — the agent sends and drains application messages. `/api/p2p/send` relays a message the
+# agent signed ITSELF (its own identity, verified at the far end); `/api/p2p/sign-and-send` makes
+# this node sign as itself. One listener, so opening it grants both.
+ce.evolver.p2p {
+  http-port = 8460
+  bind-host = "0.0.0.0"
+}
+
+# 158 — the agent may ASK an enrolled phone to authorise a transaction. It cannot sign: the device
+# holder approves every one, and that gate does not move when the bind does. Inert until a
+# `mobile-signer` block exists, and the node says so at boot rather than failing.
+ce.evolver.mobile {
+  http-port = 8470
+  bind-host = "0.0.0.0"
+}
+
+# 139 — CONTENT, so the agent can publish a document and the registry can read one back.
+#
+# `POST /content` writes to this node's own store, keyed by the bytes' own digest, and talks to
+# no peer at all (FR-006). `bind-host` below is what lets the agent and the registry reach that
+# route from their own containers. Fetching a document another node holds is the part that uses
+# the overlay, and that is what the TLS listener underneath is for.
+ce.evolver.content {
+  enabled   = true
+  http-port = 8450
+  bind-host = "0.0.0.0"
+}
+
+data.base       = "/data/chain"
+state.snapshots = "snapshots"
+# BOTH LISTENERS, and the pair is the point.
+#
+# 8440 PLAIN is what the agent and the registry talk to. They are ordinary HTTP clients in their
+# own containers, and the alternative is not "use TLS" — this node's HTTPS listener presents its
+# own IDENTITY certificate, self-signed, CN=<nodeId>, ~13 minutes old. It rotates, so it cannot
+# be pinned as a CA, so a client that verifies it must turn verification off process-wide. For
+# the agent that would also stop it verifying GoToSocial, which is not a trade worth making for
+# a hop between two containers on one network.
+#
+# 8441 TLS is what PEERS use, and it exists so `ce.evolver.content` above can: the content peer
+# route identifies its requester by client certificate, and refuses to start without somewhere
+# mTLS to live. NOT PUBLISHED in docker-compose.yml — this node is a reader behind NAT that
+# fetches outbound and serves nobody, so nothing needs to dial it.
+#
+# ⚠️ IF THIS NODE EVER SERVES CONTENT, `evolver.peer-discovery.api-url` must name 8441 and that
+# port must be publicly reachable. It is empty here (see above): a node with no routable address
+# advertises nothing and can only fetch.
+http.port       = 8440
+# Only this private Compose network may reach the unsigned processing API.
+http.bind-host  = "0.0.0.0"
+# ⚠️ REQUIRED SINCE 131 (#131), and without it this stack breaks. `http.bind-host` now defaults
+# to 127.0.0.1 — the plain listener joined the bind-is-authorization set the four local listeners
+# above already belong to, because it carries the whole API with no token and no client
+# certificate, including (this node runs `ce.evolver.execution.enabled`) the SINGLE-CONSUMER
+# cursor `GET /api/channel/next`, which a stranger can step past the registry's own deliveries.
+#
+# The claim being made here is the same one `ce.evolver.content.bind-host` and the p2p/login ones
+# above make: THIS COMPOSE NETWORK IS THE BOUNDARY. It holds because 8440 is NOT published in
+# docker-compose.yml and nothing uses host networking — the agent and the registry reach this
+# node as `node:8440`, a service name on that network. Publish the port, or run with host
+# networking, and the claim stops being true. The node cannot tell, so it logs a WARN naming it.
+http.bind-host  = "0.0.0.0"
+https.port      = 8441
+evolver.grpc.port = 9000
+
+# REQUIRED, and there is no default: `NodeBootstrap.initChainDb` reads this block
+# directly, so a node without it dies with `No configuration setting found for key
+# 'chainDb'` after the migrations have already run — which is exactly how this omission
+# was found. Same values as the bundled deployment's node.
+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
+}
+

package/deploy/docker-compose.yml

@@ -0,0 +1,104 @@
+# Evolver devnet-follower NODE + the evolver-mcp stdio server's launch context.
+#
+# One `docker compose -f deploy/docker-compose.yml up -d` starts a LOCAL Evolver node that
+# JOINS and syncs the live devnet chain (it is a non-genesis follower, not a new chain), and the
+# env contract an agent runtime supplies when it launches `npx -y @mcsherrylabs/evolver-mcp`
+# against that node.
+#
+# CONTENT LIVES HERE, NOT ON DEVNET. The MCP posts to and reads from THIS node's own content
+# cache (`ce.evolver.content.http-port = 8450`) via `EVOLVER_CONTENT_URL=http://node:8450`. The
+# devnet URL is only the FAUCET origin for the node's first-boot identity claim; every other call
+# is against the local node (`node:8440` chain API, `node:8450` content).
+#
+# GROUNDING — mirror /workspace/evolver/deployments/claude-agent/, the canonical follower pattern:
+#  - genesis.devnet.conf is a BYTE-IDENTICAL copy of the devnet genesis (committee + seed nodes).
+#    It is the chain's identity; never edit it.
+#  - node-join.sh is the claim-then-boot entrypoint: mint node keys locally, faucet-claim the
+#    identity on devnet (the committee sponsors it), persist the claim, then start as a non-genesis
+#    follower syncing from block 0.
+#  - node.conf includes genesis + peers.conf + channels.conf; content 8450, chain API 8440, TLS
+#    8441 (peer content fetches), gRPC 9000.
+#
+# THE MCP IS STDIO, NOT A LONG-RUNNING SERVICE. There is no published evolver-mcp image; an agent
+# runtime (Claude Code / Codex) launches it per session as a child process. The `mcp` service below
+# only documents the exact env contract (see the comment on it). For dockerized use, build from
+# docs/mcp.Dockerfile and exec `docker compose run --rm mcp npx -y @mcsherrylabs/evolver-mcp …`.
+
+name: evolver-mcp
+
+services:
+  # ── the LOCAL devnet follower ──────────────────────────────────────────────
+  node:
+    image: ${EVOLVER_REGISTRY:-nexus.mcsherrylabs.com}/evolver-node:${EVOLVER_VERSION:-v0.24.5}
+    restart: unless-stopped
+    environment:
+      # The node claims its OWN identity (node keys never leave this container) and persists the
+      # name to /data/keys/node-id. `<APP_NAME>node<random6>` keeps a shared chain collision-free.
+      APP_NAME: evolverscp
+      # FAUCET ONLY — the first-boot claim target. Not the chain URL the MCP talks to.
+      DEVNET_API: ${DEVNET_API:-https://devnet.mcsherrylabs.com}
+      # THE MCP READS NO CHANNEL STREAM, so the node declares NO channel. Empty on purpose: a node
+      # that declares a channel it is not a DA member of stalls its apply (evolver#83).
+      EVOLVER_CHANNEL: ${EVOLVER_CHANNEL:-}
+      # ⚠️ PIN A FRONT/SEED NODE, NOT THE COMMITTEE. `devnet1-node0` runs `allowed-inbound = 2`
+      # with both slots reserved; pinning it cannot work (every dial is refused).
+      EVOLVER_UPSTREAM_NODE_ID: ${EVOLVER_UPSTREAM_NODE_ID:-evolvermeerkatnode920080}
+      EVOLVER_DA_PEERS: ${EVOLVER_DA_PEERS:-schednode2}
+      EVOLVER_ALLOWED_OUTBOUND: ${EVOLVER_ALLOWED_OUTBOUND:-16}
+      # ⚠️ PROCESSING MODE STAYS OFF. Apply would be paced by whatever drains /api/channel/next;
+      # with no drainer the cursor never advances and committed reads answer not_found. A reader
+      # with no channel owns no stream, so leave this unset (the config's `?` makes it optional).
+      #
+      # (Deliberately ABSENT, not "false": the config reads `ce.evolver.execution.enabled = ${?EVOLVER_EXECUTION_ENABLED}`
+      #  — unset means "off", which is exactly a reader node.)
+      # p2p transport on 7100, NOT 7000 (most devnet discovery entries advertise 127.0.0.1:7000,
+      # which a node on 7000 would dial into its own loopback).
+      EVOLVER_NODE_PORT: "7100"
+    volumes:
+      - node-data:/data
+      - ./config:/config:ro
+    # INVOKED VIA /bin/sh (a bind-mounted script's exec bit depends on the checkout's file mode).
+    entrypoint: ["/bin/sh", "/config/node-join.sh"]
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://127.0.0.1:8440/api/explorer/blocks?limit=1 >/dev/null || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 30s
+    # ⚠️ PUBLISHED LOOPBACK-ONLY (B1: the frictionless single-box install path). The host-side
+    # `npx … install` bootstrap reaches the node at http://127.0.0.1:8440 (chain API) and
+    # http://127.0.0.1:8450 (content) after `up -d node`. Nothing leaves the machine: `host_ip:
+    # 127.0.0.1` keeps both listeners local, and the node's p2p/TLS listeners stay unpublished
+    # (they are for PEERS, reached over the compose network's DNS).
+    ports:
+      - target: 8440
+        published: "8440"
+        host_ip: 127.0.0.1
+        protocol: tcp
+      - target: 8450
+        published: "8450"
+        host_ip: 127.0.0.1
+        protocol: tcp
+
+  # ── the MCP launch context (documentation only) ─────────────────────────────
+  # evolver-mcp is a STDIO server launched per session by an agent runtime — NOT a long-running
+  # compose service. This service exists to (a) pin the exact env contract and (b) give a
+  # containerized operator a `docker compose run --rm mcp …` target. `depends_on` documents that
+  # the node must be healthy before an MCP launch, since the MCP probes and exits if unreachable.
+  mcp:
+    image: node:22
+    profiles: ["run-only"]           # not started by `up -d`; a run-target only
+    environment:
+      # Chain API — the LOCAL node, not devnet.
+      EVOLVER_MCP_CONFIG: "/state/config.json"
+      # Content listener — the LOCAL node's content cache, a SEPARATE port from the chain API.
+      EVOLVER_CONTENT_URL: "http://node:8450"
+      EVOLVER_KEY_PATH: "/state/<identity>.key"
+      EVOLVER_KEY_TYPE: "bls"
+    depends_on:
+      node:
+        condition: service_healthy
+    restart: "no"
+
+volumes:
+  node-data:

package/dist/cli.js

@@ -12,9 +12,28 @@
 // checkout-entry form Phase 7 locked in.
 import { main } from "./index.js";
 import { hasBootstrapFlag, runBootstrap } from "./bootstrap.js";
+import { runInstall } from "./install.js";
 const PACKAGE_NAME = "@mcsherrylabs/evolver-mcp";
 const BOOTSTRAP_ENTRY_COMMAND = () => `npx -y ${PACKAGE_NAME}`;
+/** True when the first non-flag argv token is the `install` subcommand. */
+function isInstallCommand(argv) {
+    const i = argv.findIndex((a) => !a.startsWith("-"));
+    return i >= 0 && argv[i] === "install";
+}
 await (async () => {
+    if (isInstallCommand(process.argv)) {
+        // Package mode for the install: the printed registration resolves the published package.
+        const env = { ...process.env, EVOLVER_BOOTSTRAP_CWD: process.cwd() };
+        if (env.EVOLVER_MCP_ENTRY_COMMAND === undefined) {
+            env.EVOLVER_MCP_ENTRY_COMMAND = BOOTSTRAP_ENTRY_COMMAND();
+        }
+        const r = await runInstall(process.argv, env);
+        if (r.toStderr)
+            console.error(r.output);
+        else
+            process.stdout.write(r.output);
+        process.exit(r.exitCode);
+    }
     if (hasBootstrapFlag(process.argv)) {
         // Package mode: only if the operator has not already chosen an entry command, default the
         // registration to `npx -y @mcsherrylabs/evolver-mcp` so the printed `claude mcp add` resolves

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,0FAA0F;AAC1F,EAAE;AACF,gGAAgG;AAChG,2FAA2F;AAC3F,EAAE;AACF,4FAA4F;AAC5F,+FAA+F;AAC/F,6FAA6F;AAC7F,iGAAiG;AACjG,4FAA4F;AAC5F,yCAAyC;AAEzC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEhE,MAAM,YAAY,GAAG,2BAA2B,CAAC;AACjD,MAAM,uBAAuB,GAAG,GAAG,EAAE,CAAC,UAAU,YAAY,EAAE,CAAC;AAE/D,MAAM,CAAC,KAAK,IAAI,EAAE;IAChB,IAAI,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,0FAA0F;QAC1F,8FAA8F;QAC9F,8CAA8C;QAC9C,MAAM,GAAG,GAAsB,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,qBAAqB,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;QACxF,IAAI,GAAG,CAAC,yBAAyB,KAAK,SAAS,EAAE,CAAC;YAChD,GAAG,CAAC,yBAAyB,GAAG,uBAAuB,EAAE,CAAC;QAC5D,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChD,IAAI,CAAC,CAAC,QAAQ;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;;YACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,0FAA0F;AAC1F,EAAE;AACF,gGAAgG;AAChG,2FAA2F;AAC3F,EAAE;AACF,4FAA4F;AAC5F,+FAA+F;AAC/F,6FAA6F;AAC7F,iGAAiG;AACjG,4FAA4F;AAC5F,yCAAyC;AAEzC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,MAAM,YAAY,GAAG,2BAA2B,CAAC;AACjD,MAAM,uBAAuB,GAAG,GAAG,EAAE,CAAC,UAAU,YAAY,EAAE,CAAC;AAE/D,2EAA2E;AAC3E,SAAS,gBAAgB,CAAC,IAAc;IACtC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;AACzC,CAAC;AAED,MAAM,CAAC,KAAK,IAAI,EAAE;IAChB,IAAI,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,yFAAyF;QACzF,MAAM,GAAG,GAAsB,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,qBAAqB,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;QACxF,IAAI,GAAG,CAAC,yBAAyB,KAAK,SAAS,EAAE,CAAC;YAChD,GAAG,CAAC,yBAAyB,GAAG,uBAAuB,EAAE,CAAC;QAC5D,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,CAAC,QAAQ;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;;YACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,0FAA0F;QAC1F,8FAA8F;QAC9F,8CAA8C;QAC9C,MAAM,GAAG,GAAsB,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,qBAAqB,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;QACxF,IAAI,GAAG,CAAC,yBAAyB,KAAK,SAAS,EAAE,CAAC;YAChD,GAAG,CAAC,yBAAyB,GAAG,uBAAuB,EAAE,CAAC;QAC5D,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChD,IAAI,CAAC,CAAC,QAAQ;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;;YACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC,EAAE,CAAC"}

package/dist/install.d.ts

@@ -0,0 +1,21 @@
+interface InstallEnv {
+    /** Override the shipped compose file path (default: `../deploy/docker-compose.yml` beside dist). */
+    EVOLVER_INSTALL_COMPOSE?: string;
+    /** Health-poll ceiling in ms (default 120000). */
+    EVOLVER_INSTALL_TIMEOUT_MS?: string;
+    /** Node chain-API URL to poll (default LOCAL_CHAIN_URL). Override for a non-loopback topology. */
+    EVOLVER_INSTALL_HEALTH_URL?: string;
+}
+export interface InstallResult {
+    readonly exitCode: number;
+    readonly output: string;
+    readonly toStderr: boolean;
+}
+/** Resolve the shipped `deploy/docker-compose.yml`, honoring an explicit override. */
+export declare function composePathFor(env: InstallEnv, distDir: string): string;
+/** The dist dir this module runs from (src/ → dist/ at build time; dist/cli.js is the bin). */
+export declare function distDirFor(importMetaUrl: string): string;
+/** Spin up the node, wait healthy, then delegate to the bootstrap for the agent identity. */
+export declare function runInstall(argv: string[], env: NodeJS.ProcessEnv & InstallEnv): Promise<InstallResult>;
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAwBA,UAAU,UAAU;IAClB,oGAAoG;IACpG,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,kDAAkD;IAClD,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,kGAAkG;IAClG,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,6FAA6F;AAC7F,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,UAAU,GAClC,OAAO,CAAC,aAAa,CAAC,CAkDxB"}

package/dist/install.js

@@ -0,0 +1,96 @@
+// Frictionless install: start the LOCAL devnet-follower node as a Docker container, wait for it
+// to be healthy, then bootstrap the SEPARATE agent identity against it and print the registration.
+//
+// The node is `deploy/docker-compose.yml` (a non-genesis follower that joins + syncs devnet). The
+// node claims its OWN host identity (`node-join.sh` → faucet), distinct from the agent identity the
+// bootstrap mints here. Content is read/posted through the local node's listener (`:8450`), never
+// devnet directly — devnet is only the faucet origin for the node's first-boot claim.
+//
+// Reachability (B1): the compose publishes the node's 8440/8450 loopback-only, so THIS host-side
+// process reaches `http://127.0.0.1:8440` / `:8450`. The bootstrap then derives
+// `EVOLVER_CONTENT_URL` from the node's content port (see bootstrap's local-target derivation).
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runBootstrap } from "./bootstrap.js";
+/** The node's chain-API host the install bootstrap targets, per B1 (loopback publish). */
+const LOCAL_NODE_HOST = "127.0.0.1";
+const LOCAL_CHAIN_URL = `http://${LOCAL_NODE_HOST}:8440`;
+const HEALTH_PATH = "/api/explorer/blocks?limit=1";
+/** Resolve the shipped `deploy/docker-compose.yml`, honoring an explicit override. */
+export function composePathFor(env, distDir) {
+    const explicit = env.EVOLVER_INSTALL_COMPOSE?.trim();
+    if (explicit)
+        return resolve(explicit);
+    return resolve(join(distDir, "..", "deploy", "docker-compose.yml"));
+}
+/** The dist dir this module runs from (src/ → dist/ at build time; dist/cli.js is the bin). */
+export function distDirFor(importMetaUrl) {
+    return dirname(fileURLToPath(importMetaUrl));
+}
+/** Spin up the node, wait healthy, then delegate to the bootstrap for the agent identity. */
+export async function runInstall(argv, env) {
+    const composeFile = composePathFor(env, dirname(fileURLToPath(import.meta.url)));
+    if (!existsSync(composeFile)) {
+        return {
+            exitCode: 1,
+            toStderr: true,
+            output: `install: the node compose file is missing at ${composeFile} — the published package must ship deploy/ (see package.json "files").\n`,
+        };
+    }
+    // 1. Start the follower node (claims its own identity on devnet, then syncs from block 0).
+    const up = spawnSync("docker", ["compose", "-f", composeFile, "up", "-d", "node"], {
+        encoding: "utf8",
+        env: { ...process.env, ...env },
+    });
+    if (up.status !== 0) {
+        return {
+            exitCode: 1,
+            toStderr: true,
+            output: `install: docker compose up -d node failed:\n${up.stderr || up.stdout}`,
+        };
+    }
+    // 2. Wait for the node to answer its chain API before bootstrapping against it.
+    const healthUrl = env.EVOLVER_INSTALL_HEALTH_URL?.trim() || LOCAL_CHAIN_URL + HEALTH_PATH;
+    const timeoutMs = Number(env.EVOLVER_INSTALL_TIMEOUT_MS ?? "120000");
+    const ok = await waitHealthy(healthUrl, timeoutMs);
+    if (!ok) {
+        const logs = spawnSync("docker", ["compose", "-f", composeFile, "logs", "--tail", "40", "node"], {
+            encoding: "utf8",
+            env: { ...process.env, ...env },
+        });
+        return {
+            exitCode: 1,
+            toStderr: true,
+            output: `install: node did not become healthy at ${healthUrl} within ${timeoutMs}ms.\nnode logs:\n${logs.stdout || logs.stderr || "(no logs)"}\n`,
+        };
+    }
+    // 3. Bootstrap the SEPARATE agent identity against the local node. `--target local` +
+    //    EVOLVER_NODE=http://127.0.0.1:8440 makes the bootstrap derive
+    //    EVOLVER_CONTENT_URL=http://127.0.0.1:8450 (the local node's content listener).
+    const nodeEnv = {
+        ...process.env,
+        ...env,
+        EVOLVER_NODE: env.EVOLVER_NODE ?? LOCAL_CHAIN_URL,
+    };
+    const boot = await runBootstrap(argv, nodeEnv);
+    return { exitCode: boot.exitCode, output: boot.output, toStderr: boot.toStderr };
+}
+/** Poll `url` until it answers 200 (or a healthy node's success), bounded by `timeoutMs`. */
+async function waitHealthy(url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const r = await fetch(url, { signal: AbortSignal.timeout(5000) });
+            if (r.ok)
+                return true;
+        }
+        catch {
+            // not up yet — retry below
+        }
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    return false;
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcsherrylabs/evolver-mcp",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "MCP server over a configurable Evolver node — read the chain, sign a transfer, administer what you own, write to a channel, submit a signed transaction. Wraps @mcsherrylabs/evolver-client; implements no wire format of its own.",
   "type": "module",
   "license": "Apache-2.0",
@@ -12,7 +12,8 @@
     "evolver-mcp": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "deploy"
   ],
   "publishConfig": {
     "access": "public"
@@ -41,8 +42,9 @@
     "check:group": "tsx test/group-checks.ts",
     "check:channel": "tsx test/channel-checks.ts",
     "check:bootstrap": "tsx test/bootstrap-checks.ts",
+    "check:install": "tsx test/install-checks.ts",
     "check:publish": "tsx test/publish-checks.ts",
-    "test": "npm run build && npm run typecheck && npm run check:result && npm run check:config && npm run check:heights && npm run check:principal && npm run check:keys && npm run check:channelterms && npm run check:surface && npm run check:signing && npm run check:interval && npm run check:classify && npm run check:identity && npm run check:claim && npm run check:content && npm run check:inbox && npm run check:group && npm run check:channel && npm run check:bootstrap && npm run check:publish"
+    "test": "npm run build && npm run typecheck && npm run check:result && npm run check:config && npm run check:heights && npm run check:principal && npm run check:keys && npm run check:channelterms && npm run check:surface && npm run check:signing && npm run check:interval && npm run check:classify && npm run check:identity && npm run check:claim && npm run check:content && npm run check:inbox && npm run check:group && npm run check:channel && npm run check:bootstrap && npm run check:install && npm run check:publish"
   },
   "dependencies": {
     "@mcsherrylabs/evolver-client": "0.19.1",