@mcsherrylabs/pi-meerkat 0.8.0 → 0.11.0

package/README.md

@@ -5,7 +5,9 @@ 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.8.0 adds the zero-required-parameter installer.** Version 0.7.0 introduced the
+**Version 0.9.0 makes DevNet the default install target** (`install` installs against the public
+DevNet; `install --local` creates a private local chain). Version 0.8.0 added the
+zero-required-parameter installer (local chain only). 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`.
 
@@ -23,15 +25,34 @@ Prerequisites in the environment where your MCP harness runs:
 ### 1. Install
 
 ```bash
-npx --yes @mcsherrylabs/pi-meerkat@0.8.0 install
+npx --yes @mcsherrylabs/pi-meerkat@0.9.0 install          # public DevNet (default)
+npx --yes @mcsherrylabs/pi-meerkat@0.9.0 install --local  # private local chain
 ```
 
 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.
+or paid model service is required.
+
+**Default (DevNet)** installs a single non-genesis follower node against the public DevNet, syncing
+its shared chain, and a Meerkat registry that reads and indexes the shared, pinned
+`ce.meerkat.announcements` channel (owned by the pinned `evolvermeerkatA483344` operator). That
+registry runs **read-only**: it never claims, signs or submits with any identity. DevNet catch-up
+syncs from block 0 (~14k blocks at the time of release) and is paced by the registry's own cursor
+drain, so the first install can take a while; it reports progress and fails only if sync stalls.
+
+A DevNet install **permanently claims two DevNet identities**, both funded by the public DevNet
+faucet: its node (`meerkatnode<id>`) and your agent (`meerkatuser<id>`), which signs your
+announcements. Names on DevNet cannot be reused. Re-running install never claims again. DevNet mode
+needs **outbound internet access** from Docker (the node dials DevNet's front nodes, and the faucet
+is reached over HTTPS); it still publishes no host ports.
+
+**`--local`** creates an **independent private local chain** — an owned consensus node, a separate
+processing node, and a Meerkat registry/content/inbox service. The agent's own identity
+(`meerkatuser<id>`) owns the install's private `meerkat.<id>.announcements` channel (claimed once,
+idempotently), and nothing touches DevNet. In either mode the registry claims no identity, and the
+installer never inspects unrelated keys or changes another deployment. The first install downloads public pinned artifacts and
+builds the wrapper images, so allow time for Docker/npm downloads. Failed
+preflight/build/readiness exits nonzero with a reason. Each mode keeps its own state directory
+(`devnet/` or `local/` under your XDG state directory); 0.8.0 state is never touched.
 
 ### 2. Register one server
 
@@ -40,17 +61,20 @@ if you do not already have a registration named `meerkat`, the equivalent comman
 
 ```bash
 claude mcp add --scope user --transport stdio meerkat -- \
-  npx --yes @mcsherrylabs/pi-meerkat@0.8.0 serve
+  npx --yes @mcsherrylabs/pi-meerkat@0.9.0 serve
 ```
 
+Add `--local` after `serve` if you installed with `install --local`.
+
 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
+`serve` finds the installer's saved state automatically (default `devnet`, `--local` for the
+private chain); 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

package/dist/installer/committee-init.sh

@@ -1,25 +1,13 @@
 #!/bin/sh
-# node entrypoint: host keys + genesis on first boot, then exec the node.
+# committee 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).
+# 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. It also EXPORTS the public chain spec into /public-genesis/genesis.conf so the follower
+# can join the chain from it.
 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
@@ -27,6 +15,8 @@ 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
+  # PARTIAL STATE REFUSES: an incomplete owned key set is never regenerated (that would fork the
+  # chain identity), so a node with one of three and not the other two stops rather than claims on.
   [ -s "$ED_KEY" ] && [ -s "$BLS_KEY" ] && [ -s "$GENESIS" ] || {
     echo '[node-init] incomplete owned keys/genesis; refusing regeneration' >&2; exit 1;
   }
@@ -56,15 +46,8 @@ if [ ! -f "$ED_KEY" ]; then
   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}"
+  # Render the chain spec (089): committee PUBLIC keys + the chain-wide consensus parameters.
+  PUBLIC_HOST="${PUBLIC_HOST:-committee}"
   cat > "$GENESIS" <<EOF
 ce.evolver.genesis.nodes = [
   {
@@ -85,10 +68,7 @@ ce.evolver.consensus {
   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.
+  # Low idle disk-write: after 3 empty blocks the leader lingers on a 5-MINUTE heartbeat.
   quiescence {
     idle-heartbeat-ms       = 300000
     idle-after-empty-rounds = 3
@@ -96,7 +76,6 @@ ce.evolver.consensus {
 }
 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
@@ -106,7 +85,10 @@ 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'"
+# Publish the PUBLIC chain spec (keys + consensus) into the shared volume. The follower joins
+# from this copy, never from the committee's private data/keys volume. A differing existing copy
+# refuses replacement — the chain identity is hash-pinned, so a byte-different genesis is a
+# different chain.
 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
@@ -114,4 +96,6 @@ else
   chmod 640 /public-genesis/genesis.pending
   mv /public-genesis/genesis.pending /public-genesis/genesis.conf
 fi
+
+echo "[node-init] launching evolver node '$NODE_ID'"
 exec /opt/evolver/bin/evolver -Dconfig.file=/config/node.conf "$NODE_ID"

package/dist/installer/committee.conf

@@ -17,29 +17,21 @@ ce.evolver.node {
 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.
+  # these. Joining a real chain means setting them to the ROUTABLE p2p transport
+  # (raw TCP mTLS :7000) and HTTPS API your peers can dial.
   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).
+  # caller's client certificate and needs the node's OWN TLS listener.
   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.
+# Chain-wide consensus params come from the included chain spec — do NOT set them here.
 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.
+  # IMMEDIATELY rather than waiting out the (5-minute) idle heartbeat.
   wake-on-work {
     forward-watermark = 16
   }
@@ -47,34 +39,17 @@ ce.evolver.consensus {
 
 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.
+# PLAIN HTTP on 8440 for everything that TALKS to this node, deliberately. TLS on 8441 for
+# PEERS (the content cache needs somewhere mTLS to live).
 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.
+# node's point of view — without this line the app gets connection refused.
 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
@@ -99,4 +74,7 @@ chainDb {
   useShutdownHook = false
   freeBlobsEarly  = false
 }
-ce.evolver.execution.enabled = false
+
+# The committee is CONSENSUS ONLY, never the processing node. Execution is disabled so this node
+# never serves the single-consumer channel cursor; the follower below owns that.
+ce.evolver.execution.enabled = false

package/dist/installer/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/dist/installer/node-follower.conf

@@ -0,0 +1,232 @@
+# This node: a NON-GENESIS FOLLOWER. Chain-wide params come from the genesis spec selected by the
+# wrapper that includes this file — never set them here, they must stay byte-identical on every
+# node. Only node-local knobs below.
+
+# 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.
+# Processing is enabled only by the paired managed composition with its persistent zero-module
+# shared SDK consumer. MCP sessions never drain. Independent remote nodes remain unmanaged.
+ce.evolver.execution.enabled = ${?EVOLVER_EXECUTION_ENABLED}
+# Private node-owned lifecycle capability; only the paired processor receives this volume.
+# No control route is exposed on any TCP listener. 202 is acceptance, not ACTIVE.
+ce.evolver.node-control.socket-path = "/node-control/node.sock"
+# Shared SDK controller is the SOLE writer; node sees the whole config-only directory read-only.
+# Ordinary boot/upgrade cannot merge defaults, resurrect removals or seed a lost declaration.
+include required(file("/subscriptions/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/dist/installer/node-join.sh

@@ -8,6 +8,10 @@
 # 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.
+#
+# EVOLVER_NODE_CONFIG (optional) selects the HOCON config file the JVM boots with; the default
+# is /config/node.conf (the devnet wrapper). A local-chain deployment sets it to
+# /config/node.local.conf to boot from /public-genesis/genesis.conf instead.
 set -eu
 
 # Same read-only guard on normal boot and the owned-fixture preflight. It NEVER initializes,
@@ -223,6 +227,16 @@ echo "[node-join] pinning ${_peers} as the seed; allowing ${_outbound} outbound
 '     "$_outbound"
 } > /data/chain/peers.conf
 
+# #21: an unclean exit (OOM kill, power loss, SIGKILL after the stop timeout) leaves the private
+# node-control socket behind, and the node refuses ANY pre-existing entry, so restart: unless-stopped
+# would crash-loop forever. Remove it only if it is a SOCKET: this directory is exclusive to this
+# node (the processor mount is read-only) and this entrypoint runs only while this container's
+# node JVM is not running. Any other entry type is left for the node itself to refuse.
+if [ -S /node-control/node.sock ]; then
+  echo "[node-join] removing stale node-control socket left by an unclean previous exit"
+  rm -f /node-control/node.sock
+fi
+
 echo "[node-join] launching follower '$NODE_ID' — syncing devnet from block 0"
-exec /opt/evolver/bin/evolver -Dconfig.file=/config/node.conf "$NODE_ID"
+exec /opt/evolver/bin/evolver -Dconfig.file="${EVOLVER_NODE_CONFIG:-/config/node.conf}" "$NODE_ID"