@toon-protocol/townhouse 0.1.0-rc5 → 0.1.0

package/dist/{chunk-IB6TNCUQ.js → chunk-4WCMVIO4.js}

@@ -8,11 +8,13 @@ import {
   DVM_HEALTH_PORT,
   MILL_HEALTH_PORT,
   NODE_BTP_PORT,
-  TOWN_HEALTH_PORT,
+  TOWN_HEALTH_PORT
+} from "./chunk-GQNBZJ6F.js";
+import {
   __commonJS,
   __require,
   __toESM
-} from "./chunk-UTFWPLTB.js";
+} from "./chunk-I2R4CRUX.js";
 
 // ../../node_modules/.pnpm/ws@8.19.0/node_modules/ws/lib/constants.js
 var require_constants = __commonJS({
@@ -41,7 +43,7 @@ var require_constants = __commonJS({
 var require_node_gyp_build = __commonJS({
   "../../node_modules/.pnpm/node-gyp-build@4.8.4/node_modules/node-gyp-build/node-gyp-build.js"(exports, module) {
     "use strict";
-    var fs = __require("fs");
+    var fs6 = __require("fs");
     var path = __require("path");
     var os = __require("os");
     var runtimeRequire = typeof __webpack_require__ === "function" ? __non_webpack_require__ : __require;
@@ -71,9 +73,9 @@ var require_node_gyp_build = __commonJS({
         var debug = getFirst(path.join(dir, "build/Debug"), matchBuild);
         if (debug) return debug;
       }
-      var prebuild = resolve(dir);
+      var prebuild = resolve2(dir);
       if (prebuild) return prebuild;
-      var nearby = resolve(path.dirname(process.execPath));
+      var nearby = resolve2(path.dirname(process.execPath));
       if (nearby) return nearby;
       var target = [
         "platform=" + platform,
@@ -89,7 +91,7 @@ var require_node_gyp_build = __commonJS({
         // eslint-disable-line
       ].filter(Boolean).join(" ");
       throw new Error("No native build was found for " + target + "\n    loaded from: " + dir + "\n");
-      function resolve(dir2) {
+      function resolve2(dir2) {
         var tuples = readdirSync(path.join(dir2, "prebuilds")).map(parseTuple);
         var tuple = tuples.filter(matchTuple(platform, arch)).sort(compareTuples)[0];
         if (!tuple) return;
@@ -102,7 +104,7 @@ var require_node_gyp_build = __commonJS({
     };
     function readdirSync(dir) {
       try {
-        return fs.readdirSync(dir);
+        return fs6.readdirSync(dir);
       } catch (err) {
         return [];
       }
@@ -196,7 +198,7 @@ var require_node_gyp_build = __commonJS({
       return typeof window !== "undefined" && window.process && window.process.type === "renderer";
     }
     function isAlpine(platform2) {
-      return platform2 === "linux" && fs.existsSync("/etc/alpine-release");
+      return platform2 === "linux" && fs6.existsSync("/etc/alpine-release");
     }
     load.parseTags = parseTags;
     load.matchTags = matchTags;
@@ -2327,7 +2329,7 @@ var require_extension = __commonJS({
       if (dest[name] === void 0) dest[name] = [elem];
       else dest[name].push(elem);
     }
-    function parse2(header) {
+    function parse3(header) {
       const offers = /* @__PURE__ */ Object.create(null);
       let params = /* @__PURE__ */ Object.create(null);
       let mustUnescape = false;
@@ -2467,7 +2469,7 @@ var require_extension = __commonJS({
         }).join(", ");
       }).join(", ");
     }
-    module.exports = { format, parse: parse2 };
+    module.exports = { format, parse: parse3 };
   }
 });
 
@@ -2480,7 +2482,7 @@ var require_websocket = __commonJS({
     var http3 = __require("http");
     var net2 = __require("net");
     var tls = __require("tls");
-    var { randomBytes: randomBytes2, createHash } = __require("crypto");
+    var { randomBytes: randomBytes2, createHash: createHash2 } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate = require_permessage_deflate();
@@ -2501,7 +2503,7 @@ var require_websocket = __commonJS({
     var {
       EventTarget: { addEventListener, removeEventListener }
     } = require_event_target();
-    var { format, parse: parse2 } = require_extension();
+    var { format, parse: parse3 } = require_extension();
     var { toBuffer } = require_buffer_util();
     var kAborted = /* @__PURE__ */ Symbol("kAborted");
     var protocolVersions = [8, 13];
@@ -3140,7 +3142,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket2, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash("sha1").update(key + GUID).digest("base64");
+        const digest = createHash2("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket2, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -3170,7 +3172,7 @@ var require_websocket = __commonJS({
           }
           let extensions;
           try {
-            extensions = parse2(secWebSocketExtensions);
+            extensions = parse3(secWebSocketExtensions);
           } catch (err) {
             const message = "Invalid Sec-WebSocket-Extensions header";
             abortHandshake(websocket2, socket, message);
@@ -3460,7 +3462,7 @@ var require_subprotocol = __commonJS({
   "../../node_modules/.pnpm/ws@8.19.0/node_modules/ws/lib/subprotocol.js"(exports, module) {
     "use strict";
     var { tokenChars } = require_validation();
-    function parse2(header) {
+    function parse3(header) {
       const protocols = /* @__PURE__ */ new Set();
       let start = -1;
       let end = -1;
@@ -3496,7 +3498,7 @@ var require_subprotocol = __commonJS({
       protocols.add(protocol);
       return protocols;
     }
-    module.exports = { parse: parse2 };
+    module.exports = { parse: parse3 };
   }
 });
 
@@ -3507,7 +3509,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter2 = __require("events");
     var http3 = __require("http");
     var { Duplex } = __require("stream");
-    var { createHash } = __require("crypto");
+    var { createHash: createHash2 } = __require("crypto");
     var extension = require_extension();
     var PerMessageDeflate = require_permessage_deflate();
     var subprotocol = require_subprotocol();
@@ -3808,7 +3810,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash("sha1").update(key + GUID).digest("base64");
+        const digest = createHash2("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -3896,6 +3898,16 @@ var require_websocket_server = __commonJS({
 // src/config/defaults.ts
 import { homedir } from "os";
 import { join } from "path";
+var DEFAULT_HS_CHAIN_PROVIDERS = [
+  Object.freeze({
+    chainType: "evm",
+    chainId: "evm:base:31337",
+    rpcUrl: "http://127.0.0.1:19999",
+    registryAddress: "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
+    tokenAddress: "0x5FbDB2315678afecb367f032d93F642f64180aa3",
+    keyId: "0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6"
+  })
+];
 function getDefaultConfig() {
   return {
     nodes: {
@@ -3924,6 +3936,8 @@ function getDefaultConfig() {
 }
 
 // src/config/validator.ts
+var VALID_CHAIN_TYPES = /* @__PURE__ */ new Set(["evm"]);
+var HEX_ADDRESS = /^0x[a-fA-F0-9]+$/;
 var ConfigValidationError = class extends Error {
   constructor(message) {
     super(message);
@@ -4094,6 +4108,52 @@ function validateConfig(raw) {
       'config.transport.mode="ator" requires either config.transport.externalUrl (operator-managed anon binary) or config.transport.hiddenService (connector-managed anon binary). Without one of these, the underlying connector will reject the manifest at boot.'
     );
   }
+  let chainProviders;
+  if (raw["chainProviders"] !== void 0) {
+    if (!Array.isArray(raw["chainProviders"])) {
+      throw new ConfigValidationError(
+        "config.chainProviders must be an array of ChainProviderEntry"
+      );
+    }
+    chainProviders = raw["chainProviders"].map((entry, idx) => {
+      const path = `config.chainProviders[${idx}]`;
+      assertObject(entry, path);
+      assertString(entry["chainType"], `${path}.chainType`);
+      if (!VALID_CHAIN_TYPES.has(entry["chainType"])) {
+        throw new ConfigValidationError(
+          `${path}.chainType must be one of: ${[...VALID_CHAIN_TYPES].join(", ")}`
+        );
+      }
+      assertString(entry["chainId"], `${path}.chainId`);
+      assertString(entry["rpcUrl"], `${path}.rpcUrl`);
+      assertString(entry["registryAddress"], `${path}.registryAddress`);
+      if (!HEX_ADDRESS.test(entry["registryAddress"])) {
+        throw new ConfigValidationError(
+          `${path}.registryAddress must match /^0x[a-fA-F0-9]+$/`
+        );
+      }
+      assertString(entry["tokenAddress"], `${path}.tokenAddress`);
+      if (!HEX_ADDRESS.test(entry["tokenAddress"])) {
+        throw new ConfigValidationError(
+          `${path}.tokenAddress must match /^0x[a-fA-F0-9]+$/`
+        );
+      }
+      assertString(entry["keyId"], `${path}.keyId`);
+      if (!HEX_ADDRESS.test(entry["keyId"])) {
+        throw new ConfigValidationError(
+          `${path}.keyId must match /^0x[a-fA-F0-9]+$/`
+        );
+      }
+      return {
+        chainType: entry["chainType"],
+        chainId: entry["chainId"],
+        rpcUrl: entry["rpcUrl"],
+        registryAddress: entry["registryAddress"],
+        tokenAddress: entry["tokenAddress"],
+        keyId: entry["keyId"]
+      };
+    });
+  }
   assertObject(raw["api"], "config.api");
   const api = raw["api"];
   assertNumber(api["port"], "config.api.port");
@@ -4144,7 +4204,8 @@ function validateConfig(raw) {
     },
     logging: {
       level: logging["level"]
-    }
+    },
+    ...chainProviders !== void 0 ? { chainProviders } : {}
   };
 }
 function pickOptional(obj, keys) {
@@ -4353,6 +4414,16 @@ var ConnectorConfigGenerator = class {
       peers: [],
       routes: []
     };
+    if (this.config.chainProviders !== void 0 && this.config.chainProviders.length > 0) {
+      yamlObj["chainProviders"] = this.config.chainProviders.map((p) => ({
+        chainType: p.chainType,
+        chainId: p.chainId,
+        rpcUrl: p.rpcUrl,
+        registryAddress: p.registryAddress,
+        tokenAddress: p.tokenAddress,
+        keyId: p.keyId
+      }));
+    }
     return yamlStringify(yamlObj);
   }
   // ── Private helpers ──
@@ -4435,151 +4506,956 @@ var ConnectorConfigGenerator = class {
   }
 };
 
-// src/docker/orchestrator.ts
-import { EventEmitter } from "events";
-import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
-import { dirname, join as join2 } from "path";
-var TOWN_RELAY_PORT = 7100;
-var STATS_CACHE_TTL_MS = 5e3;
-var NETWORK_NAME = "townhouse-net";
-var DEFAULT_NODE_IMAGES = {
-  town: "toon:town",
-  mill: "toon:mill",
-  dvm: "toon:dvm"
-};
-var MAX_START_RETRIES = 3;
-var CONNECTOR_INTERNAL_PORT = 3e3;
-var RELAY_ATOR_SIDECAR_IMAGE = "toon:townhouse-ator-sidecar";
-var RELAY_ATOR_SOCKS_PORT = 9051;
-function normalizeImageTag(image) {
-  const lastSlash = image.lastIndexOf("/");
-  const nameAndTag = lastSlash >= 0 ? image.slice(lastSlash + 1) : image;
-  if (nameAndTag.includes(":")) {
-    return image;
+// src/connector/admin-client.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var ConnectorAdminClient = class {
+  baseUrl;
+  timeoutMs;
+  /**
+   * @param baseUrl - Base URL for the connector admin API (e.g., 'http://localhost:9402')
+   * @param timeoutMs - Request timeout in milliseconds (default: 5000)
+   */
+  constructor(baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    this.timeoutMs = timeoutMs;
   }
-  return `${image}:latest`;
-}
-var DockerOrchestrator = class extends EventEmitter {
-  docker;
-  config;
-  configGenerator;
-  walletManager;
-  activeNodes = [];
-  statsCache = /* @__PURE__ */ new Map();
-  constructor(docker, config, walletManager) {
-    super();
-    this.docker = docker;
-    this.config = config;
-    this.configGenerator = new ConnectorConfigGenerator(config);
-    this.walletManager = walletManager;
+  /** Public read of the configured base URL (used by drill-command probes to derive a sibling client). */
+  getBaseUrl() {
+    return this.baseUrl;
   }
   /**
-   * Orchestrate full startup sequence:
-   * 1. Ensure network exists
-   * 2. Pull images (with progress)
-   * 3. Start connector, wait for health
-   * 4. Start enabled node containers in parallel
+   * GET /health on the admin-API port — checks HTTP reachability of the
+   * connector without validating the rich HealthStatus shape. Use this from
+   * the drill-command health probe when only the admin URL is available
+   * (port 9401), not the healthCheckPort (8080). The admin server's /health
+   * returns `{status:'healthy', service:'admin-api', nodeId, timestamp}` —
+   * a different shape from `getHealth()`'s validator. This method returns
+   * a coarse status from a 200 response and reads `nodeId` if present.
+   *
+   * @throws Error when connector is unreachable or returns non-2xx.
    */
-  async up(profiles) {
-    this.activeNodes = [...profiles];
-    await this.ensureNetwork();
-    await this.pullImages(profiles);
-    await this.startConnector();
-    await this.waitForHealth("townhouse-connector");
-    await Promise.all(profiles.map((type) => this.startNode(type)));
-    if (profiles.includes("town") && this.config.transport.relayHiddenService) {
-      await this.startRelayAtorSidecar();
-    }
+  async pingAdminLive() {
+    const response = await this.fetch("/health");
+    const body = await response.json().catch(() => ({}));
+    const nodeId = typeof body === "object" && body !== null && typeof body["nodeId"] === "string" ? body["nodeId"] : void 0;
+    return nodeId !== void 0 ? { status: "healthy", nodeId } : { status: "healthy" };
   }
   /**
-   * Regenerate connector config and restart the connector container
-   * with updated environment variables (peer list).
+   * GET /health — returns the connector's HealthStatus from the healthCheckPort server.
    *
-   * Sequence: emit connectorRestarting -> stop -> remove -> create -> start -> health -> emit connectorRestarted
+   * @throws Error when connector is not running, returns non-200, or shape is invalid
    */
-  async regenerateConnectorConfig(activeNodes) {
-    this.activeNodes = [...activeNodes];
-    this.emit("connectorRestarting", { reason: "peer list updated" });
-    const connectorName = `${CONTAINER_PREFIX}connector`;
-    const existingContainer = this.docker.getContainer(connectorName);
-    try {
-      await existingContainer.stop({ t: 5 });
-    } catch {
+  async getHealth() {
+    const response = await this.fetch("/health");
+    const body = await response.json();
+    if (typeof body !== "object" || body === null) {
+      throw new Error("Connector admin API: invalid health response shape");
     }
-    try {
-      await existingContainer.remove();
-    } catch {
+    const obj = body;
+    const status = obj["status"];
+    if (status !== "healthy" && status !== "unhealthy" && status !== "starting" && status !== "degraded") {
+      throw new Error("Connector admin API: invalid health response shape");
     }
-    await this.ensureNetwork();
-    try {
-      await this.startConnector();
-      await this.waitForHealth(connectorName);
-    } finally {
-      this.emit("connectorRestarted", { peers: activeNodes });
+    if (typeof obj["uptime"] !== "number" || typeof obj["peersConnected"] !== "number" || typeof obj["totalPeers"] !== "number" || typeof obj["timestamp"] !== "string") {
+      throw new Error("Connector admin API: invalid health response shape");
     }
+    return body;
   }
   /**
-   * Hot-add a node after initial startup.
-   * Starts the node container, then restarts the connector with updated peer list.
+   * GET /admin/hs-hostname — returns the connector's published .anyone hidden-service
+   * hostname (Epic 45 / Story 44.1). Returns 200 with {hostname, publishedAt} both
+   * possibly null while bootstrap is in progress, both non-null once anon publishes.
+   * Returns 503 when the connector is anon-disabled (anon.enabled: false in config).
+   *
+   * @throws Error('connector is anon-disabled (HTTP 503)') on 503 — caller can match
+   *   on this exact prefix for actionable diagnostics.
+   * @throws Error on non-200/503 status, network error, or shape-validation failure.
    */
-  async addNode(type) {
-    if (!this.activeNodes.includes(type)) {
-      this.activeNodes.push(type);
+  async getHsHostname() {
+    const url = `${this.baseUrl}/admin/hs-hostname`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let body;
+    try {
+      let response;
+      try {
+        response = await fetch(url, { signal: controller.signal });
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new Error(
+            `Connector admin API request timeout after ${this.timeoutMs}ms: ${url}`
+          );
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Connector admin API connection refused: ${msg}`);
+      }
+      if (response.status === 503) {
+        throw new Error("connector is anon-disabled (HTTP 503)");
+      }
+      if (!response.ok) {
+        throw new Error(
+          `Connector admin API unexpected status ${response.status} on /admin/hs-hostname \u2014 expected 200 or 503 (connector image may be too old or misconfigured)`
+        );
+      }
+      try {
+        body = await response.json();
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new Error(
+            `Connector admin API request timeout after ${this.timeoutMs}ms: ${url}`
+          );
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `Connector admin API: invalid JSON in hs-hostname response: ${msg}`
+        );
+      }
+    } finally {
+      clearTimeout(timer);
     }
-    await this.startNode(type);
-    await this.regenerateConnectorConfig(this.activeNodes);
+    if (typeof body !== "object" || body === null) {
+      throw new Error(
+        "Connector admin API: invalid hs-hostname response shape"
+      );
+    }
+    const obj = body;
+    const hostname = obj["hostname"];
+    const publishedAt = obj["publishedAt"];
+    if (hostname !== null && typeof hostname !== "string" || publishedAt !== null && typeof publishedAt !== "string") {
+      throw new Error(
+        "Connector admin API: invalid hs-hostname response shape"
+      );
+    }
+    if (typeof hostname === "string" && hostname.length === 0) {
+      throw new Error(
+        "Connector admin API: invalid hs-hostname response shape"
+      );
+    }
+    if (typeof publishedAt === "string" && publishedAt.length === 0) {
+      throw new Error(
+        "Connector admin API: invalid hs-hostname response shape"
+      );
+    }
+    if (typeof hostname === "string" && !hostname.endsWith(".anon")) {
+      throw new Error(
+        "Connector admin API: invalid hs-hostname response shape"
+      );
+    }
+    return body;
   }
   /**
-   * Hot-remove a node.
-   * Stops the node container, then restarts the connector with updated peer list.
+   * GET /admin/metrics.json — returns the connector's per-peer ILP counters
+   * with an aggregate rollup, mirroring `AdminMetricsJsonResponse`.
+   *
+   * @throws Error when connector is not running, returns non-200, or shape is invalid
    */
-  async removeNode(type) {
-    this.activeNodes = this.activeNodes.filter((n) => n !== type);
-    const containerName = `${CONTAINER_PREFIX}${type}`;
-    await this.stopAndRemove(containerName);
-    await this.regenerateConnectorConfig(this.activeNodes);
+  async getMetrics() {
+    const response = await this.fetch("/admin/metrics.json");
+    const body = await response.json();
+    if (typeof body !== "object" || body === null) {
+      throw new Error("Connector admin API: invalid metrics response shape");
+    }
+    const obj = body;
+    const aggregate = obj["aggregate"];
+    if (typeof obj["uptimeSeconds"] !== "number" || typeof aggregate !== "object" || aggregate === null || !Array.isArray(obj["peers"]) || typeof obj["timestamp"] !== "string") {
+      throw new Error("Connector admin API: invalid metrics response shape");
+    }
+    const agg = aggregate;
+    if (typeof agg["packetsForwarded"] !== "number" || typeof agg["packetsRejected"] !== "number" || typeof agg["bytesSent"] !== "number") {
+      throw new Error("Connector admin API: invalid metrics response shape");
+    }
+    return body;
   }
   /**
-   * Graceful shutdown — stops containers in reverse order:
-   * 1. Stop all node containers in parallel
-   * 2. Stop connector
-   * 3. Remove network
+   * GET /admin/earnings.json — returns the connector's per-peer per-asset
+   * earnings projection, mirroring `AdminEarningsJsonResponse` (connector v3.2.0+).
+   *
+   * Source of truth: @toon-protocol/connector
+   *   packages/connector/src/http/admin-api.ts:1864-1945
+   *
+   * Returns HTTP 503 when the connector is started without settlement config
+   * (accountManager / claimReceiver not wired). Townhouse's apex always wires
+   * both; 503 in production indicates connector misconfiguration.
+   *
+   * Wire-shape adaptation: the connector's `timestamp: string` field is
+   * wrapped into `{ iso: string }` on the way out (EarningsTimestamp).
+   *
+   * @throws Error when connector is not running, returns non-200, or shape is invalid
    */
-  async down() {
-    const containers = await this.docker.listContainers({ all: true });
-    const nodeContainerNames = [];
-    let connectorName;
-    for (const info of containers) {
-      for (const name of info.Names) {
-        const cleanName = name.startsWith("/") ? name.slice(1) : name;
-        if (!cleanName.startsWith(CONTAINER_PREFIX)) continue;
-        if (cleanName === `${CONTAINER_PREFIX}connector`) {
-          connectorName = cleanName;
-        } else {
-          nodeContainerNames.push(cleanName);
+  async getEarnings() {
+    const response = await this.fetch("/admin/earnings.json");
+    const body = await response.json();
+    if (typeof body !== "object" || body === null) {
+      throw new Error("Connector admin API: invalid earnings response shape");
+    }
+    const obj = body;
+    if (typeof obj["uptimeSeconds"] !== "number" || !Array.isArray(obj["peers"]) || !Array.isArray(obj["connectorFees"]) || !Array.isArray(obj["recentClaims"]) || typeof obj["timestamp"] !== "string") {
+      throw new Error("Connector admin API: invalid earnings response shape");
+    }
+    const peers = obj["peers"];
+    for (const peer of peers) {
+      if (typeof peer !== "object" || peer === null) {
+        throw new Error("Connector admin API: invalid earnings response shape");
+      }
+      const p = peer;
+      if (typeof p["peerId"] !== "string" || !Array.isArray(p["byAsset"])) {
+        throw new Error("Connector admin API: invalid earnings response shape");
+      }
+      for (const asset of p["byAsset"]) {
+        if (typeof asset !== "object" || asset === null) {
+          throw new Error(
+            "Connector admin API: invalid earnings response shape"
+          );
+        }
+        const a = asset;
+        if (typeof a["assetCode"] !== "string" || typeof a["assetScale"] !== "number" || typeof a["claimsReceivedTotal"] !== "string" || typeof a["claimsSentTotal"] !== "string" || typeof a["netBalance"] !== "string" || a["lastClaimAt"] !== null && typeof a["lastClaimAt"] !== "string") {
+          throw new Error(
+            "Connector admin API: invalid earnings response shape"
+          );
         }
       }
     }
-    await Promise.all(
-      nodeContainerNames.map((name) => this.stopAndRemove(name))
-    );
-    if (connectorName) {
-      await this.stopAndRemove(connectorName);
+    const fees = obj["connectorFees"];
+    for (const fee of fees) {
+      if (typeof fee !== "object" || fee === null) {
+        throw new Error("Connector admin API: invalid earnings response shape");
+      }
+      const f = fee;
+      if (typeof f["assetCode"] !== "string" || typeof f["assetScale"] !== "number" || typeof f["total"] !== "string") {
+        throw new Error("Connector admin API: invalid earnings response shape");
+      }
     }
-    await this.removeNetwork();
+    const claims = obj["recentClaims"];
+    for (const claim of claims) {
+      if (typeof claim !== "object" || claim === null) {
+        throw new Error("Connector admin API: invalid earnings response shape");
+      }
+      const c = claim;
+      if (typeof c["peerId"] !== "string" || typeof c["assetCode"] !== "string" || typeof c["assetScale"] !== "number" || typeof c["amount"] !== "string" || c["direction"] !== "inbound" && c["direction"] !== "outbound" || typeof c["at"] !== "string") {
+        throw new Error("Connector admin API: invalid earnings response shape");
+      }
+    }
+    const timestamp = { iso: obj["timestamp"] };
+    return {
+      uptimeSeconds: obj["uptimeSeconds"],
+      peers,
+      connectorFees: fees,
+      recentClaims: claims,
+      timestamp
+    };
   }
   /**
-   * Resolve the Nostr relay WebSocket URL for a Town node instance.
-   *
-   * Inspects the container's port bindings to get the host-bound port for
-   * the relay WebSocket (7100/tcp). Falls back to the Docker-internal URL
-   * when the server is running inside the Docker network or bindings are absent.
+   * GET /admin/peers — returns the connector's peer roster with route counts
+   * and ILP addresses. Returns the unwrapped peers array (the wrapper's
+   * nodeId / peerCount / connectedCount fields are dropped).
    *
-   * @param nodeId - The `NodeInfo.id` value (e.g. 'town', 'dev-town-01')
+   * @throws Error when connector is not running, returns non-200, or shape is invalid
    */
-  async getNodeRelayEndpoint(nodeId) {
-    const containerName = `${CONTAINER_PREFIX}${nodeId}`;
-    try {
+  async getPeers() {
+    const response = await this.fetch("/admin/peers");
+    const body = await response.json();
+    if (typeof body !== "object" || body === null) {
+      throw new Error("Connector admin API: invalid peers response shape");
+    }
+    const obj = body;
+    if (!Array.isArray(obj["peers"])) {
+      throw new Error("Connector admin API: invalid peers response shape");
+    }
+    return body.peers;
+  }
+  /**
+   * GET /admin/channels — returns the connector's payment-channel summaries
+   * across all registered chain providers. Multi-chain: one entry per channel
+   * regardless of chain.
+   *
+   * @throws Error when connector is not running, returns non-200, or shape is invalid
+   */
+  async getChannels() {
+    const response = await this.fetch("/admin/channels");
+    const body = await response.json();
+    if (!Array.isArray(body)) {
+      throw new Error("Connector admin API: invalid channels response shape");
+    }
+    for (const entry of body) {
+      if (typeof entry !== "object" || entry === null) {
+        throw new Error("Connector admin API: invalid channels response shape");
+      }
+      const e = entry;
+      if (typeof e["channelId"] !== "string" || typeof e["peerId"] !== "string" || typeof e["chain"] !== "string" || typeof e["status"] !== "string" || typeof e["deposit"] !== "string" || typeof e["lastActivity"] !== "string") {
+        throw new Error("Connector admin API: invalid channels response shape");
+      }
+    }
+    return body;
+  }
+  /**
+   * POST /admin/peers — register (or re-register, idempotent) a child peer
+   * with the connector. Used by the boot reconciler (Story 46.1) to
+   * re-register peers present in `nodes.yaml` but missing from the
+   * connector's runtime peer roster (e.g., after a connector restart).
+   *
+   * The connector's POST /admin/peers handler treats a POST whose `id`
+   * matches an existing peer as a re-registration (no-op for the peer
+   * itself; routes are appended). A POST with a new `id` triggers
+   * `addPeer()` and BTP connection setup.
+   *
+   * @param input.id - peer identifier (matches `nodes.yaml`'s `peerId` and
+   *   the connector's `PeerStatus.id`).
+   * @param input.url - BTP WebSocket URL the connector dials. MUST start
+   *   with `ws://` or `wss://` (the connector validates this).
+   * @param input.authToken - shared auth token; pass empty string for
+   *   internal Townhouse peers (no auth).
+   * @param input.routes - optional ILP route prefixes to register against
+   *   this peer. The reconciler passes the peer's ilpAddress.
+   * @param input.transport - optional per-peer transport selection
+   *   (connector >= 3.6.2). `'direct'` forces the connector to bypass the
+   *   global SOCKS5 transport for this peer, even when the apex itself
+   *   runs in `transport.type: socks5` mode. Required for Docker-sibling
+   *   peers in HS mode — the anon SOCKS5 proxy cannot resolve internal
+   *   Docker hostnames. When omitted, the peer inherits the connector's
+   *   global transport (back-compat with pre-3.6.2 connectors).
+   *
+   * @throws Error on non-2xx response, timeout, or connection refused.
+   */
+  async registerPeer(input) {
+    if (!input.url.startsWith("ws://") && !input.url.startsWith("wss://")) {
+      throw new Error(
+        `Connector admin API: registerPeer.url must start with ws:// or wss:// (got: ${input.url})`
+      );
+    }
+    const url = `${this.baseUrl}/admin/peers`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      let response;
+      try {
+        response = await fetch(url, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(input),
+          signal: controller.signal
+        });
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new Error(
+            `Connector admin API request timeout after ${this.timeoutMs}ms: POST ${url}`
+          );
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `Connector admin API request failed: POST ${url} \u2014 ${msg}`
+        );
+      }
+      if (!response.ok) {
+        let body = "";
+        try {
+          body = await response.text();
+        } catch (error) {
+          if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(
+              `Connector admin API request timeout after ${this.timeoutMs}ms: POST ${url} (body read)`
+            );
+          }
+        }
+        throw new Error(
+          `Connector admin API error: POST /admin/peers returned ${response.status} ${response.statusText}${body ? ` \u2014 ${body}` : ""}`
+        );
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * DELETE /admin/peers/:peerId?removeRoutes=true — deregister a child peer.
+   *
+   * Idempotent: a 404 from the connector (peer already removed) is treated as
+   * success so callers can safely use this as a rollback step without knowing
+   * whether the peer was ever registered.
+   *
+   * `removeRoutes=true` is always sent so the connector drops the ILP routing
+   * entries for this peer along with the BTP connection config.
+   *
+   * @throws Error on empty peerId (rejected at client, no network request made)
+   * @throws Error on non-2xx/404 response, timeout, or connection refused
+   */
+  async removePeer(peerId) {
+    if (!peerId) {
+      throw new Error(
+        "Connector admin API: removePeer requires a non-empty peerId"
+      );
+    }
+    const url = `${this.baseUrl}/admin/peers/${encodeURIComponent(peerId)}?removeRoutes=true`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      let response;
+      try {
+        response = await fetch(url, {
+          method: "DELETE",
+          signal: controller.signal
+        });
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new Error(
+            `Connector admin API request timeout after ${this.timeoutMs}ms: DELETE ${url}`
+          );
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `Connector admin API request failed: DELETE ${url} \u2014 ${msg}`
+        );
+      }
+      if (response.status === 404) {
+        return;
+      }
+      if (!response.ok) {
+        let body = "";
+        try {
+          body = await response.text();
+        } catch (error) {
+          if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(
+              `Connector admin API request timeout after ${this.timeoutMs}ms: DELETE ${url} (body read)`
+            );
+          }
+        }
+        throw new Error(
+          `Connector admin API error: DELETE /admin/peers/${peerId} returned ${response.status} ${response.statusText}${body ? ` \u2014 ${body}` : ""}`
+        );
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * GET /packets — returns the connector's raw packet log filtered by the
+   * given criteria. Used by the timeseries aggregation route (story 21.10).
+   *
+   * Townhouse-Side Contract: see packages/sdk/CONNECTOR_MIGRATION.md §getPacketLog.
+   * If the connector image does not expose GET /packets, this method throws
+   * with a `ConnectorEndpointNotFound` error code so the route can return 503.
+   *
+   * @throws Error with code='ConnectorEndpointNotFound' when connector returns 404
+   * @throws Error when connector is not running, returns non-200, or shape is invalid
+   */
+  async getPacketLog(filter = {}) {
+    const params = new URLSearchParams();
+    if (filter.ilpAddress !== void 0)
+      params.set("ilpAddress", filter.ilpAddress);
+    if (filter.since !== void 0) params.set("since", String(filter.since));
+    if (filter.limit !== void 0) params.set("limit", String(filter.limit));
+    const path = params.toString() ? `/packets?${params.toString()}` : "/packets";
+    let response;
+    try {
+      response = await this.fetch(path);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes("404")) {
+        const err = new Error(
+          "Connector does not expose GET /packets \u2014 endpoint not found"
+        );
+        err.code = "ConnectorEndpointNotFound";
+        throw err;
+      }
+      throw error;
+    }
+    const body = await response.json();
+    if (!Array.isArray(body)) {
+      throw new Error(
+        "Connector admin API: invalid packet log response shape \u2014 expected array"
+      );
+    }
+    return body;
+  }
+  // ── Private helpers ──
+  /**
+   * Perform an HTTP GET request to the connector admin API.
+   * Wraps fetch with error handling for connection refused and non-200 responses.
+   */
+  async fetch(path) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      let response;
+      try {
+        response = await fetch(url, { signal: controller.signal });
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new Error(
+            `Connector admin API request timeout after ${this.timeoutMs}ms: ${url}`
+          );
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Connector admin API connection refused: ${msg}`);
+      }
+      if (!response.ok) {
+        throw new Error(
+          `Connector admin API error: ${response.status} ${response.statusText}`
+        );
+      }
+      return response;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
+// src/docker/orchestrator.ts
+import { EventEmitter } from "events";
+import { spawn } from "child_process";
+import { existsSync, mkdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, isAbsolute, join as join2 } from "path";
+function runDockerCompose(file, args, options = {}) {
+  const {
+    timeout,
+    maxBuffer = 16 * 1024 * 1024,
+    inheritStdio = false,
+    env
+  } = options;
+  return new Promise((resolve2, reject) => {
+    const child = spawn(file, Array.from(args), {
+      stdio: inheritStdio ? ["ignore", "inherit", "pipe"] : ["ignore", "pipe", "pipe"],
+      ...env !== void 0 ? { env } : {}
+    });
+    const stderrChunks = [];
+    const stdoutChunks = [];
+    let stderrLen = 0;
+    let stdoutLen = 0;
+    let timedOut = false;
+    const timer = timeout !== void 0 && timeout > 0 ? setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (!child.killed) child.kill("SIGKILL");
+      }, 5e3).unref();
+    }, timeout) : null;
+    child.stderr?.on("data", (chunk) => {
+      if (stderrLen < maxBuffer) {
+        stderrChunks.push(chunk);
+        stderrLen += chunk.length;
+      }
+    });
+    child.stdout?.on("data", (chunk) => {
+      if (stdoutLen < maxBuffer) {
+        stdoutChunks.push(chunk);
+        stdoutLen += chunk.length;
+      }
+    });
+    child.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+    child.on("close", (code, signal) => {
+      if (timer) clearTimeout(timer);
+      const stderr = Buffer.concat(stderrChunks).toString("utf8");
+      const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+      if (timedOut) {
+        const err2 = new Error(
+          `docker subprocess timed out after ${timeout}ms`
+        );
+        err2.stdout = stdout;
+        err2.stderr = stderr;
+        err2.code = "ETIMEDOUT";
+        err2.signal = signal;
+        return reject(err2);
+      }
+      if (code === 0) {
+        return resolve2({ stdout, stderr });
+      }
+      const err = new Error(
+        `docker subprocess exited with ${code !== null ? `code ${code}` : `signal ${signal}`}`
+      );
+      err.stdout = stdout;
+      err.stderr = stderr;
+      if (code !== null) err.code = code;
+      if (signal !== null) err.signal = signal;
+      reject(err);
+    });
+  });
+}
+var TOWN_RELAY_PORT = 7100;
+var STATS_CACHE_TTL_MS = 5e3;
+var NETWORK_NAME = "townhouse-net";
+var DEFAULT_NODE_IMAGES = {
+  town: "toon:town",
+  mill: "toon:mill",
+  dvm: "toon:dvm"
+};
+var MAX_START_RETRIES = 3;
+var CONNECTOR_INTERNAL_PORT = 3e3;
+var RELAY_ATOR_SIDECAR_IMAGE = "toon:townhouse-ator-sidecar";
+var RELAY_ATOR_SOCKS_PORT = 9051;
+var OrchestratorError = class extends Error {
+  service;
+  exitCode;
+  stderr;
+  constructor(message, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : void 0);
+    this.name = "OrchestratorError";
+    if (options.service !== void 0) this.service = options.service;
+    if (options.exitCode !== void 0) this.exitCode = options.exitCode;
+    if (options.stderr !== void 0) this.stderr = options.stderr;
+  }
+};
+function redactSecretsInComposeStderr(stderr) {
+  const SECRET_KEYS2 = [
+    "TOWN_SECRET_KEY",
+    "MILL_SECRET_KEY",
+    "DVM_SECRET_KEY",
+    "TOWN_SETTLEMENT_PRIVATE_KEY",
+    "MILL_SETTLEMENT_PRIVATE_KEY",
+    "DVM_SETTLEMENT_PRIVATE_KEY",
+    "MILL_MNEMONIC",
+    "TOWNHOUSE_WALLET_PASSWORD"
+  ];
+  const pattern = new RegExp(`(${SECRET_KEYS2.join("|")})=[^\\s"'\\n\\r]+`, "g");
+  return stderr.replace(pattern, "$1=[REDACTED]");
+}
+function normalizeImageTag(image) {
+  const lastSlash = image.lastIndexOf("/");
+  const nameAndTag = lastSlash >= 0 ? image.slice(lastSlash + 1) : image;
+  if (nameAndTag.includes(":")) {
+    return image;
+  }
+  return `${image}:latest`;
+}
+var DockerOrchestrator = class extends EventEmitter {
+  docker;
+  config;
+  configGenerator;
+  walletManager;
+  activeNodes = [];
+  statsCache = /* @__PURE__ */ new Map();
+  profile;
+  composePath;
+  execFileAsync;
+  adminClientFactory;
+  constructor(docker, config, walletManager, options = {}) {
+    super();
+    this.docker = docker;
+    this.config = config;
+    this.configGenerator = new ConnectorConfigGenerator(config);
+    this.walletManager = walletManager;
+    this.profile = options.profile ?? "dev";
+    const trimmedComposePath = options.composePath?.trim();
+    this.composePath = trimmedComposePath !== void 0 && trimmedComposePath.length > 0 ? trimmedComposePath : void 0;
+    this.execFileAsync = options.execFileAsync ?? runDockerCompose;
+    this.adminClientFactory = options.adminClientFactory ?? ((url, t) => new ConnectorAdminClient(url, t));
+    if (this.profile === "hs" && !this.composePath) {
+      throw new OrchestratorError(
+        `profile: 'hs' requires a non-empty composePath. Pass options.composePath pointing at the rendered HS template (typically the composePath returned by materializeComposeTemplate('hs')).`
+      );
+    }
+  }
+  /**
+   * Orchestrate full startup sequence. Branches on profile:
+   * - 'dev' (default): dockerode-based, preserves existing dev-stack behavior
+   * - 'hs': docker compose subprocess + HS hostname readiness gate
+   */
+  async up(profiles) {
+    if (this.profile === "hs") {
+      await this.upHs(profiles);
+      this.activeNodes = [...profiles];
+    } else {
+      this.activeNodes = [...profiles];
+      await this.upDev(profiles);
+    }
+  }
+  async upDev(profiles) {
+    await this.ensureNetwork();
+    await this.pullImages(profiles);
+    await this.startConnector();
+    await this.waitForHealth("townhouse-connector");
+    await Promise.all(profiles.map((type) => this.startNode(type)));
+    if (profiles.includes("town") && this.config.transport.relayHiddenService) {
+      await this.startRelayAtorSidecar();
+    }
+  }
+  /**
+   * Narrow `this.composePath` to a definite string. The constructor enforces
+   * this invariant for `profile: 'hs'`; this helper exists so the HS-path
+   * methods don't need a non-null assertion (lint-clean) and so a constructor
+   * regression surfaces as an `OrchestratorError` rather than a `TypeError`.
+   */
+  requireComposePath() {
+    if (!this.composePath) {
+      throw new OrchestratorError(
+        `internal: composePath unset for HS profile (constructor invariant violated)`
+      );
+    }
+    return this.composePath;
+  }
+  /**
+   * validate that composePath is absolute and exists on disk before
+   * passing it to any subprocess call. Defence-in-depth — callers pass paths
+   * from materializeComposeTemplate so this should never fire in normal use.
+   */
+  validateComposePath(composePath) {
+    if (!isAbsolute(composePath)) {
+      throw new OrchestratorError(
+        `composePath must be an absolute path, got: ${composePath}`
+      );
+    }
+    if (!existsSync(composePath)) {
+      throw new OrchestratorError(
+        `composePath does not exist on disk: ${composePath}`
+      );
+    }
+  }
+  /** HS-mode startup: shell out to `docker compose up -d`, wait for HS hostname. */
+  async upHs(profiles) {
+    const composePath = this.requireComposePath();
+    this.validateComposePath(composePath);
+    const PROFILE_ORDER = ["town", "mill", "dvm"];
+    for (const p of profiles) {
+      if (!PROFILE_ORDER.includes(p)) {
+        throw new OrchestratorError(
+          `Unknown profile '${String(p)}'. Expected one of: ${PROFILE_ORDER.join(", ")}.`
+        );
+      }
+    }
+    const args = ["compose", "-f", composePath];
+    for (const type of PROFILE_ORDER) {
+      if (profiles.includes(type)) {
+        args.push("--profile", type);
+      }
+    }
+    args.push("up", "-d");
+    try {
+      await this.execFileAsync("docker", args, {
+        timeout: 18e4,
+        maxBuffer: 16 * 1024 * 1024,
+        inheritStdio: true
+      });
+    } catch (err) {
+      const e = err;
+      const stderr = String(e.stderr ?? "");
+      const numericExit = typeof e.code === "number" ? e.code : void 0;
+      const codeLabel = String(e.code ?? e.signal ?? "unknown");
+      let message;
+      if (e.code === "ENOENT") {
+        message = `docker CLI not found on PATH (ENOENT): ${stderr.trim().slice(0, 2e3)}`;
+      } else if (e.code === "ETIMEDOUT") {
+        message = `docker compose up timed out after 180000ms: ${stderr.trim().slice(0, 2e3)}`;
+      } else {
+        message = `docker compose up failed (exit ${codeLabel}): ${stderr.trim().slice(0, 2e3)}`;
+      }
+      this.surfaceComposeFailure(stderr);
+      throw new OrchestratorError(message, {
+        ...numericExit !== void 0 ? { exitCode: numericExit } : {},
+        stderr,
+        cause: err instanceof Error ? err : void 0
+      });
+    }
+    try {
+      await this.waitForHsHostname();
+    } catch (err) {
+      await this.downHs().catch(() => {
+      });
+      throw err;
+    }
+  }
+  /**
+   * Parse Docker Compose stderr for failed-service names and emit a
+   * containerState event per failed service so callers see the failure via
+   * the same channel dev-mode uses (AC #6 — "for each failed service
+   * identified, it emits..."). When no pattern matches, emit a single
+   * fallback event with name `'compose-up'`.
+   */
+  surfaceComposeFailure(stderr) {
+    const patterns = [
+      /failed to start (?:service\s+)?["']([^"']+)["']/gi,
+      /service\s+["']([^"']+)["']\s+failed/gi,
+      /Container\s+[\w-]+-([a-z][\w-]*?)(?:-\d+)?\s+Error/gi
+    ];
+    const detail = stderr.trim().slice(0, 2e3);
+    const seen = /* @__PURE__ */ new Set();
+    for (const pattern of patterns) {
+      for (const match of stderr.matchAll(pattern)) {
+        const name = match[1];
+        if (name && !seen.has(name)) {
+          seen.add(name);
+          this.emit("containerState", { name, state: "error", detail });
+        }
+      }
+    }
+    if (seen.size === 0) {
+      this.emit("containerState", {
+        name: "compose-up",
+        state: "error",
+        detail
+      });
+    }
+  }
+  async waitForHsHostname() {
+    const adminUrl = `http://127.0.0.1:${this.config.connector.adminPort}`;
+    const client = this.adminClientFactory(adminUrl, 5e3);
+    const deadlineNs = process.hrtime.bigint() + 120000000000n;
+    const pollInterval = 2e3;
+    let lastResponse;
+    let lastError;
+    while (process.hrtime.bigint() < deadlineNs) {
+      try {
+        lastResponse = await client.getHsHostname();
+        lastError = void 0;
+        if (lastResponse.hostname !== null && lastResponse.publishedAt !== null) {
+          return;
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (msg.includes("anon-disabled")) {
+          throw new OrchestratorError(
+            `connector is anon-disabled \u2014 set anon.enabled: true in the connector config`,
+            { cause: err instanceof Error ? err : void 0 }
+          );
+        }
+        if (msg.includes("invalid hs-hostname response shape") || msg.includes("invalid JSON in hs-hostname response")) {
+          throw new OrchestratorError(
+            `connector returned a malformed /admin/hs-hostname response: ${msg}`,
+            { cause: err instanceof Error ? err : void 0 }
+          );
+        }
+        if (msg.includes("unexpected status")) {
+          throw new OrchestratorError(msg, {
+            cause: err instanceof Error ? err : void 0
+          });
+        }
+      }
+      await new Promise((r) => setTimeout(r, pollInterval));
+    }
+    const tail = lastError ? ` (last error: ${lastError.message})` : lastResponse ? ` (last response: ${JSON.stringify(lastResponse)})` : " (no successful response received)";
+    throw new OrchestratorError(
+      `HS hostname publication timeout after 120000ms` + tail,
+      lastError ? { cause: lastError } : {}
+    );
+  }
+  /**
+   * Regenerate connector config and restart the connector container
+   * with updated environment variables (peer list).
+   *
+   * Sequence: emit connectorRestarting -> stop -> remove -> create -> start -> health -> emit connectorRestarted
+   */
+  async regenerateConnectorConfig(activeNodes) {
+    this.activeNodes = [...activeNodes];
+    this.emit("connectorRestarting", { reason: "peer list updated" });
+    const connectorName = `${CONTAINER_PREFIX}connector`;
+    const existingContainer = this.docker.getContainer(connectorName);
+    try {
+      await existingContainer.stop({ t: 5 });
+    } catch {
+    }
+    try {
+      await existingContainer.remove();
+    } catch {
+    }
+    await this.ensureNetwork();
+    try {
+      await this.startConnector();
+      await this.waitForHealth(connectorName);
+    } finally {
+      this.emit("connectorRestarted", { peers: activeNodes });
+    }
+  }
+  /**
+   * Hot-add a node after initial startup.
+   * Starts the node container, then restarts the connector with updated peer list.
+   */
+  async addNode(type) {
+    if (!this.activeNodes.includes(type)) {
+      this.activeNodes.push(type);
+    }
+    await this.startNode(type);
+    await this.regenerateConnectorConfig(this.activeNodes);
+  }
+  /**
+   * Hot-remove a node.
+   * Stops the node container, then restarts the connector with updated peer list.
+   */
+  async removeNode(type) {
+    this.activeNodes = this.activeNodes.filter((n) => n !== type);
+    const containerName = `${CONTAINER_PREFIX}${type}`;
+    await this.stopAndRemove(containerName);
+    await this.regenerateConnectorConfig(this.activeNodes);
+  }
+  /**
+   * Graceful shutdown. Branches on profile:
+   * - 'dev' (default): dockerode-based teardown
+   * - 'hs': docker compose subprocess
+   */
+  async down() {
+    if (this.profile === "hs") {
+      await this.downHs();
+    } else {
+      await this.downDev();
+    }
+  }
+  async downDev() {
+    const containers = await this.docker.listContainers({ all: true });
+    const nodeContainerNames = [];
+    let connectorName;
+    for (const info of containers) {
+      for (const name of info.Names) {
+        const cleanName = name.startsWith("/") ? name.slice(1) : name;
+        if (!cleanName.startsWith(CONTAINER_PREFIX)) continue;
+        if (cleanName === `${CONTAINER_PREFIX}connector`) {
+          connectorName = cleanName;
+        } else {
+          nodeContainerNames.push(cleanName);
+        }
+      }
+    }
+    await Promise.all(
+      nodeContainerNames.map((name) => this.stopAndRemove(name))
+    );
+    if (connectorName) {
+      await this.stopAndRemove(connectorName);
+    }
+    await this.removeNetwork();
+  }
+  async downHs() {
+    const composePath = this.requireComposePath();
+    const args = ["compose", "-f", composePath, "down"];
+    try {
+      await this.execFileAsync("docker", args, {
+        timeout: 12e4,
+        maxBuffer: 16 * 1024 * 1024
+      });
+    } catch (err) {
+      const e = err;
+      const stderr = String(e.stderr ?? "");
+      const numericExit = typeof e.code === "number" ? e.code : void 0;
+      const codeLabel = String(e.code ?? e.signal ?? "unknown");
+      let message;
+      if (e.code === "ENOENT") {
+        message = `docker CLI not found on PATH (ENOENT): ${stderr.trim().slice(0, 2e3)}`;
+      } else if (e.code === "ETIMEDOUT") {
+        message = `docker compose down timed out after 120000ms: ${stderr.trim().slice(0, 2e3)}`;
+      } else {
+        if (stderr.includes("no such service") || stderr.includes("no containers to remove") || stderr.includes("No such container") || stderr.includes("network") && stderr.includes("not found")) {
+          return;
+        }
+        message = `docker compose down failed (exit ${codeLabel}): ${stderr.trim().slice(0, 2e3)}`;
+      }
+      throw new OrchestratorError(message, {
+        ...numericExit !== void 0 ? { exitCode: numericExit } : {},
+        stderr,
+        cause: err instanceof Error ? err : void 0
+      });
+    }
+  }
+  /**
+   * Resolve the Nostr relay WebSocket URL for a Town node instance.
+   *
+   * Inspects the container's port bindings to get the host-bound port for
+   * the relay WebSocket (7100/tcp). Falls back to the Docker-internal URL
+   * when the server is running inside the Docker network or bindings are absent.
+   *
+   * @param nodeId - The `NodeInfo.id` value (e.g. 'town', 'dev-town-01')
+   */
+  async getNodeRelayEndpoint(nodeId) {
+    const containerName = `${CONTAINER_PREFIX}${nodeId}`;
+    try {
       const container = this.docker.getContainer(containerName);
       const info = await container.inspect();
       const portBindings = info.HostConfig?.PortBindings;
@@ -4739,18 +5615,158 @@ var DockerOrchestrator = class extends EventEmitter {
     if (profiles.includes("town") && this.config.transport.relayHiddenService) {
       imagesToPull.add(normalizeImageTag(RELAY_ATOR_SIDECAR_IMAGE));
     }
+    for (const image of imagesToPull) {
+      await this.pullImage(image);
+    }
+  }
+  /**
+   * Pull a single image by its reference (tag or digest form).
+   *
+   * Skips the pull when the image already exists locally (matches against
+   * both RepoTags and RepoDigests so digest-form refs like
+   * `ghcr.io/toon-protocol/town@sha256:abc...` are found correctly).
+   * Throws `OrchestratorError` on pull failure.
+   */
+  async pullImage(image) {
     const existingImages = await this.docker.listImages();
     const existingRefs = /* @__PURE__ */ new Set();
     for (const img of existingImages) {
       for (const tag of img.RepoTags ?? []) existingRefs.add(tag);
       for (const digest of img.RepoDigests ?? []) existingRefs.add(digest);
     }
-    for (const image of imagesToPull) {
-      if (existingRefs.has(image)) {
-        continue;
-      }
+    if (existingRefs.has(image)) {
+      return;
+    }
+    try {
       const stream = await this.docker.pull(image);
       await this.followPullProgress(image, stream);
+    } catch (err) {
+      throw new OrchestratorError(
+        `Failed to pull image ${image}: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err instanceof Error ? err : void 0 }
+      );
+    }
+  }
+  /**
+   * Start a child peer node via `docker compose --profile <type> up -d <type>`.
+   *
+   * HS-profile only — throws `OrchestratorError` when called on the dev profile.
+   *
+   * The `env` parameter supplies the per-node wallet secrets (e.g.
+   * `TOWN_SECRET_KEY`, `MILL_MNEMONIC`). It is layered on top of `process.env`
+   * so that PATH, HOME, and other process-level env vars are preserved for the
+   * docker CLI subprocess.
+   *
+   * Logging guard: the caller (nodes-lifecycle route) must NOT log the `env`
+   * argument — it contains secret keys and the wallet mnemonic.
+   */
+  async startNodeViaCompose(type, env) {
+    if (this.profile === "dev") {
+      throw new OrchestratorError(
+        `startNodeViaCompose is only available in HS profile; current profile is 'dev'`
+      );
+    }
+    const composePath = this.requireComposePath();
+    this.validateComposePath(composePath);
+    const args = [
+      "compose",
+      "-f",
+      composePath,
+      "--profile",
+      type,
+      "up",
+      "-d",
+      type
+    ];
+    try {
+      await this.execFileAsync("docker", args, {
+        timeout: 18e4,
+        maxBuffer: 16 * 1024 * 1024,
+        inheritStdio: true,
+        // Layer node secrets on top of process.env — preserves PATH, HOME, etc.
+        env: { ...process.env, ...env }
+      });
+    } catch (err) {
+      const e = err;
+      const stderr = redactSecretsInComposeStderr(String(e.stderr ?? ""));
+      const numericExit = typeof e.code === "number" ? e.code : void 0;
+      const codeLabel = String(e.code ?? e.signal ?? "unknown");
+      let message;
+      if (e.code === "ENOENT") {
+        message = `docker CLI not found on PATH (ENOENT): ${stderr.trim().slice(0, 2e3)}`;
+      } else if (e.code === "ETIMEDOUT") {
+        message = `docker compose up timed out after 180000ms: ${stderr.trim().slice(0, 2e3)}`;
+      } else {
+        message = `docker compose up failed (exit ${codeLabel}): ${stderr.trim().slice(0, 2e3)}`;
+      }
+      this.surfaceComposeFailure(stderr);
+      throw new OrchestratorError(message, {
+        ...numericExit !== void 0 ? { exitCode: numericExit } : {},
+        stderr,
+        cause: err instanceof Error ? err : void 0
+      });
+    }
+  }
+  /**
+   * Stop and remove a child peer node via `docker compose stop` + `rm -f`.
+   *
+   * HS-profile only — throws `OrchestratorError` when called on the dev profile.
+   * Idempotent: stderr patterns indicating the service/container is already gone
+   * (`'no such service'`, `'no containers to remove'`, `'No such container'`)
+   * are treated as success so callers can run this as a rollback without
+   * worrying about the container's prior state.
+   */
+  async stopNodeViaCompose(type) {
+    if (this.profile === "dev") {
+      throw new OrchestratorError(
+        `stopNodeViaCompose is only available in HS profile; current profile is 'dev'`
+      );
+    }
+    const composePath = this.requireComposePath();
+    const idempotentStderr = (stderr) => stderr.includes("no such service") || stderr.includes("no containers to remove") || stderr.includes("No such container");
+    try {
+      await this.execFileAsync(
+        "docker",
+        ["compose", "-f", composePath, "--profile", type, "stop", type],
+        { timeout: 6e4, maxBuffer: 16 * 1024 * 1024 }
+      );
+    } catch (err) {
+      const e = err;
+      const stderr = redactSecretsInComposeStderr(String(e.stderr ?? ""));
+      if (!idempotentStderr(stderr)) {
+        const numericExit = typeof e.code === "number" ? e.code : void 0;
+        const codeLabel = String(e.code ?? "unknown");
+        throw new OrchestratorError(
+          `docker compose stop failed (exit ${codeLabel}): ${stderr.trim().slice(0, 2e3)}`,
+          {
+            ...numericExit !== void 0 ? { exitCode: numericExit } : {},
+            stderr,
+            cause: err instanceof Error ? err : void 0
+          }
+        );
+      }
+    }
+    try {
+      await this.execFileAsync(
+        "docker",
+        ["compose", "-f", composePath, "--profile", type, "rm", "-f", type],
+        { timeout: 6e4, maxBuffer: 16 * 1024 * 1024 }
+      );
+    } catch (err) {
+      const e = err;
+      const stderr = redactSecretsInComposeStderr(String(e.stderr ?? ""));
+      if (!idempotentStderr(stderr)) {
+        const numericExit = typeof e.code === "number" ? e.code : void 0;
+        const codeLabel = String(e.code ?? "unknown");
+        throw new OrchestratorError(
+          `docker compose rm failed (exit ${codeLabel}): ${stderr.trim().slice(0, 2e3)}`,
+          {
+            ...numericExit !== void 0 ? { exitCode: numericExit } : {},
+            stderr,
+            cause: err instanceof Error ? err : void 0
+          }
+        );
+      }
     }
   }
   /**
@@ -4783,7 +5799,7 @@ var DockerOrchestrator = class extends EventEmitter {
           attempt
         });
       }
-      await new Promise((resolve) => setTimeout(resolve, interval));
+      await new Promise((resolve2) => setTimeout(resolve2, interval));
     }
     throw new Error(
       `Health check timeout: ${containerName} did not become healthy within ${timeout}ms`
@@ -4874,7 +5890,7 @@ var DockerOrchestrator = class extends EventEmitter {
     const name = `${CONTAINER_PREFIX}${type}`;
     const nodeConfig = this.config.nodes[type];
     const image = nodeConfig.image ?? DEFAULT_NODE_IMAGES[type];
-    const env = this.buildNodeEnv(type);
+    const env = await this.buildNodeEnv(type);
     let lastError;
     for (let attempt = 1; attempt <= MAX_START_RETRIES; attempt++) {
       try {
@@ -4984,244 +6000,112 @@ var DockerOrchestrator = class extends EventEmitter {
     } catch {
     }
   }
-  /**
-   * Build environment variables for the connector container.
-   * Delegates to ConnectorConfigGenerator for consistent config generation.
-   */
-  buildConnectorEnv() {
-    const runtimeConfig = this.configGenerator.generate(this.activeNodes);
-    return this.configGenerator.toEnvArray(runtimeConfig);
-  }
-  /**
-   * Build environment variables for a node container.
-   * If a WalletManager is provided, injects per-node identity keys.
-   */
-  buildNodeEnv(type) {
-    const connectorUrl = `ws://${CONTAINER_PREFIX}connector:${CONNECTOR_INTERNAL_PORT}`;
-    const env = [`CONNECTOR_URL=${connectorUrl}`];
-    switch (type) {
-      case "town": {
-        const feePerEvent = this.config.nodes.town.feePerEvent;
-        if (feePerEvent !== void 0) {
-          env.push(`FEE_PER_EVENT=${feePerEvent}`);
-        }
-        const relayHs = this.config.transport.relayHiddenService;
-        if (relayHs?.externalUrl) {
-          env.push(`TOON_EXTERNAL_RELAY_URL=${relayHs.externalUrl}`);
-        }
-        break;
-      }
-      case "mill": {
-        const feeBasisPoints = this.config.nodes.mill.feeBasisPoints;
-        if (feeBasisPoints !== void 0) {
-          env.push(`FEE_BASIS_POINTS=${feeBasisPoints}`);
-        }
-        break;
-      }
-      case "dvm": {
-        const feePerJob = this.config.nodes.dvm.feePerJob;
-        if (feePerJob !== void 0) {
-          env.push(`FEE_PER_JOB=${feePerJob}`);
-        }
-        const kindPricing = this.config.nodes.dvm.kindPricing;
-        if (kindPricing) {
-          for (const [kind, value] of Object.entries(kindPricing)) {
-            env.push(`KIND_PRICING_${kind}=${value}`);
-          }
-        }
-        const turboToken = process.env["TURBO_TOKEN"];
-        if (turboToken) {
-          env.push(`TURBO_TOKEN=${turboToken}`);
-        }
-        break;
-      }
-    }
-    if (this.walletManager) {
-      try {
-        const keys = this.walletManager.getNodeKeys(type);
-        env.push(`NODE_NOSTR_PUBKEY=${keys.nostrPubkey}`);
-        env.push(`NODE_EVM_ADDRESS=${keys.evmAddress}`);
-        const secretHex = Buffer.from(keys.nostrSecretKey).toString("hex");
-        env.push(`NODE_NOSTR_SECRET_KEY=${secretHex}`);
-      } catch {
-      }
-    }
-    return env;
-  }
-  /**
-   * Follow a Docker pull stream and emit progress events.
-   */
-  async followPullProgress(image, stream) {
-    return new Promise((resolve, reject) => {
-      this.docker.modem.followProgress(
-        stream,
-        (err) => {
-          if (err) {
-            reject(err);
-          } else {
-            resolve();
-          }
-        },
-        (event) => {
-          this.emit("pullProgress", {
-            image,
-            status: event.status ?? "",
-            id: event.id,
-            progress: event.progress
-          });
-        }
-      );
-    });
-  }
-};
-
-// src/connector/admin-client.ts
-var DEFAULT_TIMEOUT_MS = 5e3;
-var ConnectorAdminClient = class {
-  baseUrl;
-  timeoutMs;
-  /**
-   * @param baseUrl - Base URL for the connector admin API (e.g., 'http://localhost:9402')
-   * @param timeoutMs - Request timeout in milliseconds (default: 5000)
-   */
-  constructor(baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
-    this.timeoutMs = timeoutMs;
-  }
-  /**
-   * GET /health — returns the connector's HealthStatus from the healthCheckPort server.
-   *
-   * @throws Error when connector is not running, returns non-200, or shape is invalid
-   */
-  async getHealth() {
-    const response = await this.fetch("/health");
-    const body = await response.json();
-    if (typeof body !== "object" || body === null) {
-      throw new Error("Connector admin API: invalid health response shape");
-    }
-    const obj = body;
-    const status = obj["status"];
-    if (status !== "healthy" && status !== "unhealthy" && status !== "starting" && status !== "degraded") {
-      throw new Error("Connector admin API: invalid health response shape");
-    }
-    if (typeof obj["uptime"] !== "number" || typeof obj["peersConnected"] !== "number" || typeof obj["totalPeers"] !== "number" || typeof obj["timestamp"] !== "string") {
-      throw new Error("Connector admin API: invalid health response shape");
-    }
-    return body;
-  }
-  /**
-   * GET /admin/metrics.json — returns the connector's per-peer ILP counters
-   * with an aggregate rollup, mirroring `AdminMetricsJsonResponse`.
-   *
-   * @throws Error when connector is not running, returns non-200, or shape is invalid
-   */
-  async getMetrics() {
-    const response = await this.fetch("/admin/metrics.json");
-    const body = await response.json();
-    if (typeof body !== "object" || body === null) {
-      throw new Error("Connector admin API: invalid metrics response shape");
-    }
-    const obj = body;
-    const aggregate = obj["aggregate"];
-    if (typeof obj["uptimeSeconds"] !== "number" || typeof aggregate !== "object" || aggregate === null || !Array.isArray(obj["peers"]) || typeof obj["timestamp"] !== "string") {
-      throw new Error("Connector admin API: invalid metrics response shape");
-    }
-    const agg = aggregate;
-    if (typeof agg["packetsForwarded"] !== "number" || typeof agg["packetsRejected"] !== "number" || typeof agg["bytesSent"] !== "number") {
-      throw new Error("Connector admin API: invalid metrics response shape");
-    }
-    return body;
-  }
-  /**
-   * GET /admin/peers — returns the connector's peer roster with route counts
-   * and ILP addresses. Returns the unwrapped peers array (the wrapper's
-   * nodeId / peerCount / connectedCount fields are dropped).
-   *
-   * @throws Error when connector is not running, returns non-200, or shape is invalid
-   */
-  async getPeers() {
-    const response = await this.fetch("/admin/peers");
-    const body = await response.json();
-    if (typeof body !== "object" || body === null) {
-      throw new Error("Connector admin API: invalid peers response shape");
-    }
-    const obj = body;
-    if (!Array.isArray(obj["peers"])) {
-      throw new Error("Connector admin API: invalid peers response shape");
-    }
-    return body.peers;
-  }
-  /**
-   * GET /packets — returns the connector's raw packet log filtered by the
-   * given criteria. Used by the timeseries aggregation route (story 21.10).
-   *
-   * Townhouse-Side Contract: see packages/sdk/CONNECTOR_MIGRATION.md §getPacketLog.
-   * If the connector image does not expose GET /packets, this method throws
-   * with a `ConnectorEndpointNotFound` error code so the route can return 503.
-   *
-   * @throws Error with code='ConnectorEndpointNotFound' when connector returns 404
-   * @throws Error when connector is not running, returns non-200, or shape is invalid
-   */
-  async getPacketLog(filter = {}) {
-    const params = new URLSearchParams();
-    if (filter.ilpAddress !== void 0)
-      params.set("ilpAddress", filter.ilpAddress);
-    if (filter.since !== void 0) params.set("since", String(filter.since));
-    if (filter.limit !== void 0) params.set("limit", String(filter.limit));
-    const path = params.toString() ? `/packets?${params.toString()}` : "/packets";
-    let response;
-    try {
-      response = await this.fetch(path);
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error);
-      if (msg.includes("404")) {
-        const err = new Error(
-          "Connector does not expose GET /packets \u2014 endpoint not found"
-        );
-        err.code = "ConnectorEndpointNotFound";
-        throw err;
-      }
-      throw error;
-    }
-    const body = await response.json();
-    if (!Array.isArray(body)) {
-      throw new Error(
-        "Connector admin API: invalid packet log response shape \u2014 expected array"
-      );
-    }
-    return body;
+  /**
+   * Build environment variables for the connector container.
+   * Delegates to ConnectorConfigGenerator for consistent config generation.
+   */
+  buildConnectorEnv() {
+    const runtimeConfig = this.configGenerator.generate(this.activeNodes);
+    return this.configGenerator.toEnvArray(runtimeConfig);
   }
-  // ── Private helpers ──
   /**
-   * Perform an HTTP GET request to the connector admin API.
-   * Wraps fetch with error handling for connection refused and non-200 responses.
+   * Build environment variables for a node container.
+   * If a WalletManager is provided, injects per-node identity keys.
+   *
+   * Async because the DVM path may need to derive an RSA-4096 Arweave key
+   * via `walletManager.ensureArweaveKey('dvm')` — that derivation takes
+   * 5–30s on first call per unlocked wallet (cached thereafter).
    */
-  async fetch(path) {
-    const url = `${this.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-    try {
-      let response;
-      try {
-        response = await fetch(url, { signal: controller.signal });
-      } catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
-          throw new Error(
-            `Connector admin API request timeout after ${this.timeoutMs}ms: ${url}`
-          );
+  async buildNodeEnv(type) {
+    const connectorUrl = `ws://${CONTAINER_PREFIX}connector:${CONNECTOR_INTERNAL_PORT}`;
+    const env = [`CONNECTOR_URL=${connectorUrl}`];
+    switch (type) {
+      case "town": {
+        const feePerEvent = this.config.nodes.town.feePerEvent;
+        if (feePerEvent !== void 0) {
+          env.push(`FEE_PER_EVENT=${feePerEvent}`);
         }
-        const msg = error instanceof Error ? error.message : String(error);
-        throw new Error(`Connector admin API connection refused: ${msg}`);
+        const relayHs = this.config.transport.relayHiddenService;
+        if (relayHs?.externalUrl) {
+          env.push(`TOON_EXTERNAL_RELAY_URL=${relayHs.externalUrl}`);
+        }
+        break;
       }
-      if (!response.ok) {
-        throw new Error(
-          `Connector admin API error: ${response.status} ${response.statusText}`
-        );
+      case "mill": {
+        const feeBasisPoints = this.config.nodes.mill.feeBasisPoints;
+        if (feeBasisPoints !== void 0) {
+          env.push(`FEE_BASIS_POINTS=${feeBasisPoints}`);
+        }
+        break;
+      }
+      case "dvm": {
+        const feePerJob = this.config.nodes.dvm.feePerJob;
+        if (feePerJob !== void 0) {
+          env.push(`FEE_PER_JOB=${feePerJob}`);
+        }
+        const kindPricing = this.config.nodes.dvm.kindPricing;
+        if (kindPricing) {
+          for (const [kind, value] of Object.entries(kindPricing)) {
+            env.push(`KIND_PRICING_${kind}=${value}`);
+          }
+        }
+        if (this.walletManager) {
+          try {
+            console.log(
+              "[orchestrator] Deriving DVM Arweave key (first boot, this can take 5-30s)..."
+            );
+            await this.walletManager.ensureArweaveKey("dvm");
+            const jwk = this.walletManager.getArweaveJwk("dvm");
+            const jwkB64 = Buffer.from(JSON.stringify(jwk), "utf-8").toString(
+              "base64"
+            );
+            env.push(`DVM_ARWEAVE_JWK_B64=${jwkB64}`);
+          } catch {
+          }
+        }
+        const turboToken = process.env["TURBO_TOKEN"];
+        if (turboToken) {
+          env.push(`TURBO_TOKEN=${turboToken}`);
+        }
+        break;
+      }
+    }
+    if (this.walletManager) {
+      try {
+        const keys = this.walletManager.getNodeKeys(type);
+        env.push(`NODE_NOSTR_PUBKEY=${keys.nostrPubkey}`);
+        env.push(`NODE_EVM_ADDRESS=${keys.evmAddress}`);
+        const secretHex = Buffer.from(keys.nostrSecretKey).toString("hex");
+        env.push(`NODE_NOSTR_SECRET_KEY=${secretHex}`);
+      } catch {
       }
-      return response;
-    } finally {
-      clearTimeout(timer);
     }
+    return env;
+  }
+  /**
+   * Follow a Docker pull stream and emit progress events.
+   */
+  async followPullProgress(image, stream) {
+    return new Promise((resolve2, reject) => {
+      this.docker.modem.followProgress(
+        stream,
+        (err) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve2();
+          }
+        },
+        (event) => {
+          this.emit("pullProgress", {
+            image,
+            status: event.status ?? "",
+            id: event.id,
+            progress: event.progress
+          });
+        }
+      );
+    });
   }
 };
 
@@ -5340,7 +6224,7 @@ var TransportProbe = class {
     this.logTransition(prev, this.status, hostPort);
   }
   probeTcp(host, port) {
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const start = Date.now();
       const socket = net.createConnection({ host, port });
       let settled = false;
@@ -5351,7 +6235,7 @@ var TransportProbe = class {
           socket.destroy();
         } catch {
         }
-        resolve(result);
+        resolve2(result);
       };
       const timeout = setTimeout(() => {
         settle({ reachable: false, latencyMs: null, error: "timeout" });
@@ -5371,13 +6255,13 @@ var TransportProbe = class {
     });
   }
   probeDirectLatency() {
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const start = Date.now();
       let settled = false;
       const settle = (ms) => {
         if (settled) return;
         settled = true;
-        resolve(ms);
+        resolve2(ms);
       };
       const isHttps = this.directProbeUrl.startsWith("https://");
       const requester = isHttps ? https : http;
@@ -5404,35 +6288,598 @@ var TransportProbe = class {
           console.debug(
             `[TransportProbe] direct latency probe failed: ${err.code ?? err.message}`
           );
-          settle(null);
+          settle(null);
+        });
+        req.end();
+      } catch (err) {
+        clearTimeout(timeout);
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug(`[TransportProbe] direct latency probe threw: ${msg}`);
+        settle(null);
+      }
+    });
+  }
+  logTransition(prev, next, hostPort) {
+    if (prev.lastProbedAt === 0) return;
+    const target = hostPort ? ` (${hostPort})` : "";
+    if (prev.reachable && !next.reachable) {
+      console.warn(
+        `[TransportProbe] proxy became unreachable${target}: ${next.probeError ?? "unknown"}`
+      );
+    } else if (!prev.reachable && next.reachable) {
+      console.debug(`[TransportProbe] proxy reachable${target}`);
+    }
+  }
+};
+
+// src/connector/hs-config-writer.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync3, chmodSync } from "fs";
+import { join as join3 } from "path";
+import { parse as parse2, stringify as yamlStringify2 } from "yaml";
+var HS_DIR = "/var/lib/anon/hs";
+var HS_PORT = 3e3;
+function writeHsConnectorConfig(configDir, config, options = {}) {
+  const yamlPath = join3(configDir, "connector.yaml");
+  if (!options.force && existsSync2(yamlPath)) {
+    try {
+      const existing = parse2(readFileSync2(yamlPath, "utf-8"));
+      const anon = existing["anon"];
+      if (anon?.["enabled"] === true) {
+        return { yamlPath, created: false };
+      }
+    } catch {
+    }
+  }
+  const hsConfig = config.chainProviders !== void 0 && config.chainProviders.length > 0 ? config : { ...config, chainProviders: [...DEFAULT_HS_CHAIN_PROVIDERS] };
+  const generator = new ConnectorConfigGenerator(hsConfig);
+  const baseConfig = generator.generate([]);
+  const HS_LOCAL_SOCKS_PROXY = "socks5h://127.0.0.1:9050";
+  const hsRuntimeConfig = {
+    ...baseConfig,
+    transport: {
+      mode: "ator",
+      socksProxy: HS_LOCAL_SOCKS_PROXY,
+      externalUrl: "auto",
+      hiddenService: {
+        dir: HS_DIR,
+        port: HS_PORT,
+        // The orchestrator polls getHsHostname() for up to 120s; give the
+        // connector the same budget so the internal timeout doesn't fire first.
+        startupTimeoutMs: 12e4
+      }
+    }
+  };
+  const baseYaml = generator.toYaml(hsRuntimeConfig);
+  const parsed = parse2(baseYaml);
+  parsed["anon"] = { enabled: true };
+  const finalYaml = yamlStringify2(parsed);
+  writeFileSync3(yamlPath, finalYaml, { mode: 384, encoding: "utf-8" });
+  chmodSync(yamlPath, 384);
+  return { yamlPath, created: true };
+}
+
+// src/compose-loader.ts
+import {
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync4,
+  mkdirSync as mkdirSync2,
+  chmodSync as chmodSync2,
+  statSync,
+  lstatSync,
+  existsSync as existsSync3
+} from "fs";
+import { dirname as dirname2, join as join4, resolve, isAbsolute as isAbsolute2 } from "path";
+import { fileURLToPath } from "url";
+import { homedir as homedir2 } from "os";
+var VALID_PROFILES = ["dev", "hs"];
+var ComposeLoaderError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ComposeLoaderError";
+  }
+};
+function defaultDistDir() {
+  const here = dirname2(fileURLToPath(import.meta.url));
+  return resolve(here, "..", "dist");
+}
+function assertValidProfile(profile) {
+  if (!VALID_PROFILES.includes(profile)) {
+    throw new ComposeLoaderError(
+      `invalid compose profile: '${profile}'. Must be one of: ${VALID_PROFILES.join(", ")}.`
+    );
+  }
+}
+var SYSTEM_PATH_PREFIXES = [
+  "/etc",
+  "/usr",
+  "/bin",
+  "/sbin",
+  "/lib",
+  "/lib64",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/boot",
+  "/root"
+];
+function assertValidTownhouseHome(home) {
+  if (!home) {
+    throw new ComposeLoaderError(
+      "townhouseHome resolved to an empty path. Set $HOME or pass options.townhouseHome explicitly."
+    );
+  }
+  if (!isAbsolute2(home)) {
+    throw new ComposeLoaderError(
+      `townhouseHome must be an absolute path; got '${home}'.`
+    );
+  }
+  if (home === "/" || home === "\\") {
+    throw new ComposeLoaderError(
+      `townhouseHome must not be the filesystem root; got '${home}'. This usually means $HOME is unset and homedir() returned '/'.`
+    );
+  }
+  for (const prefix of SYSTEM_PATH_PREFIXES) {
+    if (home === prefix || home.startsWith(prefix + "/")) {
+      throw new ComposeLoaderError(
+        `townhouseHome must not target a system directory; got '${home}'. Allowed paths: under $HOME, under tmpdir(), or any user-writable location.`
+      );
+    }
+  }
+}
+function assertNotSymlink(filePath) {
+  try {
+    const lst = lstatSync(filePath);
+    if (lst.isSymbolicLink()) {
+      throw new ComposeLoaderError(
+        `${filePath} is a symlink; refusing to write through it. If this is intentional, remove the symlink and re-run.`
+      );
+    }
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") throw err;
+  }
+}
+function loadComposeTemplate(profile, options = {}) {
+  assertValidProfile(profile);
+  const distDir = options.distDir ?? defaultDistDir();
+  const composePath = join4(distDir, "compose", `townhouse-${profile}.yml`);
+  if (!existsSync3(composePath)) {
+    throw new ComposeLoaderError(
+      `compose template not found: ${composePath}. Did you run 'pnpm --filter @toon-protocol/townhouse build' first?`
+    );
+  }
+  return readFileSync3(composePath, "utf-8");
+}
+function materializeComposeTemplate(profile, options = {}) {
+  assertValidProfile(profile);
+  const home = options.townhouseHome || join4(homedir2(), ".townhouse");
+  assertValidTownhouseHome(home);
+  const distDir = options.distDir ?? defaultDistDir();
+  const manifestSrc = join4(distDir, "image-manifest.json");
+  if (profile === "hs" && !existsSync3(manifestSrc)) {
+    throw new ComposeLoaderError(
+      `image-manifest.json not found at ${manifestSrc}. HS mode requires a digest-pinned image manifest. Reinstall @toon-protocol/townhouse from npm to restore the manifest.`
+    );
+  }
+  const yaml = loadComposeTemplate(profile, options);
+  const composeDir = join4(home, "compose");
+  mkdirSync2(composeDir, { recursive: true, mode: 448 });
+  for (const dir of [home, composeDir]) {
+    const lst = lstatSync(dir);
+    if (lst.isSymbolicLink()) {
+      const target = statSync(dir);
+      if (!target.isDirectory()) {
+        throw new ComposeLoaderError(
+          `${dir} is a symlink to a non-directory; refusing to materialize.`
+        );
+      }
+      continue;
+    }
+    const currentMode = lst.mode & 511;
+    if ((currentMode & 63) !== 0) {
+      chmodSync2(dir, 448);
+    }
+  }
+  const composePath = join4(composeDir, `townhouse-${profile}.yml`);
+  assertNotSymlink(composePath);
+  writeFileSync4(composePath, yaml, { mode: 384, encoding: "utf-8" });
+  chmodSync2(composePath, 384);
+  const manifestPath = join4(home, "image-manifest.json");
+  if (existsSync3(manifestSrc)) {
+    assertNotSymlink(manifestPath);
+    const manifest = readFileSync3(manifestSrc, "utf-8");
+    writeFileSync4(manifestPath, manifest, { mode: 384, encoding: "utf-8" });
+    chmodSync2(manifestPath, 384);
+  }
+  return { composePath, manifestPath };
+}
+
+// src/state/nodes-yaml.ts
+import { promises as fs } from "fs";
+import { dirname as dirname3 } from "path";
+import { parse as yamlParse, stringify as yamlStringify3 } from "yaml";
+import { z } from "zod";
+var NodesYamlEntrySchema = z.object({
+  id: z.string().min(1),
+  type: z.enum(["town", "mill", "dvm"]),
+  peerId: z.string().min(1),
+  ilpAddress: z.string().min(1),
+  derivationIndex: z.number().int().nonnegative(),
+  enabledAt: z.string().datetime({ offset: true }),
+  lastSeenAt: z.string().datetime({ offset: true }).nullable()
+}).strict();
+var NodesYamlSchema = z.object({
+  entries: z.array(NodesYamlEntrySchema)
+}).strict().superRefine((data, ctx) => {
+  const seenPeerIds = /* @__PURE__ */ new Set();
+  const seenDerivationIndexes = /* @__PURE__ */ new Set();
+  for (const [i, e] of data.entries.entries()) {
+    if (seenPeerIds.has(e.peerId)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["entries", i, "peerId"],
+        message: `duplicate peerId: ${e.peerId}`
+      });
+    }
+    seenPeerIds.add(e.peerId);
+    if (seenDerivationIndexes.has(e.derivationIndex)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["entries", i, "derivationIndex"],
+        message: `duplicate derivationIndex: ${e.derivationIndex}`
+      });
+    }
+    seenDerivationIndexes.add(e.derivationIndex);
+  }
+});
+async function readNodesYaml(path) {
+  let raw;
+  try {
+    raw = await fs.readFile(path, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { entries: [] };
+    }
+    throw err;
+  }
+  const parsed = yamlParse(raw);
+  if (parsed === null || parsed === void 0) {
+    return { entries: [] };
+  }
+  return NodesYamlSchema.parse(parsed);
+}
+async function writeNodesYaml(path, data) {
+  const validated = NodesYamlSchema.parse(data);
+  const yamlContent = yamlStringify3(validated);
+  const tmpPath = `${path}.tmp`;
+  await fs.mkdir(dirname3(path), { recursive: true, mode: 448 });
+  await fs.writeFile(tmpPath, yamlContent, { encoding: "utf-8", mode: 384 });
+  await fs.rename(tmpPath, path);
+  await fs.chmod(path, 384);
+}
+
+// src/reconciler.ts
+import { promises as fs2 } from "fs";
+import { dirname as dirname4 } from "path";
+var BootReconciler = class {
+  constructor(adminClient, nodesYamlPath, reconcilerLogPath) {
+    this.adminClient = adminClient;
+    this.nodesYamlPath = nodesYamlPath;
+    this.reconcilerLogPath = reconcilerLogPath;
+  }
+  logDirEnsured = false;
+  logFileChmodEnsured = false;
+  /**
+   * Diff `nodes.yaml` (truth) against `GET /admin/peers` (derived state)
+   * and converge.
+   *
+   * Ordering rule (Epic 46.2 dependency — load-bearing):
+   *   `nodes.yaml` write happens BEFORE connector registration
+   *   (`POST /admin/peers`).
+   *
+   * The drift window resolves in the safe direction:
+   *   - yaml entry without a connector peer = harmless. The reconciler
+   *     re-registers it on next `hs up` (this method does that).
+   *   - connector peer without a yaml entry = treated as `'external'` and
+   *     left alone (operators may legitimately route non-Townhouse peers
+   *     through the same connector).
+   *
+   * The unsafe direction (register first, then write yaml) creates a
+   * window where the connector routes to a peer Townhouse cannot clean
+   * up. Epic 46.2's provisioning pipeline MUST honor the yaml-first rule.
+   *
+   * Failures fetching `getPeers()` are surfaced (not swallowed) so the
+   * caller in `handleHsUp` can decide whether to treat reconciler
+   * divergence as fatal. (Today: non-fatal — see cli.ts wire point.)
+   *
+   * Per-divergence appendLog failures are caught so a single log-write
+   * failure does not abort the rest of the reconciliation pass.
+   */
+  async reconcile() {
+    const yaml = await readNodesYaml(this.nodesYamlPath);
+    const peers = await this.adminClient.getPeers();
+    const plans = this.diff(yaml, peers);
+    const summary = {
+      reregistered: 0,
+      failed: 0,
+      external: 0
+    };
+    for (const plan of plans) {
+      if (plan.intent === "reregister") {
+        const entry = yaml.entries.find((e) => e.peerId === plan.peerId);
+        if (!entry) continue;
+        try {
+          await this.adminClient.registerPeer({
+            id: entry.peerId,
+            url: deriveBtpUrl(entry),
+            authToken: "",
+            routes: [{ prefix: entry.ilpAddress, priority: 0 }]
+          });
+          summary.reregistered++;
+          await this.tryAppendLog({
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            peerId: plan.peerId,
+            action: "reregistered"
+          });
+        } catch (err) {
+          summary.failed++;
+          const msg = err instanceof Error ? err.message : String(err);
+          await this.tryAppendLog({
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            peerId: plan.peerId,
+            action: "reregister-failed",
+            detail: msg
+          });
+        }
+      } else {
+        summary.external++;
+        await this.tryAppendLog({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          peerId: plan.peerId,
+          action: "external"
+        });
+      }
+    }
+    return summary;
+  }
+  /**
+   * Compute divergences without mutating the connector. Exposed for
+   * testability — production callers use `reconcile()`.
+   */
+  diff(yaml, peers) {
+    const peerIds = new Set(peers.map((p) => p.id));
+    const yamlPeerIds = new Set(yaml.entries.map((e) => e.peerId));
+    const out = [];
+    for (const entry of yaml.entries) {
+      if (!peerIds.has(entry.peerId)) {
+        out.push({ peerId: entry.peerId, intent: "reregister" });
+      }
+    }
+    for (const peer of peers) {
+      if (!yamlPeerIds.has(peer.id)) {
+        out.push({ peerId: peer.id, intent: "external" });
+      }
+    }
+    return out;
+  }
+  /**
+   * Append one divergence record without aborting the whole reconciliation
+   * pass on a single log-write failure (disk full, EACCES, etc.). Failures
+   * are themselves logged to stderr — not silently swallowed — so the
+   * operator can see them in the same `hs up` session.
+   */
+  async tryAppendLog(div) {
+    try {
+      await this.appendLog(div);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[townhouse boot-reconciler] failed to append divergence log: ${msg}`
+      );
+    }
+  }
+  /**
+   * Append one divergence record to the reconciler log as a single line of
+   * JSON (jsonl-style — easy to grep, easy to parse).
+   *
+   * `mkdir` runs once per reconciler instance. `chmod 0o600` on the log file
+   * also runs once — `fs.appendFile`'s `mode` option only applies on
+   * creation, so without a post-create chmod a pre-existing log file with
+   * permissive mode would never be tightened.
+   */
+  async appendLog(div) {
+    const line = JSON.stringify(div) + "\n";
+    if (!this.logDirEnsured) {
+      await fs2.mkdir(dirname4(this.reconcilerLogPath), {
+        recursive: true,
+        mode: 448
+      });
+      this.logDirEnsured = true;
+    }
+    await fs2.appendFile(this.reconcilerLogPath, line, {
+      encoding: "utf-8",
+      mode: 384
+    });
+    if (!this.logFileChmodEnsured) {
+      try {
+        await fs2.chmod(this.reconcilerLogPath, 384);
+      } catch {
+      }
+      this.logFileChmodEnsured = true;
+    }
+  }
+};
+function deriveBtpUrl(entry) {
+  return `ws://${CONTAINER_PREFIX}${entry.type}:${NODE_BTP_PORT}`;
+}
+
+// src/earnings/snapshot-writer.ts
+import { promises as fs3 } from "fs";
+import { dirname as dirname5 } from "path";
+var SnapshotWriter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  timer = null;
+  tickPending = false;
+  start() {
+    if (this.timer !== null) return;
+    const intervalMs = this.opts.tickIntervalMs ?? 36e5;
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, intervalMs);
+    if (this.opts.fireOnStart) {
+      void this.tick();
+    }
+  }
+  stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /** Exposed for test ergonomics — runs one full append+prune cycle. */
+  async tick() {
+    if (this.tickPending) {
+      this.opts.logger?.warn(
+        { snapshotPath: this.opts.snapshotPath },
+        "snapshot writer: tick skipped \u2014 previous tick still in flight"
+      );
+      return;
+    }
+    this.tickPending = true;
+    try {
+      await this.runTick();
+    } finally {
+      this.tickPending = false;
+    }
+  }
+  async runTick() {
+    const now = (this.opts.now ?? (() => /* @__PURE__ */ new Date()))();
+    const tsMs = Math.floor(now.getTime() / 36e5) * 36e5;
+    const ts = new Date(tsMs).toISOString();
+    let earnings;
+    try {
+      earnings = await this.opts.connectorAdmin.getEarnings();
+    } catch (err) {
+      this.opts.logger?.warn(
+        { err },
+        "snapshot writer: getEarnings failed \u2014 skipping this tick"
+      );
+      return;
+    }
+    try {
+      const entries = [];
+      for (const peer of earnings.peers ?? []) {
+        if (peer.peerId === "__apex__") {
+          this.opts.logger?.warn(
+            { peerId: peer.peerId },
+            'snapshot writer: peer with reserved id "__apex__" \u2014 row dropped'
+          );
+          continue;
+        }
+        for (const a of peer.byAsset ?? []) {
+          entries.push({
+            ts,
+            peerId: peer.peerId,
+            assetCode: a.assetCode,
+            claimsReceivedTotal: a.claimsReceivedTotal
+          });
+        }
+      }
+      for (const fee of earnings.connectorFees ?? []) {
+        entries.push({
+          ts,
+          peerId: "__apex__",
+          assetCode: fee.assetCode,
+          claimsReceivedTotal: fee.total
         });
-        req.end();
-      } catch (err) {
-        clearTimeout(timeout);
-        const msg = err instanceof Error ? err.message : String(err);
-        console.debug(`[TransportProbe] direct latency probe threw: ${msg}`);
-        settle(null);
       }
+      if (entries.length === 0) {
+        await this.pruneIfNeeded(now);
+        return;
+      }
+      await this.appendEntries(entries);
+      await this.pruneIfNeeded(now);
+    } catch (err) {
+      this.opts.logger?.warn(
+        { err },
+        "snapshot writer: append/prune failed \u2014 skipping this tick"
+      );
+    }
+  }
+  async appendEntries(entries) {
+    await fs3.mkdir(dirname5(this.opts.snapshotPath), {
+      recursive: true,
+      mode: 448
+    });
+    const body = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    await fs3.appendFile(this.opts.snapshotPath, body, {
+      encoding: "utf-8",
+      mode: 384
     });
+    await fs3.chmod(this.opts.snapshotPath, 384);
   }
-  logTransition(prev, next, hostPort) {
-    if (prev.lastProbedAt === 0) return;
-    const target = hostPort ? ` (${hostPort})` : "";
-    if (prev.reachable && !next.reachable) {
-      console.warn(
-        `[TransportProbe] proxy became unreachable${target}: ${next.probeError ?? "unknown"}`
-      );
-    } else if (!prev.reachable && next.reachable) {
-      console.debug(`[TransportProbe] proxy reachable${target}`);
+  async pruneIfNeeded(now) {
+    const WATERMARK = 256 * 1024;
+    let stat3 = null;
+    try {
+      stat3 = await fs3.stat(this.opts.snapshotPath);
+    } catch {
+      return;
+    }
+    if (stat3.size < WATERMARK) return;
+    const retentionMonths = this.opts.retentionMonths ?? 13;
+    const cutoff = new Date(now);
+    cutoff.setUTCMonth(cutoff.getUTCMonth() - retentionMonths);
+    const cutoffMs = cutoff.getTime();
+    let raw;
+    try {
+      raw = await fs3.readFile(this.opts.snapshotPath, "utf-8");
+    } catch {
+      return;
+    }
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    let anyDropped = false;
+    const kept = [];
+    for (const line of lines) {
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        anyDropped = true;
+        continue;
+      }
+      if (!isSnapshotEntry(entry)) {
+        anyDropped = true;
+        continue;
+      }
+      const entryMs = new Date(entry.ts).getTime();
+      if (isNaN(entryMs) || entryMs < cutoffMs) {
+        anyDropped = true;
+      } else {
+        kept.push(line);
+      }
     }
+    if (!anyDropped) return;
+    const tmpPath = `${this.opts.snapshotPath}.tmp`;
+    const newContent = kept.length > 0 ? kept.join("\n") + "\n" : "";
+    await fs3.writeFile(tmpPath, newContent, { encoding: "utf-8", mode: 384 });
+    await fs3.rename(tmpPath, this.opts.snapshotPath);
+    await fs3.chmod(this.opts.snapshotPath, 384);
   }
 };
+function isSnapshotEntry(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const e = v;
+  return typeof e["ts"] === "string" && typeof e["peerId"] === "string" && typeof e["assetCode"] === "string" && typeof e["claimsReceivedTotal"] === "string";
+}
 
 // src/wallet/storage.ts
 import { writeFile, readFile, mkdir, stat } from "fs/promises";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname6 } from "path";
 async function saveWallet(path, encrypted) {
-  const dir = dirname2(path);
+  const dir = dirname6(path);
   await mkdir(dir, { recursive: true, mode: 448 });
   const data = JSON.stringify(encrypted, null, 2);
   await writeFile(path, data, { encoding: "utf-8", mode: 384 });
@@ -5534,6 +6981,115 @@ function decryptWallet(encrypted, password) {
     key.fill(0);
   }
 }
+function encryptString(plaintext, password) {
+  const salt = randomBytes(SALT_LEN);
+  const iv = randomBytes(IV_LEN);
+  const key = scryptSync(password, salt, SCRYPT_KEY_LEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM
+  });
+  try {
+    const cipher = createCipheriv("aes-256-gcm", key, iv, {
+      authTagLength: AUTH_TAG_LEN
+    });
+    const ciphertext = Buffer.concat([
+      cipher.update(plaintext, "utf8"),
+      cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    return {
+      salt: salt.toString("base64"),
+      iv: iv.toString("base64"),
+      ciphertext: ciphertext.toString("base64"),
+      tag: tag.toString("base64")
+    };
+  } finally {
+    key.fill(0);
+  }
+}
+function decryptString(encrypted, password) {
+  const salt = Buffer.from(encrypted.salt, "base64");
+  const iv = Buffer.from(encrypted.iv, "base64");
+  const ciphertext = Buffer.from(encrypted.ciphertext, "base64");
+  const tag = Buffer.from(encrypted.tag, "base64");
+  const key = scryptSync(password, salt, SCRYPT_KEY_LEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM
+  });
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", key, iv, {
+      authTagLength: AUTH_TAG_LEN
+    });
+    decipher.setAuthTag(tag);
+    try {
+      const plaintext = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final()
+      ]);
+      return plaintext.toString("utf8");
+    } catch {
+      throw new Error(
+        "Decryption failed: wrong password or corrupted ciphertext"
+      );
+    }
+  } finally {
+    key.fill(0);
+  }
+}
+function encryptArweaveJwk(jwk, password) {
+  return encryptString(JSON.stringify(jwk), password);
+}
+function decryptArweaveJwk(encrypted, password) {
+  const plaintext = decryptString(encrypted, password);
+  let parsed;
+  try {
+    parsed = JSON.parse(plaintext);
+  } catch {
+    throw new Error(
+      "Arweave JWK cache is corrupt: plaintext is not valid JSON"
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || parsed.kty !== "RSA" || typeof parsed.n !== "string" || typeof parsed.e !== "string") {
+    throw new Error(
+      "Arweave JWK cache is corrupt: plaintext is not a well-formed RSA JWK"
+    );
+  }
+  return parsed;
+}
+
+// src/state/image-manifest.ts
+import { promises as fs4 } from "fs";
+import { z as z2 } from "zod";
+var ImageEntrySchema = z2.object({
+  name: z2.string().min(1),
+  tag: z2.string().min(1),
+  digest: z2.string().regex(/^sha256:[0-9a-f]{64}$/)
+}).strict();
+var ImageManifestSchema = z2.object({
+  schemaVersion: z2.literal(1),
+  townhouseVersion: z2.string(),
+  builtAt: z2.string().datetime({ offset: true }),
+  images: z2.object({
+    "townhouse-api": ImageEntrySchema,
+    town: ImageEntrySchema,
+    mill: ImageEntrySchema,
+    dvm: ImageEntrySchema,
+    connector: ImageEntrySchema
+  }).strict()
+}).strict();
+var SYNTHETIC_DIGEST_SENTINEL = "sha256:dead000000000000000000000000000000000000000000000000000000000000";
+function isSyntheticDigest(digest) {
+  return digest === SYNTHETIC_DIGEST_SENTINEL;
+}
+async function readImageManifest(path) {
+  const raw = await fs4.readFile(path, "utf-8");
+  const parsed = JSON.parse(raw);
+  return ImageManifestSchema.parse(parsed);
+}
 
 // src/wallet/manager.ts
 import {
@@ -5547,6 +7103,112 @@ import { getPublicKey } from "nostr-tools/pure";
 import { bytesToHex } from "@noble/hashes/utils";
 import { keccak_256 } from "@noble/hashes/sha3";
 import { secp256k1 } from "@noble/curves/secp256k1";
+import { createPrivateKey, createHash } from "crypto";
+
+// src/wallet/ar-cache.ts
+import { mkdir as mkdir2, readFile as readFile2, stat as stat2, writeFile as writeFile2, unlink } from "fs/promises";
+import { dirname as dirname7 } from "path";
+function arweaveCachePath(encryptedWalletPath) {
+  return `${dirname7(encryptedWalletPath)}/wallet.arweave.enc`;
+}
+async function loadArweaveCacheFile(path) {
+  let data;
+  try {
+    data = await readFile2(path, "utf-8");
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+  try {
+    const stats = await stat2(path);
+    const mode = stats.mode & 511;
+    if (mode & 63) {
+      console.error(
+        `Warning: arweave cache ${path} has permissions ${mode.toString(8)} (should be 600)`
+      );
+    }
+  } catch {
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    throw new Error(
+      `Arweave JWK cache at ${path} is corrupt: not valid JSON. Delete the file and re-run to re-derive.`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || parsed.version !== 1 || typeof parsed.nodes !== "object" || parsed.nodes === null) {
+    throw new Error(
+      `Arweave JWK cache at ${path} is corrupt: unexpected envelope shape. Delete the file and re-run to re-derive.`
+    );
+  }
+  return parsed;
+}
+async function readArweaveJwkFromCache(path, nodeType, password, expectedFingerprint) {
+  const file = await loadArweaveCacheFile(path);
+  if (!file) return { status: "miss" };
+  const entry = file.nodes[nodeType];
+  if (!entry) return { status: "miss" };
+  if (typeof entry.subSeedFingerprint !== "string" || typeof entry.arweaveAddress !== "string" || typeof entry.encryptedJwk !== "object" || entry.encryptedJwk === null) {
+    throw new Error(
+      `Arweave JWK cache entry for ${nodeType} at ${path} is corrupt: missing fields.`
+    );
+  }
+  if (entry.subSeedFingerprint !== expectedFingerprint) {
+    return {
+      status: "stale",
+      cachedFingerprint: entry.subSeedFingerprint,
+      cachedAddress: entry.arweaveAddress
+    };
+  }
+  const jwk = decryptArweaveJwk(entry.encryptedJwk, password);
+  return { status: "hit", jwk, entry };
+}
+async function writeArweaveJwkToCache(path, nodeType, jwk, password, subSeedFingerprint, arweaveAddress) {
+  const existing = await loadArweaveCacheFile(path);
+  const entry = {
+    subSeedFingerprint,
+    arweaveAddress,
+    encryptedJwk: encryptArweaveJwk(jwk, password)
+  };
+  const file = existing ?? {
+    version: 1,
+    nodes: {}
+  };
+  file.nodes[nodeType] = entry;
+  const dir = dirname7(path);
+  await mkdir2(dir, { recursive: true, mode: 448 });
+  await writeFile2(path, JSON.stringify(file, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+}
+async function deleteArweaveJwkFromCache(path, nodeType) {
+  const file = await loadArweaveCacheFile(path);
+  if (!file) return;
+  if (!(nodeType in file.nodes)) return;
+  const { [nodeType]: _removed, ...remaining } = file.nodes;
+  file.nodes = remaining;
+  if (Object.keys(file.nodes).length === 0) {
+    try {
+      await unlink(path);
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        return;
+      }
+      throw err;
+    }
+    return;
+  }
+  await writeFile2(path, JSON.stringify(file, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+}
+
+// src/wallet/manager.ts
 import { deriveMillKeys } from "@toon-protocol/mill";
 var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function base58Encode(bytes) {
@@ -5633,10 +7295,15 @@ var WalletManager = class {
         nostrDerivationPath: keys.nostrDerivationPath,
         evmDerivationPath: keys.evmDerivationPath
       };
-      if (nodeType === "mill") {
-        if (keys.solanaAddress) info.solanaAddress = keys.solanaAddress;
-        if (keys.minaAddress) info.minaAddress = keys.minaAddress;
-      }
+      if (keys.solanaAddress) info.solanaAddress = keys.solanaAddress;
+      if (keys.solanaDerivationPath)
+        info.solanaDerivationPath = keys.solanaDerivationPath;
+      if (nodeType === "mill" && keys.minaAddress) {
+        info.minaAddress = keys.minaAddress;
+      }
+      if (keys.arweaveAddress) info.arweaveAddress = keys.arweaveAddress;
+      if (keys.arweaveDerivationPath)
+        info.arweaveDerivationPath = keys.arweaveDerivationPath;
       return info;
     });
   }
@@ -5657,56 +7324,273 @@ var WalletManager = class {
       const keys = this.state.keys[nodeType];
       keys.nostrSecretKey.fill(0);
       keys.evmPrivateKey.fill(0);
+      if (keys.solanaPrivateKey) keys.solanaPrivateKey.fill(0);
+      if (keys.arweaveJwk) zeroArweaveJwk(keys.arweaveJwk);
     }
     this.state = null;
   }
   /**
-   * Derive keys for all node types from a mnemonic.
+   * Return the BIP-39 mnemonic from in-memory wallet state.
+   * Returns null when the wallet is locked or not initialized.
    */
-  async deriveAllKeys(mnemonic) {
+  getMnemonic() {
+    return this.state?.mnemonic ?? null;
+  }
+  /**
+   * Get derived keys for a specific node type at a given derivation index.
+   *
+   * Pure derivation — does NOT mutate `state`. Re-derives from the stored
+   * mnemonic each time it is called. For every node type, also derives the
+   * Solana key at the same account index. For 'dvm', also derives Arweave.
+   * Throws if the wallet is locked.
+   *
+   * v1 callers MUST pass `derivationIndex = ACCOUNT_INDEX_{type}` for the
+   * first (and only) instance per type. Multi-instance support is out of
+   * scope for v1 — the route layer enforces single-instance-per-type.
+   */
+  async deriveNodeKey(type, derivationIndex) {
+    if (!this.state) {
+      throw new Error(
+        "Wallet not initialized. Call generate() or fromMnemonic() first."
+      );
+    }
+    const mnemonic = this.state.mnemonic;
     let seed;
     try {
       seed = mnemonicToSeedSync(mnemonic);
-      const millBaseKeys = this.deriveNodeKeys(seed, "mill");
+      const baseKeys = this.deriveNodeKeys(seed, type, derivationIndex);
+      const chains = type === "mill" ? ["solana", "mina"] : ["solana"];
       let solanaAddress;
+      let solanaPrivateKey;
+      let solanaDerivationPath;
       let minaAddress;
       try {
-        const millChainKeys = await deriveMillKeys({
+        const chainKeys = await deriveMillKeys({
           mnemonic,
-          chains: ["solana", "mina"],
-          accountIndex: ACCOUNT_INDEX_MILL
+          chains,
+          accountIndex: derivationIndex
         });
-        if (millChainKeys.solana) {
-          solanaAddress = base58Encode(millChainKeys.solana.publicKey);
+        if (chainKeys.solana) {
+          solanaAddress = base58Encode(chainKeys.solana.publicKey);
+          solanaPrivateKey = chainKeys.solana.privateKey;
+          solanaDerivationPath = chainKeys.solana.path;
+        }
+        if (chainKeys.mina && type === "mill") {
+          minaAddress = chainKeys.mina.publicKey;
+        }
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `[WalletManager] deriveMillKeys failed for type=${type} accountIndex=${derivationIndex}: ${errMsg} \u2014 Solana/Mina addresses omitted`
+        );
+      }
+      return {
+        ...baseKeys,
+        solanaAddress,
+        solanaPrivateKey,
+        solanaDerivationPath,
+        minaAddress
+      };
+    } finally {
+      if (seed) seed.fill(0);
+    }
+  }
+  // ── Private-key accessors (epic-49 credit funding) ───────────────────────
+  /**
+   * Returns the EVM private key for a node as a 64-char lowercase hex string.
+   * Throws when the wallet is locked. Callers MUST treat the returned string
+   * as sensitive (no logging, no persisting). The underlying Uint8Array is
+   * still owned by WalletManager and will be zeroed by `lock()`.
+   */
+  getEvmPrivateKeyHex(nodeType) {
+    const keys = this.getNodeKeys(nodeType);
+    return bytesToHex(keys.evmPrivateKey);
+  }
+  /**
+   * Returns the Solana Ed25519 private key seed for a node as a 64-char
+   * lowercase hex string (32 raw seed bytes). Throws when the wallet is
+   * locked or when the Solana key was not derived for this node type.
+   */
+  getSolanaPrivateKeyHex(nodeType) {
+    const keys = this.getNodeKeys(nodeType);
+    if (!keys.solanaPrivateKey) {
+      throw new Error(
+        `Solana private key not available for node '${nodeType}'`
+      );
+    }
+    return bytesToHex(keys.solanaPrivateKey);
+  }
+  /**
+   * Returns the Arweave RSA JWK for a node. Throws when the wallet is locked
+   * or when AR derivation has not yet been triggered for this node type.
+   *
+   * Callers MUST `await ensureArweaveKey(nodeType)` first the first time per
+   * unlock — RSA-4096 derivation is 5–30s and is therefore not done eagerly
+   * at `fromMnemonic`/`generate` time. After the first `ensureArweaveKey`
+   * the JWK is cached on the in-memory state until `lock()`.
+   */
+  getArweaveJwk(nodeType) {
+    const keys = this.getNodeKeys(nodeType);
+    if (!keys.arweaveJwk) {
+      throw new Error(
+        `Arweave JWK not yet derived for node '${nodeType}'. Call ensureArweaveKey('${nodeType}') first (note: derivation takes 5\u201330s).`
+      );
+    }
+    return keys.arweaveJwk;
+  }
+  /**
+   * Lazily derive the Arweave RSA-4096 JWK for a node type and cache it on
+   * the in-memory wallet state. Subsequent calls (within the same unlocked
+   * session) return the cached result without re-deriving.
+   *
+   * Only meaningful for node types that participate in the Arweave credit
+   * flow — `dvm` (account 2) in the current Townhouse layout. Calling on
+   * `town` or `mill` will derive a valid AR key at the corresponding
+   * account index but those keys are not used by any current code path.
+   *
+   * Throws if the wallet is locked or RSA derivation fails (unsupported
+   * platform, etc.). On success the result is also reflected in subsequent
+   * `getAllKeys()` calls (arweaveAddress + arweaveDerivationPath fields).
+   */
+  async ensureArweaveKey(nodeType, password) {
+    if (!this.state) {
+      throw new Error(
+        "Wallet not initialized. Call generate() or fromMnemonic() first."
+      );
+    }
+    const existing = this.state.keys[nodeType].arweaveJwk;
+    if (existing) return existing;
+    const accountIndex = NODE_ACCOUNT_INDEX[nodeType];
+    const path = `m/44'/472'/${accountIndex}'/0/0`;
+    let seed;
+    let subSeed;
+    try {
+      seed = mnemonicToSeedSync(this.state.mnemonic);
+      const hdKey = HDKey.fromMasterSeed(seed).derive(path);
+      if (!hdKey.privateKey) {
+        throw new Error(`Arweave sub-seed missing at ${path}`);
+      }
+      subSeed = new Uint8Array(hdKey.privateKey);
+      const fingerprint = createHash("sha256").update(subSeed).digest("base64url");
+      if (password) {
+        const cachePath = arweaveCachePath(this.config.encryptedPath);
+        const result = await readArweaveJwkFromCache(
+          cachePath,
+          nodeType,
+          password,
+          fingerprint
+        );
+        if (result.status === "hit") {
+          this.state.keys[nodeType].arweaveJwk = result.jwk;
+          this.state.keys[nodeType].arweaveAddress = result.entry.arweaveAddress;
+          this.state.keys[nodeType].arweaveDerivationPath = path;
+          return result.jwk;
+        }
+        if (result.status === "stale") {
+          console.warn(
+            `[WalletManager] Arweave JWK cache for ${nodeType} was written from a different mnemonic (cached address ${result.cachedAddress.slice(0, 12)}\u2026). Discarding and re-deriving.`
+          );
+          await deleteArweaveJwkFromCache(cachePath, nodeType);
+        }
+      }
+      const ar = await deriveArweaveKey(seed, accountIndex);
+      if (!this.state) {
+        zeroArweaveJwk(ar.jwk);
+        throw new Error(
+          "Wallet was locked during Arweave key derivation. Discarding derived key."
+        );
+      }
+      this.state.keys[nodeType].arweaveJwk = ar.jwk;
+      this.state.keys[nodeType].arweaveAddress = ar.address;
+      this.state.keys[nodeType].arweaveDerivationPath = ar.path;
+      if (password) {
+        try {
+          const cachePath = arweaveCachePath(this.config.encryptedPath);
+          await writeArweaveJwkToCache(
+            cachePath,
+            nodeType,
+            ar.jwk,
+            password,
+            fingerprint,
+            ar.address
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.warn(
+            `[WalletManager] Failed to write Arweave JWK cache (non-fatal): ${msg}`
+          );
         }
-        if (millChainKeys.mina) {
-          minaAddress = millChainKeys.mina.publicKey;
+      }
+      return ar.jwk;
+    } finally {
+      if (seed) seed.fill(0);
+      if (subSeed) subSeed.fill(0);
+    }
+  }
+  /**
+   * Derive keys for all node types from a mnemonic.
+   */
+  async deriveAllKeys(mnemonic) {
+    let seed;
+    try {
+      seed = mnemonicToSeedSync(mnemonic);
+      const chainExtras = {
+        town: {},
+        mill: {},
+        dvm: {}
+      };
+      const types = ["town", "mill", "dvm"];
+      for (const nodeType of types) {
+        const accountIndex = NODE_ACCOUNT_INDEX[nodeType];
+        const chains = nodeType === "mill" ? ["solana", "mina"] : ["solana"];
+        try {
+          const chainKeys = await deriveMillKeys({
+            mnemonic,
+            chains,
+            accountIndex
+          });
+          if (chainKeys.solana) {
+            chainExtras[nodeType].solanaAddress = base58Encode(
+              chainKeys.solana.publicKey
+            );
+            chainExtras[nodeType].solanaPrivateKey = chainKeys.solana.privateKey;
+            chainExtras[nodeType].solanaDerivationPath = chainKeys.solana.path;
+          }
+          if (nodeType === "mill" && chainKeys.mina) {
+            chainExtras[nodeType].minaAddress = chainKeys.mina.publicKey;
+          }
+        } catch (err) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          console.warn(
+            `[WalletManager] deriveMillKeys failed for ${nodeType} (accountIndex=${accountIndex}): ${errMsg} \u2014 chain addresses omitted`
+          );
         }
-      } catch {
       }
       const keys = {
-        town: this.deriveNodeKeys(seed, "town"),
-        mill: { ...millBaseKeys, solanaAddress, minaAddress },
-        dvm: this.deriveNodeKeys(seed, "dvm")
+        town: { ...this.deriveNodeKeys(seed, "town"), ...chainExtras.town },
+        mill: { ...this.deriveNodeKeys(seed, "mill"), ...chainExtras.mill },
+        dvm: { ...this.deriveNodeKeys(seed, "dvm"), ...chainExtras.dvm }
       };
-      return { keys };
+      return { keys, mnemonic };
     } finally {
       if (seed) seed.fill(0);
     }
   }
   /**
    * Derive Nostr + EVM keys for a specific node type.
+   * Accepts an optional `accountIndex` to override the default per-type index.
+   * When omitted, uses `NODE_ACCOUNT_INDEX[nodeType]` (existing behavior).
    */
-  deriveNodeKeys(seed, nodeType) {
-    const accountIndex = NODE_ACCOUNT_INDEX[nodeType];
-    const nostrPath = `m/44'/1237'/${accountIndex}'/0/0`;
+  deriveNodeKeys(seed, nodeType, accountIndex) {
+    const idx = accountIndex ?? NODE_ACCOUNT_INDEX[nodeType];
+    const nostrPath = `m/44'/1237'/${idx}'/0/0`;
     const nostrHdKey = HDKey.fromMasterSeed(seed).derive(nostrPath);
     if (!nostrHdKey.privateKey) {
       throw new Error(`Nostr private key missing at ${nostrPath}`);
     }
     const nostrSecretKey = new Uint8Array(nostrHdKey.privateKey);
     const nostrPubkey = getPublicKey(nostrSecretKey);
-    const evmPath = `m/44'/60'/${accountIndex}'/0/0`;
+    const evmPath = `m/44'/60'/${idx}'/0/0`;
     const evmHdKey = HDKey.fromMasterSeed(seed).derive(evmPath);
     if (!evmHdKey.privateKey) {
       throw new Error(`EVM private key missing at ${evmPath}`);
@@ -5723,6 +7607,54 @@ var WalletManager = class {
     };
   }
 };
+async function deriveArweaveKey(seed, accountIndex) {
+  const path = `m/44'/472'/${accountIndex}'/0/0`;
+  const hdKey = HDKey.fromMasterSeed(seed).derive(path);
+  if (!hdKey.privateKey) {
+    throw new Error(`Arweave sub-seed missing at ${path}`);
+  }
+  const subSeed = new Uint8Array(hdKey.privateKey);
+  const { rsaPrivateKeyPemFromSeed } = await import("./rsa-from-seed-VMNLNDZM.js");
+  let pemPrivateKey;
+  try {
+    pemPrivateKey = await rsaPrivateKeyPemFromSeed(subSeed);
+  } finally {
+    subSeed.fill(0);
+  }
+  const keyObject = createPrivateKey({
+    key: pemPrivateKey,
+    format: "pem",
+    type: "pkcs1"
+  });
+  const rawJwk = keyObject.export({ format: "jwk" });
+  if (rawJwk.kty !== "RSA" || !rawJwk.n || !rawJwk.e || !rawJwk.d || !rawJwk.p || !rawJwk.q || !rawJwk.dp || !rawJwk.dq || !rawJwk.qi) {
+    throw new Error(
+      `Arweave JWK conversion produced unexpected shape (kty=${String(rawJwk.kty)}, has-private=${Boolean(rawJwk.d)})`
+    );
+  }
+  const jwk = {
+    kty: "RSA",
+    e: rawJwk.e,
+    n: rawJwk.n,
+    d: rawJwk.d,
+    p: rawJwk.p,
+    q: rawJwk.q,
+    dp: rawJwk.dp,
+    dq: rawJwk.dq,
+    qi: rawJwk.qi
+  };
+  const modulusBytes = Buffer.from(jwk.n, "base64url");
+  const address = createHash("sha256").update(modulusBytes).digest("base64url");
+  return { jwk, address, path };
+}
+function zeroArweaveJwk(jwk) {
+  jwk.d = "";
+  jwk.p = "";
+  jwk.q = "";
+  jwk.dp = "";
+  jwk.dq = "";
+  jwk.qi = "";
+}
 function computeEvmAddress(privateKey) {
   const uncompressed = secp256k1.getPublicKey(privateKey, false);
   const hash = keccak_256(uncompressed.slice(1));
@@ -5741,6 +7673,265 @@ function toChecksumAddress(addressHex) {
   return out;
 }
 
+// src/earnings/aggregator.ts
+var STUB_DELTAS = { today: "0", month: "0", year: "0" };
+async function maybeDeltas(deltaComputer, scope, assetCode, currentLifetime, logger) {
+  if (!deltaComputer) return { ...STUB_DELTAS };
+  try {
+    return await deltaComputer({ scope, assetCode, currentLifetime });
+  } catch (err) {
+    logger?.warn(
+      { err, scope, assetCode },
+      "aggregator: deltaComputer rejected \u2014 stubbing deltas to 0 for this asset"
+    );
+    return { ...STUB_DELTAS };
+  }
+}
+async function aggregateEarnings(input) {
+  let earnings;
+  try {
+    earnings = await input.connectorAdmin.getEarnings();
+  } catch (err) {
+    input.logger?.warn(
+      { err },
+      "aggregator: connectorAdmin.getEarnings failed \u2014 returning status=connector_unavailable"
+    );
+    return {
+      status: "connector_unavailable",
+      apex: { routingFees: {} },
+      peers: [],
+      recentClaims: [],
+      eventsRelayed: 0,
+      uptimeSeconds: 0
+    };
+  }
+  const buildRoutingFees = async () => {
+    const out = {};
+    await Promise.all(
+      earnings.connectorFees.map(async (fee) => {
+        const deltas = await maybeDeltas(
+          input.deltaComputer,
+          "__apex__",
+          fee.assetCode,
+          fee.total,
+          input.logger
+        );
+        out[fee.assetCode] = { lifetime: fee.total, ...deltas };
+      })
+    );
+    return out;
+  };
+  const buildPeers = async () => Promise.all(
+    earnings.peers.map(async (peer) => {
+      const type = input.peerTypeResolver.resolvePeerType(peer.peerId);
+      const byAsset = {};
+      await Promise.all(
+        peer.byAsset.map(async (a) => {
+          const deltas = await maybeDeltas(
+            input.deltaComputer,
+            peer.peerId,
+            a.assetCode,
+            a.claimsReceivedTotal,
+            input.logger
+          );
+          byAsset[a.assetCode] = {
+            lifetime: a.claimsReceivedTotal,
+            ...deltas
+          };
+        })
+      );
+      const lastClaimAt = peer.byAsset.reduce((acc, a) => {
+        const v = a.lastClaimAt;
+        if (!v) return acc;
+        const vMs = Date.parse(v);
+        if (!Number.isFinite(vMs)) return acc;
+        if (acc === null) return v;
+        const accMs = Date.parse(acc);
+        if (!Number.isFinite(accMs)) return v;
+        return vMs > accMs ? v : acc;
+      }, null);
+      return { id: peer.peerId, type, byAsset, lastClaimAt };
+    })
+  );
+  const metricsPromise = input.connectorAdmin.getMetrics().catch((err) => {
+    input.logger?.warn(
+      { err },
+      "aggregator: getMetrics failed \u2014 eventsRelayed/uptimeSeconds defaulting to 0"
+    );
+    return null;
+  });
+  const [routingFees, peers, metricsResult] = await Promise.all([
+    buildRoutingFees(),
+    buildPeers(),
+    metricsPromise
+  ]);
+  const clampInt = (n) => Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+  let eventsRelayed = 0;
+  if (metricsResult) {
+    if (metricsResult.peers.length === 0) {
+      eventsRelayed = clampInt(metricsResult.aggregate.packetsForwarded) + clampInt(metricsResult.aggregate.packetsLocallyDelivered ?? 0);
+    } else {
+      eventsRelayed = metricsResult.peers.reduce(
+        (sum, p) => sum + clampInt(p.packetsForwarded) + clampInt(p.packetsLocallyDelivered ?? 0),
+        0
+      );
+    }
+  }
+  const uptimeSeconds = clampInt(metricsResult?.uptimeSeconds ?? 0);
+  return {
+    status: "ok",
+    apex: { routingFees },
+    peers,
+    recentClaims: earnings.recentClaims,
+    eventsRelayed,
+    uptimeSeconds
+  };
+}
+
+// src/earnings/snapshot-reader.ts
+import { createReadStream } from "fs";
+import { createInterface } from "readline";
+function utcDayBoundary(ref) {
+  const d = new Date(ref);
+  d.setUTCHours(0, 0, 0, 0);
+  return d.toISOString();
+}
+function utcMonthBoundary(ref) {
+  const d = new Date(ref);
+  d.setUTCDate(1);
+  d.setUTCHours(0, 0, 0, 0);
+  return d.toISOString();
+}
+function utcYearBoundary(ref) {
+  const d = new Date(ref);
+  d.setUTCMonth(0, 1);
+  d.setUTCHours(0, 0, 0, 0);
+  return d.toISOString();
+}
+async function readSnapshotMap(snapshotPath, nowMs) {
+  const map = /* @__PURE__ */ new Map();
+  let stream;
+  try {
+    stream = createReadStream(snapshotPath, { encoding: "utf-8" });
+  } catch {
+    return map;
+  }
+  let streamFailed = false;
+  await new Promise((resolve2) => {
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    rl.on("line", (line) => {
+      if (!line.trim()) return;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        return;
+      }
+      if (!isSnapshotEntry2(entry)) return;
+      const tsMs = Date.parse(entry.ts);
+      if (!Number.isFinite(tsMs)) return;
+      if (tsMs > nowMs) return;
+      const key = `${entry.peerId}\0${entry.assetCode}`;
+      let arr = map.get(key);
+      if (!arr) {
+        arr = [];
+        map.set(key, arr);
+      }
+      arr.push(entry);
+    });
+    rl.on("close", resolve2);
+    rl.on("error", () => {
+      streamFailed = true;
+      resolve2();
+    });
+    stream.on("error", () => {
+      streamFailed = true;
+      rl.close();
+      resolve2();
+    });
+  });
+  if (streamFailed) return /* @__PURE__ */ new Map();
+  return map;
+}
+function findBestMatch(entries, boundaryMs) {
+  if (!entries || entries.length === 0) return null;
+  let best = null;
+  let bestMs = -Infinity;
+  for (const e of entries) {
+    const eMs = Date.parse(e.ts);
+    if (!Number.isFinite(eMs)) continue;
+    if (eMs <= boundaryMs && eMs > bestMs) {
+      best = e;
+      bestMs = eMs;
+    }
+  }
+  return best;
+}
+function createDeltaComputer(opts) {
+  return async ({ scope, assetCode, currentLifetime }) => {
+    const ref = (opts.now ?? (() => /* @__PURE__ */ new Date()))();
+    const nowMs = ref.getTime();
+    if (!Number.isFinite(nowMs)) {
+      return { today: "0", month: "0", year: "0" };
+    }
+    const dayMs = Date.parse(utcDayBoundary(ref));
+    const monthMs = Date.parse(utcMonthBoundary(ref));
+    const yearMs = Date.parse(utcYearBoundary(ref));
+    const map = await readSnapshotMap(opts.snapshotPath, nowMs);
+    const key = `${scope}\0${assetCode}`;
+    const entries = map.get(key);
+    const daySnap = findBestMatch(entries, dayMs);
+    const monthSnap = findBestMatch(entries, monthMs);
+    const yearSnap = findBestMatch(entries, yearMs);
+    let cur;
+    try {
+      cur = BigInt(currentLifetime);
+    } catch {
+      return { today: "0", month: "0", year: "0" };
+    }
+    const subOrZero = (snap) => {
+      if (!snap) return "0";
+      try {
+        const base = BigInt(snap.claimsReceivedTotal);
+        if (base < 0n) return "0";
+        const diff = cur - base;
+        return diff < 0n ? "0" : diff.toString();
+      } catch {
+        return "0";
+      }
+    };
+    return {
+      today: subOrZero(daySnap),
+      month: subOrZero(monthSnap),
+      year: subOrZero(yearSnap)
+    };
+  };
+}
+function isSnapshotEntry2(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const e = v;
+  return typeof e["ts"] === "string" && typeof e["peerId"] === "string" && typeof e["assetCode"] === "string" && typeof e["claimsReceivedTotal"] === "string";
+}
+
+// src/registry/peer-type-resolver.ts
+var PeerTypeResolver = class {
+  map;
+  constructor(yaml) {
+    this.map = new Map(yaml.entries.map((e) => [e.peerId, e.type]));
+  }
+  /**
+   * Resolve a connector `peerId` to its operator-declared node type.
+   * Returns `'external'` for unknown peerIds (legitimate non-Townhouse
+   * peers running through the same connector).
+   */
+  resolvePeerType(peerId) {
+    return this.map.get(peerId) ?? "external";
+  }
+};
+
+// src/api/server.ts
+import { join as join8, dirname as dirname11 } from "path";
+
 // ../../node_modules/.pnpm/ws@8.19.0/node_modules/ws/wrapper.mjs
 var import_stream = __toESM(require_stream(), 1);
 var import_receiver = __toESM(require_receiver(), 1);
@@ -5752,6 +7943,7 @@ var import_websocket_server = __toESM(require_websocket_server(), 1);
 import Fastify from "fastify";
 import cors from "@fastify/cors";
 import websocket from "@fastify/websocket";
+import { createRequire as nodeCreateRequire } from "module";
 
 // src/api/cors.ts
 var ALLOWED_ORIGINS = ["localhost", "127.0.0.1", "[::1]", "::1"];
@@ -5781,6 +7973,20 @@ function buildCorsOptions() {
 }
 
 // src/api/build-app.ts
+var STARTED_AT = (/* @__PURE__ */ new Date()).toISOString();
+var _localRequire = nodeCreateRequire(import.meta.url);
+function _loadPackageJson() {
+  for (const rel of ["../package.json", "../../package.json"]) {
+    try {
+      return _localRequire(rel);
+    } catch {
+    }
+  }
+  throw new Error(
+    "build-app.ts: could not resolve package.json from '../package.json' or '../../package.json'. Bundle layout may have changed \u2014 update the resolution ladder."
+  );
+}
+var _pkgVersion = _loadPackageJson()["version"];
 var LOOPBACK_HOSTS = ["127.0.0.1", "::1", "localhost"];
 async function buildFastifyApp(opts = {}) {
   const bindHost = opts.bindHost ?? "127.0.0.1";
@@ -5806,7 +8012,21 @@ async function buildFastifyApp(opts = {}) {
         "res.body.mnemonic",
         "mnemonic",
         "password",
-        "password_confirm"
+        "password_confirm",
+        // Story 46.2: secret-bearing fields introduced by node lifecycle
+        // routes. These never appear in request/response bodies (they go
+        // to subprocess env), but defense-in-depth covers them at every
+        // path Pino might log a stray object (error objects, debug dumps).
+        "nostrSecretKey",
+        "evmPrivateKey",
+        "TOWN_SECRET_KEY",
+        "MILL_SECRET_KEY",
+        "DVM_SECRET_KEY",
+        "TOWN_SETTLEMENT_PRIVATE_KEY",
+        "MILL_SETTLEMENT_PRIVATE_KEY",
+        "DVM_SETTLEMENT_PRIVATE_KEY",
+        "MILL_MNEMONIC",
+        "TOWNHOUSE_WALLET_PASSWORD"
       ],
       censor: "[REDACTED]"
     }
@@ -5845,6 +8065,12 @@ async function buildFastifyApp(opts = {}) {
   });
   await app.register(cors, buildCorsOptions());
   await app.register(websocket);
+  app.get("/health", async () => ({
+    status: "healthy",
+    uptime: Math.floor(process.uptime()),
+    startedAt: STARTED_AT,
+    version: _pkgVersion
+  }));
   return app;
 }
 
@@ -7131,6 +9357,15 @@ function acquireConfigMutex() {
 function releaseConfigMutex() {
   isMutating = false;
 }
+var isNodeLifecycleRunning = false;
+function acquireNodeLifecycleMutex() {
+  if (isNodeLifecycleRunning) return false;
+  isNodeLifecycleRunning = true;
+  return true;
+}
+function releaseNodeLifecycleMutex() {
+  isNodeLifecycleRunning = false;
+}
 
 // src/api/routes/nodes-patch.ts
 var patchBodySchema = {
@@ -7191,61 +9426,773 @@ function registerConfigPatchRoutes(app, deps) {
             type
           });
         }
-        const existingKindPricing = nodeConfig.kindPricing ?? void 0;
-        const mergedKindPricing = body.kindPricing !== void 0 ? { ...existingKindPricing ?? {}, ...body.kindPricing } : existingKindPricing;
-        const mergedConfig = {
-          ...currentConfig,
-          nodes: {
-            ...currentConfig.nodes,
-            [type]: {
-              ...nodeConfig,
-              ...body,
-              ...mergedKindPricing !== void 0 ? { kindPricing: mergedKindPricing } : {}
-            }
+        const existingKindPricing = nodeConfig.kindPricing ?? void 0;
+        const mergedKindPricing = body.kindPricing !== void 0 ? { ...existingKindPricing ?? {}, ...body.kindPricing } : existingKindPricing;
+        const mergedConfig = {
+          ...currentConfig,
+          nodes: {
+            ...currentConfig.nodes,
+            [type]: {
+              ...nodeConfig,
+              ...body,
+              ...mergedKindPricing !== void 0 ? { kindPricing: mergedKindPricing } : {}
+            }
+          }
+        };
+        try {
+          validateConfig(mergedConfig);
+        } catch (validationError) {
+          return reply.status(400).send({
+            error: "config_validation_error",
+            message: validationError instanceof Error ? validationError.message : "Invalid configuration"
+          });
+        }
+        await saveConfig(deps.configPath, mergedConfig);
+        deps.config.nodes = mergedConfig.nodes;
+        const nodeType = type;
+        const oldEnabled = nodeConfig.enabled;
+        const newEnabled = body.enabled !== void 0 ? body.enabled : oldEnabled;
+        if (oldEnabled !== newEnabled) {
+          if (newEnabled) {
+            await deps.orchestrator.addNode(nodeType);
+          } else {
+            await deps.orchestrator.removeNode(nodeType);
+          }
+        }
+        if (body.feePerEvent !== void 0 || body.feeBasisPoints !== void 0 || body.feePerJob !== void 0 || body.kindPricing !== void 0) {
+          const activeTypes = Object.entries(mergedConfig.nodes).filter(([, config]) => config.enabled).map(([type2]) => type2);
+          await deps.orchestrator.regenerateConnectorConfig(activeTypes);
+        }
+        const u = mergedConfig.nodes[type];
+        if (nodeType === "town") {
+          return { enabled: u.enabled, feePerEvent: u.feePerEvent };
+        } else if (nodeType === "mill") {
+          return { enabled: u.enabled, feeBasisPoints: u.feeBasisPoints };
+        } else {
+          return {
+            enabled: u.enabled,
+            feePerJob: u.feePerJob,
+            kindPricing: u.kindPricing
+          };
+        }
+      } finally {
+        releaseConfigMutex();
+      }
+    }
+  );
+}
+
+// src/api/routes/nodes-lifecycle.ts
+import { promises as fs5 } from "fs";
+import { dirname as dirname8, join as join5 } from "path";
+import { bytesToHex as bytesToHex2 } from "@noble/hashes/utils";
+var HEALTH_PORT = {
+  town: TOWN_HEALTH_PORT,
+  mill: MILL_HEALTH_PORT,
+  dvm: DVM_HEALTH_PORT
+};
+var ACCOUNT_INDEX = {
+  town: ACCOUNT_INDEX_TOWN,
+  mill: ACCOUNT_INDEX_MILL,
+  dvm: ACCOUNT_INDEX_DVM
+};
+var APEX_ILP_ADDRESS = "g.townhouse";
+function buildMillSwapPairConfig(config) {
+  const fromChain = config.chainProviders?.[0]?.chainId ?? "evm:base:31337";
+  const toChain = "solana:devnet";
+  return {
+    swapPairs: [
+      {
+        from: { assetCode: "USDC", assetScale: 6, chain: fromChain },
+        to: { assetCode: "USDC", assetScale: 6, chain: toChain },
+        rate: "1.0",
+        minAmount: "1000",
+        maxAmount: "1000000000"
+      }
+    ],
+    chains: ["evm", "solana"],
+    // Bootstrap: validateConfig() requires a non-empty channels array for
+    // each distinct pair.to.chain. The zero channelId is a valid-format
+    // sentinel that will never match a real on-chain channel.
+    channels: {
+      [toChain]: [
+        {
+          channelId: "0x" + "0".repeat(64),
+          cumulativeAmount: "0",
+          nonce: "0"
+        }
+      ]
+    },
+    // Zero initial SOL inventory; parsed to 0n by the Mill CLI.
+    inventory: {
+      [toChain]: "0"
+    }
+  };
+}
+async function waitForHealthy(url, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const POLL_INTERVAL_MS = 1e3;
+  const REQUEST_TIMEOUT_MS = 3e3;
+  while (Date.now() < deadline) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, { signal: controller.signal });
+      if (res.ok) return;
+    } catch {
+    } finally {
+      clearTimeout(timer);
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
+  }
+  throw new Error(
+    `Health check timeout: ${url} did not return 200 within ${timeoutMs}ms`
+  );
+}
+function buildNodeEnv(type, nostrSecretKeyHex, evmPrivateKeyHex, mnemonic, apexEvmAddress) {
+  const evmPrivateKeyHex0x = `0x${evmPrivateKeyHex}`;
+  switch (type) {
+    case "town":
+      return {
+        TOWN_SECRET_KEY: nostrSecretKeyHex,
+        TOWN_SETTLEMENT_PRIVATE_KEY: evmPrivateKeyHex0x,
+        APEX_EVM_ADDRESS: apexEvmAddress
+      };
+    case "mill":
+      return {
+        MILL_SECRET_KEY: nostrSecretKeyHex,
+        MILL_SETTLEMENT_PRIVATE_KEY: evmPrivateKeyHex0x,
+        MILL_MNEMONIC: mnemonic ?? "",
+        APEX_EVM_ADDRESS: apexEvmAddress
+      };
+    case "dvm":
+      return {
+        DVM_SECRET_KEY: nostrSecretKeyHex
+      };
+  }
+}
+function registerNodeLifecycleRoutes(app, deps) {
+  app.get("/api/nodes", async (request, reply) => {
+    const homeDir = dirname8(deps.configPath);
+    const nodesYamlPath = join5(homeDir, "nodes.yaml");
+    let yaml;
+    try {
+      yaml = await readNodesYaml(nodesYamlPath);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      request.log.error(
+        { event: "get_nodes_yaml_error", err: errMsg },
+        "Failed to read nodes.yaml"
+      );
+      return reply.status(500).send({ error: "yaml_read_failed", err: errMsg });
+    }
+    let peers = [];
+    let connectorUnreachable = false;
+    try {
+      peers = await deps.connectorAdmin.getPeers();
+    } catch (err) {
+      connectorUnreachable = true;
+      request.log.warn(
+        { event: "get_nodes_connector_warn", err: String(err) },
+        "connector unreachable during GET /api/nodes \u2014 returning status:unknown"
+      );
+    }
+    const nodes = yaml.entries.map((entry) => {
+      let status;
+      if (connectorUnreachable) {
+        status = "unknown";
+      } else {
+        const peer = peers.find((p) => p.id === entry.peerId);
+        status = peer?.connected ? "connected" : "disconnected";
+      }
+      return {
+        id: entry.id,
+        type: entry.type,
+        peerId: entry.peerId,
+        ilpAddress: entry.ilpAddress,
+        status,
+        enabledAt: entry.enabledAt,
+        lastSeenAt: entry.lastSeenAt
+      };
+    });
+    return reply.status(200).send({ nodes });
+  });
+  app.post(
+    "/api/nodes",
+    {
+      schema: {
+        body: {
+          type: "object",
+          additionalProperties: false,
+          required: ["type"],
+          properties: {
+            type: { type: "string", enum: ["town", "mill", "dvm"] }
+          }
+        }
+      }
+    },
+    async (request, reply) => {
+      if (!acquireNodeLifecycleMutex()) {
+        return reply.status(409).send({ error: "node_lifecycle_in_flight" });
+      }
+      try {
+        const { type } = request.body;
+        const homeDir = dirname8(deps.configPath);
+        const nodesYamlPath = join5(homeDir, "nodes.yaml");
+        const imageManifestPath = join5(homeDir, "image-manifest.json");
+        const millConfigPath = join5(homeDir, "mill.config.json");
+        const yaml = await readNodesYaml(nodesYamlPath);
+        const existing = yaml.entries.find((e) => e.type === type);
+        if (existing) {
+          return reply.status(409).send({
+            error: "node_type_in_use",
+            type,
+            existingId: existing.id
+          });
+        }
+        if (type === "mill" && !process.env["MILL_RELAYS"]?.trim()) {
+          return reply.status(400).send({
+            step: "preflight",
+            err: "MILL_RELAYS is not set or is blank. Export a comma-separated list of relay URLs before provisioning Mill (e.g. export MILL_RELAYS=wss://relay.example.com). See packages/townhouse/README.md."
+          });
+        }
+        const derivationIndex = ACCOUNT_INDEX[type];
+        const id = type;
+        const peerId = type;
+        const ilpAddress = `${APEX_ILP_ADDRESS}.${type}`;
+        const containerName = `${CONTAINER_PREFIX}hs-${type}`;
+        const healthPort = HEALTH_PORT[type];
+        const healthCheckUrl = `http://${containerName}:${healthPort}/health`;
+        const btpUrl = `ws://${CONTAINER_PREFIX}hs-${type}:${NODE_BTP_PORT}`;
+        request.log.info(
+          { event: "node_lifecycle_step", step: "derive-key", type, peerId },
+          "Step 1: deriving node key"
+        );
+        let keys;
+        try {
+          keys = await deps.wallet.deriveNodeKey(type, derivationIndex);
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "derive-key",
+              err: errMsg
+            },
+            "Step 1 failed: derive-key"
+          );
+          return reply.status(500).send({ step: "derive-key", err: errMsg });
+        }
+        const nostrSecretKeyHex = bytesToHex2(keys.nostrSecretKey);
+        const evmPrivateKeyHex = bytesToHex2(keys.evmPrivateKey);
+        const mnemonicSnapshot = deps.wallet.getMnemonic();
+        if (mnemonicSnapshot === null) {
+          const errMsg = "Wallet locked between step 1 and step 4 \u2014 refusing to start container without mnemonic";
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "derive-key",
+              err: errMsg
+            },
+            "Step 1 post-condition failed: mnemonic gone after derive"
+          );
+          return reply.status(500).send({ step: "derive-key", err: errMsg });
+        }
+        const apexEvmAddress = deps.wallet.getNodeKeys("town").evmAddress;
+        request.log.info(
+          { event: "node_lifecycle_step", step: "pull-image", type, peerId },
+          "Step 2: pulling image"
+        );
+        try {
+          const manifest = await readImageManifest(imageManifestPath);
+          const entry = manifest.images[type];
+          if (isSyntheticDigest(entry.digest)) {
+            return reply.status(400).send({
+              step: "pull-image",
+              err: `Synthetic-digest manifest: image-manifest.json was produced by the connector-publish-smoke workflow for smoke testing only. Fetch a real manifest via 'gh run download' or rerun without --skip-fetch before provisioning nodes.`
+            });
+          }
+          const imageRef = `${entry.name}@${entry.digest}`;
+          await deps.orchestrator.pullImage(imageRef);
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "pull-image",
+              err: errMsg
+            },
+            "Step 2 failed: pull-image"
+          );
+          return reply.status(502).send({ step: "pull-image", err: errMsg });
+        }
+        request.log.info(
+          { event: "node_lifecycle_step", step: "write-yaml", type, peerId },
+          "Step 3: writing nodes.yaml entry"
+        );
+        const enabledAt = (/* @__PURE__ */ new Date()).toISOString();
+        const newEntry = {
+          id,
+          type,
+          peerId,
+          ilpAddress,
+          derivationIndex,
+          enabledAt,
+          lastSeenAt: null
+        };
+        try {
+          await writeNodesYaml(nodesYamlPath, {
+            entries: [...yaml.entries, newEntry]
+          });
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "write-yaml",
+              err: errMsg
+            },
+            "Step 3 failed: write-yaml"
+          );
+          return reply.status(500).send({ step: "write-yaml", err: errMsg });
+        }
+        let millConfigWritten = false;
+        if (type === "mill") {
+          try {
+            const defaultMillConfig = JSON.stringify(
+              buildMillSwapPairConfig(deps.config),
+              null,
+              2
+            );
+            await fs5.mkdir(dirname8(millConfigPath), {
+              recursive: true,
+              mode: 448
+            });
+            await fs5.chmod(dirname8(millConfigPath), 448);
+            await fs5.writeFile(millConfigPath, defaultMillConfig, {
+              encoding: "utf-8",
+              mode: 384
+            });
+            millConfigWritten = true;
+          } catch (err) {
+            const errMsg = sanitizeErrorMessage(
+              err instanceof Error ? err.message : String(err)
+            );
+            request.log.error(
+              {
+                event: "node_lifecycle_failure",
+                step: "write-mill-config",
+                err: errMsg
+              },
+              "Step 3b failed: write mill.config.json"
+            );
+            const rollbackMillError = await safeRollbackMillConfig(
+              millConfigPath,
+              request
+            );
+            const rollbackYamlError = await safeRollbackYaml(
+              nodesYamlPath,
+              peerId,
+              request
+            );
+            const rollbackError = combineRollbackErrors(
+              rollbackMillError,
+              rollbackYamlError
+            );
+            return reply.status(500).send({ step: "write-mill-config", err: errMsg, rollbackError });
+          }
+        }
+        request.log.info(
+          {
+            event: "node_lifecycle_step",
+            step: "start-container",
+            type,
+            peerId
+          },
+          "Step 4: starting container via compose"
+        );
+        const nodeEnv = buildNodeEnv(
+          type,
+          nostrSecretKeyHex,
+          evmPrivateKeyHex,
+          mnemonicSnapshot,
+          apexEvmAddress
+        );
+        try {
+          await deps.orchestrator.startNodeViaCompose(type, nodeEnv);
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "start-container",
+              err: errMsg
+            },
+            "Step 4 failed: start-container"
+          );
+          const rollbackError = await safeRollbackYaml(
+            nodesYamlPath,
+            peerId,
+            request
+          );
+          let rollbackMillError;
+          if (millConfigWritten) {
+            rollbackMillError = await safeRollbackMillConfig(
+              millConfigPath,
+              request
+            );
+          }
+          const combinedRollbackError = combineRollbackErrors(
+            rollbackError,
+            rollbackMillError
+          );
+          return reply.status(502).send({
+            step: "start-container",
+            err: errMsg,
+            rollbackError: combinedRollbackError
+          });
+        }
+        request.log.info(
+          {
+            event: "node_lifecycle_step",
+            step: "healthcheck",
+            type,
+            peerId,
+            healthCheckUrl
+          },
+          "Step 5: waiting for container to become healthy"
+        );
+        try {
+          await waitForHealthy(healthCheckUrl, 6e4);
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "healthcheck",
+              err: errMsg
+            },
+            "Step 5 failed: healthcheck"
+          );
+          const rollbackYamlError = await safeRollbackYaml(
+            nodesYamlPath,
+            peerId,
+            request
+          );
+          const rollbackStopError = await safeRollbackStop(
+            type,
+            deps.orchestrator,
+            request
+          );
+          let rollbackMillError;
+          if (millConfigWritten) {
+            rollbackMillError = await safeRollbackMillConfig(
+              millConfigPath,
+              request
+            );
           }
-        };
+          const combinedRollbackError = combineRollbackErrors(
+            rollbackYamlError,
+            rollbackStopError,
+            rollbackMillError
+          );
+          return reply.status(502).send({
+            step: "healthcheck",
+            err: errMsg,
+            rollbackError: combinedRollbackError
+          });
+        }
+        request.log.info(
+          {
+            event: "node_lifecycle_step",
+            step: "register-peer",
+            type,
+            peerId,
+            ilpAddress
+          },
+          "Step 6: registering peer with connector"
+        );
         try {
-          validateConfig(mergedConfig);
-        } catch (validationError) {
-          return reply.status(400).send({
-            error: "config_validation_error",
-            message: validationError instanceof Error ? validationError.message : "Invalid configuration"
+          await deps.connectorAdmin.registerPeer({
+            id: peerId,
+            url: btpUrl,
+            authToken: "",
+            routes: [{ prefix: ilpAddress, priority: 0 }],
+            // Force direct (non-SOCKS5) BTP dial for this Docker-sibling
+            // peer. The apex connector runs with `transport.type: socks5`
+            // so the .anyone HS can publish; without this override, every
+            // peer dial gets routed through the anon proxy and fails with
+            // `HostUnreachable` on Docker-internal hostnames. Requires
+            // connector >= 3.6.2 (toon-protocol/connector#70). Discovered
+            // by Story 46.4 live gate run (Finding Q, 2026-05-12).
+            transport: "direct"
+          });
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "register-peer",
+              err: errMsg
+            },
+            "Step 6 failed: register-peer"
+          );
+          const rollbackYamlError = await safeRollbackYaml(
+            nodesYamlPath,
+            peerId,
+            request
+          );
+          const rollbackStopError = await safeRollbackStop(
+            type,
+            deps.orchestrator,
+            request
+          );
+          let rollbackMillError;
+          if (millConfigWritten) {
+            rollbackMillError = await safeRollbackMillConfig(
+              millConfigPath,
+              request
+            );
+          }
+          const combinedRollbackError = combineRollbackErrors(
+            rollbackYamlError,
+            rollbackStopError,
+            rollbackMillError
+          );
+          return reply.status(502).send({
+            step: "register-peer",
+            err: errMsg,
+            rollbackError: combinedRollbackError
           });
         }
-        await saveConfig(deps.configPath, mergedConfig);
-        deps.config.nodes = mergedConfig.nodes;
-        const nodeType = type;
-        const oldEnabled = nodeConfig.enabled;
-        const newEnabled = body.enabled !== void 0 ? body.enabled : oldEnabled;
-        if (oldEnabled !== newEnabled) {
-          if (newEnabled) {
-            await deps.orchestrator.addNode(nodeType);
-          } else {
-            await deps.orchestrator.removeNode(nodeType);
+        request.log.info(
+          { event: "node_lifecycle_success", type, peerId, ilpAddress },
+          "Node provisioned successfully"
+        );
+        return reply.status(201).send({
+          id,
+          type,
+          peerId,
+          ilpAddress,
+          hsRoute: ilpAddress,
+          healthCheckUrl
+        });
+      } finally {
+        releaseNodeLifecycleMutex();
+      }
+    }
+  );
+  app.delete(
+    "/api/nodes/:id",
+    {
+      schema: {
+        params: {
+          type: "object",
+          required: ["id"],
+          properties: {
+            id: {
+              type: "string",
+              minLength: 1,
+              maxLength: 64,
+              pattern: "^[a-z][a-z0-9-]*$"
+            }
           }
         }
-        if (body.feePerEvent !== void 0 || body.feeBasisPoints !== void 0 || body.feePerJob !== void 0 || body.kindPricing !== void 0) {
-          const activeTypes = Object.entries(mergedConfig.nodes).filter(([, config]) => config.enabled).map(([type2]) => type2);
-          await deps.orchestrator.regenerateConnectorConfig(activeTypes);
+      }
+    },
+    async (request, reply) => {
+      if (!acquireNodeLifecycleMutex()) {
+        return reply.status(409).send({ error: "node_lifecycle_in_flight" });
+      }
+      try {
+        const { id } = request.params;
+        const homeDir = dirname8(deps.configPath);
+        const nodesYamlPath = join5(homeDir, "nodes.yaml");
+        const millConfigPath = join5(homeDir, "mill.config.json");
+        const yaml = await readNodesYaml(nodesYamlPath);
+        const entry = yaml.entries.find((e) => e.id === id);
+        if (!entry) {
+          return reply.status(404).send({ error: "unknown_node", id });
+        }
+        request.log.info(
+          {
+            event: "node_lifecycle_step",
+            step: "deregister-peer",
+            type: entry.type,
+            peerId: entry.peerId
+          },
+          "DELETE step 1: deregistering peer from connector"
+        );
+        try {
+          await deps.connectorAdmin.removePeer(entry.peerId);
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "deregister-peer",
+              err: errMsg
+            },
+            "DELETE step 1 failed: deregister-peer"
+          );
+          return reply.status(502).send({ step: "deregister-peer", err: errMsg });
         }
-        const u = mergedConfig.nodes[type];
-        if (nodeType === "town") {
-          return { enabled: u.enabled, feePerEvent: u.feePerEvent };
-        } else if (nodeType === "mill") {
-          return { enabled: u.enabled, feeBasisPoints: u.feeBasisPoints };
-        } else {
-          return {
-            enabled: u.enabled,
-            feePerJob: u.feePerJob,
-            kindPricing: u.kindPricing
-          };
+        request.log.info(
+          {
+            event: "node_lifecycle_step",
+            step: "stop-container",
+            type: entry.type
+          },
+          "DELETE step 2: stopping container"
+        );
+        try {
+          await deps.orchestrator.stopNodeViaCompose(entry.type);
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "stop-container",
+              err: errMsg
+            },
+            "DELETE step 2 failed: stop-container"
+          );
+          return reply.status(502).send({ step: "stop-container", err: errMsg });
+        }
+        request.log.info(
+          {
+            event: "node_lifecycle_step",
+            step: "remove-yaml",
+            type: entry.type
+          },
+          "DELETE step 3: removing nodes.yaml entry"
+        );
+        try {
+          await writeNodesYaml(nodesYamlPath, {
+            entries: yaml.entries.filter((e) => e.id !== id)
+          });
+        } catch (err) {
+          const errMsg = sanitizeErrorMessage(
+            err instanceof Error ? err.message : String(err)
+          );
+          request.log.error(
+            {
+              event: "node_lifecycle_failure",
+              step: "remove-yaml",
+              err: errMsg
+            },
+            "DELETE step 3 failed: remove-yaml"
+          );
+          return reply.status(500).send({ step: "remove-yaml", err: errMsg });
+        }
+        if (entry.type === "mill") {
+          await fs5.rm(millConfigPath, { force: true });
         }
+        request.log.info(
+          { event: "node_lifecycle_deleted", id, type: entry.type },
+          "Node deprovisioned successfully"
+        );
+        return reply.status(200).send({ id, type: entry.type });
       } finally {
-        releaseConfigMutex();
+        releaseNodeLifecycleMutex();
       }
     }
   );
 }
+async function safeRollbackYaml(nodesYamlPath, addedPeerId, request) {
+  try {
+    const current = await readNodesYaml(nodesYamlPath);
+    const filtered = current.entries.filter((e) => e.peerId !== addedPeerId);
+    await writeNodesYaml(nodesYamlPath, { entries: filtered });
+    return void 0;
+  } catch (err) {
+    const errMsg = sanitizeErrorMessage(
+      err instanceof Error ? err.message : String(err)
+    );
+    request.log.error(
+      {
+        event: "node_lifecycle_rollback_failure",
+        step: "write-yaml",
+        err: errMsg
+      },
+      "Rollback: failed to remove yaml entry \u2014 operator may need to hand-edit nodes.yaml"
+    );
+    return `write-yaml: ${errMsg}`;
+  }
+}
+async function safeRollbackMillConfig(millConfigPath, request) {
+  try {
+    await fs5.rm(millConfigPath, { force: true });
+    return void 0;
+  } catch (err) {
+    const errMsg = sanitizeErrorMessage(
+      err instanceof Error ? err.message : String(err)
+    );
+    request.log.error(
+      {
+        event: "node_lifecycle_rollback_failure",
+        step: "remove-mill-config",
+        err: errMsg
+      },
+      "Rollback: failed to remove mill.config.json"
+    );
+    return `remove-mill-config: ${errMsg}`;
+  }
+}
+async function safeRollbackStop(type, orchestrator, request) {
+  try {
+    await orchestrator.stopNodeViaCompose(type);
+    return void 0;
+  } catch (err) {
+    const errMsg = sanitizeErrorMessage(
+      err instanceof Error ? err.message : String(err)
+    );
+    request.log.error(
+      {
+        event: "node_lifecycle_rollback_failure",
+        step: "stop-container",
+        err: errMsg
+      },
+      "Rollback: failed to stop container \u2014 operator may need to docker rm by hand"
+    );
+    return `stop-container: ${errMsg}`;
+  }
+}
+function combineRollbackErrors(...errors) {
+  const present = errors.filter((e) => e !== void 0);
+  if (present.length === 0) return void 0;
+  return present.join("; ");
+}
+var SECRET_KEYS = [
+  "TOWN_SECRET_KEY",
+  "MILL_SECRET_KEY",
+  "DVM_SECRET_KEY",
+  "TOWN_SETTLEMENT_PRIVATE_KEY",
+  "MILL_SETTLEMENT_PRIVATE_KEY",
+  "DVM_SETTLEMENT_PRIVATE_KEY",
+  "MILL_MNEMONIC",
+  "TOWNHOUSE_WALLET_PASSWORD"
+];
+var REDACT_RE = new RegExp(`(${SECRET_KEYS.join("|")})=[^\\s"'\\n\\r]+`, "g");
+function sanitizeErrorMessage(msg) {
+  return msg.replace(REDACT_RE, "$1=[REDACTED]");
+}
 
 // src/api/routes/metrics-ws.ts
 import { decode as decodeToon } from "@toon-format/toon";
@@ -7528,8 +10475,8 @@ function registerMetricsWsRoutes(app, deps) {
 }
 
 // src/api/routes/wizard.ts
-import { existsSync, unlinkSync, chmodSync } from "fs";
-import { dirname as dirname3, join as join3 } from "path";
+import { existsSync as existsSync4, unlinkSync, chmodSync as chmodSync3 } from "fs";
+import { dirname as dirname9, join as join6 } from "path";
 import { generateMnemonic as generateMnemonic2, validateMnemonic as validateMnemonic2 } from "@scure/bip39";
 import { wordlist as wordlist2 } from "@scure/bip39/wordlists/english.js";
 var PROGRESS_BUFFER_MAX = 200;
@@ -7550,8 +10497,8 @@ function isAllowedWsOrigin(origin) {
 }
 function registerWizardRoutes(app, deps, state, onInit) {
   app.get("/wizard/state", async (_request, reply) => {
-    const configExists = existsSync(deps.configPath);
-    const walletExists = existsSync(deps.walletPath);
+    const configExists = existsSync4(deps.configPath);
+    const walletExists = existsSync4(deps.walletPath);
     const containersRunning = state.mode === "normal";
     return reply.status(200).send({
       config_exists: configExists,
@@ -7672,13 +10619,13 @@ function registerWizardRoutes(app, deps, state, onInit) {
           message: 'transport.mode must be "direct" or "ator".'
         });
       }
-      if (existsSync(deps.walletPath)) {
+      if (existsSync4(deps.walletPath)) {
         return reply.status(409).send({
           code: "wallet_already_exists",
           message: `A wallet already exists at ${deps.walletPath}. Delete it first.`
         });
       }
-      if (existsSync(deps.configPath)) {
+      if (existsSync4(deps.configPath)) {
         return reply.status(409).send({
           code: "config_already_exists",
           message: `A config already exists at ${deps.configPath}. Delete it first.`
@@ -7691,7 +10638,7 @@ function registerWizardRoutes(app, deps, state, onInit) {
       const encrypted = encryptWallet(cleanMnemonic, password);
       await saveWallet(deps.walletPath, encrypted);
       try {
-        chmodSync(deps.walletPath, 384);
+        chmodSync3(deps.walletPath, 384);
       } catch {
       }
       let config;
@@ -7792,8 +10739,8 @@ function registerWizardRoutes(app, deps, state, onInit) {
 }
 function buildConfigFromRequest(request, configPath) {
   const config = getDefaultConfig();
-  const configDir = dirname3(configPath);
-  config.wallet.encrypted_path = join3(configDir, "wallet.enc");
+  const configDir = dirname9(configPath);
+  config.wallet.encrypted_path = join6(configDir, "wallet.enc");
   config.nodes.town.enabled = request.nodes.town.enabled;
   if (request.nodes.town.enabled && request.nodes.town.feePerEvent !== void 0) {
     config.nodes.town.feePerEvent = request.nodes.town.feePerEvent;
@@ -8014,9 +10961,480 @@ function registerTransportRoutes(app, deps, opts = {}) {
   );
 }
 
+// src/api/routes/earnings.ts
+import { dirname as dirname10, join as join7 } from "path";
+
+// src/api/schemas/earnings.ts
+var DECIMAL_STRING_PATTERN = "^-?\\d+$";
+var perAssetSchema = {
+  type: "object",
+  properties: {
+    lifetime: { type: "string", pattern: DECIMAL_STRING_PATTERN },
+    today: { type: "string", pattern: DECIMAL_STRING_PATTERN },
+    month: { type: "string", pattern: DECIMAL_STRING_PATTERN },
+    year: { type: "string", pattern: DECIMAL_STRING_PATTERN }
+  },
+  required: ["lifetime", "today", "month", "year"]
+  // Open to future connector-derived fields per D2 decision (2026-05-13).
+};
+var routingFeesSchema = {
+  type: "object",
+  additionalProperties: perAssetSchema
+};
+var peerSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    type: {
+      type: "string",
+      enum: ["town", "mill", "dvm", "external"]
+    },
+    byAsset: routingFeesSchema,
+    lastClaimAt: {
+      oneOf: [{ type: "string", format: "date-time" }, { type: "null" }]
+    }
+  },
+  required: ["id", "type", "byAsset", "lastClaimAt"],
+  additionalProperties: false
+  // Townhouse owns the peer shape.
+};
+var recentClaimSchema = {
+  type: "object",
+  properties: {
+    peerId: { type: "string" },
+    assetCode: { type: "string" },
+    assetScale: { type: "integer", minimum: 0 },
+    amount: { type: "string", pattern: DECIMAL_STRING_PATTERN },
+    direction: { type: "string", enum: ["inbound", "outbound"] },
+    at: { type: "string", format: "date-time" }
+  },
+  required: [
+    "peerId",
+    "assetCode",
+    "assetScale",
+    "amount",
+    "direction",
+    "at"
+  ]
+  // Open to future connector-shipped fields per D2 decision (2026-05-13).
+};
+var earningsResponseSchema = {
+  response: {
+    200: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["ok", "connector_unavailable"] },
+        apex: {
+          type: "object",
+          properties: {
+            routingFees: routingFeesSchema
+          },
+          required: ["routingFees"],
+          additionalProperties: false
+        },
+        peers: {
+          type: "array",
+          items: peerSchema
+        },
+        recentClaims: {
+          type: "array",
+          items: recentClaimSchema
+        },
+        eventsRelayed: { type: "integer", minimum: 0 },
+        uptimeSeconds: { type: "integer", minimum: 0 }
+      },
+      required: [
+        "status",
+        "apex",
+        "peers",
+        "recentClaims",
+        "eventsRelayed",
+        "uptimeSeconds"
+      ],
+      additionalProperties: false
+    }
+  }
+};
+
+// src/api/routes/earnings.ts
+function resolveNodesYamlPath(deps) {
+  return join7(dirname10(deps.configPath), "nodes.yaml");
+}
+function resolveSnapshotPath(deps) {
+  return join7(dirname10(deps.configPath), "earnings-snapshots.jsonl");
+}
+function registerEarningsRoutes(app, deps) {
+  app.get(
+    "/api/earnings",
+    { schema: earningsResponseSchema },
+    async (request, reply) => {
+      let yaml;
+      try {
+        yaml = await readNodesYaml(resolveNodesYamlPath(deps));
+      } catch (err) {
+        request.log.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          "earnings: nodes.yaml read/validate failed"
+        );
+        return reply.status(500).send({ error: "nodes_yaml_invalid" });
+      }
+      const peerTypeResolver = new PeerTypeResolver(yaml);
+      const deltaComputer = createDeltaComputer({
+        snapshotPath: resolveSnapshotPath(deps)
+      });
+      return aggregateEarnings({
+        connectorAdmin: deps.connectorAdmin,
+        peerTypeResolver,
+        deltaComputer,
+        logger: request.log
+      });
+    }
+  );
+}
+
+// src/api/routes/logs.ts
+import Docker from "dockerode";
+
+// src/docker/log-tail.ts
+var LOG_SERVICES = [
+  "town",
+  "mill",
+  "dvm",
+  "connector"
+];
+function stripDockerFrame(chunk) {
+  if (chunk.length < 8) return chunk;
+  const streamType = chunk[0];
+  if (streamType !== 1 && streamType !== 2 || chunk[1] !== 0 || chunk[2] !== 0 || chunk[3] !== 0) {
+    return chunk;
+  }
+  const out = [];
+  let offset = 0;
+  while (offset + 8 <= chunk.length) {
+    const st = chunk[offset];
+    if (st !== 1 && st !== 2 || chunk[offset + 1] !== 0 || chunk[offset + 2] !== 0 || chunk[offset + 3] !== 0) {
+      out.push(chunk.subarray(offset));
+      return Buffer.concat(out);
+    }
+    const size = chunk.readUInt32BE(offset + 4);
+    const start = offset + 8;
+    const end = start + size;
+    if (end > chunk.length) {
+      out.push(chunk.subarray(start));
+      return Buffer.concat(out);
+    }
+    out.push(chunk.subarray(start, end));
+    offset = end;
+  }
+  return Buffer.concat(out);
+}
+function parseLogLine(line, service) {
+  const trimmed = line.replace(/\r$/, "").trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    try {
+      const obj = JSON.parse(trimmed);
+      const level = pinoLevelToLevel(obj["level"]);
+      const ts = pickTimestamp(obj["time"] ?? obj["ts"] ?? obj["@timestamp"]);
+      const msg = pickMsg(obj["msg"] ?? obj["message"] ?? obj["text"]) ?? trimmed;
+      return { ts, service, level, msg, raw: trimmed };
+    } catch {
+    }
+  }
+  const levelMatch = trimmed.match(
+    /^\s*\[?(DEBUG|INFO|WARN|WARNING|ERROR|ERR|FATAL)\]?[:\s]+(.*)$/i
+  );
+  if (levelMatch && levelMatch[1] !== void 0) {
+    const lvl = levelMatch[1].toUpperCase();
+    const msg = levelMatch[2] ?? "";
+    return {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      service,
+      level: textLevelToLevel(lvl),
+      msg,
+      raw: trimmed
+    };
+  }
+  return {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    service,
+    level: "info",
+    msg: trimmed,
+    raw: trimmed
+  };
+}
+function pinoLevelToLevel(raw) {
+  if (typeof raw === "number") {
+    if (raw >= 50) return "error";
+    if (raw >= 40) return "warn";
+    if (raw >= 30) return "info";
+    return "debug";
+  }
+  if (typeof raw === "string") {
+    return textLevelToLevel(raw.toUpperCase());
+  }
+  return "info";
+}
+function textLevelToLevel(upper) {
+  switch (upper) {
+    case "DEBUG":
+    case "TRACE":
+      return "debug";
+    case "WARN":
+    case "WARNING":
+      return "warn";
+    case "ERR":
+    case "ERROR":
+    case "FATAL":
+    case "CRITICAL":
+      return "error";
+    case "INFO":
+    default:
+      return "info";
+  }
+}
+function pickTimestamp(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  if (typeof value === "string") {
+    const d = new Date(value);
+    if (!Number.isNaN(d.getTime())) return d.toISOString();
+  }
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function pickMsg(value) {
+  if (typeof value === "string") return value;
+  if (value == null) return null;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+var LineSplitter = class {
+  buffer = "";
+  push(chunk) {
+    this.buffer += stripDockerFrame(chunk).toString("utf8");
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop() ?? "";
+    return lines;
+  }
+  flush() {
+    if (!this.buffer) return [];
+    const out = [this.buffer];
+    this.buffer = "";
+    return out;
+  }
+};
+function serviceFromContainerName(name) {
+  const clean = name.replace(/^\//, "");
+  if (!clean.startsWith(CONTAINER_PREFIX)) return null;
+  const suffix = clean.slice(CONTAINER_PREFIX.length);
+  for (const svc of LOG_SERVICES) {
+    if (suffix === svc || suffix.startsWith(`${svc}-`) || suffix.includes(`-${svc}-`) || suffix.endsWith(`-${svc}`)) {
+      return svc;
+    }
+  }
+  return null;
+}
+async function* tailContainerLogs(docker, containerName, service, opts = {}) {
+  const tail = opts.tail ?? 50;
+  const container = docker.getContainer(containerName);
+  const stream = await container.logs({
+    follow: true,
+    stdout: true,
+    stderr: true,
+    tail,
+    timestamps: false
+  });
+  const splitter = new LineSplitter();
+  const queue = [];
+  let waiter = null;
+  let done = false;
+  let err = null;
+  function wake() {
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w();
+    }
+  }
+  stream.on("data", (chunk) => {
+    for (const line of splitter.push(chunk)) {
+      const evt = parseLogLine(line, service);
+      if (evt) queue.push(evt);
+    }
+    wake();
+  });
+  stream.on("end", () => {
+    for (const line of splitter.flush()) {
+      const evt = parseLogLine(line, service);
+      if (evt) queue.push(evt);
+    }
+    done = true;
+    wake();
+  });
+  stream.on("error", (e) => {
+    err = e;
+    done = true;
+    wake();
+  });
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      try {
+        stream.destroy();
+      } catch {
+      }
+      done = true;
+    } else {
+      opts.signal.addEventListener(
+        "abort",
+        () => {
+          try {
+            stream.destroy();
+          } catch {
+          }
+          done = true;
+          wake();
+        },
+        { once: true }
+      );
+    }
+  }
+  while (true) {
+    const next = queue.shift();
+    if (next !== void 0) {
+      yield next;
+      continue;
+    }
+    if (done) break;
+    await new Promise((resolve2) => {
+      waiter = resolve2;
+    });
+  }
+  if (err) throw err;
+}
+
+// src/api/routes/logs.ts
+var HEARTBEAT_INTERVAL_MS2 = 15e3;
+async function listTownhouseContainers(docker) {
+  const containers = await docker.listContainers({ all: false });
+  const out = [];
+  for (const c of containers) {
+    for (const rawName of c.Names) {
+      const name = rawName.startsWith("/") ? rawName.slice(1) : rawName;
+      const service = serviceFromContainerName(name);
+      if (service) {
+        out.push({ name, service });
+        break;
+      }
+    }
+  }
+  return out;
+}
+function registerLogsRoutes(app, _deps, opts = {}) {
+  const docker = opts.docker ?? new Docker();
+  const tailFn = opts.tailFn ?? tailContainerLogs;
+  app.get("/api/logs/stream", async (request, reply) => {
+    await streamLogs(request, reply, docker, tailFn);
+  });
+}
+async function streamLogs(request, reply, docker, tailFn) {
+  const raw = reply.raw;
+  raw.statusCode = 200;
+  raw.setHeader("Content-Type", "text/event-stream");
+  raw.setHeader("Cache-Control", "no-cache, no-transform");
+  raw.setHeader("Connection", "keep-alive");
+  raw.setHeader("X-Accel-Buffering", "no");
+  raw.flushHeaders?.();
+  const controller = new AbortController();
+  const heartbeat = setInterval(() => {
+    if (raw.writableEnded) return;
+    try {
+      raw.write(`: heartbeat ${Date.now()}
+
+`);
+    } catch {
+    }
+  }, HEARTBEAT_INTERVAL_MS2);
+  function teardown() {
+    clearInterval(heartbeat);
+    controller.abort();
+  }
+  request.raw.on("close", teardown);
+  request.raw.on("error", teardown);
+  let containers;
+  try {
+    containers = await listTownhouseContainers(docker);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    writeEvent(raw, {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      service: "connector",
+      level: "error",
+      msg: `log-tail: docker unavailable (${msg})`
+    });
+    teardown();
+    raw.end();
+    return;
+  }
+  if (containers.length === 0) {
+    writeEvent(raw, {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      service: "connector",
+      level: "warn",
+      msg: "log-tail: no townhouse containers running"
+    });
+  }
+  const tasks = containers.map(async (c) => {
+    try {
+      for await (const evt of tailFn(docker, c.name, c.service, {
+        signal: controller.signal,
+        tail: 50
+      })) {
+        if (raw.writableEnded) break;
+        writeEvent(raw, evt);
+      }
+    } catch (err) {
+      if (controller.signal.aborted) return;
+      const msg = err instanceof Error ? err.message : String(err);
+      writeEvent(raw, {
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        service: c.service,
+        level: "error",
+        msg: `log-tail: ${c.name} stream error (${msg})`
+      });
+    }
+  });
+  await Promise.allSettled(tasks);
+  teardown();
+  if (!raw.writableEnded) {
+    raw.end();
+  }
+}
+function writeEvent(raw, evt) {
+  if (raw.writableEnded) return;
+  try {
+    raw.write(`data: ${JSON.stringify(evt)}
+
+`);
+  } catch {
+  }
+}
+
 // src/api/server.ts
 async function createApiServer(deps) {
   const { config, logger } = deps;
+  const snapshotPath = join8(
+    dirname11(deps.configPath),
+    "earnings-snapshots.jsonl"
+  );
+  const snapshotWriter = new SnapshotWriter({
+    connectorAdmin: deps.connectorAdmin,
+    snapshotPath,
+    logger
+  });
   const app = await buildFastifyApp({
     logger: logger ?? true,
     bindHost: config.api.host ?? "127.0.0.1"
@@ -8036,9 +11454,17 @@ async function createApiServer(deps) {
   registerWalletRevealRoutes(app, deps);
   registerWalletWithdrawRoutes(app, deps);
   registerConfigPatchRoutes(app, deps);
+  registerNodeLifecycleRoutes(app, deps);
+  registerEarningsRoutes(app, deps);
+  registerLogsRoutes(app, deps);
   registerMetricsWsRoutes(app, deps);
+  snapshotWriter.start();
   const CLOSE_TIMEOUT_MS2 = 5e3;
   async function close() {
+    try {
+      snapshotWriter.stop();
+    } catch {
+    }
     try {
       deps.transportProbe.stop();
     } catch {
@@ -8055,7 +11481,7 @@ async function createApiServer(deps) {
     openSockets.clear();
     await Promise.race([
       app.close(),
-      new Promise((resolve) => setTimeout(resolve, CLOSE_TIMEOUT_MS2))
+      new Promise((resolve2) => setTimeout(resolve2, CLOSE_TIMEOUT_MS2))
     ]);
   }
   return { app, close };
@@ -8246,7 +11672,7 @@ async function createWizardApiServer(initialDeps) {
     state.progressSockets.clear();
     await Promise.race([
       app.close(),
-      new Promise((resolve) => setTimeout(resolve, CLOSE_TIMEOUT_MS))
+      new Promise((resolve2) => setTimeout(resolve2, CLOSE_TIMEOUT_MS))
     ]);
   }
   return { app, close };
@@ -8260,15 +11686,38 @@ export {
   saveConfig,
   DEFAULT_ATOR_PROXY,
   ConnectorConfigGenerator,
-  DockerOrchestrator,
   ConnectorAdminClient,
+  OrchestratorError,
+  DockerOrchestrator,
   TransportProbe,
+  writeHsConnectorConfig,
+  ComposeLoaderError,
+  loadComposeTemplate,
+  materializeComposeTemplate,
+  NodesYamlEntrySchema,
+  NodesYamlSchema,
+  readNodesYaml,
+  writeNodesYaml,
+  BootReconciler,
+  SnapshotWriter,
   saveWallet,
   loadWallet,
   encryptWallet,
   decryptWallet,
+  ImageManifestSchema,
+  isSyntheticDigest,
+  readImageManifest,
   WalletManager,
+  aggregateEarnings,
+  utcDayBoundary,
+  utcMonthBoundary,
+  utcYearBoundary,
+  createDeltaComputer,
+  PeerTypeResolver,
+  LOG_SERVICES,
+  serviceFromContainerName,
+  tailContainerLogs,
   createApiServer,
   createWizardApiServer
 };
-//# sourceMappingURL=chunk-IB6TNCUQ.js.map
+//# sourceMappingURL=chunk-4WCMVIO4.js.map