@toon-protocol/townhouse 0.1.0-rc5 → 0.1.0

package/dist/cli.js

@@ -1,30 +1,59 @@
 #!/usr/bin/env node
 import { createRequire } from 'module'; const require = createRequire(import.meta.url);
 import {
+  BootReconciler,
   ConnectorAdminClient,
   DEFAULT_ATOR_PROXY,
   DockerOrchestrator,
+  LOG_SERVICES,
+  OrchestratorError,
+  PeerTypeResolver,
   TransportProbe,
   WalletManager,
+  aggregateEarnings,
   createApiServer,
+  createDeltaComputer,
   createWizardApiServer,
   decryptWallet,
   encryptWallet,
   getDefaultConfig,
+  isSyntheticDigest,
   loadConfig,
   loadWallet,
-  saveWallet
-} from "./chunk-IB6TNCUQ.js";
-import "./chunk-UTFWPLTB.js";
+  materializeComposeTemplate,
+  readImageManifest,
+  readNodesYaml,
+  saveWallet,
+  serviceFromContainerName,
+  tailContainerLogs,
+  writeHsConnectorConfig
+} from "./chunk-4WCMVIO4.js";
+import {
+  CONTAINER_PREFIX
+} from "./chunk-GQNBZJ6F.js";
+import {
+  formatRelativeTime,
+  formatUsdc
+} from "./chunk-JCOFMUPL.js";
+import "./chunk-I2R4CRUX.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
-import { mkdirSync, writeFileSync, existsSync } from "fs";
-import { join, resolve } from "path";
+import {
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  renameSync,
+  rmSync,
+  statSync
+} from "fs";
+import { join, resolve, dirname } from "path";
 import { homedir } from "os";
 import { pathToFileURL } from "url";
+import { spawn as spawn2 } from "child_process";
 import { stringify } from "yaml";
-import Docker from "dockerode";
+import Docker2 from "dockerode";
+import { nip19 } from "nostr-tools";
 
 // src/cli/browser-opener.ts
 import { spawn } from "child_process";
@@ -46,36 +75,1906 @@ var RealBrowserOpener = class {
         args = [url];
         break;
     }
-    return new Promise((resolve2) => {
-      let settled = false;
-      const settle = () => {
-        if (settled) return;
-        settled = true;
-        resolve2();
-      };
-      try {
-        const child = spawn(cmd, args, {
-          stdio: ["ignore", "ignore", "ignore"],
-          detached: true
-        });
-        child.once("error", (err) => {
-          console.warn(
-            `[Townhouse] Could not open browser via ${cmd}: ${err.message}`
-          );
-          settle();
-        });
-        child.once("spawn", () => {
-          child.unref();
-          settle();
-        });
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`[Townhouse] Could not open browser: ${msg}`);
-        settle();
-      }
-    });
+    return new Promise((resolve2) => {
+      let settled = false;
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        resolve2();
+      };
+      try {
+        const child = spawn(cmd, args, {
+          stdio: ["ignore", "ignore", "ignore"],
+          detached: true
+        });
+        child.once("error", (err) => {
+          console.warn(
+            `[Townhouse] Could not open browser via ${cmd}: ${err.message}`
+          );
+          settle();
+        });
+        child.once("spawn", () => {
+          child.unref();
+          settle();
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[Townhouse] Could not open browser: ${msg}`);
+        settle();
+      }
+    });
+  }
+};
+
+// src/cli/onboarding-ribbon.ts
+var PHASES = {
+  pull: "Pulling apex image\u2026",
+  bootstrap: "Bootstrapping hidden service (this takes 30\u201390s)\u2026"
+};
+var SPINNER_FRAMES = ["|", "/", "-", "\\"];
+function isTty() {
+  return process.stdout.isTTY === true;
+}
+function supportsUnicode() {
+  const term = process.env["TERM"] ?? "";
+  if (term === "dumb") return false;
+  if (/xterm|screen|tmux/i.test(term)) return true;
+  if (process.env["COLORTERM"] !== void 0) return true;
+  return false;
+}
+function isAnimationDisabled() {
+  if (process.env["NO_COLOR"] !== void 0 && process.env["NO_COLOR"] !== "")
+    return true;
+  if (process.env["CI"] === "true") return true;
+  return false;
+}
+function useAnsiRewrite() {
+  return isTty() && supportsUnicode() && !isAnimationDisabled();
+}
+var OnboardingRibbon = class {
+  currentPhase = null;
+  spinnerTimer = null;
+  spinnerFrame = 0;
+  hasWrittenLine = false;
+  start(phase, detail) {
+    this._stopSpinner();
+    if (phase === "live") {
+      const line = detail ? `Apex live at ${detail}` : "Apex live.";
+      this._writeLine(line);
+      this.currentPhase = "live";
+      return;
+    }
+    const text = PHASES[phase];
+    if (useAnsiRewrite() && this.hasWrittenLine) {
+      process.stdout.write("\x1B[1A\x1B[2K");
+    }
+    if (isAnimationDisabled() || !isTty()) {
+      this._writeLine(text);
+    } else {
+      this._writeLine(`${text} ${SPINNER_FRAMES[0]}`);
+      this.spinnerFrame = 1;
+      this.spinnerTimer = setInterval(() => {
+        const idx = this.spinnerFrame % SPINNER_FRAMES.length;
+        const frame = SPINNER_FRAMES[idx] ?? "|";
+        this.spinnerFrame++;
+        if (useAnsiRewrite()) {
+          process.stdout.write("\x1B[1A\x1B[2K");
+          process.stdout.write(`${text} ${frame}
+`);
+        } else {
+          process.stdout.write(`${text} ${frame}
+`);
+        }
+      }, 100);
+    }
+    this.currentPhase = phase;
+  }
+  stop() {
+    this._stopSpinner();
+  }
+  _stopSpinner() {
+    if (this.spinnerTimer !== null) {
+      clearInterval(this.spinnerTimer);
+      this.spinnerTimer = null;
+    }
+  }
+  _writeLine(text) {
+    process.stdout.write(`${text}
+`);
+    this.hasWrittenLine = true;
+  }
+};
+
+// src/cli/failure-copy.ts
+var FAILURE_COPY = {
+  "anon-timeout": {
+    headline: "Hidden service didn't publish in time.",
+    explanation: "The .anyone descriptor did not publish within the allotted time.",
+    nextStep: "Re-run with DEBUG=townhouse:* for verbose anon logs."
+  },
+  "anon-disabled": {
+    headline: "Connector is anon-disabled.",
+    explanation: "The connector config has anon.enabled: false.",
+    nextStep: "Edit ~/.townhouse/connector.yaml and set anon.enabled: true."
+  },
+  "image-pull-failure": {
+    headline: "Image pull failed.",
+    explanation: "Docker could not pull the required townhouse images.",
+    nextStep: "Check your network and try again."
+  },
+  "port-collision": {
+    headline: "Port already in use.",
+    explanation: "A required host port is already bound by another process.",
+    nextStep: "Stop the conflicting service or override the port via --connector-admin-port."
+  },
+  "missing-docker-sock": {
+    headline: "Docker daemon unreachable.",
+    explanation: "The Docker socket is not accessible or Docker is not running.",
+    nextStep: "Start Docker and re-run `townhouse hs up`."
+  },
+  generic: {
+    headline: "Apex boot failed.",
+    explanation: "",
+    nextStep: "Run with DEBUG=townhouse:* for verbose logs."
+  }
+};
+function supportsUnicode2() {
+  const term = process.env["TERM"] ?? "";
+  if (term === "dumb") return false;
+  if (/xterm|screen|tmux/i.test(term)) return true;
+  if (process.env["COLORTERM"] !== void 0) return true;
+  return false;
+}
+function useAscii() {
+  if (process.env["NO_COLOR"] !== void 0 && process.env["NO_COLOR"] !== "")
+    return true;
+  return !supportsUnicode2();
+}
+function classify(error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  const isOrchError = error instanceof OrchestratorError;
+  const stderr = isOrchError ? error.stderr ?? "" : "";
+  if (msg.includes("HS hostname publication timeout")) {
+    return { key: "anon-timeout", explanation: msg };
+  }
+  if (isOrchError && msg.includes("anon-disabled")) {
+    return { key: "anon-timeout", explanation: msg };
+  }
+  if (!isOrchError && msg.includes("anon-disabled")) {
+    return { key: "anon-disabled", explanation: msg };
+  }
+  if (stderr.includes("failed to pull") || stderr.includes("pull access denied") || msg.includes("failed to pull") || msg.includes("pull access denied")) {
+    return { key: "image-pull-failure", explanation: msg };
+  }
+  if (stderr.includes("address already in use") || stderr.includes("port is already allocated") || msg.includes("address already in use") || msg.includes("port is already allocated")) {
+    return { key: "port-collision", explanation: msg };
+  }
+  if (stderr.includes("Cannot connect to the Docker daemon") || msg.includes("Cannot connect to the Docker daemon") || msg.includes("docker CLI not found on PATH")) {
+    return { key: "missing-docker-sock", explanation: msg };
+  }
+  return { key: "generic", explanation: msg };
+}
+function renderFailure(error) {
+  const ascii = useAscii();
+  const { key, explanation } = classify(error);
+  const entry = FAILURE_COPY[key];
+  if (!entry) {
+    const xMark2 = ascii ? "[X]" : "\u2715";
+    const arrow2 = ascii ? "->" : "\u2192";
+    process.stderr.write(`${xMark2} Apex boot failed.
+`);
+    process.stderr.write(`  ${explanation}
+`);
+    process.stderr.write(
+      `  ${arrow2} Run with DEBUG=townhouse:* for verbose logs.
+`
+    );
+    return { exitCode: 1 };
+  }
+  const xMark = ascii ? "[X]" : "\u2715";
+  const arrow = ascii ? "->" : "\u2192";
+  const explanationText = key === "generic" ? explanation : entry.explanation;
+  process.stderr.write(`${xMark} ${entry.headline}
+`);
+  process.stderr.write(`  ${explanationText}
+`);
+  process.stderr.write(`  ${arrow} ${entry.nextStep}
+`);
+  return { exitCode: 1 };
+}
+
+// src/cli/password-prompt.ts
+import { createInterface } from "readline";
+function promptPassword(prompt = "Wallet password: ") {
+  return new Promise((resolve2, reject) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true
+    });
+    const iface = rl;
+    const origWrite = iface._writeToOutput.bind(iface);
+    iface._writeToOutput = (str) => {
+      if (str === "\r\n" || str === "\n" || str === "\r") {
+        origWrite(str);
+      } else if (/^[\x20-\x7e€-￿]/.test(str)) {
+        origWrite("*".repeat(str.length));
+      } else {
+        origWrite(str);
+      }
+    };
+    rl.question(prompt, (answer) => {
+      iface._writeToOutput = origWrite;
+      process.stdout.write("\n");
+      rl.close();
+      resolve2(answer);
+    });
+    rl.once("error", (err) => {
+      iface._writeToOutput = origWrite;
+      rl.close();
+      reject(err);
+    });
+    rl.once("close", () => {
+    });
+  });
+}
+
+// src/cli/preflight-ports.ts
+import { createServer } from "net";
+var HS_CANONICAL_PORTS = [
+  9401,
+  28090,
+  7100,
+  3100,
+  3200,
+  3400
+];
+async function isPortInUse(port) {
+  return new Promise((resolve2, reject) => {
+    const server = createServer();
+    let settled = false;
+    const finalize = (result) => {
+      if (settled) return;
+      settled = true;
+      server.removeAllListeners("error");
+      server.removeAllListeners("listening");
+      try {
+        server.close();
+      } catch {
+      }
+      if (result instanceof Error) reject(result);
+      else resolve2(result);
+    };
+    server.once("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        finalize(true);
+      } else {
+        finalize(err);
+      }
+    });
+    server.once("listening", () => {
+      const addr = server.address();
+      void addr;
+      finalize(false);
+    });
+    try {
+      server.listen({ port, host: "127.0.0.1", exclusive: true });
+    } catch (err) {
+      finalize(err);
+    }
+  });
+}
+function findDockerCulprit(containers, port) {
+  for (const c of containers) {
+    const ports = c.Ports ?? [];
+    for (const p of ports) {
+      if (p.PublicPort === port) {
+        const rawName = c.Names?.[0] ?? "";
+        const name = rawName.startsWith("/") ? rawName.slice(1) : rawName;
+        const project = c.Labels?.["com.docker.compose.project"];
+        return {
+          containerName: name || void 0,
+          composeProject: project,
+          status: c.Status
+        };
+      }
+    }
+  }
+  return void 0;
+}
+async function checkHsPortCollisions(docker, ports = HS_CANONICAL_PORTS) {
+  const probes = await Promise.all(
+    ports.map(async (port) => {
+      try {
+        const inUse = await isPortInUse(port);
+        return { port, inUse, probeError: void 0 };
+      } catch (err) {
+        return {
+          port,
+          inUse: true,
+          probeError: err instanceof Error ? err : new Error(String(err))
+        };
+      }
+    })
+  );
+  const taken = probes.filter((p) => p.inUse);
+  if (taken.length === 0) return [];
+  let containers = [];
+  if (docker) {
+    try {
+      containers = await docker.listContainers({ all: false });
+    } catch {
+      containers = [];
+    }
+  }
+  return taken.map((t) => {
+    const culprit = findDockerCulprit(containers, t.port);
+    return {
+      port: t.port,
+      ...culprit ?? {}
+    };
+  });
+}
+function formatCollisionMessage(collisions) {
+  if (collisions.length === 0) return "";
+  const lines = [];
+  lines.push("townhouse hs up: cannot start \u2014 host ports already in use:");
+  lines.push("");
+  for (const c of collisions) {
+    const portLabel = `127.0.0.1:${c.port}`.padEnd(18);
+    if (c.containerName) {
+      lines.push(`  ${portLabel}in use by container '${c.containerName}'`);
+      const project = c.composeProject ?? "<no compose project>";
+      const status = c.status ? `, ${c.status}` : "";
+      lines.push(`  ${" ".repeat(18)}(compose project '${project}'${status})`);
+    } else {
+      lines.push(
+        `  ${portLabel}port in use (no Docker container found \u2014 try \`sudo lsof -iTCP:${c.port} -sTCP:LISTEN\`)`
+      );
+    }
+  }
+  lines.push("");
+  lines.push("The HS template needs canonical ports \u2014 it cannot remap.");
+  const projects = /* @__PURE__ */ new Set();
+  for (const c of collisions) {
+    if (c.composeProject) projects.add(c.composeProject);
+  }
+  if (projects.size > 0) {
+    lines.push("Stop the conflicting project to free them:");
+    lines.push("");
+    for (const project of projects) {
+      lines.push(`  docker compose -p ${project} down`);
+    }
+    lines.push("");
+    lines.push(
+      "Or, if the conflicting process is NOT a townhouse stack, identify it with:"
+    );
+  } else {
+    lines.push("Identify the conflicting processes with:");
+  }
+  lines.push("");
+  const examplePort = collisions[0]?.port ?? 9401;
+  lines.push(`  sudo lsof -iTCP:${examplePort} -sTCP:LISTEN`);
+  lines.push("");
+  lines.push("Re-run with --skip-preflight to bypass this check.");
+  return lines.join("\n") + "\n";
+}
+
+// src/cli/pull-narrator.ts
+var THROTTLED_STATUSES = /* @__PURE__ */ new Set(["Downloading", "Extracting"]);
+var PullNarrator = class {
+  now;
+  throttleMs;
+  perImage = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.now = options.now ?? Date.now;
+    this.throttleMs = options.throttleMs ?? 1e3;
+  }
+  /**
+   * Render an event to a stdout-ready line, or `null` if it should be
+   * suppressed by the throttle.
+   */
+  format(event) {
+    const status = event.status;
+    if (!status) {
+      return null;
+    }
+    const state = this.perImage.get(event.image) ?? {
+      lastStatus: void 0,
+      lastThrottledAtMs: 0
+    };
+    const isThrottled = THROTTLED_STATUSES.has(status);
+    const isTransition = state.lastStatus !== status;
+    if (isThrottled && !isTransition) {
+      const elapsed = this.now() - state.lastThrottledAtMs;
+      if (elapsed < this.throttleMs) {
+        return null;
+      }
+    }
+    state.lastStatus = status;
+    if (isThrottled) {
+      state.lastThrottledAtMs = this.now();
+    }
+    this.perImage.set(event.image, state);
+    const progress = event.progress ? ` ${event.progress}` : "";
+    return `  [pull] ${event.image}: ${status}${progress}`;
+  }
+  /**
+   * Reset the narrator's per-image state. Useful between separate pull
+   * batches in the same process.
+   */
+  reset() {
+    this.perImage.clear();
+  }
+};
+
+// src/cli/node-commands.ts
+import * as readline from "readline";
+var DEFAULT_HS_API_URL = "http://127.0.0.1:28090";
+var STEP_TO_STAGE = {
+  preflight: "Preflight",
+  "derive-key": "Deriving wallet",
+  "pull-image": "Pulling image",
+  "write-yaml": "Deriving wallet",
+  // same disk-class bucket from operator POV
+  "write-mill-config": "Deriving wallet",
+  // same disk-class bucket as write-yaml
+  "start-container": "Registering with apex",
+  healthcheck: "Registering with apex",
+  "register-peer": "Live"
+};
+var STAGE_LABELS = [
+  "Pulling image",
+  "Deriving wallet",
+  "Registering with apex",
+  "Live"
+];
+var NODE_ADD_HELP = `townhouse node add \u2014 Provision a child node
+
+Usage:
+  townhouse node add [<type>] [--json] [-c <path>]
+
+Arguments:
+  <type>   Node type to provision: town, mill, dvm (default: town)
+
+Flags:
+  --json   Machine-readable JSON output
+  -c       Path to config file
+
+Examples:
+  townhouse node add           # provision a Town relay (default)
+  townhouse node add town      # same as above
+  townhouse node add mill   # earn from chain swaps (5x earnings unlock)
+  townhouse node add dvm       # add a DVM compute node`;
+var NODE_REMOVE_HELP = `townhouse node remove \u2014 Deprovision a child node
+
+Usage:
+  townhouse node remove <id> [--yes] [--json] [-c <path>]
+
+Arguments:
+  <id>     Node ID to remove (use 'townhouse node list' to find IDs)
+
+Flags:
+  --yes    Skip confirmation prompt (required in non-interactive mode)
+  --json   Machine-readable JSON output; implies non-interactive (no prompt)
+  -c       Path to config file`;
+var NODE_LIST_HELP = `townhouse node list \u2014 List provisioned nodes
+
+Usage:
+  townhouse node list [--json] [-c <path>]
+
+Flags:
+  --json   Machine-readable JSON output (emits API response verbatim)
+  -c       Path to config file`;
+var NODE_HELP = `townhouse node \u2014 Manage child nodes
+
+Usage:
+  townhouse node add [<type>] [--json] [-c <path>]    Provision a child node (default: town)
+  townhouse node remove <id> [--yes] [--json] [-c <path>]   Deprovision a child node
+  townhouse node list [--json] [-c <path>]            List provisioned nodes
+
+Run 'townhouse node <verb> --help' for details on each verb.
+
+Tip:
+  townhouse node add mill   # earn from chain swaps (5x earnings unlock)`;
+function resolveApiUrl(apiUrl) {
+  return apiUrl ?? DEFAULT_HS_API_URL;
+}
+function formatRelativeTime2(iso) {
+  const ts = new Date(iso).getTime();
+  if (Number.isNaN(ts)) return "\u2014";
+  const diffMs = Date.now() - ts;
+  if (diffMs < 0) return "just now";
+  const secs = Math.floor(diffMs / 1e3);
+  if (secs < 60) return `${secs}s ago`;
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+async function confirmInteractive(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const answer = await new Promise(
+      (resolve2) => rl.question(question, resolve2)
+    );
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+function emitJsonError(obj, exitCode = 1) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+  process.exitCode = exitCode;
+}
+async function handleNodeAdd(type, options) {
+  const ascii = useAscii();
+  const check = ascii ? "[OK]" : "\u2713";
+  const xMark = ascii ? "[X]" : "\u2715";
+  const dot = ascii ? "." : "\xB7";
+  if (type !== "town" && type !== "mill" && type !== "dvm") {
+    const msg = `Unknown type: '${type}'. Supported: town, mill, dvm`;
+    if (options.json) {
+      emitJsonError({ ok: false, error: "invalid_type", message: msg });
+    } else {
+      process.stderr.write(`${xMark} ${msg}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const url = resolveApiUrl(options.apiUrl);
+  const fetchImpl = options.fetch ?? fetch;
+  if (!options.json) {
+    process.stdout.write(
+      `  ${STAGE_LABELS.map((s) => `${dot} ${s}`).join(" \xB7 ")}
+`
+    );
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 12e4);
+  let response;
+  try {
+    response = await fetchImpl(`${url}/api/nodes`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type }),
+      signal: controller.signal
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    const isAborted = err instanceof Error && err.name === "AbortError";
+    const errMsg = isAborted ? "Request timed out after 120 seconds." : "townhouse hs up isn't running. Run 'townhouse hs up' first.";
+    if (options.json) {
+      emitJsonError({
+        ok: false,
+        error: isAborted ? "timeout" : "econnrefused",
+        message: errMsg
+      });
+    } else {
+      process.stderr.write(`${xMark} ${errMsg}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  clearTimeout(timer);
+  if (response.status === 201) {
+    const body2 = await response.json().catch(() => ({}));
+    if (options.json) {
+      process.stdout.write(JSON.stringify({ ok: true, ...body2 }) + "\n");
+    } else {
+      process.stdout.write(
+        `  ${STAGE_LABELS.map((s) => `${check} ${s}`).join(" \xB7 ")}
+`
+      );
+      const addedId = body2.id ?? type;
+      const addedPeer = body2.peerId ? ` (${body2.peerId})` : "";
+      const addedAddr = body2.ilpAddress ? ` at ${body2.ilpAddress}` : "";
+      process.stdout.write(`  Added ${addedId}${addedPeer}${addedAddr}
+`);
+    }
+    return;
+  }
+  const body = await response.json().catch(() => ({}));
+  if (options.json) {
+    emitJsonError({ ok: false, ...body });
+    return;
+  }
+  if (response.status === 409 && body.error === "node_type_in_use") {
+    process.stderr.write(
+      `${xMark} Node of type '${body.type}' already exists with id '${body.existingId}'. Remove it first or use a different type.
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (response.status === 409 && body.error === "node_lifecycle_in_flight") {
+    process.stderr.write(
+      `${xMark} Another node operation is in flight. Try again in a moment.
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const step = body.step ?? "unknown";
+  const errText = body.err ?? "";
+  if (step === "pull-image") {
+    const syntheticErr = new Error(`failed to pull: ${errText}`);
+    renderFailure(syntheticErr);
+  } else if (step === "start-container" && (errText.includes("port is already allocated") || errText.includes("Cannot connect to the Docker daemon"))) {
+    renderFailure(new Error(errText));
+  } else if (step === "preflight") {
+    const arrow = ascii ? "->" : "\u2192";
+    process.stderr.write(`${xMark} ${errText}
+`);
+    process.stderr.write(
+      `  ${arrow} Fix the configuration above, then retry 'townhouse node add'.
+`
+    );
+  } else {
+    const stageName = STEP_TO_STAGE[step] ?? step;
+    const arrow = ascii ? "->" : "\u2192";
+    process.stderr.write(
+      `${xMark} Step ${step} failed (stage: ${stageName}): ${errText}
+`
+    );
+    process.stderr.write(
+      `  ${arrow} Run 'townhouse hs down && townhouse hs up' to reset state, then retry.
+`
+    );
+  }
+  if (body.rollbackError) {
+    process.stderr.write(`  Rollback error: ${body.rollbackError}
+`);
+  }
+  process.exitCode = 1;
+}
+var NODE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+async function handleNodeRemove(id, options) {
+  const ascii = useAscii();
+  const check = ascii ? "[OK]" : "\u2713";
+  const xMark = ascii ? "[X]" : "\u2715";
+  if (!id) {
+    const msg = "Usage: townhouse node remove <id> [--yes] [--json]";
+    if (options.json) {
+      emitJsonError({ ok: false, error: "missing_id", message: msg });
+    } else {
+      process.stderr.write(`${msg}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (!NODE_ID_PATTERN.test(id)) {
+    const msg = `Invalid node id '${id}'. IDs must match ^[a-z][a-z0-9-]*$ (lowercase, no leading hyphens or underscores).`;
+    if (options.json) {
+      emitJsonError({ ok: false, error: "invalid_id", message: msg });
+    } else {
+      process.stderr.write(`${xMark} ${msg}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const skipPrompt = options.yes || options.json;
+  if (!skipPrompt) {
+    if (!process.stdin.isTTY) {
+      const msg = "--yes required when stdin is not a TTY (use --yes for non-interactive removal).";
+      process.stderr.write(`${xMark} ${msg}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    const confirmFn = options.confirm ?? confirmInteractive;
+    const confirmed = await confirmFn(
+      `Remove node '${id}'? This deprovisions the container and deregisters the peer. [y/N] `
+    );
+    if (!confirmed) {
+      process.stdout.write("Cancelled.\n");
+      return;
+    }
+  }
+  const url = resolveApiUrl(options.apiUrl);
+  const fetchImpl = options.fetch ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 6e4);
+  let response;
+  try {
+    response = await fetchImpl(`${url}/api/nodes/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+      signal: controller.signal
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    const isAborted = err instanceof Error && err.name === "AbortError";
+    const errMsg = isAborted ? "Request timed out." : "townhouse hs up isn't running. Run 'townhouse hs up' first.";
+    if (options.json) {
+      emitJsonError({
+        ok: false,
+        error: isAborted ? "timeout" : "econnrefused",
+        message: errMsg
+      });
+    } else {
+      process.stderr.write(`${xMark} ${errMsg}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  clearTimeout(timer);
+  if (response.status === 200) {
+    const body2 = await response.json().catch(() => ({}));
+    const removedId = body2.id ?? id;
+    if (options.json) {
+      process.stdout.write(
+        JSON.stringify({ ok: true, id: removedId, type: body2.type }) + "\n"
+      );
+    } else {
+      process.stdout.write(`${check} Removed ${removedId}
+`);
+    }
+    return;
+  }
+  const body = await response.json().catch(() => ({}));
+  if (options.json) {
+    emitJsonError({ ok: false, ...body });
+    return;
+  }
+  if (response.status === 404) {
+    process.stderr.write(`${xMark} No node with id '${id}'
+`);
+  } else if (response.status === 409 && body.error === "node_lifecycle_in_flight") {
+    process.stderr.write(
+      `${xMark} Another node operation is in flight. Try again in a moment.
+`
+    );
+  } else {
+    const step = body.step ?? "unknown";
+    process.stderr.write(`${xMark} Step ${step} failed: ${body.err ?? ""}
+`);
+  }
+  process.exitCode = 1;
+}
+async function handleNodeList(options) {
+  const ascii = useAscii();
+  const xMark = ascii ? "[X]" : "\u2715";
+  const emDash = ascii ? "-" : "\u2014";
+  const url = resolveApiUrl(options.apiUrl);
+  const fetchImpl = options.fetch ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 3e4);
+  let response;
+  try {
+    response = await fetchImpl(`${url}/api/nodes`, {
+      method: "GET",
+      signal: controller.signal
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    const isAborted = err instanceof Error && err.name === "AbortError";
+    const errMsg = isAborted ? "Request timed out." : "townhouse hs up isn't running. Run 'townhouse hs up' first.";
+    if (options.json) {
+      emitJsonError({
+        ok: false,
+        error: isAborted ? "timeout" : "econnrefused",
+        message: errMsg
+      });
+    } else {
+      process.stderr.write(`${xMark} ${errMsg}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  clearTimeout(timer);
+  if (response.status !== 200) {
+    const body2 = await response.json().catch(() => ({}));
+    if (options.json) {
+      emitJsonError({ ok: false, ...body2 });
+    } else {
+      process.stderr.write(
+        `${xMark} Failed to fetch nodes (HTTP ${response.status})
+`
+      );
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const body = await response.json().catch(() => ({ nodes: [] }));
+  const nodes = body.nodes ?? [];
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ nodes }) + "\n");
+    return;
+  }
+  if (nodes.length === 0) {
+    process.stdout.write(
+      "No nodes provisioned. Run 'townhouse node add town' to add one.\n"
+    );
+    return;
+  }
+  const rows = nodes.map((node) => ({
+    peer: node.id,
+    type: node.type,
+    status: node.status,
+    lastClaim: node.lastSeenAt !== null ? formatRelativeTime2(node.lastSeenAt) : emDash
+  }));
+  const HEADERS = {
+    peer: "peer",
+    type: "type",
+    status: "status",
+    lastClaim: "last claim"
+  };
+  const widths = {
+    peer: Math.max(HEADERS.peer.length, ...rows.map((r) => r.peer.length)),
+    type: Math.max(HEADERS.type.length, ...rows.map((r) => r.type.length)),
+    status: Math.max(
+      HEADERS.status.length,
+      ...rows.map((r) => r.status.length)
+    ),
+    lastClaim: Math.max(
+      HEADERS.lastClaim.length,
+      ...rows.map((r) => r.lastClaim.length)
+    )
+  };
+  function pad(s, width) {
+    return s.length >= width ? s : s + " ".repeat(width - s.length);
+  }
+  const divider = ascii ? "-" : "\u2500";
+  process.stdout.write(
+    `${pad(HEADERS.peer, widths.peer)}  ${pad(HEADERS.type, widths.type)}  ${pad(HEADERS.status, widths.status)}  ${HEADERS.lastClaim}
+`
+  );
+  process.stdout.write(
+    `${divider.repeat(widths.peer)}  ${divider.repeat(widths.type)}  ${divider.repeat(widths.status)}  ${divider.repeat(widths.lastClaim)}
+`
+  );
+  for (const row of rows) {
+    process.stdout.write(
+      `${pad(row.peer, widths.peer)}  ${pad(row.type, widths.type)}  ${pad(row.status, widths.status)}  ${row.lastClaim}
+`
+    );
+  }
+}
+
+// src/cli/drill-commands.ts
+import Docker from "dockerode";
+function truncate16(s) {
+  return s.length > 16 ? s.slice(0, 16) + "\u2026" : s;
+}
+function emitJson(payload, opts) {
+  process.stdout.write(
+    JSON.stringify(payload, null, opts.compact ? 0 : 2) + "\n"
+  );
+}
+function emitJsonError2(message, code, opts) {
+  process.stdout.write(
+    JSON.stringify({ error: message, code }, null, opts.compact ? 0 : 2) + "\n"
+  );
+  process.exitCode = 1;
+}
+async function handleChannels(adminClient, opts) {
+  let channels;
+  try {
+    channels = await adminClient.getChannels();
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (opts.json) {
+      emitJsonError2(
+        `Failed to fetch connector channels: ${msg}`,
+        "unreachable",
+        opts
+      );
+    } else {
+      console.error(`Failed to fetch connector channels: ${msg}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (opts.json) {
+    emitJson(channels, opts);
+    return;
+  }
+  if (channels.length === 0) {
+    console.log("No channels open");
+    return;
+  }
+  const now = opts.now ?? /* @__PURE__ */ new Date();
+  const HEADERS = {
+    channel: "CHANNEL",
+    peer: "PEER",
+    chain: "CHAIN",
+    status: "STATUS",
+    deposit: "DEPOSIT",
+    lastActivity: "LAST ACTIVITY"
+  };
+  const rows = channels.map((c) => ({
+    channel: truncate16(c.channelId),
+    peer: truncate16(c.peerId),
+    chain: c.chain,
+    status: c.status,
+    deposit: c.deposit,
+    lastActivity: formatRelativeTime(c.lastActivity, now)
+  }));
+  const widths = {
+    channel: Math.max(
+      HEADERS.channel.length,
+      ...rows.map((r) => r.channel.length)
+    ),
+    peer: Math.max(HEADERS.peer.length, ...rows.map((r) => r.peer.length)),
+    chain: Math.max(HEADERS.chain.length, ...rows.map((r) => r.chain.length)),
+    status: Math.max(
+      HEADERS.status.length,
+      ...rows.map((r) => r.status.length)
+    ),
+    deposit: Math.max(
+      HEADERS.deposit.length,
+      ...rows.map((r) => r.deposit.length)
+    ),
+    lastActivity: Math.max(
+      HEADERS.lastActivity.length,
+      ...rows.map((r) => r.lastActivity.length)
+    )
+  };
+  const header = HEADERS.channel.padEnd(widths.channel) + "  " + HEADERS.peer.padEnd(widths.peer) + "  " + HEADERS.chain.padEnd(widths.chain) + "  " + HEADERS.status.padEnd(widths.status) + "  " + HEADERS.deposit.padEnd(widths.deposit) + "  " + HEADERS.lastActivity;
+  console.log(header);
+  console.log("-".repeat(header.length));
+  for (const row of rows) {
+    console.log(
+      row.channel.padEnd(widths.channel) + "  " + row.peer.padEnd(widths.peer) + "  " + row.chain.padEnd(widths.chain) + "  " + row.status.padEnd(widths.status) + "  " + row.deposit.padEnd(widths.deposit) + "  " + row.lastActivity
+    );
+  }
+}
+async function handleMetrics(adminClient, opts) {
+  try {
+    const metrics = await adminClient.getMetrics();
+    const peers = await adminClient.getPeers();
+    const peerMetrics = new Map(metrics.peers.map((p) => [p.peerId, p]));
+    if (opts.json) {
+      emitJson(
+        {
+          aggregate: metrics.aggregate,
+          peers: metrics.peers,
+          peersDetail: peers,
+          uptimeSeconds: metrics.uptimeSeconds,
+          timestamp: metrics.timestamp
+        },
+        opts
+      );
+      return;
+    }
+    const now = opts.now ?? /* @__PURE__ */ new Date();
+    console.log("Connector Metrics:");
+    console.log("------------------");
+    console.log(`  Packets forwarded: ${metrics.aggregate.packetsForwarded}`);
+    console.log(`  Packets rejected:  ${metrics.aggregate.packetsRejected}`);
+    console.log(`  Bytes sent:        ${metrics.aggregate.bytesSent}`);
+    console.log("");
+    console.log("Peers:");
+    console.log("------");
+    if (peers.length === 0) {
+      console.log("  No peers connected");
+    } else {
+      const HEADERS = {
+        peer: "PEER",
+        connected: "STATUS",
+        packetsForwarded: "PACKETS FWD",
+        packetsRejected: "PACKETS REJ",
+        bytesSent: "BYTES SENT",
+        lastPacket: "LAST PACKET"
+      };
+      const rows = peers.map((peer) => {
+        const pm = peerMetrics.get(peer.id);
+        return {
+          peer: peer.id,
+          connected: peer.connected ? "connected" : "disconnected",
+          packetsForwarded: String(pm?.packetsForwarded ?? 0),
+          packetsRejected: String(pm?.packetsRejected ?? 0),
+          bytesSent: String(pm?.bytesSent ?? 0),
+          lastPacket: pm?.lastPacketAt != null ? formatRelativeTime(pm.lastPacketAt, now) : "\u2014"
+        };
+      });
+      const widths = {
+        peer: Math.max(HEADERS.peer.length, ...rows.map((r) => r.peer.length)),
+        connected: Math.max(
+          HEADERS.connected.length,
+          ...rows.map((r) => r.connected.length)
+        ),
+        packetsForwarded: Math.max(
+          HEADERS.packetsForwarded.length,
+          ...rows.map((r) => r.packetsForwarded.length)
+        ),
+        packetsRejected: Math.max(
+          HEADERS.packetsRejected.length,
+          ...rows.map((r) => r.packetsRejected.length)
+        ),
+        bytesSent: Math.max(
+          HEADERS.bytesSent.length,
+          ...rows.map((r) => r.bytesSent.length)
+        ),
+        lastPacket: Math.max(
+          HEADERS.lastPacket.length,
+          ...rows.map((r) => r.lastPacket.length)
+        )
+      };
+      const headerLine = `  ${HEADERS.peer.padEnd(widths.peer)}  ${HEADERS.connected.padEnd(widths.connected)}  ${HEADERS.packetsForwarded.padEnd(widths.packetsForwarded)}  ${HEADERS.packetsRejected.padEnd(widths.packetsRejected)}  ${HEADERS.bytesSent.padEnd(widths.bytesSent)}  ` + HEADERS.lastPacket;
+      console.log(headerLine);
+      console.log(`  ${"-".repeat(headerLine.trim().length)}`);
+      for (const row of rows) {
+        console.log(
+          `  ${row.peer.padEnd(widths.peer)}  ${row.connected.padEnd(widths.connected)}  ${row.packetsForwarded.padEnd(widths.packetsForwarded)}  ${row.packetsRejected.padEnd(widths.packetsRejected)}  ${row.bytesSent.padEnd(widths.bytesSent)}  ` + row.lastPacket
+        );
+      }
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (opts.json) {
+      emitJsonError2(
+        `Failed to fetch connector metrics: ${msg}`,
+        "unreachable",
+        opts
+      );
+    } else {
+      console.error(`Failed to fetch connector metrics: ${msg}`);
+      process.exitCode = 1;
+    }
+  }
+}
+async function resolveContainerName(docker, nodeId) {
+  let containers;
+  try {
+    containers = await docker.listContainers({ all: false });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      error: `Cannot connect to docker daemon: ${msg}. Is docker running?`,
+      code: "docker-unavailable"
+    };
+  }
+  const allNames = containers.flatMap(
+    (c) => c.Names.map((n) => n.replace(/^\//, ""))
+  );
+  if (nodeId.startsWith(CONTAINER_PREFIX)) {
+    if (!allNames.includes(nodeId)) {
+      return {
+        error: `Node "${nodeId}" is not running (no container named "${nodeId}").`,
+        code: "unknown-node"
+      };
+    }
+    const svc = serviceFromContainerName(nodeId) ?? "town";
+    return { name: nodeId, service: svc };
+  }
+  const candidates = [];
+  const exactName = `${CONTAINER_PREFIX}${nodeId}`;
+  if (allNames.includes(exactName)) {
+    const svc = serviceFromContainerName(exactName) ?? "town";
+    candidates.push({ name: exactName, service: svc });
+  }
+  const isService = LOG_SERVICES.includes(nodeId);
+  if (isService) {
+    for (const name of allNames) {
+      if (name === exactName) continue;
+      const svc = serviceFromContainerName(name);
+      if (svc === nodeId) {
+        candidates.push({ name, service: svc });
+      }
+    }
+  }
+  const unique = candidates.filter(
+    (c, i) => candidates.findIndex((x) => x.name === c.name) === i
+  );
+  if (unique.length === 0) {
+    const resolvedName = `${CONTAINER_PREFIX}${nodeId}`;
+    return {
+      error: `Node "${nodeId}" is not running (no container named "${resolvedName}").`,
+      code: "unknown-node"
+    };
+  }
+  if (unique.length > 1) {
+    const names = unique.map((c) => c.name).join(", ");
+    return {
+      error: `Ambiguous node-id "${nodeId}" \u2014 matches multiple containers: ${names}. Use the full container name.`,
+      code: "ambiguous-node"
+    };
+  }
+  const first = unique[0];
+  if (first === void 0) {
+    return {
+      error: `Internal error resolving container name for "${nodeId}"`,
+      code: "internal"
+    };
+  }
+  return first;
+}
+async function handleLogs(docker, nodeId, opts) {
+  const resolved = await resolveContainerName(docker, nodeId);
+  if ("error" in resolved) {
+    if (opts.json) {
+      emitJsonError2(resolved.error, resolved.code, opts);
+    } else {
+      process.stderr.write(resolved.error + "\n");
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const { name: containerName, service } = resolved;
+  const controller = new AbortController();
+  const sigintHandler = () => {
+    controller.abort();
+    process.stdout.write("", () => {
+      process.exit(process.exitCode ?? 0);
+    });
+  };
+  process.once("SIGINT", sigintHandler);
+  try {
+    const gen = tailContainerLogs(docker, containerName, service, {
+      tail: opts.lines,
+      signal: controller.signal
+    });
+    for await (const evt of gen) {
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(evt) + "\n");
+      } else {
+        process.stdout.write(
+          `${evt.ts} [${evt.service}] ${evt.level}: ${evt.msg}
+`
+        );
+      }
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    const isDockerError = msg.includes("ENOENT") && msg.includes("/var/run/docker.sock") || msg.includes("connect ENOENT") || msg.includes("Cannot connect to the Docker daemon") || msg.includes("ECONNREFUSED") && msg.includes("docker");
+    if (isDockerError) {
+      const errMsg = `Cannot connect to docker daemon: ${msg}. Is docker running?`;
+      if (opts.json) {
+        emitJsonError2(errMsg, "docker-unavailable", opts);
+      } else {
+        process.stderr.write(errMsg + "\n");
+        process.exitCode = 1;
+      }
+    } else {
+      const errMsg = `Log stream error for "${nodeId}": ${msg}`;
+      if (opts.json) {
+        emitJsonError2(errMsg, "internal", opts);
+      } else {
+        process.stderr.write(errMsg + "\n");
+        process.exitCode = 1;
+      }
+    }
+  } finally {
+    process.off("SIGINT", sigintHandler);
+  }
+}
+async function handlePeerDetail(adminClient, peerId, opts) {
+  const now = opts.now ?? /* @__PURE__ */ new Date();
+  let peers;
+  try {
+    peers = await adminClient.getPeers();
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (opts.json) {
+      emitJsonError2(msg, "unreachable", opts);
+    } else {
+      process.stderr.write(`Failed to fetch peers: ${msg}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const peer = peers.find((p) => p.id === peerId);
+  if (peer === void 0) {
+    const errMsg = `Unknown peer "${peerId}". Use \`townhouse metrics\` to see registered peers.`;
+    if (opts.json) {
+      emitJsonError2(errMsg, "unknown-peer", opts);
+    } else {
+      process.stderr.write(errMsg + "\n");
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const [earningsRaw, channelsRaw] = await Promise.all([
+    adminClient.getEarnings().catch(() => null),
+    adminClient.getChannels().catch(() => null)
+  ]);
+  const peerEarnings = earningsRaw?.peers.find((p) => p.peerId === peerId) ?? null;
+  const peerChannels = channelsRaw?.filter((c) => c.peerId === peerId) ?? [];
+  if (opts.json) {
+    const earningsForJson = peerEarnings && peerEarnings.byAsset.length > 0 ? peerEarnings : null;
+    emitJson(
+      {
+        peer,
+        earnings: earningsForJson,
+        channels: peerChannels
+      },
+      opts
+    );
+    return;
+  }
+  console.log(`Peer: ${peerId}`);
+  console.log("");
+  if (peer.ilpAddresses.length === 0) {
+    console.log("  (no ILP addresses registered)");
+  } else {
+    for (const addr of peer.ilpAddresses) {
+      console.log(`  ${addr}`);
+    }
+  }
+  console.log(`  Routes: ${peer.routeCount}`);
+  console.log("");
+  console.log(`Connected: ${peer.connected ? "yes" : "no"}`);
+  console.log("");
+  if (earningsRaw === null) {
+    console.log("Earnings:");
+    console.log(
+      "  (earnings endpoint unavailable: connector is not settlement-configured)"
+    );
+  } else if (peerEarnings === null || peerEarnings.byAsset.length === 0) {
+    console.log("Earnings:");
+    console.log("  (no settlement activity yet)");
+  } else {
+    console.log("Earnings:");
+    for (const asset of peerEarnings.byAsset) {
+      const lastClaim = asset.lastClaimAt ? formatRelativeTime(asset.lastClaimAt, now) : "never";
+      console.log(
+        `  ${asset.assetCode} \xB7 received ${asset.claimsReceivedTotal} \xB7 sent ${asset.claimsSentTotal} \xB7 net ${asset.netBalance} \xB7 last claim ${lastClaim}`
+      );
+    }
+  }
+  console.log("");
+  if (channelsRaw === null) {
+    console.log("Channels:");
+    console.log(
+      "  (channels endpoint unavailable: connector is not settlement-configured)"
+    );
+  } else if (peerChannels.length === 0) {
+    console.log("Channels:");
+    console.log("  (no channels open)");
+  } else {
+    console.log("Channels:");
+    for (const ch of peerChannels) {
+      console.log(
+        `  ${truncate16(ch.channelId)} \xB7 ${ch.chain} \xB7 ${ch.status} \xB7 deposit ${ch.deposit} \xB7 ${formatRelativeTime(ch.lastActivity, now)}`
+      );
+    }
+  }
+}
+var PROBE_TIMEOUT_MS = 3e3;
+async function probeConnector(adminClient) {
+  try {
+    await adminClient.pingAdminLive();
+    return { source: "connector", status: "healthy" };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { source: "connector", status: "unreachable", error: msg };
+  }
+}
+async function probeHostApi(apiUrl, fetchImpl) {
+  try {
+    const response = await fetchImpl(`${apiUrl}/health`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      return {
+        source: "api",
+        status: "unhealthy",
+        error: `HTTP ${response.status}`
+      };
+    }
+    const body = await response.json();
+    return {
+      source: "api",
+      status: "healthy",
+      uptime: body.uptime,
+      startedAt: body.startedAt,
+      version: body.version
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { source: "api", status: "unreachable", error: msg };
+  }
+}
+async function probeNodes(apiUrl, fetchImpl) {
+  let nodes;
+  try {
+    const resp = await fetchImpl(`${apiUrl}/api/nodes`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+    });
+    if (!resp.ok) {
+      return [
+        {
+          source: "nodes",
+          status: "unknown",
+          error: `failed to enumerate nodes: HTTP ${resp.status}`
+        }
+      ];
+    }
+    const body = await resp.json();
+    nodes = body.nodes ?? [];
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return [
+      {
+        source: "nodes",
+        status: "unknown",
+        error: `failed to enumerate nodes: ${msg}`
+      }
+    ];
+  }
+  return Promise.all(
+    nodes.map(async (node) => {
+      try {
+        const resp = await fetchImpl(
+          `${apiUrl}/api/nodes/${encodeURIComponent(node.id)}/health`,
+          {
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+          }
+        );
+        if (!resp.ok) {
+          return {
+            source: `node:${node.id}`,
+            status: "unhealthy",
+            error: `HTTP ${resp.status}`
+          };
+        }
+        const body = await resp.json();
+        const s = body.status;
+        const status = s === "healthy" ? "healthy" : s === "unhealthy" ? "unhealthy" : s === "starting" ? "starting" : s === "degraded" ? "degraded" : "unknown";
+        return { source: `node:${node.id}`, status };
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+          source: `node:${node.id}`,
+          status: "unreachable",
+          error: msg
+        };
+      }
+    })
+  );
+}
+async function probeAnyone(adminClient) {
+  try {
+    const result = await adminClient.getHsHostname();
+    if (result.hostname !== null) {
+      return {
+        source: "anyone-hostname",
+        status: "healthy",
+        hostname: result.hostname,
+        publishedAt: result.publishedAt ?? void 0
+      };
+    }
+    return {
+      source: "anyone-hostname",
+      status: "starting",
+      message: "anon publish pending"
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.startsWith("connector is anon-disabled") || /(?:^|:\s)503\b/.test(msg)) {
+      return {
+        source: "anyone-hostname",
+        status: "n/a",
+        message: "anon disabled in config"
+      };
+    }
+    return { source: "anyone-hostname", status: "unreachable", error: msg };
+  }
+}
+function computeOverall(probes) {
+  const statuses = probes.map((p) => p.status);
+  if (statuses.some(
+    (s) => s === "unhealthy" || s === "unreachable" || s === "unknown"
+  )) {
+    return "unhealthy";
+  }
+  if (statuses.some((s) => s === "starting" || s === "degraded")) {
+    return "degraded";
+  }
+  return "healthy";
+}
+async function handleHealth(adminClient, opts) {
+  const apiUrl = opts.apiUrl ?? "http://127.0.0.1:28090";
+  const fetchImpl = opts.fetch ?? fetch;
+  const healthClient = opts.adminClient ?? new ConnectorAdminClient(adminClient.getBaseUrl(), PROBE_TIMEOUT_MS);
+  const [connectorProbe, apiProbe, nodeProbes, anyoneProbe] = await Promise.all(
+    [
+      probeConnector(healthClient),
+      probeHostApi(apiUrl, fetchImpl),
+      probeNodes(apiUrl, fetchImpl),
+      probeAnyone(healthClient)
+    ]
+  );
+  const probes = [
+    connectorProbe,
+    apiProbe,
+    ...nodeProbes,
+    anyoneProbe
+  ];
+  const overall = computeOverall(probes);
+  if (opts.json) {
+    emitJson({ overall, probes }, opts);
+  } else {
+    for (const probe of probes) {
+      console.log(`${probe.source}: ${probe.status}`);
+      if (probe.error) console.log(`  error: ${probe.error}`);
+      if (probe.uptime !== void 0) console.log(`  uptime: ${probe.uptime}s`);
+      if (probe.peersConnected !== void 0)
+        console.log(
+          `  peers: ${probe.peersConnected}/${probe.totalPeers ?? "?"} connected`
+        );
+      if (probe.startedAt) console.log(`  startedAt: ${probe.startedAt}`);
+      if (probe.version) console.log(`  version: ${probe.version}`);
+      if (probe.hostname) console.log(`  hostname: ${probe.hostname}`);
+      if (probe.publishedAt) console.log(`  publishedAt: ${probe.publishedAt}`);
+      if (probe.message) console.log(`  ${probe.message}`);
+    }
+    console.log(`Overall: ${overall}`);
+  }
+  if (overall === "unhealthy") {
+    process.exitCode = 1;
+  }
+}
+async function dispatchDrillCommand(command, deps) {
+  const { values, positionals, adminUrl, apiUrl } = deps;
+  const json = values["json"] === true;
+  const jsonCompact = values["json-compact"] === true;
+  const baseOpts = { json, jsonCompact };
+  const usageError = (msg, code) => {
+    if (json) emitJsonError2(msg, code, baseOpts);
+    else {
+      console.error(msg);
+      process.exitCode = 1;
+    }
+  };
+  switch (command) {
+    case "channels": {
+      await handleChannels(new ConnectorAdminClient(adminUrl), baseOpts);
+      return true;
+    }
+    case "metrics": {
+      await handleMetrics(new ConnectorAdminClient(adminUrl), baseOpts);
+      return true;
+    }
+    case "logs": {
+      const nodeId = positionals[1];
+      if (!nodeId) {
+        usageError(
+          "Usage: townhouse logs <node-id> [--lines N] [-f|--follow] [--json]",
+          "usage"
+        );
+        return true;
+      }
+      const linesRaw = values["lines"];
+      let lines = 50;
+      if (linesRaw !== void 0) {
+        if (!/^\d+$/.test(linesRaw)) {
+          usageError(
+            "--lines must be an integer between 0 and 10000",
+            "bad-flag"
+          );
+          return true;
+        }
+        lines = Number(linesRaw);
+        if (lines < 0 || lines > 1e4) {
+          usageError(
+            "--lines must be an integer between 0 and 10000",
+            "bad-flag"
+          );
+          return true;
+        }
+      }
+      const docker = deps.docker ?? new Docker();
+      await handleLogs(docker, nodeId, { ...baseOpts, lines });
+      return true;
+    }
+    case "peer": {
+      const peerId = positionals[1];
+      if (!peerId) {
+        usageError("Usage: townhouse peer <id> [--json]", "usage");
+        return true;
+      }
+      await handlePeerDetail(
+        new ConnectorAdminClient(adminUrl),
+        peerId,
+        baseOpts
+      );
+      return true;
+    }
+    case "health": {
+      await handleHealth(new ConnectorAdminClient(adminUrl, PROBE_TIMEOUT_MS), {
+        ...baseOpts,
+        apiUrl
+      });
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+
+// src/cli/status-earnings.ts
+var USDC_SCALE = 6;
+var USDC_ASSET = "USDC";
+var DECIMAL_RE = /^-?\d+$/;
+var POSITIVE_INT_RE = /^[1-9]\d*$/;
+function addDecimalStrings(a, b) {
+  if (!DECIMAL_RE.test(b)) return a;
+  try {
+    return (BigInt(a) + BigInt(b)).toString();
+  } catch {
+    return a;
+  }
+}
+function computeUsdcScalars(earnings) {
+  let today = "0";
+  let month = "0";
+  let year = "0";
+  let lifetime = "0";
+  const apexUsdc = earnings.apex.routingFees[USDC_ASSET];
+  if (apexUsdc !== void 0) {
+    today = addDecimalStrings(today, apexUsdc.today);
+    month = addDecimalStrings(month, apexUsdc.month);
+    year = addDecimalStrings(year, apexUsdc.year);
+    lifetime = addDecimalStrings(lifetime, apexUsdc.lifetime);
+  }
+  for (const peer of earnings.peers) {
+    const peerUsdc = peer.byAsset[USDC_ASSET];
+    if (peerUsdc !== void 0) {
+      today = addDecimalStrings(today, peerUsdc.today);
+      month = addDecimalStrings(month, peerUsdc.month);
+      year = addDecimalStrings(year, peerUsdc.year);
+      lifetime = addDecimalStrings(lifetime, peerUsdc.lifetime);
+    }
+  }
+  return { today, month, year, lifetime };
+}
+function usdcMicroToSats(decimalString, satsPerUsdc) {
+  if (!DECIMAL_RE.test(decimalString)) return "0";
+  if (!Number.isInteger(satsPerUsdc) || satsPerUsdc <= 0) {
+    throw new Error("satsPerUsdc must be a positive integer");
+  }
+  const negative = decimalString.startsWith("-");
+  const absolute = negative ? decimalString.slice(1) : decimalString;
+  const sats = BigInt(absolute) * BigInt(satsPerUsdc) / 10n ** BigInt(USDC_SCALE);
+  return (negative && sats !== 0n ? "-" : "") + sats.toString();
+}
+function formatSatsRow(value) {
+  if (!value || !DECIMAL_RE.test(value)) return "0 sats";
+  const negative = value.startsWith("-");
+  const abs = negative ? value.slice(1) : value;
+  if (!abs || abs === "0") return "0 sats";
+  let formatted;
+  const absN = BigInt(abs);
+  if (absN < BigInt(Number.MAX_SAFE_INTEGER)) {
+    formatted = Number(abs).toLocaleString("en-US");
+  } else {
+    formatted = abs.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  }
+  return (negative ? "-" : "") + formatted + " sats";
+}
+function renderEarningsSection(opts) {
+  if (opts.earnings.status === "connector_unavailable") {
+    return ["", "Earnings (USDC): unavailable"];
+  }
+  const scalars = computeUsdcScalars(opts.earnings);
+  if (opts.units === "usdc") {
+    return [
+      "",
+      "Earnings (USDC):",
+      "----------------",
+      `  TODAY    ${formatUsdc(scalars.today, USDC_SCALE)}`,
+      `  MONTH    ${formatUsdc(scalars.month, USDC_SCALE)}`,
+      `  YEAR     ${formatUsdc(scalars.year, USDC_SCALE)}`,
+      `  LIFETIME ${formatUsdc(scalars.lifetime, USDC_SCALE)}`
+    ];
+  }
+  if (opts.satsPerUsdc === void 0 || !Number.isInteger(opts.satsPerUsdc) || opts.satsPerUsdc <= 0) {
+    throw new Error(
+      "renderEarningsSection: units='sats' requires a positive-integer satsPerUsdc"
+    );
+  }
+  const rate = opts.satsPerUsdc;
+  const header = `Earnings (sats @ ${rate}/USDC):`;
+  return [
+    "",
+    header,
+    "-".repeat(header.length),
+    `  TODAY    ${formatSatsRow(usdcMicroToSats(scalars.today, rate))}`,
+    `  MONTH    ${formatSatsRow(usdcMicroToSats(scalars.month, rate))}`,
+    `  YEAR     ${formatSatsRow(usdcMicroToSats(scalars.year, rate))}`,
+    `  LIFETIME ${formatSatsRow(usdcMicroToSats(scalars.lifetime, rate))}`
+  ];
+}
+function resolveSatsRate(values, env) {
+  const cliRaw = typeof values["rate"] === "string" ? values["rate"] : void 0;
+  const cliRate = cliRaw !== void 0 && cliRaw !== "" ? cliRaw : void 0;
+  const envRate = env["TOWNHOUSE_SATS_PER_USDC"];
+  const raw = cliRate ?? envRate;
+  const source = cliRate !== void 0 ? "--rate" : "TOWNHOUSE_SATS_PER_USDC env var";
+  if (raw === void 0) {
+    return {
+      error: "--units=sats requires --rate <sats-per-usdc> or TOWNHOUSE_SATS_PER_USDC env var (e.g. --rate 1500 for 1500 sats per 1 USDC)"
+    };
+  }
+  if (!POSITIVE_INT_RE.test(raw)) {
+    return {
+      error: `${source} must be a positive integer (sats per 1 USDC); got: ${JSON.stringify(raw)}`
+    };
+  }
+  const rate = Number(raw);
+  if (!Number.isSafeInteger(rate) || rate <= 0) {
+    return { error: `${source} is out of range` };
+  }
+  return { rate };
+}
+
+// src/credits/buy.ts
+import { TurboFactory } from "@ardrive/turbo-sdk/node";
+
+// src/wallet/turbo-signer.ts
+import {
+  ArweaveSigner,
+  EthereumSigner,
+  HexSolanaSigner
+} from "@ardrive/turbo-sdk/node";
+import bs58 from "bs58";
+function solanaSecretKeyBase58(privateKeyHex, publicKeyBase58) {
+  const priv = Buffer.from(privateKeyHex, "hex");
+  if (priv.length !== 32) {
+    throw new Error(
+      `Solana private key seed must be 32 bytes, got ${priv.length}`
+    );
+  }
+  const pub = bs58.decode(publicKeyBase58);
+  if (pub.length !== 32) {
+    throw new Error(`Solana public key must be 32 bytes, got ${pub.length}`);
+  }
+  const secret = new Uint8Array(64);
+  secret.set(priv, 0);
+  secret.set(pub, 32);
+  return bs58.encode(secret);
+}
+var TURBO_TOKEN_MAP = {
+  eth: "ethereum",
+  pol: "pol",
+  "base-eth": "base-eth",
+  "base-usdc": "base-usdc",
+  "usdc-eth": "usdc",
+  "usdc-pol": "polygon-usdc",
+  sol: "solana",
+  ar: "arweave"
+};
+var EVM_TOKENS = /* @__PURE__ */ new Set([
+  "eth",
+  "pol",
+  "base-eth",
+  "base-usdc",
+  "usdc-eth",
+  "usdc-pol"
+]);
+function canonicalTurboToken(token) {
+  const canonical = TURBO_TOKEN_MAP[token];
+  if (!canonical) {
+    throw new Error(
+      `Unknown TurboTokenId '${String(token)}'. Supported: ${Object.keys(TURBO_TOKEN_MAP).join(", ")}`
+    );
+  }
+  return canonical;
+}
+async function buildTurboSigner(wallet, nodeType, token) {
+  const canonical = canonicalTurboToken(token);
+  if (EVM_TOKENS.has(token)) {
+    const privateKeyHex = wallet.getEvmPrivateKeyHex(nodeType);
+    const signer = new EthereumSigner(privateKeyHex);
+    const keys = wallet.getNodeKeys(nodeType);
+    return { signer, token: canonical, address: keys.evmAddress };
+  }
+  if (token === "sol") {
+    const privateKeyHex = wallet.getSolanaPrivateKeyHex(nodeType);
+    const keys = wallet.getNodeKeys(nodeType);
+    if (!keys.solanaAddress) {
+      throw new Error(`Solana address not available for node '${nodeType}'`);
+    }
+    const secretBase58 = solanaSecretKeyBase58(
+      privateKeyHex,
+      keys.solanaAddress
+    );
+    const signer = new HexSolanaSigner(secretBase58);
+    return { signer, token: canonical, address: keys.solanaAddress };
+  }
+  if (token === "ar") {
+    await wallet.ensureArweaveKey(nodeType);
+    const jwk = wallet.getArweaveJwk(nodeType);
+    const signer = new ArweaveSigner(jwk);
+    const keys = wallet.getNodeKeys(nodeType);
+    if (!keys.arweaveAddress) {
+      throw new Error(
+        `Arweave address not populated for node '${nodeType}' after ensureArweaveKey`
+      );
+    }
+    return { signer, token: canonical, address: keys.arweaveAddress };
+  }
+  throw new Error(`Unsupported TurboTokenId: ${String(token)}`);
+}
+
+// src/credits/units.ts
+var WINC_PER_BYTE_APPROX = 610000n;
+function wincToBytes(winc) {
+  if (winc < 0n) return 0n;
+  return winc / WINC_PER_BYTE_APPROX;
+}
+function formatWincAsBytes(winc) {
+  const bytes = wincToBytes(winc);
+  if (bytes < 1000n) return `~${bytes.toString()} B`;
+  if (bytes < 1000000n) {
+    return `~${(bytes / 1000n).toString()} KB`;
+  }
+  if (bytes < 1000000000n) {
+    return `~${(bytes / 1000000n).toString()} MB`;
+  }
+  if (bytes < 1000000000000n) {
+    return `~${(bytes / 1000000000n).toString()} GB`;
   }
+  return `~${(bytes / 1000000000000n).toString()} TB`;
+}
+var TOKEN_DECIMALS = {
+  ar: 12,
+  sol: 9,
+  eth: 18,
+  pol: 18,
+  "base-eth": 18,
+  "base-usdc": 6,
+  "usdc-eth": 6,
+  "usdc-pol": 6
+};
+var TOKEN_SYMBOL = {
+  ar: "AR",
+  sol: "SOL",
+  eth: "ETH",
+  pol: "POL",
+  "base-eth": "ETH (Base)",
+  "base-usdc": "USDC (Base)",
+  "usdc-eth": "USDC (Ethereum)",
+  "usdc-pol": "USDC (Polygon)"
 };
+function formatTokenAmount(token, baseAmount) {
+  const decimals = TOKEN_DECIMALS[token];
+  const symbol = TOKEN_SYMBOL[token];
+  if (decimals === void 0 || symbol === void 0) {
+    throw new Error(`Unknown TurboTokenId for formatting: ${String(token)}`);
+  }
+  const scale = 10n ** BigInt(decimals);
+  const isNegative = baseAmount < 0n;
+  const abs = isNegative ? -baseAmount : baseAmount;
+  const whole = abs / scale;
+  const frac = abs % scale;
+  const fracStr = frac.toString().padStart(decimals, "0");
+  const sign = isNegative ? "-" : "";
+  return `${sign}${whole.toString()}.${fracStr} ${symbol}`;
+}
+function parseTokenAmount(token, decimal) {
+  const decimals = TOKEN_DECIMALS[token];
+  if (decimals === void 0) {
+    throw new Error(`Unknown TurboTokenId: ${String(token)}`);
+  }
+  const trimmed = decimal.trim();
+  if (!/^\d+(\.\d+)?$/.test(trimmed)) {
+    throw new Error(
+      `Invalid decimal amount '${decimal}' for token '${token}'. Use plain decimal notation (e.g. "0.05").`
+    );
+  }
+  const [wholeStr, fracStr = ""] = trimmed.split(".");
+  if (fracStr.length > decimals) {
+    throw new Error(
+      `Amount '${decimal}' has ${fracStr.length} decimal places, but '${token}' supports at most ${decimals}.`
+    );
+  }
+  const fracPadded = fracStr.padEnd(decimals, "0");
+  const whole = BigInt(wholeStr);
+  const frac = fracPadded.length > 0 ? BigInt(fracPadded) : 0n;
+  return whole * 10n ** BigInt(decimals) + frac;
+}
+
+// src/credits/buy.ts
+async function buyCredits(opts) {
+  const {
+    wallet,
+    nodeType,
+    token,
+    amount,
+    feeMultiplier,
+    quoteOnly,
+    destinationAddress
+  } = opts;
+  const baseAmount = parseTokenAmount(token, amount);
+  const {
+    signer,
+    token: canonicalToken,
+    address: fromAddress
+  } = await buildTurboSigner(wallet, nodeType, token);
+  const creditAddress = destinationAddress ?? fromAddress;
+  const turbo = TurboFactory.authenticated({
+    signer,
+    token: canonicalToken
+  });
+  const quote = await turbo.getWincForToken({
+    tokenAmount: baseAmount.toString()
+  });
+  const quotedWinc = BigInt(quote.winc);
+  if (quoteOnly) {
+    return {
+      kind: "quote",
+      fromAddress,
+      creditAddress,
+      baseAmount,
+      winc: quotedWinc,
+      raw: {
+        winc: quote.winc,
+        actualTokenAmount: quote.actualTokenAmount,
+        equivalentWincTokenAmount: quote.equivalentWincTokenAmount
+      }
+    };
+  }
+  const topUpParams = {
+    tokenAmount: baseAmount.toString()
+  };
+  if (feeMultiplier !== void 0) topUpParams.feeMultiplier = feeMultiplier;
+  if (destinationAddress !== void 0) {
+    topUpParams.turboCreditDestinationAddress = destinationAddress;
+  }
+  const submitted = await turbo.topUpWithTokens(topUpParams);
+  return {
+    kind: "submit",
+    fromAddress,
+    creditAddress,
+    baseAmount,
+    winc: BigInt(submitted.winc),
+    id: submitted.id,
+    status: submitted.status,
+    token: submitted.token,
+    ...submitted.block !== void 0 ? { block: submitted.block } : {}
+  };
+}
+
+// src/credits/balance.ts
+import { TurboFactory as TurboFactory2 } from "@ardrive/turbo-sdk/node";
+async function getCreditBalance(opts) {
+  const { wallet, nodeType, token, address: explicitAddress } = opts;
+  const {
+    signer,
+    token: canonicalToken,
+    address: signerAddress
+  } = await buildTurboSigner(wallet, nodeType, token);
+  const turbo = TurboFactory2.authenticated({
+    signer,
+    token: canonicalToken
+  });
+  const balance = explicitAddress ? await turbo.getBalance(explicitAddress) : await turbo.getBalance();
+  return {
+    winc: BigInt(balance.winc),
+    controlledWinc: BigInt(balance.controlledWinc),
+    effectiveBalance: BigInt(balance.effectiveBalance),
+    address: explicitAddress ?? signerAddress
+  };
+}
+
+// src/tui/tty-detect.ts
+function isOptOut(value) {
+  if (value === void 0) return false;
+  if (value === "" || value === "0" || value.toLowerCase() === "false")
+    return false;
+  return true;
+}
+function shouldRenderInk() {
+  if (process.stdout.isTTY !== true) return false;
+  if (process.env["CI"] === "true") return false;
+  if (isOptOut(process.env["NO_TUI"])) return false;
+  if ((process.env["TERM"] ?? "") === "dumb") return false;
+  return true;
+}
 
 // src/cli.ts
 var CliHelpRequested = class extends Error {
@@ -93,18 +1992,36 @@ Usage:
   townhouse down [-c <path>]                     Stop all nodes
   townhouse status [-c <path>]                   Show node status
   townhouse metrics [-c <path>]                  Show connector metrics
-  townhouse wallet show [-c <path>] [--password <pw>]  Show derived addresses
+  townhouse wallet show [--json] [--hex] [--paths] [-c <path>] [--password <pw>]  Show derived addresses
+  townhouse wallet seed --confirm [-c <path>] [--password <pw>]    Print the BIP-39 seed phrase (password-gated, requires --confirm)
+  townhouse credits buy --token <id> --amount <decimal> [--fee-multiplier <n>] [--quote-only] [--yes] [-c <path>] [--password <pw>]
+                                                 Buy Arweave upload credits (token: eth|sol|pol|base-eth|base-usdc|usdc-eth|usdc-pol)
+  townhouse credits balance --token <id> [-c <path>] [--password <pw>]  Show Turbo credit balance for the funding address
+  townhouse hs up [--password <pw>] [--skip-preflight] [-c <path>]  Boot apex (connector + .anyone HS) (launches dashboard TUI in TTY mode)
+  townhouse hs down [--rotate-keys] [-c <path>]               Stop apex (--rotate-keys deletes .anyone keypair)
+  townhouse node add [<type>] [--json] [-c <path>]    Provision a child node (default: town)
+  townhouse node remove <id> [--yes] [--json] [-c <path>]   Deprovision a child node
+  townhouse node list [--json] [-c <path>]            List provisioned nodes
+  townhouse channels [--json]                    Show open payment channels
+  townhouse logs <node-id> [-f|--follow] [--lines N] [--json]   Tail logs for a node (Ctrl-C to stop)
+  townhouse peer <id> [--json]                   Show per-peer detail card
+  townhouse health [--json]                      Probe apex/api/nodes/.anyone health
   townhouse --help                               Show this help
 
 Flags:
-  --town       Start Town (Nostr relay) node
-  --mill       Start Mill (swap) node
-  --dvm        Start DVM (compute) node
-  --password   Wallet password (non-interactive mode)
-  --no-browser Skip opening the browser automatically (setup command)
-  --port       Override the API port (setup command, default 9400)
-  --preset     Init from a named preset (init only). Supported: demo
-  --yes        Non-interactive (init only); with --preset=demo uses demo password if --password absent
+  --town         Start Town (Nostr relay) node
+  --mill         Start Mill (swap) node
+  --dvm          Start DVM (compute) node
+  --password     Wallet password (non-interactive mode)
+  --rotate-keys  Delete the .anyone keypair volume on hs down (produces a new address on next hs up)
+  --skip-preflight  Skip the port-collision preflight check on hs up (escape hatch)
+  --no-browser   Skip opening the browser automatically (setup command)
+  --port         Override the API port (setup command, default 9400)
+  --preset       Init from a named preset (init only). Supported: demo
+  --yes          Non-interactive (init only); with --preset=demo uses demo password if --password absent
+  --json         Machine-readable JSON output (node commands; NDJSON for \`logs\`)
+  --lines        Number of historical log lines to fetch on attach (logs command, default 50)
+  -f|--follow    Accepted for \`tail -f\` muscle memory on \`logs\` (no-op \u2014 follow is default)
   If no flags given, starts all enabled nodes from config.`;
 var DEFAULT_CONFIG_DIR = join(homedir(), ".townhouse");
 var DEFAULT_CONFIG_PATH = join(DEFAULT_CONFIG_DIR, "config.yaml");
@@ -121,7 +2038,7 @@ async function handleInit(force, configDir, password, preset, yes) {
   mkdirSync(dir, { recursive: true, mode: 448 });
   let configToWrite;
   if (preset === "demo") {
-    const { buildDemoConfig, DEMO_DETERMINISTIC_PASSWORD } = await import("./demo-MJR47QHZ.js");
+    const { buildDemoConfig, DEMO_DETERMINISTIC_PASSWORD } = await import("./demo-3DWRDMYY.js");
     configToWrite = buildDemoConfig({ walletPath: join(dir, "wallet.enc") });
     if (yes && !password) {
       password = DEMO_DETERMINISTIC_PASSWORD;
@@ -194,7 +2111,7 @@ Delete the orphan config and re-run \`townhouse setup\`, or restore the wallet f
     process.exitCode = 1;
     return;
   }
-  const docker = dockerInstance ?? new Docker();
+  const docker = dockerInstance ?? new Docker2();
   const opener = browserOpener ?? new RealBrowserOpener();
   const wizardServer = await createWizardApiServer({
     configDir: dir,
@@ -244,7 +2161,207 @@ Received ${sig}, shutting down...`);
     void shutdown("SIGTERM");
   });
 }
-async function handleWalletShow(config, password) {
+var NODE_ROLE_DESCRIPTIONS = {
+  town: "Nostr relay \u2014 earns ILP fees per event relayed.",
+  mill: "Multi-chain swap peer \u2014 settles cross-chain swaps for fees.",
+  dvm: "Compute / DVM worker \u2014 collects job payments, signs Arweave uploads."
+};
+function buildNodeRows(info, options) {
+  const rows = [];
+  const npub = nip19.npubEncode(info.nostrPubkey);
+  const nostrPurposeByNode = {
+    town: "share this to be found",
+    mill: "announces swap quotes",
+    dvm: "offers DVM services"
+  };
+  rows.push({
+    label: "Nostr",
+    value: npub,
+    purpose: nostrPurposeByNode[info.nodeType],
+    hex: options.hex ? info.nostrPubkey : void 0,
+    path: options.paths ? info.nostrDerivationPath : void 0
+  });
+  const evmPurposeByNode = {
+    town: "receives ILP earnings",
+    mill: "settles EVM swaps",
+    dvm: "collects job payments"
+  };
+  rows.push({
+    label: "EVM",
+    value: info.evmAddress,
+    purpose: evmPurposeByNode[info.nodeType],
+    path: options.paths ? info.evmDerivationPath : void 0
+  });
+  const solPurposeByNode = {
+    town: "receives swap fills",
+    mill: "settles SOL swaps",
+    dvm: "spends Arweave credits"
+  };
+  rows.push({
+    label: "SOL",
+    value: info.solanaAddress ?? "\u2014",
+    purpose: solPurposeByNode[info.nodeType],
+    path: options.paths ? info.solanaDerivationPath : void 0
+  });
+  if (info.nodeType === "mill") {
+    rows.push({
+      label: "Mina",
+      value: info.minaAddress ?? "\u2014",
+      purpose: "settles Mina swaps"
+      // Mina derivation path is not currently surfaced through NodeKeyInfo.
+    });
+  }
+  if (info.nodeType === "dvm") {
+    rows.push({
+      label: "AR",
+      value: info.arweaveAddress ?? "\u2014",
+      purpose: "signs Arweave uploads",
+      path: options.paths ? info.arweaveDerivationPath : void 0
+    });
+  }
+  return rows;
+}
+function renderNodeCard(info, rows) {
+  const role = NODE_ROLE_DESCRIPTIONS[info.nodeType];
+  const labelWidth = Math.max(...rows.map((r) => r.label.length));
+  const headerLine = `${info.nodeType.toUpperCase()} \u2014 ${role}`;
+  const bodyLines = [];
+  for (const row of rows) {
+    bodyLines.push(`${row.label.padEnd(labelWidth)}  ${row.value}`);
+    bodyLines.push(`${" ".repeat(labelWidth)}    (${row.purpose})`);
+    if (row.hex) {
+      bodyLines.push(`${" ".repeat(labelWidth)}    hex: ${row.hex}`);
+    }
+    if (row.path) {
+      bodyLines.push(`${" ".repeat(labelWidth)}    path: ${row.path}`);
+    }
+  }
+  const innerWidth = Math.max(
+    headerLine.length,
+    ...bodyLines.map((l) => l.length)
+  );
+  const totalInner = innerWidth + 2;
+  const horizontal = "\u2500".repeat(totalInner);
+  const top = `\u250C${horizontal}\u2510`;
+  const bottom = `\u2514${horizontal}\u2518`;
+  const lines = [];
+  lines.push(top);
+  lines.push(`\u2502 ${headerLine.padEnd(innerWidth)} \u2502`);
+  lines.push(`\u251C${horizontal}\u2524`);
+  for (const body of bodyLines) {
+    lines.push(`\u2502 ${body.padEnd(innerWidth)} \u2502`);
+  }
+  lines.push(bottom);
+  return lines.join("\n");
+}
+function buildWalletJson(allKeys) {
+  const out = {};
+  for (const info of allKeys) {
+    const node = {
+      nostr: {
+        npub: nip19.npubEncode(info.nostrPubkey),
+        hex: info.nostrPubkey,
+        path: info.nostrDerivationPath
+      },
+      evm: { address: info.evmAddress, path: info.evmDerivationPath }
+    };
+    if (info.solanaAddress) {
+      node["sol"] = {
+        address: info.solanaAddress,
+        path: info.solanaDerivationPath
+      };
+    }
+    if (info.nodeType === "mill" && info.minaAddress) {
+      node["mina"] = { address: info.minaAddress };
+    }
+    if (info.nodeType === "dvm" && info.arweaveAddress) {
+      node["arweave"] = {
+        address: info.arweaveAddress,
+        path: info.arweaveDerivationPath
+      };
+    }
+    out[info.nodeType] = node;
+  }
+  return out;
+}
+async function handleWalletShow(config, password, options = {}) {
+  const walletPath = config.wallet.encrypted_path;
+  const result = await loadWallet(walletPath);
+  if (!result) {
+    console.error("No wallet found. Run `townhouse init` first.");
+    process.exitCode = 1;
+    return;
+  }
+  if (result.permissionsWarning) {
+    console.error(result.permissionsWarning);
+  }
+  const walletPassword = password ?? process.env["TOWNHOUSE_WALLET_PASSWORD"];
+  if (!walletPassword) {
+    console.error(
+      "Wallet password required. Use --password flag or TOWNHOUSE_WALLET_PASSWORD env var."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const walletManager = new WalletManager({ encryptedPath: walletPath });
+  try {
+    await walletManager.fromMnemonic(
+      decryptWallet(result.wallet, walletPassword)
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Failed to decrypt wallet: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const arStartMs = Date.now();
+    const arStatusTimer = setTimeout(() => {
+      process.stderr.write("deriving Arweave key (first run, ~15s)...\n");
+    }, 200);
+    try {
+      await walletManager.ensureArweaveKey("dvm", walletPassword);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `Warning: Arweave key derivation failed (${msg}). AR address will display as '\u2014'.`
+      );
+    } finally {
+      clearTimeout(arStatusTimer);
+      void arStartMs;
+    }
+    const allKeys = walletManager.getAllKeys();
+    if (options.json) {
+      console.log(JSON.stringify(buildWalletJson(allKeys), null, 2));
+      return;
+    }
+    const renderOpts = {
+      hex: options.hex === true,
+      paths: options.paths === true
+    };
+    for (const info of allKeys) {
+      const rows = buildNodeRows(info, renderOpts);
+      console.log(renderNodeCard(info, rows));
+      console.log("");
+    }
+    console.log("Tip: townhouse wallet show --json   for scripting");
+    console.log("     townhouse wallet show --hex    to see raw hex pubkeys");
+    console.log("     townhouse wallet show --paths  to see derivation paths");
+    console.log(
+      "     townhouse credits buy --token sol --amount <n>  to fund Arweave uploads"
+    );
+  } finally {
+    walletManager.lock();
+  }
+}
+async function handleWalletSeed(config, password, confirm) {
+  if (!confirm) {
+    console.error(
+      "This command will print your seed phrase to your terminal. Re-run with --confirm to acknowledge."
+    );
+    process.exitCode = 1;
+    return;
+  }
   const walletPath = config.wallet.encrypted_path;
   const result = await loadWallet(walletPath);
   if (!result) {
@@ -252,44 +2369,354 @@ async function handleWalletShow(config, password) {
     process.exitCode = 1;
     return;
   }
-  if (result.permissionsWarning) {
-    console.error(result.permissionsWarning);
+  if (result.permissionsWarning) {
+    console.error(result.permissionsWarning);
+  }
+  const walletPassword = password ?? process.env["TOWNHOUSE_WALLET_PASSWORD"];
+  if (!walletPassword) {
+    console.error(
+      "Wallet password required. Use --password flag or TOWNHOUSE_WALLET_PASSWORD env var."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const walletManager = new WalletManager({ encryptedPath: walletPath });
+  try {
+    await walletManager.fromMnemonic(
+      decryptWallet(result.wallet, walletPassword)
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Failed to decrypt wallet: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const mnemonic = walletManager.getMnemonic();
+    if (!mnemonic) {
+      console.error("Internal error: mnemonic unavailable after unlock.");
+      process.exitCode = 1;
+      return;
+    }
+    console.log(
+      "============================================================="
+    );
+    console.log(" [!] Anyone who sees this seed owns your townhouse identity.");
+    console.log(" [!] Anyone who records this terminal owns your earnings.");
+    console.log(
+      " [!] Shoulder-surf, screen-shares, and tmux logs are vectors."
+    );
+    console.log(
+      "============================================================="
+    );
+    console.log("");
+    console.log("");
+    console.log(`  ${mnemonic}`);
+    console.log("");
+    console.log("");
+    console.log(
+      "This is the same 12 words shown at `townhouse init`. Storing them elsewhere is your responsibility."
+    );
+  } finally {
+    walletManager.lock();
+  }
+}
+var VALID_TURBO_TOKENS = /* @__PURE__ */ new Set([
+  "eth",
+  "pol",
+  "base-eth",
+  "base-usdc",
+  "usdc-eth",
+  "usdc-pol",
+  "sol",
+  "ar"
+]);
+function isTurboTokenId(value) {
+  return VALID_TURBO_TOKENS.has(value);
+}
+async function resolveWalletPassword(flagPassword) {
+  const envPassword = process.env["TOWNHOUSE_WALLET_PASSWORD"];
+  if (flagPassword) return flagPassword;
+  if (envPassword) return envPassword;
+  if (process.stdin.isTTY) {
+    return await promptPassword("Wallet password: ");
+  }
+  return null;
+}
+async function promptYesNo(question) {
+  const { createInterface: createInterface3 } = await import("readline");
+  const answer = await new Promise((resolve2) => {
+    const rl = createInterface3({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(question, (ans) => {
+      rl.close();
+      resolve2(ans);
+    });
+  });
+  return ["y", "yes"].includes(answer.trim().toLowerCase());
+}
+async function handleCreditsBuy(config, values, nodeType = "dvm") {
+  const tokenRaw = values["token"];
+  const amountRaw = values["amount"];
+  if (!tokenRaw || !amountRaw) {
+    console.error(
+      "Usage: townhouse credits buy --token <id> --amount <decimal> [--fee-multiplier <n>] [--credit-destination <addr>] [--quote-only] [--yes]"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!isTurboTokenId(tokenRaw)) {
+    console.error(
+      `Unknown token '${tokenRaw}'. Supported: ${Array.from(VALID_TURBO_TOKENS).join(", ")}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const token = tokenRaw;
+  let feeMultiplier;
+  const feeRaw = values["fee-multiplier"];
+  if (feeRaw !== void 0) {
+    const parsed = Number(feeRaw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      console.error(
+        `--fee-multiplier must be a positive number, got '${feeRaw}'`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    feeMultiplier = parsed;
+  }
+  const quoteOnly = values["quote-only"] === true;
+  const skipConfirm = values["yes"] === true;
+  const destinationOverride = values["credit-destination"];
+  const walletPath = config.wallet.encrypted_path;
+  const loaded = await loadWallet(walletPath);
+  if (!loaded) {
+    console.error(
+      `No wallet found at ${walletPath}. Run \`townhouse init\` first.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (loaded.permissionsWarning) console.error(loaded.permissionsWarning);
+  const resolvedPassword = await resolveWalletPassword(
+    values["password"]
+  );
+  if (!resolvedPassword) {
+    console.error(
+      "Wallet password required. Use --password flag or TOWNHOUSE_WALLET_PASSWORD env var."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const wallet = new WalletManager({ encryptedPath: walletPath });
+  try {
+    await wallet.fromMnemonic(decryptWallet(loaded.wallet, resolvedPassword));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Failed to decrypt wallet: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    let destinationAddress;
+    if (destinationOverride) {
+      destinationAddress = destinationOverride;
+    } else if (token !== "ar" && nodeType === "dvm") {
+      process.stdout.write(
+        `Resolving DVM Arweave credit address (first run, ~10s)...
+`
+      );
+      await wallet.ensureArweaveKey("dvm", resolvedPassword);
+      const dvmKeys = wallet.getNodeKeys("dvm");
+      if (!dvmKeys.arweaveAddress) {
+        throw new Error(
+          "DVM Arweave address not populated after ensureArweaveKey"
+        );
+      }
+      destinationAddress = dvmKeys.arweaveAddress;
+    }
+    process.stdout.write(
+      `Quoting ${amountRaw} ${token} for ${nodeType}'s credit address...
+`
+    );
+    const quote = await buyCredits({
+      wallet,
+      nodeType,
+      token,
+      amount: amountRaw,
+      quoteOnly: true,
+      ...destinationAddress ? { destinationAddress } : {}
+    });
+    if (quote.kind !== "quote") {
+      throw new Error("Internal error: quoteOnly returned non-quote result");
+    }
+    const quotedDisplay = `${quote.winc.toString()} winc (${formatWincAsBytes(quote.winc)})`;
+    process.stdout.write(
+      `Quote: ${formatTokenAmount(token, quote.baseAmount)} \u2192 ${quotedDisplay}
+`
+    );
+    process.stdout.write(`Source address (${token}): ${quote.fromAddress}
+`);
+    process.stdout.write(`Credit recipient: ${quote.creditAddress}
+`);
+    if (quoteOnly) {
+      process.stdout.write("Quote-only; no on-chain transaction submitted.\n");
+      return;
+    }
+    if (!skipConfirm) {
+      const ok = await promptYesNo("Proceed? [y/N] ");
+      if (!ok) {
+        process.stdout.write("Aborted. No transaction submitted.\n");
+        process.exitCode = 1;
+        return;
+      }
+    }
+    process.stdout.write("Submitting on-chain transaction...\n");
+    const result = await buyCredits({
+      wallet,
+      nodeType,
+      token,
+      amount: amountRaw,
+      ...feeMultiplier !== void 0 ? { feeMultiplier } : {},
+      ...destinationAddress ? { destinationAddress } : {}
+    });
+    if (result.kind !== "submit") {
+      throw new Error("Internal error: submit path returned non-submit result");
+    }
+    process.stdout.write(`Transaction submitted: ${result.id}
+`);
+    process.stdout.write(`Status: ${result.status}
+`);
+    process.stdout.write(
+      `Credited: ${result.winc.toString()} winc (${formatWincAsBytes(result.winc)})
+`
+    );
+    if (result.block !== void 0) {
+      process.stdout.write(`Block: ${result.block}
+`);
+    }
+    process.stdout.write("Done.\n");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`credits buy failed: ${msg}`);
+    process.exitCode = 1;
+  } finally {
+    wallet.lock();
+  }
+}
+async function handleCreditsBalance(config, values, nodeType = "dvm") {
+  const tokenRaw = values["token"];
+  if (!tokenRaw) {
+    console.error(
+      "Usage: townhouse credits balance --token <id> [-c <path>] [--password <pw>]"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!isTurboTokenId(tokenRaw)) {
+    console.error(
+      `Unknown token '${tokenRaw}'. Supported: ${Array.from(VALID_TURBO_TOKENS).join(", ")}`
+    );
+    process.exitCode = 1;
+    return;
   }
-  const walletPassword = password ?? process.env["TOWNHOUSE_WALLET_PASSWORD"];
-  if (!walletPassword) {
+  const token = tokenRaw;
+  const walletPath = config.wallet.encrypted_path;
+  const loaded = await loadWallet(walletPath);
+  if (!loaded) {
+    console.error(
+      `No wallet found at ${walletPath}. Run \`townhouse init\` first.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (loaded.permissionsWarning) console.error(loaded.permissionsWarning);
+  const resolvedPassword = await resolveWalletPassword(
+    values["password"]
+  );
+  if (!resolvedPassword) {
     console.error(
       "Wallet password required. Use --password flag or TOWNHOUSE_WALLET_PASSWORD env var."
     );
     process.exitCode = 1;
     return;
   }
-  const walletManager = new WalletManager({ encryptedPath: walletPath });
+  const wallet = new WalletManager({ encryptedPath: walletPath });
   try {
-    await walletManager.fromMnemonic(
-      decryptWallet(result.wallet, walletPassword)
-    );
+    await wallet.fromMnemonic(decryptWallet(loaded.wallet, resolvedPassword));
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Failed to decrypt wallet: ${msg}`);
     process.exitCode = 1;
     return;
   }
-  console.log(
-    "Node Type  | Nostr Pubkey                                                     | EVM Address                                | Derivation Path"
-  );
-  console.log(
-    "-----------|------------------------------------------------------------------|--------------------------------------------|--------------------------"
-  );
-  const allKeys = walletManager.getAllKeys();
-  for (const info of allKeys) {
-    console.log(
-      `${info.nodeType.padEnd(10)} | ${info.nostrPubkey} | ${info.evmAddress} | ${info.nostrDerivationPath}`
+  try {
+    const balance = await getCreditBalance({ wallet, nodeType, token });
+    process.stdout.write(`Address (${token}): ${balance.address}
+`);
+    process.stdout.write(
+      `Balance: ${balance.winc.toString()} winc (${formatWincAsBytes(balance.winc)})
+`
     );
+    if (balance.effectiveBalance !== balance.winc) {
+      process.stdout.write(
+        `Effective (incl. received approvals): ${balance.effectiveBalance.toString()} winc (${formatWincAsBytes(balance.effectiveBalance)})
+`
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`credits balance failed: ${msg}`);
+    process.exitCode = 1;
+  } finally {
+    wallet.lock();
   }
-  walletManager.lock();
 }
-async function handleStatus(docker, config) {
-  const orchestrator = new DockerOrchestrator(docker, config);
+async function resolveEarnings(adminUrl, configPath) {
+  const base = dirname(configPath);
+  try {
+    const yaml = await readNodesYaml(join(base, "nodes.yaml"));
+    return await aggregateEarnings({
+      connectorAdmin: new ConnectorAdminClient(adminUrl),
+      peerTypeResolver: new PeerTypeResolver(yaml),
+      deltaComputer: createDeltaComputer({
+        snapshotPath: join(base, "earnings-snapshots.jsonl")
+      })
+    });
+  } catch (err) {
+    console.error(`Earnings unavailable: ${formatLocalEarningsError(err)}`);
+    return {
+      status: "connector_unavailable",
+      apex: { routingFees: {} },
+      peers: [],
+      recentClaims: [],
+      eventsRelayed: 0,
+      uptimeSeconds: 0
+    };
+  }
+}
+function formatLocalEarningsError(err) {
+  if (err !== null && typeof err === "object" && "issues" in err && Array.isArray(err.issues)) {
+    const issues = err.issues;
+    const parts = issues.map((i) => {
+      const path = Array.isArray(i.path) && i.path.length > 0 ? i.path.join(".") : "<root>";
+      const msg = typeof i.message === "string" ? i.message : "invalid";
+      return `${path}: ${msg}`;
+    }).join("; ");
+    if (parts) return parts;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+async function handleStatus(docker, config, opts = {
+  units: "usdc",
+  configPath: DEFAULT_CONFIG_PATH
+}) {
+  const orchestrator = new DockerOrchestrator(docker, config, void 0, {
+    profile: "dev"
+  });
   const statuses = await orchestrator.status();
   console.log("Node Status:");
   console.log("------------");
@@ -330,37 +2757,17 @@ async function handleStatus(docker, config) {
     console.log("");
     console.log("Connector Metrics: unavailable");
   }
-}
-async function handleMetrics(config) {
-  const adminClient = new ConnectorAdminClient(
-    `http://127.0.0.1:${config.connector.adminPort}`
+  if (opts.units === "sats" && opts.satsPerUsdc === void 0) return;
+  const earnings = await resolveEarnings(
+    `http://127.0.0.1:${config.connector.adminPort}`,
+    opts.configPath
   );
-  try {
-    const metrics = await adminClient.getMetrics();
-    const peers = await adminClient.getPeers();
-    const peerMetrics = new Map(metrics.peers.map((p) => [p.peerId, p]));
-    console.log("Connector Metrics:");
-    console.log("------------------");
-    console.log(`  Packets forwarded: ${metrics.aggregate.packetsForwarded}`);
-    console.log(`  Packets rejected:  ${metrics.aggregate.packetsRejected}`);
-    console.log(`  Bytes sent:        ${metrics.aggregate.bytesSent}`);
-    console.log("");
-    console.log("Peers:");
-    console.log("------");
-    if (peers.length === 0) {
-      console.log("  No peers connected");
-    } else {
-      for (const peer of peers) {
-        const status = peer.connected ? "connected" : "disconnected";
-        const packets = peerMetrics.get(peer.id)?.packetsForwarded ?? 0;
-        console.log(`  ${peer.id.padEnd(12)} ${status}  (${packets} packets)`);
-      }
-    }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    console.error(`Failed to fetch connector metrics: ${msg}`);
-    process.exitCode = 1;
-  }
+  for (const line of renderEarningsSection({
+    earnings,
+    units: opts.units,
+    satsPerUsdc: opts.satsPerUsdc
+  }))
+    console.log(line);
 }
 function resolveProfiles(values, config) {
   const explicitFlags = [];
@@ -414,8 +2821,20 @@ async function handleUp(configPath, config, profiles, docker, password, dryRun =
       const msg = err instanceof Error ? err.message : String(err);
       throw new Error(`Failed to decrypt wallet: ${msg}`);
     }
+    if (profiles.includes("dvm")) {
+      try {
+        await walletManager.ensureArweaveKey("dvm", walletPassword);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `[townhouse up] AR pre-warm failed (non-fatal, orchestrator will retry): ${msg}`
+        );
+      }
+    }
   }
-  const orchestrator = new DockerOrchestrator(docker, config, walletManager);
+  const orchestrator = new DockerOrchestrator(docker, config, walletManager, {
+    profile: "dev"
+  });
   orchestrator.on(
     "containerState",
     (event) => {
@@ -534,7 +2953,9 @@ async function handleUp(configPath, config, profiles, docker, password, dryRun =
   }
 }
 async function handleDown(config, docker) {
-  const orchestrator = new DockerOrchestrator(docker, config);
+  const orchestrator = new DockerOrchestrator(docker, config, void 0, {
+    profile: "dev"
+  });
   orchestrator.on(
     "containerState",
     (event) => {
@@ -545,7 +2966,434 @@ async function handleDown(config, docker) {
   await orchestrator.down();
   console.log("All nodes stopped.");
 }
-async function main(argv, dockerInstance, browserOpener) {
+var HS_CONNECTOR_ADMIN_URL = "http://127.0.0.1:9401";
+var HS_TOWNHOUSE_API_URL = "http://127.0.0.1:28090";
+async function reconcileWithBriefRetry(reconciler, budgetMs) {
+  const deadline = Date.now() + budgetMs;
+  for (; ; ) {
+    try {
+      await reconciler.reconcile();
+      return;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const transient = msg.includes("ECONNREFUSED") || msg.includes("connection refused") || msg.includes("request timeout");
+      if (!transient || Date.now() >= deadline) {
+        throw err;
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, 250));
+    }
+  }
+}
+async function collectApexImageRefs(configDir) {
+  const manifestPath = join(configDir, "image-manifest.json");
+  if (!existsSync(manifestPath)) return [];
+  try {
+    const manifest = await readImageManifest(manifestPath);
+    if (isSyntheticDigest(manifest.images.connector.digest) || isSyntheticDigest(manifest.images["townhouse-api"].digest)) {
+      return [];
+    }
+    return [
+      `${manifest.images.connector.name}@${manifest.images.connector.digest}`,
+      `${manifest.images["townhouse-api"].name}@${manifest.images["townhouse-api"].digest}`
+    ];
+  } catch {
+    return [];
+  }
+}
+function isAnonBootstrapTimeout(err) {
+  if (!(err instanceof OrchestratorError)) return false;
+  const text = `${err.message}
+${err.stderr ?? ""}`;
+  return /connector.*unhealthy|dependency.*connector.*fail/i.test(text);
+}
+async function handleHsUp(_configPath, configDir, config, docker, options) {
+  const { password, force, skipPreflight, hsOverrides } = options;
+  if (!skipPreflight) {
+    const preflight = hsOverrides?.checkPortCollisions ?? ((d) => checkHsPortCollisions(d));
+    try {
+      const collisions = await preflight(docker);
+      if (collisions.length > 0) {
+        const msg = formatCollisionMessage(collisions);
+        process.stderr.write(msg);
+        process.exitCode = 1;
+        return;
+      }
+    } catch (preflightErr) {
+      const detail = preflightErr instanceof Error ? preflightErr.message : String(preflightErr);
+      console.error(
+        `[townhouse hs up] port preflight skipped (non-fatal): ${detail}`
+      );
+    }
+  }
+  const walletPath = config.wallet.encrypted_path;
+  if (!existsSync(walletPath)) {
+    console.error(
+      `Wallet not found at ${walletPath}. Run \`townhouse init\` first.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const walletPassword = password ?? process.env["TOWNHOUSE_WALLET_PASSWORD"];
+  let resolvedPassword;
+  if (walletPassword) {
+    resolvedPassword = walletPassword;
+  } else if (process.stdin.isTTY) {
+    resolvedPassword = await promptPassword("Wallet password: ");
+  } else {
+    console.error(
+      "Wallet password required. Use --password flag or TOWNHOUSE_WALLET_PASSWORD env var."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const loaded = await loadWallet(walletPath);
+  if (!loaded) {
+    console.error(`Wallet at ${walletPath} could not be read.`);
+    process.exitCode = 1;
+    return;
+  }
+  let walletManager;
+  try {
+    walletManager = new WalletManager({ encryptedPath: walletPath });
+    await walletManager.fromMnemonic(
+      decryptWallet(loaded.wallet, resolvedPassword)
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Failed to decrypt wallet: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  const ribbon = new OnboardingRibbon();
+  try {
+    if (!force) {
+      const adminClientFactory = hsOverrides?.createAdminClient ?? ((url, t) => new ConnectorAdminClient(url, t));
+      const probe = adminClientFactory(HS_CONNECTOR_ADMIN_URL, 3e3);
+      try {
+        const existing = await probe.getHsHostname();
+        if (existing.hostname !== null) {
+          console.log(`Apex live at ${existing.hostname}`);
+          _writeHostJson(configDir, {
+            hostname: existing.hostname,
+            publishedAt: existing.publishedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+            writtenAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          return;
+        }
+      } catch (probeErr) {
+        const msg = probeErr instanceof Error ? probeErr.message : String(probeErr);
+        if (msg.includes("anon-disabled")) {
+          const { exitCode } = renderFailure(probeErr);
+          process.exitCode = exitCode;
+          return;
+        }
+      }
+    }
+    writeHsConnectorConfig(configDir, config, { force });
+    const materialize = hsOverrides?.materializeComposeTemplate ?? materializeComposeTemplate;
+    const { composePath } = materialize("hs", { townhouseHome: configDir });
+    ribbon.start("pull");
+    const orchestratorFactory = hsOverrides?.createOrchestrator ?? ((d, cfg, wm, opts) => new DockerOrchestrator(d, cfg, wm, opts));
+    const orch = orchestratorFactory(docker, config, walletManager, {
+      profile: "hs",
+      composePath
+    });
+    const narrator = new PullNarrator();
+    orch.on("pullProgress", (event) => {
+      const ev = event;
+      if (!ev.image || !ev.status) return;
+      const line = narrator.format({
+        image: ev.image,
+        status: ev.status,
+        id: ev.id,
+        progress: ev.progress
+      });
+      if (line !== null) console.log(line);
+    });
+    let bootstrapStarted = false;
+    orch.on("containerState", (event) => {
+      const ev = event;
+      if (!bootstrapStarted && (ev.state === "creating" || ev.state === "starting")) {
+        bootstrapStarted = true;
+        ribbon.start("bootstrap");
+      }
+    });
+    if (typeof orch.pullImage === "function") {
+      try {
+        const apexImages = await collectApexImageRefs(configDir);
+        if (apexImages.length > 0) {
+          console.log(
+            `Pulling ${apexImages.length} apex ${apexImages.length === 1 ? "image" : "images"}...`
+          );
+          let pulled = 0;
+          for (const ref of apexImages) {
+            pulled++;
+            console.log(`  [${pulled}/${apexImages.length}] ${ref}`);
+            await orch.pullImage(ref);
+          }
+        }
+      } catch (pullErr) {
+        const detail = pullErr instanceof Error ? pullErr.message : String(pullErr);
+        console.error(
+          `[townhouse hs up] pre-pull skipped (non-fatal, compose will retry): ${detail}`
+        );
+      }
+    }
+    let dockerSockGid = 0;
+    try {
+      dockerSockGid = statSync("/var/run/docker.sock").gid;
+    } catch {
+    }
+    const prevTownhouseHome = process.env["TOWNHOUSE_HOME"];
+    const prevWalletPassword = process.env["TOWNHOUSE_WALLET_PASSWORD"];
+    const prevTownhouseUid = process.env["TOWNHOUSE_UID"];
+    const prevWalletDir = process.env["TOWNHOUSE_WALLET_DIR"];
+    const prevDockerGid = process.env["TOWNHOUSE_DOCKER_GID"];
+    process.env["TOWNHOUSE_HOME"] = configDir;
+    process.env["TOWNHOUSE_WALLET_PASSWORD"] = resolvedPassword;
+    process.env["TOWNHOUSE_UID"] = String(process.getuid?.() ?? 1e3);
+    process.env["TOWNHOUSE_WALLET_DIR"] = dirname(
+      resolve(config.wallet.encrypted_path)
+    );
+    process.env["TOWNHOUSE_DOCKER_GID"] = String(dockerSockGid);
+    const MAX_ANON_RETRIES = 3;
+    try {
+      for (let attempt = 1; attempt <= MAX_ANON_RETRIES; attempt++) {
+        try {
+          await orch.up([]);
+          break;
+        } catch (err) {
+          if (isAnonBootstrapTimeout(err) && attempt < MAX_ANON_RETRIES) {
+            console.error(
+              `[townhouse hs up] ATOR bootstrap timed out (attempt ${attempt}/${MAX_ANON_RETRIES}) \u2014 retrying...`
+            );
+            await orch.down().catch(() => void 0);
+            continue;
+          }
+          throw err;
+        }
+      }
+    } finally {
+      if (prevTownhouseHome === void 0) {
+        delete process.env["TOWNHOUSE_HOME"];
+      } else {
+        process.env["TOWNHOUSE_HOME"] = prevTownhouseHome;
+      }
+      if (prevWalletPassword === void 0) {
+        delete process.env["TOWNHOUSE_WALLET_PASSWORD"];
+      } else {
+        process.env["TOWNHOUSE_WALLET_PASSWORD"] = prevWalletPassword;
+      }
+      if (prevTownhouseUid === void 0) {
+        delete process.env["TOWNHOUSE_UID"];
+      } else {
+        process.env["TOWNHOUSE_UID"] = prevTownhouseUid;
+      }
+      if (prevWalletDir === void 0) {
+        delete process.env["TOWNHOUSE_WALLET_DIR"];
+      } else {
+        process.env["TOWNHOUSE_WALLET_DIR"] = prevWalletDir;
+      }
+      if (prevDockerGid === void 0) {
+        delete process.env["TOWNHOUSE_DOCKER_GID"];
+      } else {
+        process.env["TOWNHOUSE_DOCKER_GID"] = prevDockerGid;
+      }
+    }
+    const nodesYamlPath = join(configDir, "nodes.yaml");
+    const reconcilerLogPath = join(configDir, "reconciler.log");
+    const reconcilerFactory = hsOverrides?.createReconciler ?? ((nodesPath, logPath) => {
+      const reconcilerAdminClient = new ConnectorAdminClient(
+        HS_CONNECTOR_ADMIN_URL,
+        5e3
+      );
+      return new BootReconciler(reconcilerAdminClient, nodesPath, logPath);
+    });
+    const reconciler = reconcilerFactory(nodesYamlPath, reconcilerLogPath);
+    try {
+      await reconcileWithBriefRetry(reconciler, 5e3);
+    } catch (reconcilerErr) {
+      const detail = reconcilerErr instanceof Error ? reconcilerErr.stack ?? reconcilerErr.message : String(reconcilerErr);
+      console.error(
+        `[townhouse hs up] reconciler error (non-fatal): ${detail}`
+      );
+    }
+    const adminClientFactory2 = hsOverrides?.createAdminClient ?? ((url, t) => new ConnectorAdminClient(url, t));
+    const adminClient = adminClientFactory2(HS_CONNECTOR_ADMIN_URL, 5e3);
+    const hsInfo = await adminClient.getHsHostname();
+    const hostname = hsInfo.hostname ?? "";
+    const publishedAt = hsInfo.publishedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+    _writeHostJson(configDir, {
+      hostname,
+      publishedAt,
+      writtenAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    ribbon.start("live", hostname);
+    if (shouldRenderInk()) {
+      const { mountTui } = await import("./tui-OIFXGBTL.js");
+      const apiUrlOverride = process.env["HS_TOWNHOUSE_API_URL"];
+      const mountOpts = apiUrlOverride !== void 0 ? { apiUrl: apiUrlOverride } : {};
+      const instance = mountTui(mountOpts);
+      await instance.waitUntilExit();
+    }
+  } catch (err) {
+    const { exitCode } = renderFailure(err);
+    process.exitCode = exitCode;
+  } finally {
+    ribbon.stop();
+    if (walletManager) {
+      walletManager.lock();
+    }
+  }
+}
+function _writeHostJson(configDir, data) {
+  const hostJsonPath = join(configDir, "host.json");
+  const tmpPath = `${hostJsonPath}.tmp`;
+  const content = JSON.stringify(
+    {
+      hostname: data.hostname,
+      publishedAt: data.publishedAt,
+      connectorAdminUrl: HS_CONNECTOR_ADMIN_URL,
+      townhouseApiUrl: HS_TOWNHOUSE_API_URL,
+      writtenAt: data.writtenAt
+    },
+    null,
+    2
+  );
+  writeFileSync(tmpPath, content, { mode: 384, encoding: "utf-8" });
+  renameSync(tmpPath, hostJsonPath);
+}
+async function handleHsDown(configDir, config, docker, options) {
+  const { rotateKeys, hsOverrides } = options;
+  const materialize = hsOverrides?.materializeComposeTemplate ?? materializeComposeTemplate;
+  const { composePath } = materialize("hs", { townhouseHome: configDir });
+  const prevTownhouseHome = process.env["TOWNHOUSE_HOME"];
+  const prevTownhouseUid = process.env["TOWNHOUSE_UID"];
+  const prevWalletDir = process.env["TOWNHOUSE_WALLET_DIR"];
+  const prevDockerGid = process.env["TOWNHOUSE_DOCKER_GID"];
+  const prevWalletPassword = process.env["TOWNHOUSE_WALLET_PASSWORD"];
+  process.env["TOWNHOUSE_HOME"] = configDir;
+  process.env["TOWNHOUSE_UID"] = String(process.getuid?.() ?? 1e3);
+  process.env["TOWNHOUSE_WALLET_DIR"] = dirname(
+    resolve(config.wallet.encrypted_path)
+  );
+  let dockerSockGid = 0;
+  try {
+    dockerSockGid = statSync("/var/run/docker.sock").gid;
+  } catch {
+  }
+  process.env["TOWNHOUSE_DOCKER_GID"] = String(dockerSockGid);
+  if (prevWalletPassword === void 0) {
+    process.env["TOWNHOUSE_WALLET_PASSWORD"] = "";
+  }
+  const restoreTownhouseHome = () => {
+    if (prevTownhouseHome === void 0) {
+      delete process.env["TOWNHOUSE_HOME"];
+    } else {
+      process.env["TOWNHOUSE_HOME"] = prevTownhouseHome;
+    }
+    if (prevTownhouseUid === void 0) {
+      delete process.env["TOWNHOUSE_UID"];
+    } else {
+      process.env["TOWNHOUSE_UID"] = prevTownhouseUid;
+    }
+    if (prevWalletDir === void 0) {
+      delete process.env["TOWNHOUSE_WALLET_DIR"];
+    } else {
+      process.env["TOWNHOUSE_WALLET_DIR"] = prevWalletDir;
+    }
+    if (prevDockerGid === void 0) {
+      delete process.env["TOWNHOUSE_DOCKER_GID"];
+    } else {
+      process.env["TOWNHOUSE_DOCKER_GID"] = prevDockerGid;
+    }
+    if (prevWalletPassword === void 0) {
+      delete process.env["TOWNHOUSE_WALLET_PASSWORD"];
+    }
+  };
+  if (rotateKeys) {
+    if (process.stdin.isTTY) {
+      let existingHostname = "(unknown)";
+      const hostJsonPath = join(configDir, "host.json");
+      if (existsSync(hostJsonPath)) {
+        try {
+          const { readFileSync } = await import("fs");
+          const json = JSON.parse(readFileSync(hostJsonPath, "utf-8"));
+          existingHostname = json.hostname ?? existingHostname;
+        } catch {
+        }
+      }
+      const { createInterface: createInterface3 } = await import("readline");
+      const answer = await new Promise((resolve2) => {
+        const rl = createInterface3({
+          input: process.stdin,
+          output: process.stdout
+        });
+        rl.question(
+          `WARNING: --rotate-keys will permanently delete your current .anyone address (${existingHostname}). The next 'hs up' will publish a new address. Continue? [y/N] `,
+          (ans) => {
+            rl.close();
+            resolve2(ans);
+          }
+        );
+      });
+      if (!["y", "yes"].includes(answer.trim().toLowerCase())) {
+        console.log("Cancelled.");
+        return;
+      }
+    }
+    const runDown = hsOverrides?.runComposeDown ?? _runDockerComposeDown;
+    try {
+      await runDown(composePath, true);
+    } catch (err) {
+      const { exitCode } = renderFailure(err);
+      process.exitCode = exitCode;
+      restoreTownhouseHome();
+      return;
+    }
+    rmSync(join(configDir, "host.json"), { force: true });
+    console.log(
+      "Apex stopped. Volumes deleted \u2014 your next 'hs up' will publish a NEW .anyone address."
+    );
+    restoreTownhouseHome();
+    return;
+  }
+  const orchestratorFactory = hsOverrides?.createOrchestrator ?? ((d, cfg, wm, opts) => new DockerOrchestrator(d, cfg, wm, opts));
+  const orch = orchestratorFactory(docker, config, void 0, {
+    profile: "hs",
+    composePath
+  });
+  try {
+    await orch.down();
+  } catch (err) {
+    const { exitCode } = renderFailure(err);
+    process.exitCode = exitCode;
+    restoreTownhouseHome();
+    return;
+  }
+  restoreTownhouseHome();
+  console.log(
+    "Apex stopped. Volumes preserved \u2014 your .anyone address is stable."
+  );
+}
+function _runDockerComposeDown(composePath, withVolumes) {
+  return new Promise((resolve2, reject) => {
+    const args = ["compose", "-f", composePath, "down"];
+    if (withVolumes) args.push("-v");
+    const child = spawn2("docker", args, {
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve2();
+      } else {
+        reject(new Error(`docker compose down exited with code ${code}`));
+      }
+    });
+  });
+}
+async function main(argv, dockerInstance, browserOpener, hsOverrides, nodeCommandOverrides) {
   const { values, positionals } = parseArgs({
     args: argv,
     options: {
@@ -561,16 +3409,40 @@ async function main(argv, dockerInstance, browserOpener) {
       "no-browser": { type: "boolean" },
       port: { type: "string" },
       preset: { type: "string" },
-      yes: { type: "boolean" }
+      yes: { type: "boolean" },
+      "rotate-keys": { type: "boolean" },
+      "skip-preflight": { type: "boolean" },
+      json: { type: "boolean" },
+      "json-compact": { type: "boolean" },
+      lines: { type: "string" },
+      follow: { type: "boolean", short: "f" },
+      units: { type: "string" },
+      rate: { type: "string" },
+      // credits buy / credits balance (epic-49, Phase 2)
+      token: { type: "string" },
+      amount: { type: "string" },
+      "fee-multiplier": { type: "string" },
+      "quote-only": { type: "boolean" },
+      "credit-destination": { type: "string" },
+      // wallet show / wallet seed (epic-49, Phase 3)
+      hex: { type: "boolean" },
+      paths: { type: "boolean" },
+      confirm: { type: "boolean" }
     },
     strict: false,
     allowPositionals: true
   });
+  const command = positionals[0];
+  if (command === "node" && values.help) {
+    const action = positionals[1];
+    const subHelp = action === "add" ? NODE_ADD_HELP : action === "remove" ? NODE_REMOVE_HELP : action === "list" ? NODE_LIST_HELP : NODE_HELP;
+    console.log(subHelp);
+    throw new CliHelpRequested();
+  }
   if (values.help) {
     console.log(HELP_TEXT);
     throw new CliHelpRequested();
   }
-  const command = positionals[0];
   if (!command) {
     console.log(HELP_TEXT);
     throw new CliHelpRequested();
@@ -614,26 +3486,76 @@ async function main(argv, dockerInstance, browserOpener) {
       if (subCommand === "show") {
         const configPath = values.config ?? DEFAULT_CONFIG_PATH;
         const config = loadConfig(configPath);
-        await handleWalletShow(config, values.password);
+        await handleWalletShow(config, values.password, {
+          json: values.json === true,
+          hex: values.hex === true,
+          paths: values.paths === true
+        });
+      } else if (subCommand === "seed") {
+        const configPath = values.config ?? DEFAULT_CONFIG_PATH;
+        const config = loadConfig(configPath);
+        await handleWalletSeed(
+          config,
+          values.password,
+          values.confirm === true
+        );
       } else {
         console.error(
-          "Usage: townhouse wallet show [-c <path>] [--password <pw>]"
+          "Usage:\n  townhouse wallet show [--json] [--hex] [--paths] [-c <path>] [--password <pw>]\n  townhouse wallet seed --confirm [-c <path>] [--password <pw>]"
         );
         process.exitCode = 1;
       }
       break;
     }
-    case "status": {
+    case "credits": {
+      const subCommand = positionals[1];
       const configPath = values.config ?? DEFAULT_CONFIG_PATH;
       const config = loadConfig(configPath);
-      const docker = dockerInstance ?? new Docker();
-      await handleStatus(docker, config);
+      if (subCommand === "buy") {
+        await handleCreditsBuy(config, values);
+      } else if (subCommand === "balance") {
+        await handleCreditsBalance(config, values);
+      } else {
+        console.error(
+          "Usage:\n  townhouse credits buy --token <id> --amount <decimal> [--fee-multiplier <n>] [--quote-only] [--yes] [-c <path>] [--password <pw>]\n  townhouse credits balance --token <id> [-c <path>] [--password <pw>]"
+        );
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "status": {
+      const configPath = values["config"] ?? DEFAULT_CONFIG_PATH;
+      const rawUnits = values["units"] ?? "usdc";
+      if (rawUnits !== "usdc" && rawUnits !== "sats") {
+        console.error(`--units must be 'usdc' or 'sats'`);
+        process.exitCode = 1;
+        break;
+      }
+      let satsPerUsdc;
+      if (rawUnits === "sats") {
+        const r = resolveSatsRate(
+          values,
+          process.env
+        );
+        if ("error" in r) {
+          console.error(r.error);
+          process.exitCode = 1;
+        } else {
+          satsPerUsdc = r.rate;
+        }
+      }
+      const units = rawUnits;
+      await handleStatus(
+        dockerInstance ?? new Docker2(),
+        loadConfig(configPath),
+        { units, satsPerUsdc, configPath }
+      );
       break;
     }
     case "up": {
       const configPath = values.config ?? DEFAULT_CONFIG_PATH;
       const config = loadConfig(configPath);
-      const docker = dockerInstance ?? new Docker();
+      const docker = dockerInstance ?? new Docker2();
       const profiles = resolveProfiles(values, config);
       await handleUp(
         configPath,
@@ -648,14 +3570,96 @@ async function main(argv, dockerInstance, browserOpener) {
     case "down": {
       const configPath = values.config ?? DEFAULT_CONFIG_PATH;
       const config = loadConfig(configPath);
-      const docker = dockerInstance ?? new Docker();
+      const docker = dockerInstance ?? new Docker2();
       await handleDown(config, docker);
       break;
     }
-    case "metrics": {
+    case "channels":
+    case "metrics":
+    case "logs":
+    case "peer":
+    case "health": {
+      await dispatchDrillCommand(command, {
+        adminUrl: HS_CONNECTOR_ADMIN_URL,
+        apiUrl: HS_TOWNHOUSE_API_URL,
+        values,
+        positionals,
+        docker: dockerInstance
+      });
+      break;
+    }
+    case "hs": {
+      const action = positionals[1];
       const configPath = values.config ?? DEFAULT_CONFIG_PATH;
       const config = loadConfig(configPath);
-      await handleMetrics(config);
+      const docker = dockerInstance ?? new Docker2();
+      const configDir = dirname(configPath);
+      if (action === "up") {
+        await handleHsUp(configPath, configDir, config, docker, {
+          password: values.password,
+          force: values.force === true,
+          skipPreflight: values["skip-preflight"] === true,
+          hsOverrides
+        });
+      } else if (action === "down") {
+        await handleHsDown(configDir, config, docker, {
+          rotateKeys: values["rotate-keys"] === true,
+          hsOverrides
+        });
+      } else {
+        console.error(
+          "Usage: townhouse hs <up|down> [--rotate-keys] [--password <pw>] [-c <path>]"
+        );
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "node": {
+      const action = positionals[1];
+      const jsonMode = values.json === true;
+      const yesMode = values.yes === true;
+      const nodeApiUrl = nodeCommandOverrides?.apiUrl ?? HS_TOWNHOUSE_API_URL;
+      if (!action) {
+        console.log(NODE_HELP);
+        throw new CliHelpRequested();
+      }
+      switch (action) {
+        case "add": {
+          const typeArg = positionals[2] ?? "town";
+          await handleNodeAdd(typeArg, {
+            json: jsonMode,
+            apiUrl: nodeApiUrl,
+            fetch: nodeCommandOverrides?.fetch,
+            confirm: nodeCommandOverrides?.confirm
+          });
+          break;
+        }
+        case "remove": {
+          const idArg = positionals[2] ?? "";
+          await handleNodeRemove(idArg, {
+            yes: yesMode,
+            json: jsonMode,
+            apiUrl: nodeApiUrl,
+            fetch: nodeCommandOverrides?.fetch,
+            confirm: nodeCommandOverrides?.confirm
+          });
+          break;
+        }
+        case "list": {
+          await handleNodeList({
+            json: jsonMode,
+            apiUrl: nodeApiUrl,
+            fetch: nodeCommandOverrides?.fetch
+          });
+          break;
+        }
+        default: {
+          const safeAction = action.replace(/[\x00-\x1f\x7f]/g, "");
+          console.error(`Unknown node subcommand: ${safeAction}`);
+          console.log(NODE_HELP);
+          process.exitCode = 1;
+        }
+      }
       break;
     }
     default: {