mycomesh-consumer 0.1.50 → 0.1.52

package/src/consumer-sessions.mjs

@@ -0,0 +1,205 @@
+import { randomUUID } from "node:crypto";
+
+// Routing-only hints: never forward these as Gateway stateful-history headers.
+export const CONSUMER_SESSION_HEADERS = Object.freeze([
+  "x-mycomesh-session-id",
+  "x-session-id",
+  "session_id",
+]);
+
+const TOOL_CALL_TYPES = new Set([
+  "tool_call", "function_call", "local_shell_call", "tool_search_call",
+  "custom_tool_call", "mcp_tool_call",
+]);
+const TOOL_OUTPUT_TYPES = new Set([
+  "function_call_output", "tool_search_output", "custom_tool_call_output",
+  "mcp_tool_call_output",
+]);
+
+export class ConsumerSessionError extends Error {
+  constructor(message, statusCode = 400) {
+    super(message);
+    this.name = "ConsumerSessionError";
+    this.statusCode = statusCode;
+    this.status = statusCode;
+    this.code = statusCode === 409 ? "session_continuation_unavailable" : "invalid_session";
+  }
+}
+
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validIdentifier(value, limit) {
+  return typeof value === "string" && value.length > 0 && value.length <= limit
+    && /^[\x21-\x7e]+$/.test(value) && !value.includes(",");
+}
+
+function sessionIdentifier(value) {
+  if (!validIdentifier(value, 128)) {
+    throw new ConsumerSessionError("Session id must be 1–128 printable ASCII characters without whitespace or commas");
+  }
+  return value;
+}
+
+function headerSignals(headers) {
+  const values = [];
+  const entries = typeof headers?.entries === "function"
+    ? headers.entries() : Object.entries(headers || {});
+  for (const [name, value] of entries) {
+    if (!CONSUMER_SESSION_HEADERS.includes(name.toLowerCase())) continue;
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      if (value.length !== 1) throw new ConsumerSessionError("Duplicate session headers are not allowed");
+      values.push(sessionIdentifier(value[0]));
+    } else {
+      values.push(sessionIdentifier(value));
+    }
+  }
+  return values;
+}
+
+function toolReferences(body) {
+  const context = new Set();
+  const outputs = [];
+  for (const item of Array.isArray(body.input) ? body.input : []) {
+    if (!object(item)) continue;
+    if (TOOL_CALL_TYPES.has(item.type) && validIdentifier(item.call_id, 256)) context.add(item.call_id);
+    if (TOOL_OUTPUT_TYPES.has(item.type)) outputs.push(item.call_id);
+  }
+  for (const message of Array.isArray(body.messages) ? body.messages : []) {
+    if (!object(message)) continue;
+    if (message.role === "assistant" && Array.isArray(message.tool_calls)) {
+      for (const call of message.tool_calls) {
+        if (object(call) && validIdentifier(call.id, 256)) context.add(call.id);
+      }
+    }
+    if (message.role === "tool") outputs.push(message.tool_call_id);
+  }
+  return { context, outputs };
+}
+
+/**
+ * One instance belongs to one authenticated Consumer routing namespace.
+ * No prompt, cache key, wallet, or payment request id is treated as a session.
+ * Continuation mappings are process-local, bounded, and expire after inactivity.
+ */
+export class ConsumerSessions {
+  constructor({ ttlMs = 30 * 60_000, maxEntries = 10_000, now = Date.now, generateId = randomUUID } = {}) {
+    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || !Number.isSafeInteger(maxEntries) || maxEntries <= 0) {
+      throw new TypeError("Session TTL and capacity must be positive safe integers");
+    }
+    if (typeof now !== "function" || typeof generateId !== "function") {
+      throw new TypeError("Session clock and id generator must be functions");
+    }
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+    this.now = now;
+    this.generateId = generateId;
+    this.entries = new Map();
+  }
+
+  get size() {
+    this.prune(this.now());
+    return this.entries.size;
+  }
+
+  prune(now) {
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= now) this.entries.delete(key);
+    }
+  }
+
+  resolve(body, headers = {}) {
+    if (!object(body)) throw new ConsumerSessionError("Request body must be a JSON object");
+    if (body.metadata != null && !object(body.metadata)) {
+      throw new ConsumerSessionError("Request metadata must be a JSON object");
+    }
+    const signals = headerSignals(headers);
+    if (Object.hasOwn(body.metadata || {}, "mycomesh_session_id")) {
+      signals.push(sessionIdentifier(body.metadata.mycomesh_session_id));
+    }
+    if (body.conversation != null) {
+      const value = object(body.conversation) ? body.conversation.id : body.conversation;
+      signals.push(sessionIdentifier(value));
+    }
+    if (new Set(signals).size > 1) throw new ConsumerSessionError("Explicit session identifiers disagree");
+
+    const now = this.now();
+    this.prune(now);
+    const continuationSessions = new Set();
+    const matchedKeys = new Set();
+    const resolveReference = (kind, value, selfContained = false) => {
+      if (!validIdentifier(value, 256)) {
+        throw new ConsumerSessionError("Continuation reference must be a nonempty ASCII identifier", 409);
+      }
+      const key = `${kind}:${value}`;
+      const entry = this.entries.get(key);
+      // Full-history SDK/Codex requests may include old call+output pairs and
+      // are already supported statelessly by the Provider backend. An explicit
+      // new session may fork that history without inheriting its old route.
+      if (selfContained && signals.length) return;
+      if (!entry && selfContained) return;
+      if (!entry || !entry.sessionId) {
+        throw new ConsumerSessionError("Continuation is unknown, expired, or ambiguous; its original route is unavailable", 409);
+      }
+      continuationSessions.add(entry.sessionId);
+      matchedKeys.add(key);
+    };
+    if (body.previous_response_id != null) resolveReference("response", body.previous_response_id);
+    const { context, outputs } = toolReferences(body);
+    for (const callId of outputs) resolveReference("call", callId, context.has(callId));
+    if (continuationSessions.size > 1) {
+      throw new ConsumerSessionError("Continuation references belong to different sessions", 409);
+    }
+    const previousSession = continuationSessions.values().next().value;
+    if (previousSession && signals.length && previousSession !== signals[0]) {
+      throw new ConsumerSessionError("Explicit session does not match the continuation's original session", 409);
+    }
+    const id = signals[0] || previousSession || sessionIdentifier(this.generateId());
+    for (const key of matchedKeys) {
+      const entry = this.entries.get(key);
+      this.entries.delete(key);
+      this.entries.set(key, { ...entry, expiresAt: now + this.ttlMs });
+    }
+    return {
+      id,
+      body: { ...body, metadata: { ...body.metadata, mycomesh_session_id: id } },
+      explicit: signals.length > 0,
+      requiresOriginalRoute: matchedKeys.size > 0,
+    };
+  }
+
+  // Accept either a raw OpenAI response or relayInference's {status, payload}.
+  // Call only after the actual request succeeded on the selected route.
+  remember(result, sessionId) {
+    sessionIdentifier(sessionId);
+    if (!object(result) || (typeof result.status === "number" && (result.status < 200 || result.status >= 300))) return 0;
+    const payload = object(result.payload) ? result.payload : result;
+    if (payload.error) return 0;
+    const now = this.now();
+    this.prune(now);
+    let remembered = 0;
+    const save = (kind, value) => {
+      if (!validIdentifier(value, 256)) return;
+      const key = `${kind}:${value}`;
+      const previous = this.entries.get(key);
+      // A reused upstream id must not silently transfer a continuation route.
+      const resolvedSession = previous && previous.sessionId !== sessionId ? null : sessionId;
+      this.entries.delete(key);
+      this.entries.set(key, { sessionId: resolvedSession, expiresAt: now + this.ttlMs });
+      while (this.entries.size > this.maxEntries) this.entries.delete(this.entries.keys().next().value);
+      remembered += 1;
+    };
+    save("response", payload.id);
+    for (const item of Array.isArray(payload.output) ? payload.output : []) {
+      if (object(item) && TOOL_CALL_TYPES.has(item.type)) save("call", item.call_id);
+    }
+    for (const choice of Array.isArray(payload.choices) ? payload.choices : []) {
+      for (const call of Array.isArray(choice?.message?.tool_calls) ? choice.message.tool_calls : []) {
+        if (object(call)) save("call", call.id);
+      }
+    }
+    return remembered;
+  }
+}

package/src/consumer.mjs

@@ -1,7 +1,11 @@
 import { spawn as defaultSpawn } from "node:child_process";
 import { existsSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { request as httpsRequest } from "node:https";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as readline from "node:readline/promises";
+import { CONSUMER_RELEASE_VERSION } from "./release.mjs";
+export { CONSUMER_RELEASE_VERSION } from "./release.mjs";
 
 import {
   DEFAULT_BASE_URL,
@@ -9,9 +13,19 @@ import {
   DEFAULT_RELAY_URL,
   NativeConsumerState,
   createConsumerServer,
+  parseNetworkConfig,
+  paymentKeyAddress,
 } from "./consumer-runtime.mjs";
 
-export const CONSUMER_RELEASE_VERSION = "0.1.50";
+// V10 is a controlled committee testnet. Keep its manifest in the package,
+// but make selecting it an explicit opt-in so the legacy V8 default remains
+// safe for existing installs.
+export const V10_CONTROLLED_TEST_NETWORK = fileURLToPath(
+  new URL("../networks/v10-controlled-test.json", import.meta.url),
+);
+export const V10_DYNAMIC_PROVIDER_AI_NETWORK = fileURLToPath(
+  new URL("../networks/v10-dynamic-20260926.json", import.meta.url),
+);
 export const API_COMMANDS = new Set(["health", "models", "responses", "chat"]);
 const API_VALUE_OPTIONS = new Set([
   "--base-url",
@@ -31,7 +45,7 @@ const API_VALUE_OPTIONS = new Set([
 export const CONSUMER_HELP = `Usage: mycomesh-consumer [options] [-- codex-options]
 
 Start the local MycoMesh Consumer without Docker, Python, or a public Gateway.
-The process owns one persisted V8 payment key, selects healthy Relays, and
+The process manages a persisted access key, selects healthy Relays, and
 exposes an OpenAI-compatible loopback API.
 
 Options:
@@ -44,17 +58,26 @@ Options:
   --ready-timeout SEC   Relay readiness timeout (default: 1800)
   --data-dir DIR        Payment key and history directory
   --relay URLS          Comma-separated Relay URLs for automatic failover
+  --network-config FILE Use a trusted network manifest and its backup Relays
+  --ca-file FILE       Private CA PEM for an explicit controlled-test network
+  --controlled-test     Explicitly opt into a controlled test committee
+  --v10-controlled-test Select the bundled V10 fixed-budget controlled testnet
+  --v10-dynamic-provider-ai Select the bundled V10 dynamic Provider-AI testnet
   --proxy URL           Optional outbound HTTP proxy
   --host HOST           Listen address (default: 127.0.0.1)
   --port PORT           Listen port (default: 8110)
   --max-fee UNITS       Maximum fee per request (default: 100000)
   --dry-run             Print the native startup plan
+  --doctor              Check local Consumer configuration without starting or paying
+  --doctor-json         Emit the same check as stable JSON for automation
   -h, --help            Show this help
   -v, --version         Show the package version
 
-The browser page displays only the export URL/key, prepaid balance, key
-operations, and local consumption history. No browser conversation state is
-created.`;
+Each Consumer process starts locked. Connect your browser wallet on the setup
+page. For first use, choose Enable API access and confirm the wallet request;
+returning users reuse the existing authorization. Copy the API URL and key (or
+the combined export) into your client. Never enter a wallet private key.
+The page has no browser conversation state.`;
 
 class ConsumerCliError extends Error {
   constructor(message, exitCode = 1) {
@@ -78,10 +101,13 @@ export async function main(argv, dependencies = {}) {
       stdout.write(`${CONSUMER_RELEASE_VERSION}\n`);
       return 0;
     }
+    if (parsed.doctor || parsed.doctorJson) {
+      return await consumerDoctor({ parsed, env, stdout, fetch: dependencies.fetch, json: parsed.doctorJson });
+    }
     if (parsed.dryRun) {
       stdout.write(`Native Consumer: ${parsed.host}:${parsed.port}\n`);
       stdout.write(`Data directory: ${parsed.dataDir}\n`);
-      stdout.write(`Relays: ${parsed.relayUrls}\n`);
+      stdout.write(`Relays: ${!parsed.relayUrlsExplicit && parsed.networkConfig ? "from selected network manifest (legacy default if absent)" : parsed.relayUrls}\n`);
       stdout.write("Docker: disabled\n");
       return 0;
     }
@@ -93,7 +119,10 @@ export async function main(argv, dependencies = {}) {
       : new NativeConsumerState({
           env: { ...env, MYCOMESH_CONSUMER_DATA_DIR: parsed.dataDir },
           dataDir: parsed.dataDir,
-          relayUrls: parsed.relayUrls,
+          relayUrls: parsed.relayUrlsExplicit ? parsed.relayUrls : undefined,
+          networkConfig: parsed.networkConfig,
+          caFile: parsed.caFile,
+          allowControlledTest: parsed.allowControlledTest,
           proxy: parsed.proxy,
           baseUrl: parsed.baseUrl,
           maxFeeUnits: parsed.maxFeeUnits,
@@ -105,7 +134,7 @@ export async function main(argv, dependencies = {}) {
     const rootUrl = `${parsed.scheme}://${parsed.hostForUrl}:${parsed.port}`;
     const credentialsUrl = `${rootUrl}/`;
     writePid(parsed.dataDir);
-    stdout.write(`MycoMesh Consumer credentials: ${credentialsUrl}\n`);
+    stdout.write(`MycoMesh Consumer setup: ${credentialsUrl}\n`);
     stdout.write(`OpenAI API: ${state.baseUrl}\n`);
     if (!parsed.noBrowser) openBrowser(credentialsUrl, stderr);
 
@@ -119,6 +148,7 @@ export async function main(argv, dependencies = {}) {
       return 0;
     }
     await waitUntilReady(state, parsed.readyTimeout, stdout);
+    await waitUntilUnlocked(state, parsed.readyTimeout, stdout);
     const code = await runCodex(parsed, state, dependencies.spawn ?? defaultSpawn, stdout, stderr);
     await shutdown();
     return code;
@@ -138,6 +168,9 @@ export function parseArguments(argv, env = process.env) {
     baseUrlExplicit: Boolean(env.MYCOMESH_CONSUMER_PUBLIC_BASE_URL),
     dataDir: env.MYCOMESH_CONSUMER_DATA_DIR || join(env.HOME || process.cwd(), ".mycomesh", "consumer"),
     relayUrls: env.MYCOMESH_V8_RELAY_URLS || env.MYCOMESH_CONSUMER_RELAY_URL || DEFAULT_RELAY_URL,
+    relayUrlsExplicit: Boolean(env.MYCOMESH_V8_RELAY_URLS || env.MYCOMESH_CONSUMER_RELAY_URL),
+    networkConfig: env.MYCOMESH_CONSUMER_NETWORK_CONFIG || undefined,
+    caFile: env.MYCOMESH_CONSUMER_CA_FILE || undefined,
     proxy: env.MYCOMESH_CONSUMER_PROXY || "",
     codexCommand: env.MYCOMESH_CODEX_COMMAND || "codex",
     readyTimeout: parsePositive(env.MYCOMESH_CONSUMER_READY_TIMEOUT_SECONDS || "1800", "ready timeout", 86400),
@@ -146,11 +179,16 @@ export function parseArguments(argv, env = process.env) {
     hostForUrl: env.MYCOMESH_CONSUMER_HOST || "127.0.0.1",
     port: parsePositive(env.MYCOMESH_CONSUMER_PORT || "8110", "port", 65535),
     scheme: "http",
+    allowControlledTest: false,
+    v10ControlledTest: false,
+    v10DynamicProviderAi: false,
     noBrowser: false,
     noCodex: env.MYCOMESH_CONSUMER_START_CODEX !== "1",
     stop: false,
     resetLocal: false,
     dryRun: false,
+    doctor: false,
+    doctorJson: false,
     help: false,
     version: false,
     codexArgs: [],
@@ -160,22 +198,37 @@ export function parseArguments(argv, env = process.env) {
     if (token === "--") { parsed.codexArgs = argv.slice(index + 1); break; }
     if (token === "-h" || token === "--help") { parsed.help = true; continue; }
     if (token === "-v" || token === "--version") { parsed.version = true; continue; }
+    if (token === "--controlled-test") { parsed.allowControlledTest = true; continue; }
+    if (token === "--v10-controlled-test") {
+      parsed.v10ControlledTest = true;
+      parsed.allowControlledTest = true;
+      continue;
+    }
+    if (token === "--v10-dynamic-provider-ai") {
+      parsed.v10DynamicProviderAi = true;
+      parsed.allowControlledTest = true;
+      continue;
+    }
     if (token === "--no-browser") { parsed.noBrowser = true; continue; }
     if (token === "--codex") { parsed.noCodex = false; continue; }
     if (token === "--no-codex") { parsed.noCodex = true; continue; }
     if (token === "--stop") { parsed.stop = true; continue; }
     if (token === "--reset-local") { parsed.resetLocal = true; continue; }
     if (token === "--dry-run") { parsed.dryRun = true; continue; }
+    if (token === "--doctor") { parsed.doctor = true; continue; }
+    if (token === "--doctor-json") { parsed.doctorJson = true; continue; }
     const separator = token.indexOf("=");
     const name = separator === -1 ? token : token.slice(0, separator);
     let value = separator === -1 ? undefined : token.slice(separator + 1);
-    const options = new Set(["--base-url", "--data-dir", "--relay", "--proxy", "--codex-command", "--ready-timeout", "--host", "--port", "--max-fee"]);
+    const options = new Set(["--base-url", "--data-dir", "--relay", "--network-config", "--ca-file", "--proxy", "--codex-command", "--ready-timeout", "--host", "--port", "--max-fee"]);
     if (!options.has(name)) throw new ConsumerCliError(`unknown option: ${token}`, 2);
     if (value === undefined) { index += 1; value = argv[index]; }
     if (!value) throw new ConsumerCliError(`${name} requires a value`, 2);
     if (name === "--base-url") { parsed.baseUrl = value; parsed.baseUrlExplicit = true; }
     if (name === "--data-dir") parsed.dataDir = value;
-    if (name === "--relay") parsed.relayUrls = value;
+    if (name === "--relay") { parsed.relayUrls = value; parsed.relayUrlsExplicit = true; }
+    if (name === "--network-config") parsed.networkConfig = value;
+    if (name === "--ca-file") parsed.caFile = value;
     if (name === "--proxy") parsed.proxy = value;
     if (name === "--codex-command") parsed.codexCommand = value;
     if (name === "--ready-timeout") parsed.readyTimeout = parsePositive(value, name, 86400);
@@ -183,11 +236,149 @@ export function parseArguments(argv, env = process.env) {
     if (name === "--port") parsed.port = parsePositive(value, name, 65535);
     if (name === "--max-fee") parsed.maxFeeUnits = parsePositive(value, name);
   }
+  if (parsed.v10ControlledTest && !parsed.networkConfig) {
+    parsed.networkConfig = env.MYCOMESH_V10_NETWORK_CONFIG || V10_CONTROLLED_TEST_NETWORK;
+  }
+  if (parsed.v10DynamicProviderAi && !parsed.networkConfig) {
+    parsed.networkConfig = env.MYCOMESH_V10_DYNAMIC_NETWORK_CONFIG || V10_DYNAMIC_PROVIDER_AI_NETWORK;
+  }
   if (!parsed.baseUrlExplicit) parsed.baseUrl = `http://${parsed.hostForUrl}:${parsed.port}/v1`;
   try { new URL(parsed.baseUrl); } catch { throw new ConsumerCliError("--base-url must be an absolute URL", 2); }
   return parsed;
 }
 
+// Read-only preflight. This deliberately does not construct NativeConsumerState:
+// its constructor creates a payment key on first run. A doctor command must be
+// safe to run from installers, CI and support scripts without changing state.
+async function consumerDoctor({ parsed, env, stdout, fetch: injectedFetch, json }) {
+  const checks = [];
+  const add = (id, status, message, details = undefined) => {
+    const check = { id, status, message };
+    if (details !== undefined) check.details = details;
+    checks.push(check);
+  };
+  const dataDir = parsed.dataDir;
+  if (existsSync(dataDir)) add("data_dir", "ready", "Consumer data directory exists", { path: dataDir });
+  else add("data_dir", "setup_required", "Consumer data directory has not been created", { path: dataDir });
+
+  const keyPath = join(dataDir, "payment-key");
+  const configuredKey = String(env.MYCOMESH_V8_PAYMENT_KEY || "").trim();
+  let paymentAddress;
+  try {
+    if (configuredKey) paymentAddress = paymentKeyAddress(configuredKey);
+    else if (existsSync(keyPath)) paymentAddress = paymentKeyAddress(readFileSync(keyPath, "utf8").trim());
+    else throw Object.assign(new Error("payment key is not initialized"), { code: "setup_required" });
+    add("payment_key", "ready", "Payment key is present and valid", {
+      source: configuredKey ? "environment" : "data_dir",
+      address: paymentAddress,
+    });
+  } catch (error) {
+    add("payment_key", error.code === "setup_required" ? "setup_required" : "blocked", error.message);
+  }
+
+  let network;
+  try {
+    network = parseNetworkConfig(parsed.networkConfig, { allowControlledTest: parsed.allowControlledTest });
+    add("network_manifest", "ready", parsed.networkConfig ? "Settlement network manifest is valid" : "Using built-in settlement network", {
+      path: parsed.networkConfig || null,
+      protocol_version: network.protocol_version,
+      chain_id: network.chain_id,
+      settlement_contract: network.settlement_contract,
+    });
+  } catch (error) {
+    add("network_manifest", "blocked", error.message, { path: parsed.networkConfig || null });
+  }
+
+  const relayUrls = network?.relay_urls?.length ? network.relay_urls : String(parsed.relayUrls || "")
+    .split(",").map((value) => value.trim()).filter(Boolean);
+  const validRelays = [];
+  for (const value of relayUrls) {
+    try {
+      const url = new URL(value);
+      if (!/^https?:$/.test(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error("URL must be an HTTPS origin without credentials or query");
+      validRelays.push(url.href.replace(/\/+$/, ""));
+    } catch (error) {
+      add("relay_urls", "blocked", `Invalid Relay URL: ${error.message}`, { url: value });
+    }
+  }
+  if (validRelays.length) add("relay_urls", "ready", `${validRelays.length} Relay URL${validRelays.length === 1 ? "" : "s"} configured`, { urls: validRelays });
+  else if (!checks.some((check) => check.id === "relay_urls")) add("relay_urls", "blocked", "No usable Relay URL is configured");
+
+  const pidPath = join(dataDir, "consumer.pid");
+  if (!existsSync(pidPath)) add("local_process", "ready", "No stale Consumer pid file found", { running: false });
+  else {
+    const pid = Number(readFileSync(pidPath, "utf8").trim());
+    let running = false;
+    try { if (Number.isInteger(pid) && pid > 1) { process.kill(pid, 0); running = true; } } catch (error) { if (error.code !== "ESRCH") running = true; }
+    add("local_process", running ? "ready" : "blocked", running ? "Consumer process is running" : "Consumer pid file is stale", { pid, running });
+  }
+
+  const fetchImpl = injectedFetch || ((url, options) => consumerDoctorFetch(url, options, parsed));
+  const health = [];
+  if (validRelays.length && typeof fetchImpl === "function") {
+    await Promise.all(validRelays.map(async (relay) => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 1500);
+      try {
+        const response = await fetchImpl(`${relay}/health`, { method: "GET", redirect: "error", signal: controller.signal });
+        health.push({ url: relay, status: response.ok ? "ready" : "blocked", http_status: response.status });
+        await response.body?.cancel?.();
+      } catch (error) { health.push({ url: relay, status: "blocked", error: error.message }); }
+      finally { clearTimeout(timer); }
+    }));
+    const healthy = health.filter((item) => item.status === "ready").length;
+    const relayStatus = healthy === 0 ? "blocked" : healthy < health.length ? "degraded" : "ready";
+    add("relay_health", relayStatus, healthy ? `${healthy}/${health.length} Relay health checks passed` : "All Relay health checks failed", { relays: health });
+  } else add("relay_health", "setup_required", "Relay health was not checked because no usable Relay URL is configured");
+
+  const hasBlocked = checks.some((check) => check.status === "blocked");
+  const hasSetup = checks.some((check) => check.status === "setup_required");
+  const hasDegraded = checks.some((check) => check.status === "degraded");
+  const report = {
+    schema: "mycomesh.consumer.doctor.v1",
+    status: hasBlocked ? "blocked" : hasSetup ? "setup_required" : hasDegraded ? "degraded" : "ready",
+    release: { version: CONSUMER_RELEASE_VERSION },
+    config: { data_dir: dataDir, host: parsed.host, port: parsed.port, base_url: parsed.baseUrl },
+    checks,
+  };
+  if (json) stdout.write(`${JSON.stringify(report)}\n`);
+  else {
+    stdout.write(`Consumer doctor: ${report.status}\n`);
+    for (const check of checks) stdout.write(`${check.status === "ready" ? "✓" : check.status === "setup_required" ? "!" : check.status === "degraded" ? "~" : "✗"} ${check.id}: ${check.message}\n`);
+  }
+  return report.status === "blocked" ? 1 : 0;
+}
+
+function consumerDoctorFetch(url, options = {}, parsed) {
+  const target = new URL(url);
+  if (target.protocol !== "https:" || !parsed.caFile) return globalThis.fetch(url, options);
+  const ca = readFileSync(resolve(parsed.caFile));
+  return new Promise((resolvePromise, reject) => {
+    const request = httpsRequest({
+      protocol: target.protocol,
+      hostname: target.hostname,
+      port: target.port || 443,
+      path: `${target.pathname}${target.search}`,
+      method: options.method || "GET",
+      ca,
+      rejectUnauthorized: true,
+    }, (response) => {
+      response.resume();
+      resolvePromise({
+        ok: (response.statusCode || 0) >= 200 && (response.statusCode || 0) < 300,
+        status: response.statusCode || 0,
+        body: { cancel: async () => {} },
+      });
+    });
+    const abort = () => request.destroy(options.signal?.reason || new Error("request aborted"));
+    options.signal?.addEventListener("abort", abort, { once: true });
+    request.setTimeout(1500, () => request.destroy(new Error("request timed out")));
+    request.once("error", reject);
+    request.once("close", () => options.signal?.removeEventListener("abort", abort));
+    request.end();
+  });
+}
+
 function parsePositive(value, label, maximum = Number.MAX_SAFE_INTEGER) {
   if (!/^[1-9][0-9]*$/.test(String(value))) throw new ConsumerCliError(`${label} must be a positive integer`, 2);
   const parsed = Number(value);
@@ -212,7 +403,7 @@ export function isApiInvocation(argv) {
 
 async function waitUntilReady(state, timeoutSeconds, stdout) {
   const started = Date.now();
-  stdout.write("Waiting for a healthy Settlement V8 Relay...\n");
+  stdout.write(`Waiting for a healthy Settlement V${state.network?.protocol_version || 8} Relay...\n`);
   while (true) {
     try { await state.chooseRelay(); return; } catch (error) {
       if (Date.now() - started >= timeoutSeconds * 1000) throw new ConsumerCliError(`timed out waiting for a healthy Relay: ${error.message}`);
@@ -221,6 +412,17 @@ async function waitUntilReady(state, timeoutSeconds, stdout) {
   }
 }
 
+async function waitUntilUnlocked(state, timeoutSeconds, stdout) {
+  const started = Date.now();
+  stdout.write("Waiting for wallet verification in the local Consumer page...\n");
+  while (!state.paymentUnlocked) {
+    if (Date.now() - started >= timeoutSeconds * 1000) {
+      throw new ConsumerCliError("timed out waiting for the payment-key owner wallet to unlock Consumer");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+}
+
 function runCodex(parsed, state, spawn, stdout, stderr) {
   return new Promise((resolve) => {
     const args = [

package/src/release.mjs

@@ -0,0 +1,12 @@
+// Package versions are kept in one runtime module so every executable reports
+// the same version as the package metadata that ships it.
+export const CONSUMER_RELEASE_VERSION = "0.1.52";
+export const PROVIDER_RELEASE_VERSION = "0.1.38";
+
+// Provider release pins are intentionally unbound in the source tree. The
+// release candidate builder injects the commit and immutable OCI digest into a
+// temporary Provider package after the image has been published. Keeping these
+// values null prevents a source checkout from pretending that a not-yet-built
+// image belongs to the current source.
+export const PROVIDER_RELEASE_SOURCE_COMMIT = null;
+export const PROVIDER_RELEASE_IMAGE = null;