@mcsherrylabs/pi-meerkat 0.10.1 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -86,8 +86,8 @@ export const CHAIN_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
86
86
  * `??` is the wrong operator for these. Compose renders a pass-through variable as
87
87
  * PRESENT-AND-EMPTY rather than omitting it (`EVOLVER_DEVNET_URL: ${EVOLVER_DEVNET_URL:-}`),
88
88
  * and `process.env.X ?? default` only falls back on undefined — so an empty value WINS and
89
- * the default never applies. That is not hypothetical: `docker-compose.remote.yml` was the
90
- * first caller to pass these through, devnet's url resolved to the empty string, and the
89
+ * the default never applies. That is not hypothetical: a pass-through deploy that rendered
90
+ * these present-and-empty once made devnet's url resolve to the empty string, and the
91
91
  * deployment failed with `chain not ready at (target 'devnet')`. Every optional variable
92
92
  * in this project goes through here. */
93
93
  export function optionalEnv(k) {
@@ -362,42 +362,45 @@ export function registryChannelOperator() {
362
362
  export function registryReadOnly() {
363
363
  return optionalEnv("REGISTRY_READ_ONLY") === "1";
364
364
  }
365
- // ── 004-event-processor-inbox ─────────────────────────────────────────────────
366
- /** A setting 004 renamed. It is REFUSED, not read: see `processorHttpPort`. */
365
+ // ── 004-event-processor-inbox / 177-managed-processor-shell ───────────────────
366
+ /** A retired setting that the managed shell no longer reads. A non-empty value is REFUSED, not
367
+ * read, so a stale deployment cannot silently diverge (processing with no node control, or
368
+ * serving nothing). See `refuseRetiredSettings`. */
367
369
  export class RenamedSettingError extends Error {
368
370
  }
371
+ /** `registryStatePath(target)` moves here beside [[ensureStateDir]] — the shell owns the store
372
+ * path, and both `src/service.ts` and `scripts/recover-owner.ts` need it. */
373
+ export function registryStatePath(target) {
374
+ return join(target.stateDir, "registry.db");
375
+ }
369
376
  /**
370
- * THE SWITCH BETWEEN THE APP'S TWO SHAPES, and the event processor's read-server port.
371
- *
372
- * `> 0` is the SERVICE shape: the event processor with the registry module, serving its routes
373
- * on this port, until stopped. Unset or `0` is the DEMO shape: the event processor with the demo
374
- * module, for as long as the template's steps take. Both shapes have exactly one consumer of
375
- * the node's stream — the processor — and both keep what nobody handles in the inbox.
376
- *
377
- * ⚠️ IT STAYS ONE SWITCH BECAUSE THE NODE READS IT TOO. `node-join.sh` decides from the same
378
- * value whether the node subscribes to `REGISTRY_CHANNEL`, and phase M of the command suite
379
- * fails the build if the two are keyed on anything else. A second "which modules" setting could
380
- * disagree with the node's channel list, and the registry would then index nothing (research R1).
377
+ * FR-031 — the managed shell reads ONLY the binding (`EVOLVER_CHAIN_ID`, `APP_NODE_ID`) from the
378
+ * environment. Every other retired Meerkat setting is a fixed container default or an explicit
379
+ * option, and a non-empty value must REFUSE startup. A compose `${X:-}` renders present-and-EMPTY,
380
+ * so an empty string is NOT a refusal (it is "unset"); only a non-empty value refuses. The message
381
+ * names the offending variable.
381
382
  *
382
- * `0` = no read server, mirroring `https.port`'s convention in the node — the port IS the switch,
383
- * so there is no second `enabled` flag.
384
- *
385
- * ⚠️ `REGISTRY_HTTP_PORT`, its name before 004, is REFUSED whenever it is set — not read, not
386
- * aliased. Ignoring it would be worse than either: a registry deployment whose environment still
387
- * says `REGISTRY_HTTP_PORT=8090` would start as the template DEMO, drain its node with the wrong
388
- * module and serve nothing, and say so nowhere. The refusal names the fix.
383
+ * `EVOLVER_MANAGED_NODE_CONTAINER` is evolver-mcp's node container_name and is deliberately NOT on
384
+ * this list.
389
385
  */
390
- export function processorHttpPort() {
391
- const old = optionalEnv("REGISTRY_HTTP_PORT");
392
- if (old !== undefined)
393
- throw new RenamedSettingError(`REGISTRY_HTTP_PORT is set (${old}), but it was renamed PROCESSOR_HTTP_PORT and is no longer read.\n` +
394
- ` Set PROCESSOR_HTTP_PORT=${old} and remove REGISTRY_HTTP_PORT. Left as it is, this deployment\n` +
395
- ` would start as the template demo instead of the registry.`);
396
- const port = Number(optionalEnv("PROCESSOR_HTTP_PORT") ?? 0);
397
- if (!Number.isSafeInteger(port) || port < 0 || port > 65535)
398
- throw new TargetError("invalid PROCESSOR_HTTP_PORT");
399
- return port;
386
+ export function refuseRetiredSettings(env = process.env) {
387
+ for (const name of RETIRED_SETTINGS) {
388
+ const value = env[name];
389
+ if (value !== undefined && value !== "") {
390
+ throw new RenamedSettingError(`${name} is set (${value}), but it is a retired Meerkat setting and is no longer read:\n` +
391
+ ` the managed processor shell fixes every setting as a container default or an explicit\n` +
392
+ ` option, reading only EVOLVER_CHAIN_ID / APP_NODE_ID from the environment. Unset ${name}\n` +
393
+ ` and start again; reading it would let a stale deployment silently diverge.`);
394
+ }
395
+ }
400
396
  }
397
+ const RETIRED_SETTINGS = [
398
+ "EVOLVER_PROCESSOR_CONTROL_SOCKET",
399
+ "PROCESSOR_HTTP_PORT",
400
+ "REGISTRY_HTTP_PORT",
401
+ "PROCESSOR_READ_HOST",
402
+ "EVOLVER_SUBSCRIPTIONS_FILE",
403
+ ];
401
404
  /** The lease ceiling, in ROUNDS, measured from the round an announcement is ordered.
402
405
  *
403
406
  * ⚠️ Rounds, never wall-clock: devnet commits on a ~600 ms floor when busy and a 300-second
@@ -0,0 +1,151 @@
1
+ // The registry service: application configuration + module registration only (FR-004, SC-001).
2
+ // All generic cursor/storage/config/control/lifecycle ownership lives in the SDK managed shell
3
+ // (`startManagedProcessor`); this file wires the registry module, its routes, the state path, the
4
+ // own-node client and the operator identity to that shell. No processor-composition code of its
5
+ // own remains here.
6
+ import { fileURLToPath } from "node:url";
7
+ import { readFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+ import { isValidNodeId, NodeClient } from "@mcsherrylabs/evolver-client";
10
+ import { deadlineFetch, MANAGED_PROCESSOR_DEFAULTS, startManagedProcessor, } from "@mcsherrylabs/evolver-client/processor";
11
+ import { ensureStateDir, refuseRetiredSettings, registryChannelOperator, registryReadOnly, registryStatePath, ROOT, } from "./env.js";
12
+ import * as store from "./store.js";
13
+ import { identityPrefix } from "../scripts/versions.mjs";
14
+ import { CHAIN_TIMEOUT_MS } from "./chainfetch.js";
15
+ import { registryModule, registryReadRoutes } from "./registry/index.js";
16
+ /** The operator identity name the registry claims/signs as. Resolved BEFORE any network: from
17
+ * saved state, else a freshly derived name, always carrying the per-target suffix on a shared
18
+ * chain so two deployments never collide on one name. */
19
+ function nameFor(target, prefix, suffix) {
20
+ return target.chainIsEphemeral ? `${prefix}A` : `${prefix}A${suffix()}`;
21
+ }
22
+ function devnetSuffixFor(target, prefix) {
23
+ let cached = null;
24
+ return () => {
25
+ if (cached)
26
+ return cached;
27
+ for (const { nodeId } of store.summary(target)) {
28
+ const m = new RegExp(`^${prefix}A(\\d+)$`).exec(nodeId);
29
+ if (m)
30
+ return (cached = m[1]);
31
+ }
32
+ return (cached = String(Date.now()).slice(-6));
33
+ };
34
+ }
35
+ /**
36
+ * The registry service: refuse retired settings, build the own-node client (never the target's node URL,
37
+ * FR-012), claim/resolve the operator identity, register the registry module with the SDK shell,
38
+ * and start it. Everything the shell owns (owner lock, banner, control socket, stale-socket
39
+ * recovery, node-control restart, signals) is the SDK's.
40
+ */
41
+ export async function startRegistryService(options) {
42
+ refuseRetiredSettings(); // FR-031
43
+ const nodeUrl = options.shell?.nodeUrl ?? MANAGED_PROCESSOR_DEFAULTS.nodeUrl; // FR-012: never the target's node URL
44
+ const node = new NodeClient({ baseUrl: nodeUrl, fetch: deadlineFetch(CHAIN_TIMEOUT_MS) });
45
+ // ── operator identity + read-only mode (ported from the old service branch of src/app.ts) ──
46
+ const readOnly = registryReadOnly();
47
+ // READ-ONLY: the installer's registry never claims or signs with any identity. The operator is
48
+ // the PINNED channel operator; no sender identity is ever loaded or claimed, so the identity()
49
+ // claim path is never reached in this mode. A read-only registry without a valid pinned operator
50
+ // has nobody to trust the channel's terms to, so it refuses at startup rather than proceeding
51
+ // owner-less.
52
+ const pinnedOperator = registryChannelOperator();
53
+ if (readOnly && !pinnedOperator)
54
+ throw new Error("REGISTRY_READ_ONLY=1 requires a valid REGISTRY_CHANNEL_OPERATOR naming the identity " +
55
+ "that owns the index channel; the installer's rendered compose always sets both.");
56
+ // This app's own name, from package.json — never a literal, so a rename cannot leave a stale one.
57
+ const appName = (() => {
58
+ try {
59
+ return JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).name ?? "app";
60
+ }
61
+ catch {
62
+ return "app";
63
+ }
64
+ })();
65
+ const prefix = identityPrefix(appName);
66
+ const suffix = devnetSuffixFor(options.target, prefix);
67
+ const operator = readOnly ? pinnedOperator : store.get(options.target, "sender")?.nodeId ?? nameFor(options.target, prefix, suffix);
68
+ const nodeIdentity = process.env.APP_NODE_ID?.trim() ?? "";
69
+ const faucet = new NodeClient({ baseUrl: options.target.faucetUrl, fetch: deadlineFetch(CHAIN_TIMEOUT_MS) });
70
+ /** Load, or claim and persist, the sender identity. Only the "sender" role is ever used by the
71
+ * registry. Reconciles against the chain (the faucet's committed view) rather than trusting
72
+ * state — see the extensive note that lived in the old app.ts service branch. */
73
+ const identity = async () => {
74
+ if (readOnly)
75
+ throw new Error("read-only registry must never claim or sign with any identity");
76
+ const existing = store.get(options.target, "sender");
77
+ if (existing) {
78
+ const onChain = await faucet.getIdentity(existing.nodeId);
79
+ if (onChain !== null)
80
+ return { sender: existing, signer: store.signerFor(existing) };
81
+ options.say(` sender: ${existing.nodeId} is in state but not on chain — claiming it now`);
82
+ const retry = await faucet.claimIdentity(existing);
83
+ if (retry.kind === "committed")
84
+ return { sender: existing, signer: store.signerFor(existing) };
85
+ if (retry.kind === "exists") {
86
+ throw new Error(`'${existing.nodeId}' is on chain with keys this app does not hold.\n` +
87
+ ` state/${options.target.name} is stale for 'sender'. npm run state:reset` +
88
+ (options.target.chainIsEphemeral ? ` (or npm run reset for chain + state)` : ``));
89
+ }
90
+ throw new Error(`re-claim of '${existing.nodeId}' failed: ${retry.error}` +
91
+ `${retry.message ? ` — ${retry.message}` : ""}`);
92
+ }
93
+ const name = nameFor(options.target, prefix, suffix);
94
+ if (!isValidNodeId(name)) {
95
+ throw new Error(`'${name}' is not a usable identity name — the node requires 1–50 ASCII ` +
96
+ `alphanumeric characters (letters and digits only).`);
97
+ }
98
+ const id = store.create(options.target, "sender", name);
99
+ const r = await faucet.claimIdentity(id);
100
+ switch (r.kind) {
101
+ case "committed": return { sender: id, signer: store.signerFor(id) };
102
+ case "exists":
103
+ throw new Error(`'${name}' already exists on chain and these keys are not its keys.\n` +
104
+ (!options.target.chainIsEphemeral
105
+ ? ` this target's state was reset but the name was reused — npm run state:reset, then retry`
106
+ : process.env.EVOLVER_IN_CONTAINER === "1"
107
+ ? ` the chain outlived the app's state. Discard both together:\n` +
108
+ ` docker compose down -v (or: docker compose -f oci://<ref> down -v)`
109
+ : ` the local chain outlived its state: npm run reset (chain + state together)`));
110
+ case "failed":
111
+ if (r.error === "digest_mismatch") {
112
+ throw new Error(`CLAIM RECIPE DRIFT — ${r.message}\n` +
113
+ ` Nothing was signed. The node and @mcsherrylabs/evolver-client disagree on the\n` +
114
+ ` proof-of-possession digest, which means their versions do not match.`);
115
+ }
116
+ throw new Error(`claim of '${name}' failed: ${r.error}${r.message ? ` — ${r.message}` : ""}`);
117
+ }
118
+ };
119
+ /** Wait until this own node can actually write (stopped bulk-syncing) before provisioning. */
120
+ const beforeProvision = async () => {
121
+ const deadline = Date.now() + 180_000;
122
+ let last = await node.currentRound();
123
+ let announced = false;
124
+ while (Date.now() < deadline) {
125
+ await new Promise((r) => setTimeout(r, 500));
126
+ const now = await node.currentRound();
127
+ const advanced = now - last;
128
+ last = now;
129
+ if (advanced < 5)
130
+ return;
131
+ if (!announced) {
132
+ options.say(` this node is still catching up (round ${now}, +${advanced}/500ms) — waiting`);
133
+ announced = true;
134
+ }
135
+ }
136
+ throw new Error(`this node is still bulk-syncing after 3 minutes (round ${last}).\n` +
137
+ ` A submit would be accepted and then sit unrouted, so nothing is sent.`);
138
+ };
139
+ const module = registryModule({
140
+ chain: options.target.name, node, chainUrl: nodeUrl,
141
+ chainAgreedUrl: options.target.faucetUrl, operator, nodeIdentity, readOnly, identity,
142
+ beforeProvision, say: options.say,
143
+ });
144
+ ensureStateDir(options.target);
145
+ return startManagedProcessor({ ...options.shell,
146
+ recovery: { service: "registry", command: `node ${fileURLToPath(new URL("../scripts/recover-owner.js", import.meta.url))} --force` },
147
+ paths: { ...options.shell?.paths, state: registryStatePath(options.target) },
148
+ storeModules: [module.worker], lifecycle: [module.lifecycle],
149
+ routes: runtime => registryReadRoutes(runtime, async () => String(await node.currentRound())),
150
+ say: options.say });
151
+ }
@@ -22,7 +22,7 @@ export interface Installation {
22
22
  };
23
23
  }
24
24
  export interface InstallerDeps {
25
- command(command: string, args: string[], env?: NodeJS.ProcessEnv, cwd?: string): Promise<string>;
25
+ command(command: string, args: string[], env?: NodeJS.ProcessEnv, cwd?: string, options?: CommandOptions): Promise<string>;
26
26
  committeeReady?(state: Installation, env: NodeJS.ProcessEnv): Promise<void>;
27
27
  nodeBinding(state: Installation, env: NodeJS.ProcessEnv): Promise<{
28
28
  chainId: string;
@@ -31,6 +31,8 @@ export interface InstallerDeps {
31
31
  registryReady(state: Installation, env: NodeJS.ProcessEnv): Promise<void>;
32
32
  bootstrap(state: Installation, env: NodeJS.ProcessEnv): Promise<void>;
33
33
  claimChannel?(state: Installation, env: NodeJS.ProcessEnv): Promise<void>;
34
+ /** Human-facing progress sink. Defaults to stderr, one `[meerkat] …` line per call. Tests inject this to assert ordering. */
35
+ say?(line: string): void;
34
36
  }
35
37
  export declare function managedDirectory(env?: NodeJS.ProcessEnv): string;
36
38
  /** Per-mode state directory. The 0.8.0 path `<state>/meerkat/` (installation.json) is never used. */
@@ -72,7 +74,7 @@ export declare function renderDeployment(state: Installation): {
72
74
  EVOLVER_ALLOWED_OUTBOUND: string;
73
75
  EVOLVER_EXECUTION_ENABLED: string;
74
76
  EVOLVER_NODE_PORT: string;
75
- EVOLVER_NODE_CONFIG: string;
77
+ EVOLVER_NODE_CONFIG?: undefined;
76
78
  CLAIM_TIMEOUT?: undefined;
77
79
  CLAIM_WATCH_SECS?: undefined;
78
80
  };
@@ -92,6 +94,9 @@ export declare function renderDeployment(state: Installation): {
92
94
  labels: {
93
95
  "io.meerkat.installation": string;
94
96
  };
97
+ args: {
98
+ EVOLVER_PROCESSOR_IMAGE: string;
99
+ };
95
100
  };
96
101
  user: string;
97
102
  group_add: string[];
@@ -99,14 +104,10 @@ export declare function renderDeployment(state: Installation): {
99
104
  EVOLVER_FAUCET_URL: string;
100
105
  EVOLVER_CHAIN_ID: string;
101
106
  APP_NODE_ID: string;
102
- EVOLVER_SUBSCRIPTIONS_FILE: string;
103
107
  REGISTRY_CHANNEL: string;
104
108
  REGISTRY_CHANNEL_OPERATOR: string;
105
109
  REGISTRY_READ_ONLY: string;
106
110
  REGISTRY_CONTENT_URL: string;
107
- PROCESSOR_HTTP_PORT: string;
108
- PROCESSOR_READ_HOST: string;
109
- EVOLVER_PROCESSOR_CONTROL_SOCKET: string;
110
111
  EVOLVER_DEVNET_URL?: string | undefined;
111
112
  EVOLVER_TARGET: string;
112
113
  EVOLVER_NODE: string;
@@ -128,14 +129,10 @@ export declare function renderDeployment(state: Installation): {
128
129
  EVOLVER_FAUCET_URL: string;
129
130
  EVOLVER_CHAIN_ID: string;
130
131
  APP_NODE_ID: string;
131
- EVOLVER_SUBSCRIPTIONS_FILE: string;
132
132
  REGISTRY_CHANNEL: string;
133
133
  REGISTRY_CHANNEL_OPERATOR: string;
134
134
  REGISTRY_READ_ONLY: string;
135
135
  REGISTRY_CONTENT_URL: string;
136
- PROCESSOR_HTTP_PORT: string;
137
- PROCESSOR_READ_HOST: string;
138
- EVOLVER_PROCESSOR_CONTROL_SOCKET: string;
139
136
  EVOLVER_DEVNET_URL?: string | undefined;
140
137
  EVOLVER_TARGET: string;
141
138
  EVOLVER_NODE: string;
@@ -247,10 +244,10 @@ export declare function renderDeployment(state: Installation): {
247
244
  EVOLVER_ALLOWED_OUTBOUND: string;
248
245
  EVOLVER_EXECUTION_ENABLED: string;
249
246
  EVOLVER_NODE_PORT: string;
247
+ EVOLVER_NODE_CONFIG: string;
250
248
  CLAIM_TIMEOUT: string;
251
249
  CLAIM_WATCH_SECS: string;
252
250
  EVOLVER_DA_PEERS?: undefined;
253
- EVOLVER_NODE_CONFIG?: undefined;
254
251
  };
255
252
  group_add: string[];
256
253
  volumes: string[];
@@ -268,6 +265,9 @@ export declare function renderDeployment(state: Installation): {
268
265
  labels: {
269
266
  "io.meerkat.installation": string;
270
267
  };
268
+ args: {
269
+ EVOLVER_PROCESSOR_IMAGE: string;
270
+ };
271
271
  };
272
272
  user: string;
273
273
  group_add: string[];
@@ -275,14 +275,10 @@ export declare function renderDeployment(state: Installation): {
275
275
  EVOLVER_FAUCET_URL: string;
276
276
  EVOLVER_CHAIN_ID: string;
277
277
  APP_NODE_ID: string;
278
- EVOLVER_SUBSCRIPTIONS_FILE: string;
279
278
  REGISTRY_CHANNEL: string;
280
279
  REGISTRY_CHANNEL_OPERATOR: string;
281
280
  REGISTRY_READ_ONLY: string;
282
281
  REGISTRY_CONTENT_URL: string;
283
- PROCESSOR_HTTP_PORT: string;
284
- PROCESSOR_READ_HOST: string;
285
- EVOLVER_PROCESSOR_CONTROL_SOCKET: string;
286
282
  EVOLVER_DEVNET_URL?: string | undefined;
287
283
  EVOLVER_TARGET: string;
288
284
  EVOLVER_NODE: string;
@@ -304,14 +300,10 @@ export declare function renderDeployment(state: Installation): {
304
300
  EVOLVER_FAUCET_URL: string;
305
301
  EVOLVER_CHAIN_ID: string;
306
302
  APP_NODE_ID: string;
307
- EVOLVER_SUBSCRIPTIONS_FILE: string;
308
303
  REGISTRY_CHANNEL: string;
309
304
  REGISTRY_CHANNEL_OPERATOR: string;
310
305
  REGISTRY_READ_ONLY: string;
311
306
  REGISTRY_CONTENT_URL: string;
312
- PROCESSOR_HTTP_PORT: string;
313
- PROCESSOR_READ_HOST: string;
314
- EVOLVER_PROCESSOR_CONTROL_SOCKET: string;
315
307
  EVOLVER_DEVNET_URL?: string | undefined;
316
308
  EVOLVER_TARGET: string;
317
309
  EVOLVER_NODE: string;
@@ -381,6 +373,15 @@ export declare function renderDeployment(state: Installation): {
381
373
  };
382
374
  };
383
375
  };
376
+ interface CommandOptions {
377
+ progress?: boolean;
378
+ timeoutMs?: number;
379
+ heartbeat?: (elapsedMs: number) => void;
380
+ heartbeatMs?: number;
381
+ }
382
+ /** Rewrites a stderr chunk into the `[meerkat]` lines to stream live. Only `[installer] `-prefixed
383
+ * lines surface (the runtime helper's own progress); everything else stays buffered for failures. */
384
+ export declare function installerProgressLines(chunk: string): string[];
384
385
  export declare function operatorEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
385
386
  export declare function managedInstallation(mode?: Mode, env?: NodeJS.ProcessEnv): Promise<Installation | undefined>;
386
387
  /** Protocol-only stdio bridge, one new facade/private child/session per harness connection.
@@ -398,4 +399,5 @@ export declare function installMeerkat(mode?: Mode, env?: NodeJS.ProcessEnv, dep
398
399
  };
399
400
  };
400
401
  }>;
402
+ export {};
401
403
  //# sourceMappingURL=installer.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"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"}
package/dist/installer.js CHANGED
@@ -25,7 +25,10 @@ const NODE_IMAGE = 'nexus.mcsherrylabs.com/evolver-node@sha256:f78974686dcdfacfd
25
25
  const NODE_CONTROL_UID = '10001';
26
26
  const NODE_CONTROL_GID = '999';
27
27
  const OWNER = 'io.meerkat.installation';
28
- const installed = '/opt/meerkat/node_modules/@mcsherrylabs/pi-meerkat';
28
+ // Pinned processor base digest this installer layers the packaged pi-meerkat runtime onto (FR-015).
29
+ // Placeholder digest; the orchestrator sed-replaces it after evolver-mcp v0.17.0 is published.
30
+ const PROCESSOR_IMAGE = 'nexus.mcsherrylabs.com/evolver-mcp-processor:v0.17.0@sha256:f72a54e61e4fb963d6d050800934e23e8a0a328db2cdb16c150ed14c2034ff2e';
31
+ const installed = '/app/node_modules/@mcsherrylabs/pi-meerkat';
29
32
  const runtime = `${installed}/dist/installer-runtime`;
30
33
  const control = `${installed}/installer/runtime-control.mjs`;
31
34
  // DevNet facts (verified by the coordinator, pinned exactly). See the task brief.
@@ -62,14 +65,10 @@ const registryEnvironment = (state, committee) => ({
62
65
  EVOLVER_FAUCET_URL: committee ? 'http://committee:8440' : DEVNET_ORIGIN,
63
66
  EVOLVER_CHAIN_ID: state.mode === 'devnet' ? DEVNET_CHAIN_ID : state.binding?.chainId ?? '',
64
67
  APP_NODE_ID: state.nodeId,
65
- EVOLVER_SUBSCRIPTIONS_FILE: '/subscriptions/channels.conf',
66
68
  REGISTRY_CHANNEL: state.channel,
67
69
  REGISTRY_CHANNEL_OPERATOR: state.registryOperator,
68
70
  REGISTRY_READ_ONLY: '1',
69
71
  REGISTRY_CONTENT_URL: 'http://node:8450',
70
- PROCESSOR_HTTP_PORT: '8090',
71
- PROCESSOR_READ_HOST: '0.0.0.0',
72
- EVOLVER_PROCESSOR_CONTROL_SOCKET: '/control/control.sock',
73
72
  });
74
73
  export function renderDeployment(state) {
75
74
  const labels = { [OWNER]: state.id };
@@ -83,11 +82,11 @@ export function renderDeployment(state) {
83
82
  build: { context: './package', dockerfile: 'installer/Node.Dockerfile', labels, args: { EVOLVER_NODE_IMAGE: NODE_IMAGE } },
84
83
  environment: { APP_NODE_ID: state.nodeId, DEVNET_API: DEVNET_ORIGIN, EVOLVER_UPSTREAM_NODE_ID: DEVNET_UPSTREAM_NODE_ID,
85
84
  EVOLVER_DA_PEERS: DEVNET_DA_PEERS, EVOLVER_ALLOWED_OUTBOUND: DEVNET_ALLOWED_OUTBOUND,
86
- EVOLVER_EXECUTION_ENABLED: 'true', EVOLVER_NODE_PORT: '7100', EVOLVER_NODE_CONFIG: '/config/node.devnet.conf' },
85
+ EVOLVER_EXECUTION_ENABLED: 'true', EVOLVER_NODE_PORT: '7100' },
87
86
  group_add: ['1000'], volumes: ['node-data:/data', 'subscriptions:/subscriptions:ro', 'node-control:/node-control'],
88
87
  restart: 'unless-stopped' },
89
88
  registry: { image: `${state.project}-registry:${state.packageVersion}`, labels, container_name: `${state.project}-registry`,
90
- build: { context: './package', dockerfile: 'installer/Registry.Dockerfile', labels },
89
+ build: { context: './package', dockerfile: 'installer/Registry.Dockerfile', labels, args: { EVOLVER_PROCESSOR_IMAGE: PROCESSOR_IMAGE } },
91
90
  user: '1000:1000', group_add: [NODE_CONTROL_GID], environment: registryEnv,
92
91
  volumes: [`app-state:${runtime}/state`, 'subscriptions:/subscriptions', 'agent-state:/meerkat/agent',
93
92
  'node-control:/node-control:ro', 'control:/control'],
@@ -117,11 +116,11 @@ export function renderDeployment(state) {
117
116
  node: { image: `${state.project}-node:${state.packageVersion}`, labels, container_name: `${state.project}-node`, entrypoint: ['sh', '/config/node-join.sh'],
118
117
  build: { context: './package', dockerfile: 'installer/Node.Dockerfile', labels, args: { EVOLVER_NODE_IMAGE: NODE_IMAGE } },
119
118
  environment: { APP_NODE_ID: state.nodeId, DEVNET_API: 'http://committee:8440', EVOLVER_UPSTREAM_NODE_ID: state.committeeId,
120
- EVOLVER_ALLOWED_OUTBOUND: '1', EVOLVER_EXECUTION_ENABLED: 'true', EVOLVER_NODE_PORT: '7100', CLAIM_TIMEOUT: '90', CLAIM_WATCH_SECS: '30' },
119
+ EVOLVER_ALLOWED_OUTBOUND: '1', EVOLVER_EXECUTION_ENABLED: 'true', EVOLVER_NODE_PORT: '7100', EVOLVER_NODE_CONFIG: '/config/node.local.conf', CLAIM_TIMEOUT: '90', CLAIM_WATCH_SECS: '30' },
121
120
  group_add: ['1000'], volumes: ['node-data:/data', 'subscriptions:/subscriptions:ro', 'genesis:/public-genesis:ro', 'node-control:/node-control'],
122
121
  restart: 'unless-stopped' },
123
122
  registry: { image: `${state.project}-registry:${state.packageVersion}`, labels, container_name: `${state.project}-registry`,
124
- build: { context: './package', dockerfile: 'installer/Registry.Dockerfile', labels },
123
+ build: { context: './package', dockerfile: 'installer/Registry.Dockerfile', labels, args: { EVOLVER_PROCESSOR_IMAGE: PROCESSOR_IMAGE } },
125
124
  user: '1000:1000', group_add: [NODE_CONTROL_GID], environment,
126
125
  volumes: [`app-state:${runtime}/state`, 'subscriptions:/subscriptions', 'agent-state:/meerkat/agent',
127
126
  'node-control:/node-control:ro', 'control:/control'],
@@ -139,16 +138,33 @@ export function renderDeployment(state) {
139
138
  networks: { default: { name: `${state.project}-network`, internal: true, labels } },
140
139
  };
141
140
  }
142
- async function command(command, args, env = process.env, cwd, timeoutMs = 600_000) {
141
+ async function command(command, args, env = process.env, cwd, options = {}) {
142
+ const { progress = false, timeoutMs = 600_000 } = options;
143
143
  return new Promise((resolve, reject) => {
144
144
  const child = spawn(command, args, { env, cwd, stdio: ['ignore', 'pipe', 'pipe'] });
145
145
  let stdout = '', stderr = '', timedOut = false;
146
+ const started = Date.now();
146
147
  const timer = setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, timeoutMs);
147
148
  const hard = setTimeout(() => child.kill('SIGKILL'), timeoutMs + 5_000);
149
+ // A heartbeat for a long silent phase: report elapsed wall-clock (never raw BuildKit output).
150
+ const heartbeat = options.heartbeat
151
+ ? setInterval(() => options.heartbeat(Date.now() - started), options.heartbeatMs ?? 30_000) : undefined;
152
+ heartbeat?.unref?.();
148
153
  child.stdout.on('data', data => { stdout = (stdout + String(data)).slice(-2 * 1024 * 1024); });
149
- child.stderr.on('data', data => { stderr = (stderr + String(data)).slice(-8192); });
150
- child.on('error', error => { clearTimeout(timer); clearTimeout(hard); reject(error); });
154
+ child.stderr.on('data', data => {
155
+ const chunk = String(data);
156
+ stderr = (stderr + chunk).slice(-8192);
157
+ // Stream only the runtime-control `[installer] …` lines live; everything else stays buffered
158
+ // for the failure message (so a successful run never dumps raw build/exec noise to stderr).
159
+ if (progress)
160
+ for (const line of installerProgressLines(chunk))
161
+ process.stderr.write(`${line}\n`);
162
+ });
163
+ child.on('error', error => { if (heartbeat)
164
+ clearInterval(heartbeat); clearTimeout(timer); clearTimeout(hard); reject(error); });
151
165
  child.on('close', code => {
166
+ if (heartbeat)
167
+ clearInterval(heartbeat);
152
168
  clearTimeout(timer);
153
169
  clearTimeout(hard);
154
170
  if (code !== 0 || timedOut)
@@ -160,19 +176,26 @@ async function command(command, args, env = process.env, cwd, timeoutMs = 600_00
160
176
  }
161
177
  const composeArgs = (state) => ['compose', '--project-name', state.project, '--file', join(state.dir, 'compose.json')];
162
178
  const request = (state) => JSON.stringify({ mode: state.mode, nodeId: state.nodeId, committeeId: state.committeeId ?? '', identity: state.identity, channel: state.channel, binding: state.binding });
179
+ const sayLine = (line) => { process.stderr.write(`[meerkat] ${line}\n`); };
180
+ /** Rewrites a stderr chunk into the `[meerkat]` lines to stream live. Only `[installer] `-prefixed
181
+ * lines surface (the runtime helper's own progress); everything else stays buffered for failures. */
182
+ export function installerProgressLines(chunk) {
183
+ return chunk.split('\n').filter(line => line.startsWith('[installer] ')).map(line => `[meerkat] ${line.slice('[installer] '.length)}`);
184
+ }
163
185
  const defaults = {
164
186
  command,
165
187
  committeeReady: async (state, env) => {
166
188
  await command('docker', [...composeArgs(state), 'run', '--rm', '--no-deps',
167
189
  '--entrypoint', 'node', 'registry', control, 'committee-ready', request(state)], env, state.dir);
168
190
  },
191
+ // node-binding owns a progress-aware wait (DevNet: syncs from round 0); stream its `[installer]` lines.
169
192
  nodeBinding: async (state, env) => JSON.parse(await command('docker', [...composeArgs(state), 'run', '--rm', '--no-deps',
170
- '--entrypoint', 'node', 'registry', control, 'node-binding', request(state)], env, state.dir)),
193
+ '--entrypoint', 'node', 'registry', control, 'node-binding', request(state)], env, state.dir, { progress: true })),
171
194
  // runtime-control 'ready' owns a progress-aware wait (DevNet: 45 min budget, 10 min stall); a fresh
172
195
  // DevNet follower needs well over 10 min to sync, so the outer deadline must sit above that budget.
173
- registryReady: async (state, env) => { await command('docker', ['exec', `${state.project}-registry`, 'node', control, 'ready', request(state)], env, undefined, 50 * 60_000); },
174
- bootstrap: async (state, env) => { await command('docker', ['exec', '--workdir', '/meerkat/agent', `${state.project}-registry`, 'node', control, 'bootstrap', request(state)], env); },
175
- claimChannel: async (state, env) => { await command('docker', ['exec', '--workdir', '/meerkat/agent', `${state.project}-registry`, 'node', control, 'claim-channel', request(state)], env); },
196
+ registryReady: async (state, env) => { await command('docker', ['exec', `${state.project}-registry`, 'node', control, 'ready', request(state)], env, undefined, { progress: true, timeoutMs: 50 * 60_000 }); },
197
+ bootstrap: async (state, env) => { await command('docker', ['exec', '--workdir', '/meerkat/agent', `${state.project}-registry`, 'node', control, 'bootstrap', request(state)], env, undefined, { progress: true }); },
198
+ claimChannel: async (state, env) => { await command('docker', ['exec', '--workdir', '/meerkat/agent', `${state.project}-registry`, 'node', control, 'claim-channel', request(state)], env, undefined, { progress: true }); },
176
199
  };
177
200
  export function operatorEnvironment(env) {
178
201
  const result = {};
@@ -328,6 +351,9 @@ export async function serveManaged(state, env = process.env) {
328
351
  export async function installMeerkat(mode = 'devnet', env = process.env, deps = defaults) {
329
352
  if (Number(process.versions.node.split('.')[0]) < 22)
330
353
  throw new Error('Meerkat install requires Node.js 22 or newer, npm/npx, and Docker Engine with Compose v2');
354
+ const say = deps.say ?? sayLine;
355
+ const devnet = mode === 'devnet';
356
+ const started = Date.now();
331
357
  const packageVersion = JSON.parse(await readFile(join(packageDir, 'package.json'), 'utf8')).version;
332
358
  const dir = modeDirectory(mode, env), configPath = managedConfigPath(mode, env), cleanEnv = operatorEnvironment(env);
333
359
  await deps.command('docker', ['version', '--format', 'json'], cleanEnv);
@@ -377,6 +403,12 @@ export async function installMeerkat(mode = 'devnet', env = process.env, deps =
377
403
  throw new Error('fresh initialization was interrupted; retained state requires operator inspection, never automatic reseeding');
378
404
  await ownership(state, deps, cleanEnv, fresh);
379
405
  checkpoint();
406
+ if (fresh) {
407
+ say(`${devnet ? 'DevNet' : 'Local'} install into ${dir} — the first run downloads about 1 GB of images`);
408
+ }
409
+ else {
410
+ say(`Resuming ${devnet ? 'DevNet' : 'local'} install in ${dir}`);
411
+ }
380
412
  if (fresh) {
381
413
  await cp(join(packageDir, 'dist'), join(dir, 'package', 'dist'), { recursive: true, errorOnExist: true, force: false });
382
414
  await cp(join(packageDir, 'installer'), join(dir, 'package', 'installer'), { recursive: true, errorOnExist: true, force: false });
@@ -389,7 +421,8 @@ export async function installMeerkat(mode = 'devnet', env = process.env, deps =
389
421
  await compose('config', '--quiet');
390
422
  checkpoint();
391
423
  if (state.initialization === 'pending') {
392
- await compose('build', ...(state.mode === 'devnet' ? ['node', 'registry'] : ['committee', 'node', 'registry']));
424
+ say('Downloading and building images (first install: usually 2–10 minutes, depending on your connection) …');
425
+ await deps.command('docker', [...composeArgs(state), 'build', ...(state.mode === 'devnet' ? ['node', 'registry'] : ['committee', 'node', 'registry'])], cleanEnv, dir, { timeoutMs: 45 * 60_000, heartbeat: (elapsed) => say(`still downloading/building images… ${Math.round(elapsed / 60_000)}m elapsed`) });
393
426
  checkpoint();
394
427
  state.initialization = 'attempted';
395
428
  await saveState(state);
@@ -398,11 +431,21 @@ export async function installMeerkat(mode = 'devnet', env = process.env, deps =
398
431
  await saveState(state);
399
432
  checkpoint();
400
433
  }
434
+ else {
435
+ say('Images already built — skipping build');
436
+ }
401
437
  if (state.mode === 'local') {
438
+ say(state.binding ? 'Starting the local consensus committee (already built) …' : 'Starting the local consensus committee …');
402
439
  await compose('up', '-d', '--no-build', '--no-recreate', 'committee');
403
440
  await deps.committeeReady(state, cleanEnv);
404
441
  checkpoint();
405
442
  }
443
+ if (devnet) {
444
+ say('Starting the node — it now begins syncing the public DevNet from round 0 (the live “round X of Y” progress lines report the real target); the installer waits for it to catch up at the end');
445
+ }
446
+ else {
447
+ say(state.binding ? 'Starting the processing node (already running) …' : 'Starting the processing node …');
448
+ }
406
449
  await compose('up', '-d', '--no-build', '--no-recreate', 'node');
407
450
  checkpoint();
408
451
  const observed = await deps.nodeBinding(state, cleanEnv);
@@ -417,19 +460,28 @@ export async function installMeerkat(mode = 'devnet', env = process.env, deps =
417
460
  await writeFile(composePath, JSON.stringify(renderDeployment(state), null, 2), { mode: 0o600 });
418
461
  await compose('up', '-d', '--no-build', '--no-recreate', 'registry');
419
462
  checkpoint();
463
+ say(devnet ? 'Claiming identities through the DevNet faucet …' : 'Claiming the agent identity through the local committee …');
420
464
  await deps.bootstrap(state, cleanEnv);
421
465
  if (state.mode === 'local' && !state.ready) {
422
466
  // The agent owns the install's private channel; claim it once through the child's own tools,
423
467
  // BEFORE the registry's readiness check, so the read-only registry sees its pinned operator.
424
468
  // A completed install never repeats the step. An interrupted one retries it: the runtime
425
469
  // reads the terms first and never re-claims a channel the agent already owns.
470
+ say('Claiming the private announcement channel …');
426
471
  await deps.claimChannel(state, cleanEnv);
427
472
  }
473
+ if (devnet) {
474
+ say('Waiting for the node and registry to catch up with DevNet (usually 10–30 minutes; progress every 30 s). You can leave this running; re-running the same install command later resumes.');
475
+ }
476
+ else {
477
+ say(state.ready ? 'Waiting for the registry (already ready) …' : 'Waiting for the registry (usually under a minute) …');
478
+ }
428
479
  await deps.registryReady(state, cleanEnv);
429
480
  checkpoint();
430
481
  state.ready = true;
431
482
  await saveState(state);
432
483
  checkpoint();
484
+ say(`Ready after ${Math.round((Date.now() - started) / 1000)}s. Next: register with — claude mcp add --scope user --transport stdio meerkat -- npx --yes ${PACKAGE}@${state.packageVersion} serve${devnet ? '' : ' --local'}`);
433
485
  return { dir, configPath, registration: pinnedRegistration(state.packageVersion, state.mode) };
434
486
  }
435
487
  finally {