@mcsherrylabs/pi-meerkat 0.7.0 → 0.8.0

package/dist/installer/node.conf

@@ -0,0 +1,235 @@
+# 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("/public-genesis/genesis.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 = "/public-genesis/genesis.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.
+# 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}
+# 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/runtime.json

@@ -0,0 +1 @@
+{"operatorIdentity":"evolvermeerkatA","sdk":"0.22.1","bootstrap":"0.15.0"}

package/dist/installer-runtime/dist/scripts/recover-owner.js

@@ -0,0 +1,15 @@
+// Explicit offline operator action. Never imported/called by ordinary startup.
+import { pathToFileURL } from "node:url";
+import { recoverProcessorOwnerLock } from "@mcsherrylabs/evolver-client/processor";
+import { currentTarget } from "../src/env.js";
+import { processorStatePath } from "../src/runtime.js";
+export function recoverMeerkatOwner(args, target, say = console.error) {
+    if (args.length !== 1 || args[0] !== "--force")
+        throw new Error("usage: recover-owner --force (only after stopping ALL collectors and disabling automatic restarts)");
+    say("WARNING: --force acknowledges ALL collectors are stopped and automatic restarts disabled; this command cannot verify that.");
+    const result = recoverProcessorOwnerLock({ path: processorStatePath(target), force: true });
+    say(`${result.removed ? "Removed owner lock" : "No owner lock present"}: ${result.marker}. Database/WAL, progress, subscriptions and keys unchanged. Start ONE collector normally with the SAME target/state environment to acquire a new lock.`);
+    return result;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+    recoverMeerkatOwner(process.argv.slice(2), currentTarget());

package/dist/installer-runtime/dist/scripts/subscriptions-init.js

@@ -0,0 +1,35 @@
+// Explicit fresh-resource operation; NEVER imported/called by ordinary startup or upgrade.
+import { chown, chmod, mkdir, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { initializeSubscriptions } from "@mcsherrylabs/evolver-client/processor";
+import { currentTarget, ROOT } from "../src/env.js";
+import { processorConfigPath } from "../src/runtime.js";
+const raw = process.env.EVOLVER_INITIAL_CHANNELS;
+if (raw === undefined)
+    throw new Error("set EVOLVER_INITIAL_CHANNELS to an explicit JSON array (including []); initialization is fresh-only");
+const channels = JSON.parse(raw);
+if (!Array.isArray(channels) || channels.some(id => typeof id !== "string"))
+    throw new Error("EVOLVER_INITIAL_CHANNELS must be a JSON string array");
+const path = processorConfigPath(currentTarget());
+const directory = dirname(path);
+if (process.getuid?.() === 0) {
+    const uid = Number(process.env.EVOLVER_OPERATOR_UID), gid = Number(process.env.EVOLVER_OPERATOR_GID);
+    if (![uid, gid].every(id => Number.isSafeInteger(id) && id >= 1))
+        throw new Error("root fresh initializer requires non-root operator uid/gid");
+    for (const dir of [directory, join(ROOT, "state")]) {
+        await mkdir(dir, { recursive: true, mode: 0o750 });
+        if ((await readdir(dir)).length !== 0)
+            throw new Error("fresh initialization refuses nonempty managed volumes; no valued migration/reseed");
+    }
+    for (const dir of [directory, join(ROOT, "state")]) {
+        await chown(dir, uid, gid);
+        await chmod(dir, 0o750);
+    }
+    process.setgroups([]);
+    process.setgid(gid);
+    process.setuid(uid);
+}
+else
+    await mkdir(directory, { recursive: true, mode: 0o750 });
+await initializeSubscriptions(path, channels);
+console.log(`initialized subscription declaration ${path}; ordinary startup will never reseed it`);

package/dist/installer-runtime/dist/scripts/versions.mjs

@@ -0,0 +1,86 @@
+// Read .env — the single source of truth for versions and image names.
+//
+// Deliberately hand-parsed rather than pulling in dotenv: this is a template, and a
+// dependency whose whole job is reading six lines of KEY=value is a dependency a reader has
+// to evaluate. docker compose reads the same file natively, so there is one file and two
+// consumers, not two sources.
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+// fileURLToPath, not url.pathname — see the note in src/env.ts.
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const ENV_PATH = join(ROOT, ".env");
+export function readEnv() {
+    const out = {};
+    for (const line of readFileSync(ENV_PATH, "utf8").split("\n")) {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        const i = t.indexOf("=");
+        if (i < 0)
+            continue;
+        // Match docker compose's grammar, because it reads this same file: strip an inline
+        // comment and surrounding quotes, and tolerate CRLF. Diverging here is worse than not
+        // parsing at all — `npm run image` would tag one thing while `docker compose up` ran
+        // another, and nothing would report a conflict.
+        let v = t.slice(i + 1).replace(/\r$/, "").trim();
+        v = v.replace(/\s+#.*$/, "").trim();
+        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+            v = v.slice(1, -1);
+        }
+        if (!v)
+            continue; // empty ⇒ treat as missing, so the required-keys check reports it
+        out[t.slice(0, i).trim()] = v;
+    }
+    for (const k of ["EVOLVER_REGISTRY", "REGISTRY", "EVOLVER_VERSION", "APP_NAME", "APP_VERSION"]) {
+        if (!out[k])
+            throw new Error(`${ENV_PATH}: ${k} is missing — it is required, see the comments in that file`);
+    }
+    return out;
+}
+/** Update keys in .env IN PLACE, preserving comments and order — the comments are the
+ *  documentation, so rewriting the file from an object would delete the explanation. */
+export function updateEnv(updates) {
+    const lines = readFileSync(ENV_PATH, "utf8").split("\n");
+    const seen = new Set();
+    const out = lines.map((line) => {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            return line;
+        const i = t.indexOf("=");
+        if (i < 0)
+            return line;
+        const key = t.slice(0, i).trim();
+        if (!(key in updates))
+            return line;
+        seen.add(key);
+        return `${key}=${updates[key]}`;
+    });
+    for (const [k, v] of Object.entries(updates))
+        if (!seen.has(k))
+            out.push(`${k}=${v}`);
+    writeFileSync(ENV_PATH, out.join("\n"));
+}
+export const appImage = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}:${e.APP_VERSION}`;
+export const deployRef = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}-deploy:${e.APP_VERSION}`;
+/** The app-ALONE deployment, pointed at a chain that already exists — from
+ *  `docker-compose.remote.yml`. */
+export const remoteDeployRef = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}-deploy-remote:${e.APP_VERSION}`;
+/** The app PLUS ITS OWN NODE, that node joining devnet — from `docker-compose.devnet.yml`.
+ *
+ *  Three refs because they are three different things to hand someone, and the difference is
+ *  not cosmetic: one carries a throwaway chain, one borrows somebody else's node on a real
+ *  chain, and one brings a node of its own onto that real chain (which is the only shape that
+ *  can read an ordered channel stream or join a DA overlay). */
+export const devnetDeployRef = (e = readEnv()) => `${e.REGISTRY}/${e.APP_NAME}-deploy-devnet:${e.APP_VERSION}`;
+/** Identity names are `^[A-Za-z0-9]{1,50}$` — no hyphens, dots or underscores — so an app
+ *  name cannot be used verbatim. Strip it to what a node id may contain and bound it.
+ *
+ *  This exists because the identity names used to be hardcoded `tmplA`/`tmplB`: rename your
+ *  app to anything you like and it still claimed identities named after the template, which
+ *  on a SHARED chain like devnet is the one place provenance matters. Empty after stripping
+ *  (a name of only separators) falls back to `app` rather than producing `A`/`B`.  */
+export function identityPrefix(appName) {
+    const stripped = String(appName ?? "").replace(/[^A-Za-z0-9]/g, "").slice(0, 40);
+    return stripped || "app";
+}

package/dist/installer-runtime/dist/scripts/wait-for-chain.js

@@ -0,0 +1,90 @@
+// Wait until the target's node is up AND its chain is actually committing.
+//
+// "The container is running" is not the same as "the chain is usable": the node generates
+// keys, writes genesis, migrates two databases and starts consensus before it will accept a
+// transaction. Polling for a COMMITTED round is the only honest readiness signal — a node
+// that answers /status can still refuse every write with `not-ready`.
+//
+// It resolves the node URL through src/env.ts, the SAME place the app does. It used to read
+// EVOLVER_NODE directly and default to localhost, which made it target-BLIND: the published
+// image runs this before the app, so `docker run -e EVOLVER_TARGET=devnet <image>` polled
+// its own localhost for 180 s and exited before the app ever started.
+//
+// An OPTIONAL argument PINS the chain, and the local-chain scripts pass `local`. They have
+// to: once the default chain can be a remote one, a bare currentTarget() here makes
+// `npm run chain:up` boot the local node and then report the REMOTE chain's tip as its
+// readiness — green while nothing local is up at all. The no-argument form is still what the
+// container runs, where the environment names the chain and the answer must follow it.
+import { currentTarget, isTargetName, targetByName, knownTargets, optionalEnv, TargetError } from "../src/env.js";
+const want = process.argv[2];
+let target;
+try {
+    if (want && !isTargetName(want)) {
+        console.error(`unknown chain '${want}' — available by name: ${knownTargets().map((t) => t.name).join(", ")}`);
+        process.exit(1);
+    }
+    target = want ? targetByName(want) : currentTarget();
+}
+catch (e) {
+    if (e instanceof TargetError) {
+        console.error(`\n✗ ${e.message}\n`);
+        process.exit(1);
+    }
+    throw e;
+}
+// Through optionalEnv for the reason documented there: compose passes CHAIN_WAIT_MS through
+// as present-and-empty, `Number("")` is 0, and a 0 ms deadline means the loop below never
+// runs even once — the app then reports "chain not ready after 0s" about a chain it never
+// asked. Junk is treated the same way as absent, because "unparseable" must not silently
+// become "do not wait at all".
+const DEADLINE_MS = (() => {
+    const raw = optionalEnv("CHAIN_WAIT_MS");
+    const n = raw === undefined ? NaN : Number(raw);
+    if (raw !== undefined && !(Number.isFinite(n) && n > 0))
+        console.error(`(ignoring CHAIN_WAIT_MS='${raw}' — not a positive number of milliseconds)`);
+    return Number.isFinite(n) && n > 0 ? n : 180_000;
+})();
+if (process.env.EVOLVER_INSECURE_TLS === "1")
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+const started = Date.now();
+let lastErr = "never reached";
+while (Date.now() - started < DEADLINE_MS) {
+    try {
+        const res = await fetch(`${target.nodeUrl}/api/explorer/blocks?limit=1`, {
+            headers: { Accept: "application/json" },
+        });
+        if (res.ok) {
+            const b = (await res.json());
+            const round = b?.blocks?.[0]?.roundNum ?? 0;
+            if (round > 0) {
+                console.log(`chain ready — ${target.nodeUrl}, committed round ${round}`);
+                process.exit(0);
+            }
+            lastErr = "tip still round 0 (consensus started, nothing committed yet)";
+        }
+        else {
+            lastErr = `HTTP ${res.status}`;
+        }
+    }
+    catch (e) {
+        lastErr = e instanceof Error ? e.message.split("\n")[0] : String(e);
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+}
+// Advice depends on WHERE this is running: inside the published image there is no npm
+// project and no docker compose, so the host-side commands would be a dead end.
+const inContainer = process.env.EVOLVER_IN_CONTAINER === "1";
+const advice = inContainer
+    ? [
+        `  · this container waits for target '${target.name}' at ${target.nodeUrl}`,
+        `  · pointing at a remote chain?   docker run -e EVOLVER_TARGET=devnet ...`,
+        `  · running the bundled chain?    the 'node' service must be healthy first`,
+    ]
+    : [
+        `  · docker compose ps            is the node running?`,
+        `  · docker compose logs node     what did it say?`,
+        `  · npm run reset                wipe chain + local state and start over`,
+    ];
+console.error(`\n✗ chain not ready after ${Math.round(DEADLINE_MS / 1000)}s at ${target.nodeUrl} ` +
+    `(target '${target.name}') — last: ${lastErr}\n` + advice.join("\n") + "\n");
+process.exit(1);