@toon-protocol/townhouse 0.1.0-rc5 → 0.1.0

package/dist/index.d.ts

@@ -1,150 +1,50 @@
+import { E as EncryptedWallet, T as TownhouseConfig, W as WalletManager, a as ComposeProfile, N as NodeType$1, B as BandwidthStats, H as HealthCheckOptions } from './manager-SsneW_Mj.js';
+export { A as ApiConfig, b as ComposeLoaderError, C as ComposeLoaderOptions, c as ConnectorConfig, d as ContainerSpec, D as DerivedNodeKeys, e as DvmNodeConfig, L as LoggingConfig, M as MillNodeConfig, f as NodeKeyInfo, g as NodeKeys, h as NodesConfig, O as OrchestratorEvents, i as TownNodeConfig, j as TransportConfig, k as WalletConfig, l as WalletManagerConfig, m as WalletState, n as loadComposeTemplate, o as materializeComposeTemplate } from './manager-SsneW_Mj.js';
 import { EventEmitter } from 'node:events';
 import Docker from 'dockerode';
 import { FastifyBaseLogger, FastifyInstance } from 'fastify';
 import { MillHealthResponse } from '@toon-protocol/mill';
 export { MillHealthResponse } from '@toon-protocol/mill';
+import { z } from 'zod';
 
 /**
- * Townhouse configuration schema — TypeScript interfaces only.
- * Runtime validation lives in validator.ts.
+ * Wallet encryption/decryption for Townhouse (Story 21.4, Task 2).
+ *
+ * Uses Node.js crypto: scrypt for KDF, AES-256-GCM for authenticated encryption.
+ * The mnemonic is the plaintext being encrypted.
  */
-interface TownNodeConfig {
-    enabled: boolean;
-    /** Nostr relay fee in millisatoshis per event */
-    feePerEvent?: number;
-    /** Docker image override */
-    image?: string;
-}
-interface ChainEndpoint {
-    rpcUrl: string;
-    wsUrl?: string;
-}
-interface MillChainsConfig {
-    evm?: ChainEndpoint;
-    solana?: ChainEndpoint;
-    mina?: ChainEndpoint;
-}
-interface MillNodeConfig {
-    enabled: boolean;
-    /** Swap fee basis points (1 = 0.01%) */
-    feeBasisPoints?: number;
-    /** Docker image override */
-    image?: string;
-    /**
-     * Chain RPC endpoints the mill should swap against (D2). The orchestrator
-     * does not currently forward this directly into MILL_CONFIG_JSON — it
-     * round-trips through YAML so the dashboard and future stories can read it.
-     */
-    chains?: MillChainsConfig;
-    /** Enabled swap pairs, e.g. ['EVM<->SOL']. Informational; D2-introduced. */
-    pairs?: string[];
-}
-interface DvmNodeConfig {
-    enabled: boolean;
-    /** DVM job fee in millisatoshis */
-    feePerJob?: number;
-    /** Per-kind pricing in millisatoshis (key = stringified kind number) */
-    kindPricing?: Record<string, number>;
-    /** Docker image override */
-    image?: string;
-}
-interface NodesConfig {
-    town: TownNodeConfig;
-    mill: MillNodeConfig;
-    dvm: DvmNodeConfig;
-}
-interface WalletConfig {
-    /** Path to encrypted wallet file (no plaintext mnemonic in config) */
-    encrypted_path: string;
-}
-interface ConnectorConfig {
-    /** Docker image for the shared ILP connector */
-    image: string;
-    /** Admin API port */
-    adminPort: number;
-}
+
 /**
- * Hidden-service publication config (Story 35.5 of the connector repo).
- *
- * When set, the connector boots `@anyone-protocol/anyone-client` in-process,
- * spawns the `anon` binary, publishes a v3 hidden service, and advertises
- * its `wss://<addr>.anyone/btp` URL to peers. The keypair lives at `dir`
- * inside the connector container and persists across restarts when that
- * path is on a mounted volume.
+ * Encrypt a mnemonic with a password using scrypt + AES-256-GCM.
+ */
+declare function encryptWallet(mnemonic: string, password: string): EncryptedWallet;
+/**
+ * Decrypt an encrypted wallet with a password.
+ * Throws on wrong password (GCM auth tag verification failure).
+ */
+declare function decryptWallet(encrypted: EncryptedWallet, password: string): string;
+
+/**
+ * Wallet file I/O for Townhouse (Story 21.4, Task 2.2).
  *
- * Operator surface (this type) is intentionally narrow; the connector's
- * own config has more knobs (binaryPath, configFilePath) that we omit
- * here until a real use case demands them.
+ * Persists encrypted wallet to disk with 0o600 permissions (owner-only).
+ * Warns if existing file has world-readable permissions.
  */
-interface HiddenServiceConfig$1 {
-    /** Path inside the connector container for hs_ed25519_secret_key etc. */
-    dir: string;
-    /** Hidden service port — peers dial <addr>.anyone:<port>. */
-    port: number;
-    /**
-     * Optional override of the externalUrl the connector advertises. Default
-     * is `"auto"` — the connector reads `${dir}/hostname` at startup and
-     * builds `wss://<hostname>.anyone/btp` itself.
-     */
-    externalUrl?: string;
-    /** Optional override of the SDK's start-up readiness deadline (ms). */
-    startupTimeoutMs?: number;
-    /** Optional override of the SDK's shutdown deadline (ms). */
-    stopTimeoutMs?: number;
-}
-interface TransportConfig {
-    /** Transport mode: 'ator' for Tor-based, 'direct' for clearnet */
-    mode: 'ator' | 'direct';
-    /** SOCKS5 proxy address when using ator transport */
-    socksProxy?: string;
-    /**
-     * Externally reachable BTP URL. Required when mode='ator' AND
-     * hiddenService is unset (operator runs their own anon binary external
-     * to the connector and is responsible for the URL). Ignored for
-     * mode='direct'. When hiddenService is set and externalUrl is unset,
-     * the generator emits the literal `"auto"` so the connector resolves
-     * the .anyone hostname from disk at startup.
-     */
-    externalUrl?: string;
-    /**
-     * Optional inbound hidden-service publication. When set, the connector
-     * manages its own anon binary and publishes a .anyone hidden service.
-     */
-    hiddenService?: HiddenServiceConfig$1;
-    /**
-     * Town relay hidden service. When set, the orchestrator starts a second
-     * ator sidecar (parallel to any connector HS sidecar) that forwards
-     * inbound HS traffic to the town container's Nostr WebSocket port (7100),
-     * and the town container is configured to advertise the .anyone URL.
-     * Reuses HiddenServiceConfig — same shape as connector HS config.
-     */
-    relayHiddenService?: HiddenServiceConfig$1;
-}
-interface ApiConfig {
-    /** Dashboard/API port */
-    port: number;
-    /** Bind address */
-    host: string;
-}
-interface LoggingConfig {
-    level: 'debug' | 'info' | 'warn' | 'error';
-}
-interface PresetMetadata {
-    /** Preset that produced this config (D2). */
-    name: 'demo';
-    /** Where the chain endpoints came from — leases.json path or 'local-fallback'. */
-    chainEndpointSource: string;
-}
-interface TownhouseConfig {
-    nodes: NodesConfig;
-    wallet: WalletConfig;
-    connector: ConnectorConfig;
-    transport: TransportConfig;
-    api: ApiConfig;
-    logging: LoggingConfig;
-    /** Present only when the config was generated by `init --preset=<name>`. */
-    preset?: PresetMetadata;
-}
+
+/**
+ * Save encrypted wallet to disk with restrictive permissions.
+ * Creates parent directory if missing.
+ */
+declare function saveWallet(path: string, encrypted: EncryptedWallet): Promise<void>;
+/**
+ * Load encrypted wallet from disk.
+ * Returns null if file does not exist.
+ * Warns (via returned flag) if file permissions are too open.
+ */
+declare function loadWallet(path: string): Promise<{
+    wallet: EncryptedWallet;
+    permissionsWarning?: string;
+} | null>;
 
 /**
  * Sensible default configuration. All nodes disabled by default —
@@ -185,244 +85,476 @@ declare class ConfigValidationError extends Error {
 declare function validateConfig(raw: unknown): TownhouseConfig;
 
 /**
- * Docker orchestration types for Townhouse (Story 21.2).
+ * Connector types for Townhouse (Story 21.3).
  *
- * STUB FILE: Created by ATDD workflow (red phase).
- * Implementation will be added during the green phase.
+ * Defines the runtime configuration shape for the standalone ILP connector,
+ * peer entries, and admin API response types.
  */
-/** Node types that can be orchestrated by Townhouse. */
-type NodeType$1 = 'town' | 'mill' | 'dvm';
-/** Specification for a container to be created by the orchestrator. */
-interface ContainerSpec {
-    /** Container name (e.g., 'townhouse-town') */
-    name: string;
-    /** Docker image to use */
-    image: string;
-    /** Environment variables to pass to the container */
-    env: Record<string, string>;
-    /** Network to attach the container to */
-    network: string;
-    /** Port mappings (host:container) */
-    ports?: Record<string, string>;
-}
-/** Events emitted by the orchestrator during operations. */
-interface OrchestratorEvents {
-    /** Emitted during image pull with progress info */
-    pullProgress: {
-        image: string;
-        status: string;
-        id?: string;
-        progress?: string;
-    };
-    /** Emitted when a container changes state */
-    containerState: {
-        name: string;
-        state: 'creating' | 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
-        /** Additional context for error states (e.g., error message) */
-        detail?: string;
-    };
-    /** Emitted during health check polling */
-    healthCheck: {
-        name: string;
-        status: string;
-        attempt: number;
-    };
-    /** Emitted before connector restart during peer registration update */
-    connectorRestarting: {
-        reason: string;
+
+/**
+ * A peer entry representing a child node connected to the connector via BTP.
+ * Each active node becomes a child peer of the connector.
+ */
+interface PeerEntry {
+    /** Node type identifier (e.g., 'town', 'mill', 'dvm') */
+    id: string;
+    /** Relationship to connector — nodes are always children */
+    relation: 'child';
+    /** BTP WebSocket URL for Docker-internal communication */
+    btpUrl: string;
+    /** Asset code for ILP packets (e.g., 'USD') */
+    assetCode: string;
+    /** Asset scale (e.g., 6 for micro-units) */
+    assetScale: number;
+}
+/**
+/**
+ * Hidden-service configuration for the connector's inbound BTP path.
+ *
+ * When set under transport.hiddenService, the connector boots the
+ * `@anyone-protocol/anyone-client` SDK in-process (Story 35.5 of the
+ * connector repo, "ManagedAnonClient") which spawns the `anon` binary
+ * and publishes a v3 hidden service. The .anyone hostname is read from
+ * `${dir}/hostname` after publish and substituted into the connector's
+ * externalUrl as `wss://<hostname>.anyone/btp`.
+ *
+ * Operator surface lives at transport.hiddenService.{dir, port}; the
+ * connector's wire format is more verbose (transport.managedOptions.*) —
+ * config-generator handles the translation.
+ *
+ * Per-townhouse-instance keypair: the secret key under `${dir}/` is the
+ * .anyone identity. Persist it across redeploys to keep the address stable;
+ * delete it to rotate.
+ */
+interface HiddenServiceConfig {
+    /**
+     * Absolute path to the v3 hidden-service key directory inside the
+     * connector container. The connector creates `hs_ed25519_secret_key`,
+     * `hs_ed25519_public_key`, and `hostname` here on first boot, then
+     * reuses them on subsequent boots if present.
+     */
+    dir: string;
+    /**
+     * Hidden service port advertised on the .anyone address. Forwards to
+     * the connector's BTP server (typically same port as connector's
+     * btpServerPort, since the HS port = the port external peers dial).
+     */
+    port: number;
+    /**
+     * Optional override for the externalUrl the connector advertises.
+     * Defaults to the literal "auto" when unset, which makes the connector
+     * resolve the .anyone hostname from `${dir}/hostname` at startup.
+     * Set explicitly only when forcing a specific .anyone address (rare).
+     */
+    externalUrl?: string;
+    /** Overall deadline for SOCKS port readiness (ms). Default 60000. */
+    startupTimeoutMs?: number;
+    /** Overall deadline for `sdk.stop()` (ms). Default 10000. */
+    stopTimeoutMs?: number;
+}
+/**
+ * Runtime configuration for the standalone ILP connector.
+ * Generated by ConnectorConfigGenerator from TownhouseConfig.
+ */
+interface ConnectorRuntimeConfig {
+    /** Admin API listen port */
+    adminPort: number;
+    /** Base ILP address for this connector */
+    ilpAddress: string;
+    /** List of child peer entries (one per active node) */
+    peers: PeerEntry[];
+    /** Transport configuration */
+    transport: {
+        /**
+         * Operator-facing transport selection. Maps to the connector's
+         * discriminated union internally (mode='ator' → type='socks5').
+         */
+        mode: 'ator' | 'direct';
+        /** SOCKS5 proxy URL (must be socks5h://) — required when mode='ator'. */
+        socksProxy?: string;
+        /**
+         * Externally reachable BTP URL the connector advertises to peers.
+         * Required when mode='ator' AND hiddenService is unset (operator runs
+         * their own anon binary externally). Ignored for mode='direct'.
+         * When hiddenService IS set and externalUrl is unset, the generator
+         * emits the literal "auto" so the connector resolves the .anyone
+         * hostname at startup.
+         */
+        externalUrl?: string;
+        /** Inbound hidden-service publication (Story 35.5 path). */
+        hiddenService?: HiddenServiceConfig;
     };
-    /** Emitted after connector restart and health check passes */
-    connectorRestarted: {
-        peers: string[];
+}
+/**
+ * Response from GET /health on the connector's healthCheckPort.
+ * Mirrors `HealthStatus` from `@toon-protocol/connector`.
+ */
+interface HealthResponse {
+    status: 'healthy' | 'unhealthy' | 'starting' | 'degraded';
+    uptime: number;
+    peersConnected: number;
+    totalPeers: number;
+    timestamp: string;
+    nodeId?: string;
+    version?: string;
+}
+/**
+ * Per-peer ILP counter snapshot from GET /admin/metrics.json.
+ * Mirrors `AdminMetricsJsonPeer` from `@toon-protocol/connector`.
+ */
+interface MetricsPeerEntry {
+    peerId: string;
+    connected: boolean;
+    packetsForwarded: number;
+    packetsRejected: number;
+    bytesSent: number;
+    /** Connector v3.7.0+ (toon-protocol/connector#73). Counts packets accepted
+     *  via the self-delivery code path (route nextHop === connector's own
+     *  nodeId). Older connectors omit this field — default to 0 at consumers. */
+    packetsLocallyDelivered?: number;
+    lastPacketAt: string | null;
+}
+/**
+ * Response from GET /admin/metrics.json on the connector's adminApi port.
+ * Mirrors `AdminMetricsJsonResponse` from `@toon-protocol/connector`.
+ */
+interface MetricsResponse {
+    uptimeSeconds: number;
+    aggregate: {
+        packetsForwarded: number;
+        packetsRejected: number;
+        bytesSent: number;
+        /** Connector v3.7.0+ — see MetricsPeerEntry.packetsLocallyDelivered. */
+        packetsLocallyDelivered?: number;
     };
+    peers: MetricsPeerEntry[];
+    timestamp: string;
 }
-/** Options for health check polling. */
-interface HealthCheckOptions {
-    /** Polling interval in milliseconds (default: 2000) */
-    interval?: number;
-    /** Timeout in milliseconds (default: 60000) */
-    timeout?: number;
+/**
+ * Peer entry from GET /admin/peers on the connector's adminApi port.
+ * Mirrors the response of the connector's `router.get('/peers', …)` handler.
+ * Note: per-peer packet counters live on /admin/metrics.json, not here.
+ */
+interface PeerStatus {
+    id: string;
+    connected: boolean;
+    ilpAddresses: string[];
+    routeCount: number;
 }
-/** Network I/O stats for a container (from dockerode stats stream) */
-interface BandwidthStats {
-    bytesIn: number;
-    bytesOut: number;
-    sampleAt: number;
+/**
+ * Wrapper response from GET /admin/peers.
+ * Mirrors the connector's `router.get('/peers')` JSON envelope.
+ */
+interface PeersResponse {
+    nodeId: string;
+    peerCount: number;
+    connectedCount: number;
+    peers: PeerStatus[];
 }
-
 /**
- * Wallet management types for Townhouse (Story 21.4).
+ * Channel summary entry from GET /admin/channels on the connector's adminApi port.
+ * Mirrors `ChannelSummary` from `@toon-protocol/connector`
+ * (packages/connector/src/http/admin-api.ts ChannelSummary at v3.x).
  *
- * Defines interfaces for HD wallet key derivation, encryption at rest,
- * and node key management.
+ * `status` is kept as `string` (not a union) because the connector's enum may
+ * grow without warning — the contract canary catches shape drift, not enum domain.
  */
-
-/** Configuration for the WalletManager */
-interface WalletManagerConfig {
-    /** Path to encrypted wallet file */
-    encryptedPath: string;
-}
-/** Keys derived for a specific node type */
-interface NodeKeys {
-    /** Nostr public key (hex-encoded, 32 bytes) */
-    nostrPubkey: string;
-    /** Nostr secret key (raw 32-byte scalar) */
-    nostrSecretKey: Uint8Array;
-    /** EVM address (checksummed, 0x-prefixed) */
-    evmAddress: string;
-    /** EVM private key (raw 32 bytes) */
-    evmPrivateKey: Uint8Array;
-    /** BIP-44 derivation path used for Nostr key */
-    nostrDerivationPath: string;
-    /** BIP-44 derivation path used for EVM key */
-    evmDerivationPath: string;
-    /** Base58-encoded Solana public key — mill only, omitted for town/dvm */
-    solanaAddress?: string;
-    /** Mina public key hex — mill only, omitted for town/dvm */
-    minaAddress?: string;
-}
-/** Map of node type to its derived keys */
-interface DerivedNodeKeys {
-    town: NodeKeys;
-    mill: NodeKeys;
-    dvm: NodeKeys;
-}
-/** Summary info for display (no secrets) */
-interface NodeKeyInfo {
-    /** Node type */
-    nodeType: NodeType$1;
-    /** Nostr public key (hex) */
-    nostrPubkey: string;
-    /** EVM address (checksummed) */
-    evmAddress: string;
-    /** Nostr derivation path */
-    nostrDerivationPath: string;
-    /** EVM derivation path */
-    evmDerivationPath: string;
-    /** Base58-encoded Solana public key — mill only, omitted for town/dvm */
-    solanaAddress?: string;
-    /** Mina public key hex — mill only, omitted for town/dvm */
-    minaAddress?: string;
-}
-/** Persisted wallet state (in memory after decryption) */
-interface WalletState {
-    /** All derived node keys */
-    keys: DerivedNodeKeys;
-}
-/** Encrypted wallet file format (JSON, all fields base64-encoded) */
-interface EncryptedWallet {
-    /** scrypt salt (base64) */
-    salt: string;
-    /** AES-GCM initialization vector (base64) */
-    iv: string;
-    /** AES-256-GCM ciphertext (base64) */
-    ciphertext: string;
-    /** AES-GCM authentication tag (base64) */
-    tag: string;
+interface ChannelSummary {
+    channelId: string;
+    peerId: string;
+    chain: string;
+    status: string;
+    deposit: string;
+    lastActivity: string;
+}
+/**
+ * Filter params for GET /packets on the connector admin API.
+ *
+ * Townhouse-Side Contract (§getPacketLog) — added in story 21.10.
+ * The connector must expose `GET /packets?ilpAddress=<>&since=<>&limit=<>`.
+ * If the running connector image does not expose this endpoint, the
+ * /nodes/:type/packets/timeseries route returns 503 and the contract canary
+ * will catch the drift. See packages/sdk/CONNECTOR_MIGRATION.md §Townhouse-Side Contract.
+ */
+interface PacketLogFilter {
+    ilpAddress?: string;
+    since?: number;
+    limit?: number;
+}
+/** A single packet log entry returned by GET /packets */
+interface PacketLogEntry {
+    ts: number;
+    ilpAddressFrom: string;
+    ilpAddressTo: string;
+    amount: string;
+    result: 'fulfill' | 'reject' | 'timeout';
+}
+/**
+ * Response from GET /admin/hs-hostname on the connector's adminApi port.
+ * Mirrors the connector v3.5.0+ `HsHostnameResponse` (Story 44.1 / AC FR35).
+ * Both fields are null while the .anyone hidden-service bootstrap is in
+ * progress; both become non-null once the descriptor is published.
+ */
+interface HsHostnameResponse {
+    hostname: string | null;
+    publishedAt: string | null;
 }
 
 /**
- * WalletManager — HD key derivation for Townhouse (Story 21.4, Task 1).
+ * Per-asset earnings row from GET /admin/earnings.json (endpoint added in connector v3.2.0).
+ * Mirrors `AdminEarningsByAsset` from `@toon-protocol/connector` admin-api.
  *
- * Single BIP-39 mnemonic, deterministic HD derivation per node type.
- * Uses BIP-44 paths with distinct account indices per node type:
- *   - Town: account 0
- *   - Mill: account 1
- *   - DVM:  account 2
+ * Cumulative amounts are decimal-string bigints (JSON-safe for any asset scale).
+ * `claimsReceivedTotal` tracks value received from the peer (they paid us);
+ * `claimsSentTotal` tracks value forwarded to the peer (they earned).
+ */
+interface AssetEarnings {
+    assetCode: string;
+    assetScale: number;
+    claimsReceivedTotal: string;
+    claimsSentTotal: string;
+    netBalance: string;
+    lastClaimAt: string | null;
+}
+/**
+ * Per-peer earnings entry from GET /admin/earnings.json.
+ * Mirrors `AdminEarningsJsonPeer` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:278-281`.
+ */
+interface PeerEarnings {
+    peerId: string;
+    byAsset: AssetEarnings[];
+}
+/**
+ * Connector fee rollup from GET /admin/earnings.json.
+ * Mirrors `AdminEarningsConnectorFee` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:283-287`.
+ */
+interface ConnectorFeeEntry {
+    assetCode: string;
+    assetScale: number;
+    total: string;
+}
+/**
+ * A single recent claim entry from GET /admin/earnings.json.
+ * Mirrors `AdminEarningsRecentClaim` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:289-296`.
+ */
+interface RecentClaim {
+    peerId: string;
+    assetCode: string;
+    assetScale: number;
+    amount: string;
+    direction: 'inbound' | 'outbound';
+    at: string;
+}
+/**
+ * Typed wrapper around the connector's wire-level `timestamp: string` field.
+ * The connector's `AdminEarningsJsonResponse` carries a plain ISO-8601 string
+ * (`packages/connector/src/http/admin-api.ts:298-304`). Townhouse wraps it as
+ * a value object so dashboard consumers have a typed handle and the field can
+ * be extended (`epoch?`, `timezone?`) without breaking callers.
  *
- * Nostr keys use NIP-06 coin type 1237: m/44'/1237'/{account}'/0/0
- * EVM keys use standard coin type 60:   m/44'/60'/{account}'/0/0
+ * `ConnectorAdminClient.getEarnings()` performs the wrap on the way out:
+ * `timestamp: { iso: rawString }`.
  */
+interface EarningsTimestamp {
+    iso: string;
+}
+/**
+ * Response from GET /admin/earnings.json on the connector's adminApi port.
+ * Mirrors `AdminEarningsJsonResponse` from
+ * `@toon-protocol/connector packages/connector/src/http/admin-api.ts:298-304`.
+ *
+ * NOTE: The connector's wire shape carries `timestamp: string`. Townhouse's
+ * `getEarnings()` adapts it to `timestamp: EarningsTimestamp` (value object).
+ *
+ * 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.
+ */
+interface EarningsResponse {
+    uptimeSeconds: number;
+    peers: PeerEarnings[];
+    connectorFees: ConnectorFeeEntry[];
+    recentClaims: RecentClaim[];
+    timestamp: EarningsTimestamp;
+}
 
 /**
- * WalletManager handles mnemonic generation, key derivation, and in-memory
- * key lifecycle for Townhouse node operations.
+ * Connector Admin Client for Townhouse (Story 21.3, contract aligned in 21.7.5).
+ *
+ * HTTP client for the connector's admin API endpoints. Paths and response
+ * shapes mirror the connector source-of-truth — see
+ * `@toon-protocol/connector` `packages/connector/src/http/{types,admin-api}.ts`.
+ *
+ * Uses Node.js native fetch (available in Node 20+).
+ *
+ * Two distinct HTTP servers live on the connector image:
+ *   - healthCheckPort serves /health and /health/{live,ready}
+ *   - adminApi.port serves /admin/* (peers, metrics.json, routes, channels, …)
+ *
+ * The base URL passed to this client must point at whichever server hosts
+ * the endpoint being called: pass the healthCheckPort base for `getHealth`
+ * and the adminApi.port base for `getPeers` / `getMetrics`. In practice
+ * Townhouse currently runs both ports on the same host, so callers either
+ * construct two clients or hit a shared base URL when the ports overlap.
  */
-declare class WalletManager {
-    private readonly config;
-    private state;
-    constructor(config: WalletManagerConfig);
-    /** Path to the encrypted wallet file */
-    get encryptedPath(): string;
+
+declare class ConnectorAdminClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
     /**
-     * Generate a new 12-word BIP-39 mnemonic and derive all node keys.
-     * Returns the mnemonic (for one-time display) and the derived state.
+     * @param baseUrl - Base URL for the connector admin API (e.g., 'http://localhost:9402')
+     * @param timeoutMs - Request timeout in milliseconds (default: 5000)
      */
-    generate(): Promise<{
-        mnemonic: string;
-        state: WalletState;
-    }>;
+    constructor(baseUrl: string, timeoutMs?: number);
+    /** Public read of the configured base URL (used by drill-command probes to derive a sibling client). */
+    getBaseUrl(): string;
     /**
-     * Import an existing mnemonic (12 or 24 words) and derive all node keys.
-     * Throws if mnemonic is invalid (wrong checksum, wrong word count, etc).
+     * 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.
      */
-    fromMnemonic(mnemonic: string): Promise<WalletState>;
+    pingAdminLive(): Promise<{
+        status: 'healthy';
+        nodeId?: string;
+    }>;
     /**
-     * Get derived keys for a specific node type.
-     * Throws if wallet has not been initialized (call generate() or fromMnemonic() first).
+     * 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
      */
-    getNodeKeys(nodeType: NodeType$1): NodeKeys;
+    getHealth(): Promise<HealthResponse>;
     /**
-     * Get display-safe info for all node types (no secrets).
+     * 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.
      */
-    getAllKeys(): NodeKeyInfo[];
+    getHsHostname(): Promise<HsHostnameResponse>;
     /**
-     * List keys for all node types (alias for getAllKeys for API compatibility).
+     * 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
      */
-    listKeys(): NodeKeyInfo[];
+    getMetrics(): Promise<MetricsResponse>;
     /**
-     * Zero all in-memory key material. After calling lock(),
-     * getNodeKeys() and getAllKeys() will throw.
+     * 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
      */
-    lock(): void;
+    getEarnings(): Promise<EarningsResponse>;
     /**
-     * Derive keys for all node types from a mnemonic.
+     * 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
      */
-    private deriveAllKeys;
+    getPeers(): Promise<PeerStatus[]>;
     /**
-     * Derive Nostr + EVM keys for a specific node type.
+     * 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
      */
-    private deriveNodeKeys;
-}
-
-/**
- * Wallet encryption/decryption for Townhouse (Story 21.4, Task 2).
- *
- * Uses Node.js crypto: scrypt for KDF, AES-256-GCM for authenticated encryption.
- * The mnemonic is the plaintext being encrypted.
- */
-
-/**
- * Encrypt a mnemonic with a password using scrypt + AES-256-GCM.
- */
-declare function encryptWallet(mnemonic: string, password: string): EncryptedWallet;
-/**
- * Decrypt an encrypted wallet with a password.
- * Throws on wrong password (GCM auth tag verification failure).
- */
-declare function decryptWallet(encrypted: EncryptedWallet, password: string): string;
-
-/**
- * Wallet file I/O for Townhouse (Story 21.4, Task 2.2).
- *
- * Persists encrypted wallet to disk with 0o600 permissions (owner-only).
- * Warns if existing file has world-readable permissions.
- */
-
-/**
- * Save encrypted wallet to disk with restrictive permissions.
- * Creates parent directory if missing.
- */
-declare function saveWallet(path: string, encrypted: EncryptedWallet): Promise<void>;
-/**
- * Load encrypted wallet from disk.
- * Returns null if file does not exist.
- * Warns (via returned flag) if file permissions are too open.
- */
-declare function loadWallet(path: string): Promise<{
-    wallet: EncryptedWallet;
-    permissionsWarning?: string;
-} | null>;
+    getChannels(): Promise<ChannelSummary[]>;
+    /**
+     * 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.
+     */
+    registerPeer(input: {
+        id: string;
+        url: string;
+        authToken: string;
+        routes?: {
+            prefix: string;
+            priority?: number;
+        }[];
+        transport?: 'direct' | 'socks5';
+        relation?: 'parent' | 'peer' | 'child';
+    }): Promise<void>;
+    /**
+     * 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
+     */
+    removePeer(peerId: string): Promise<void>;
+    /**
+     * 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
+     */
+    getPacketLog(filter?: PacketLogFilter): Promise<PacketLogEntry[]>;
+    /**
+     * Perform an HTTP GET request to the connector admin API.
+     * Wraps fetch with error handling for connection refused and non-200 responses.
+     */
+    private fetch;
+}
 
 /**
  * Docker Orchestration Engine for Townhouse (Story 21.2).
@@ -432,6 +564,33 @@ declare function loadWallet(path: string): Promise<{
  * Uses dockerode for programmatic Docker control with DI for testability.
  */
 
+interface RunDockerOptions {
+    timeout?: number;
+    maxBuffer?: number;
+    inheritStdio?: boolean;
+    /** Override the subprocess env. Defaults to process.env when omitted. */
+    env?: NodeJS.ProcessEnv;
+}
+type ExecFileAsyncSignature = (file: string, args: readonly string[], options?: RunDockerOptions) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Error thrown by DockerOrchestrator HS-path failures (Story 45.3).
+ * Carries the failed-service name + subprocess diagnostics so CLI consumers
+ * (Story 45.4) can render Sally's failure-state copy library (UX-DR5).
+ */
+declare class OrchestratorError extends Error {
+    readonly service?: string;
+    readonly exitCode?: number;
+    readonly stderr?: string;
+    constructor(message: string, options?: {
+        service?: string;
+        exitCode?: number;
+        stderr?: string;
+        cause?: Error;
+    });
+}
 /**
  * DockerOrchestrator manages the lifecycle of Townhouse containers.
  *
@@ -446,15 +605,47 @@ declare class DockerOrchestrator extends EventEmitter {
     private readonly walletManager;
     private activeNodes;
     private readonly statsCache;
-    constructor(docker: Docker, config: TownhouseConfig, walletManager?: WalletManager);
+    private readonly profile;
+    private readonly composePath;
+    private readonly execFileAsync;
+    private readonly adminClientFactory;
+    constructor(docker: Docker, config: TownhouseConfig, walletManager?: WalletManager, options?: {
+        profile?: ComposeProfile;
+        composePath?: string;
+        execFileAsync?: ExecFileAsyncSignature;
+        adminClientFactory?: (baseUrl: string, timeoutMs: number) => ConnectorAdminClient;
+    });
     /**
-     * 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
+     * Orchestrate full startup sequence. Branches on profile:
+     * - 'dev' (default): dockerode-based, preserves existing dev-stack behavior
+     * - 'hs': docker compose subprocess + HS hostname readiness gate
      */
     up(profiles: NodeType$1[]): Promise<void>;
+    private upDev;
+    /**
+     * 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`.
+     */
+    private requireComposePath;
+    /**
+     * 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.
+     */
+    private validateComposePath;
+    /** HS-mode startup: shell out to `docker compose up -d`, wait for HS hostname. */
+    private upHs;
+    /**
+     * 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'`.
+     */
+    private surfaceComposeFailure;
+    private waitForHsHostname;
     /**
      * Regenerate connector config and restart the connector container
      * with updated environment variables (peer list).
@@ -473,12 +664,13 @@ declare class DockerOrchestrator extends EventEmitter {
      */
     removeNode(type: NodeType$1): Promise<void>;
     /**
-     * Graceful shutdown — stops containers in reverse order:
-     * 1. Stop all node containers in parallel
-     * 2. Stop connector
-     * 3. Remove network
+     * Graceful shutdown. Branches on profile:
+     * - 'dev' (default): dockerode-based teardown
+     * - 'hs': docker compose subprocess
      */
     down(): Promise<void>;
+    private downDev;
+    private downHs;
     /**
      * Resolve the Nostr relay WebSocket URL for a Town node instance.
      *
@@ -529,6 +721,39 @@ declare class DockerOrchestrator extends EventEmitter {
      * Emits pullProgress events during download.
      */
     pullImages(profiles: NodeType$1[]): Promise<void>;
+    /**
+     * 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.
+     */
+    pullImage(image: string): Promise<void>;
+    /**
+     * 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.
+     */
+    startNodeViaCompose(type: NodeType$1, env: Record<string, string>): Promise<void>;
+    /**
+     * 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.
+     */
+    stopNodeViaCompose(type: NodeType$1): Promise<void>;
     /**
      * Poll container health status via inspect().
      * Retries at configurable interval, throws on timeout.
@@ -565,217 +790,37 @@ declare class DockerOrchestrator extends EventEmitter {
      * forwarding inbound traffic to the town container's Nostr WebSocket port.
      *
      * The keypair directory is mounted read-write because the sidecar's
-     * entrypoint writes the `hostname` file on first boot (see
-     * docker/townhouse-ator-sidecar/Dockerfile). The town container picks up
-     * the resulting .anyone URL via the operator-set externalUrl field.
-     */
-    private startRelayAtorSidecar;
-    /**
-     * Stop and remove a single container.
-     */
-    private stopAndRemove;
-    /**
-     * Remove the townhouse-net network if it exists.
-     */
-    private removeNetwork;
-    /**
-     * Build environment variables for the connector container.
-     * Delegates to ConnectorConfigGenerator for consistent config generation.
-     */
-    private buildConnectorEnv;
-    /**
-     * Build environment variables for a node container.
-     * If a WalletManager is provided, injects per-node identity keys.
-     */
-    private buildNodeEnv;
-    /**
-     * Follow a Docker pull stream and emit progress events.
-     */
-    private followPullProgress;
-}
-
-/**
- * Connector types for Townhouse (Story 21.3).
- *
- * Defines the runtime configuration shape for the standalone ILP connector,
- * peer entries, and admin API response types.
- */
-
-/**
- * A peer entry representing a child node connected to the connector via BTP.
- * Each active node becomes a child peer of the connector.
- */
-interface PeerEntry {
-    /** Node type identifier (e.g., 'town', 'mill', 'dvm') */
-    id: string;
-    /** Relationship to connector — nodes are always children */
-    relation: 'child';
-    /** BTP WebSocket URL for Docker-internal communication */
-    btpUrl: string;
-    /** Asset code for ILP packets (e.g., 'USD') */
-    assetCode: string;
-    /** Asset scale (e.g., 6 for micro-units) */
-    assetScale: number;
-}
-/**
-/**
- * Hidden-service configuration for the connector's inbound BTP path.
- *
- * When set under transport.hiddenService, the connector boots the
- * `@anyone-protocol/anyone-client` SDK in-process (Story 35.5 of the
- * connector repo, "ManagedAnonClient") which spawns the `anon` binary
- * and publishes a v3 hidden service. The .anyone hostname is read from
- * `${dir}/hostname` after publish and substituted into the connector's
- * externalUrl as `wss://<hostname>.anyone/btp`.
- *
- * Operator surface lives at transport.hiddenService.{dir, port}; the
- * connector's wire format is more verbose (transport.managedOptions.*) —
- * config-generator handles the translation.
- *
- * Per-townhouse-instance keypair: the secret key under `${dir}/` is the
- * .anyone identity. Persist it across redeploys to keep the address stable;
- * delete it to rotate.
- */
-interface HiddenServiceConfig {
-    /**
-     * Absolute path to the v3 hidden-service key directory inside the
-     * connector container. The connector creates `hs_ed25519_secret_key`,
-     * `hs_ed25519_public_key`, and `hostname` here on first boot, then
-     * reuses them on subsequent boots if present.
-     */
-    dir: string;
-    /**
-     * Hidden service port advertised on the .anyone address. Forwards to
-     * the connector's BTP server (typically same port as connector's
-     * btpServerPort, since the HS port = the port external peers dial).
-     */
-    port: number;
-    /**
-     * Optional override for the externalUrl the connector advertises.
-     * Defaults to the literal "auto" when unset, which makes the connector
-     * resolve the .anyone hostname from `${dir}/hostname` at startup.
-     * Set explicitly only when forcing a specific .anyone address (rare).
-     */
-    externalUrl?: string;
-    /** Overall deadline for SOCKS port readiness (ms). Default 60000. */
-    startupTimeoutMs?: number;
-    /** Overall deadline for `sdk.stop()` (ms). Default 10000. */
-    stopTimeoutMs?: number;
-}
-/**
- * Runtime configuration for the standalone ILP connector.
- * Generated by ConnectorConfigGenerator from TownhouseConfig.
- */
-interface ConnectorRuntimeConfig {
-    /** Admin API listen port */
-    adminPort: number;
-    /** Base ILP address for this connector */
-    ilpAddress: string;
-    /** List of child peer entries (one per active node) */
-    peers: PeerEntry[];
-    /** Transport configuration */
-    transport: {
-        /**
-         * Operator-facing transport selection. Maps to the connector's
-         * discriminated union internally (mode='ator' → type='socks5').
-         */
-        mode: 'ator' | 'direct';
-        /** SOCKS5 proxy URL (must be socks5h://) — required when mode='ator'. */
-        socksProxy?: string;
-        /**
-         * Externally reachable BTP URL the connector advertises to peers.
-         * Required when mode='ator' AND hiddenService is unset (operator runs
-         * their own anon binary externally). Ignored for mode='direct'.
-         * When hiddenService IS set and externalUrl is unset, the generator
-         * emits the literal "auto" so the connector resolves the .anyone
-         * hostname at startup.
-         */
-        externalUrl?: string;
-        /** Inbound hidden-service publication (Story 35.5 path). */
-        hiddenService?: HiddenServiceConfig;
-    };
-}
-/**
- * Response from GET /health on the connector's healthCheckPort.
- * Mirrors `HealthStatus` from `@toon-protocol/connector`.
- */
-interface HealthResponse {
-    status: 'healthy' | 'unhealthy' | 'starting' | 'degraded';
-    uptime: number;
-    peersConnected: number;
-    totalPeers: number;
-    timestamp: string;
-    nodeId?: string;
-    version?: string;
-}
-/**
- * Per-peer ILP counter snapshot from GET /admin/metrics.json.
- * Mirrors `AdminMetricsJsonPeer` from `@toon-protocol/connector`.
- */
-interface MetricsPeerEntry {
-    peerId: string;
-    connected: boolean;
-    packetsForwarded: number;
-    packetsRejected: number;
-    bytesSent: number;
-    lastPacketAt: string | null;
-}
-/**
- * Response from GET /admin/metrics.json on the connector's adminApi port.
- * Mirrors `AdminMetricsJsonResponse` from `@toon-protocol/connector`.
- */
-interface MetricsResponse {
-    uptimeSeconds: number;
-    aggregate: {
-        packetsForwarded: number;
-        packetsRejected: number;
-        bytesSent: number;
-    };
-    peers: MetricsPeerEntry[];
-    timestamp: string;
-}
-/**
- * Peer entry from GET /admin/peers on the connector's adminApi port.
- * Mirrors the response of the connector's `router.get('/peers', …)` handler.
- * Note: per-peer packet counters live on /admin/metrics.json, not here.
- */
-interface PeerStatus {
-    id: string;
-    connected: boolean;
-    ilpAddresses: string[];
-    routeCount: number;
-}
-/**
- * Wrapper response from GET /admin/peers.
- * Mirrors the connector's `router.get('/peers')` JSON envelope.
- */
-interface PeersResponse {
-    nodeId: string;
-    peerCount: number;
-    connectedCount: number;
-    peers: PeerStatus[];
-}
-/**
- * Filter params for GET /packets on the connector admin API.
- *
- * Townhouse-Side Contract (§getPacketLog) — added in story 21.10.
- * The connector must expose `GET /packets?ilpAddress=<>&since=<>&limit=<>`.
- * If the running connector image does not expose this endpoint, the
- * /nodes/:type/packets/timeseries route returns 503 and the contract canary
- * will catch the drift. See packages/sdk/CONNECTOR_MIGRATION.md §Townhouse-Side Contract.
- */
-interface PacketLogFilter {
-    ilpAddress?: string;
-    since?: number;
-    limit?: number;
-}
-/** A single packet log entry returned by GET /packets */
-interface PacketLogEntry {
-    ts: number;
-    ilpAddressFrom: string;
-    ilpAddressTo: string;
-    amount: string;
-    result: 'fulfill' | 'reject' | 'timeout';
+     * entrypoint writes the `hostname` file on first boot (see
+     * docker/townhouse-ator-sidecar/Dockerfile). The town container picks up
+     * the resulting .anyone URL via the operator-set externalUrl field.
+     */
+    private startRelayAtorSidecar;
+    /**
+     * Stop and remove a single container.
+     */
+    private stopAndRemove;
+    /**
+     * Remove the townhouse-net network if it exists.
+     */
+    private removeNetwork;
+    /**
+     * Build environment variables for the connector container.
+     * Delegates to ConnectorConfigGenerator for consistent config generation.
+     */
+    private buildConnectorEnv;
+    /**
+     * 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).
+     */
+    private buildNodeEnv;
+    /**
+     * Follow a Docker pull stream and emit progress events.
+     */
+    private followPullProgress;
 }
 
 /**
@@ -853,74 +898,6 @@ declare class ConnectorConfigGenerator {
     private generateTransportConfig;
 }
 
-/**
- * Connector Admin Client for Townhouse (Story 21.3, contract aligned in 21.7.5).
- *
- * HTTP client for the connector's admin API endpoints. Paths and response
- * shapes mirror the connector source-of-truth — see
- * `@toon-protocol/connector` `packages/connector/src/http/{types,admin-api}.ts`.
- *
- * Uses Node.js native fetch (available in Node 20+).
- *
- * Two distinct HTTP servers live on the connector image:
- *   - healthCheckPort serves /health and /health/{live,ready}
- *   - adminApi.port serves /admin/* (peers, metrics.json, routes, channels, …)
- *
- * The base URL passed to this client must point at whichever server hosts
- * the endpoint being called: pass the healthCheckPort base for `getHealth`
- * and the adminApi.port base for `getPeers` / `getMetrics`. In practice
- * Townhouse currently runs both ports on the same host, so callers either
- * construct two clients or hit a shared base URL when the ports overlap.
- */
-
-declare class ConnectorAdminClient {
-    private readonly baseUrl;
-    private readonly 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: string, timeoutMs?: number);
-    /**
-     * 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
-     */
-    getHealth(): Promise<HealthResponse>;
-    /**
-     * 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
-     */
-    getMetrics(): Promise<MetricsResponse>;
-    /**
-     * 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
-     */
-    getPeers(): Promise<PeerStatus[]>;
-    /**
-     * 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
-     */
-    getPacketLog(filter?: PacketLogFilter): Promise<PacketLogEntry[]>;
-    /**
-     * Perform an HTTP GET request to the connector admin API.
-     * Wraps fetch with error handling for connection refused and non-200 responses.
-     */
-    private fetch;
-}
-
 /**
  * ATOR transport probe — periodically TCP-connects to the configured SOCKS5
  * proxy host:port and measures direct HTTPS latency for comparison.
@@ -970,36 +947,6 @@ declare class TransportProbe {
     private logTransition;
 }
 
-type ComposeProfile = 'dev' | 'hs';
-interface ComposeLoaderOptions {
-    /** Override default `~/.townhouse/` write target. Used by tests. */
-    townhouseHome?: string;
-    /** Override the package-relative dist directory the loader reads from.
-     *  Defaults to the `dist/` adjacent to compose-loader.js at runtime.
-     *  Tests use this to point at fixture directories. */
-    distDir?: string;
-}
-declare class ComposeLoaderError extends Error {
-    constructor(message: string);
-}
-/**
- * Returns the rendered compose YAML for the requested profile.
- * For 'hs', digest substitutions are already applied (resolved at build time).
- * For 'dev', the YAML is returned verbatim (uses local `toon:*` image tags).
- * Throws `ComposeLoaderError` if the requested profile's YAML is unreadable.
- */
-declare function loadComposeTemplate(profile: ComposeProfile, options?: ComposeLoaderOptions): string;
-/**
- * Writes the resolved compose YAML to `<townhouseHome>/compose/<profile>.yml`
- * and copies `dist/image-manifest.json` to `<townhouseHome>/image-manifest.json`.
- * BOTH output files are written with mode 0o600 (NFR8 — operator-secret file mode).
- * Returns the absolute paths of the two files written.
- */
-declare function materializeComposeTemplate(profile: ComposeProfile, options?: ComposeLoaderOptions): {
-    composePath: string;
-    manifestPath: string;
-};
-
 /**
  * Townhouse API — type definitions.
  */
@@ -1407,4 +1354,656 @@ interface WizardInitialDeps {
  */
 declare function createWizardApiServer(initialDeps: WizardInitialDeps): Promise<ApiServer>;
 
-export { type ApiConfig, type ApiDeps, type ApiServer, type BandwidthPayload, type BandwidthStats, ComposeLoaderError, type ComposeLoaderOptions, type ComposeProfile, ConfigValidationError, ConnectorAdminClient, type ConnectorConfig, ConnectorConfigGenerator, type ConnectorRuntimeConfig, type ContainerSpec, DEFAULT_ATOR_PROXY, type DepositAddressEntry, type DepositAddressesPayload, type DerivedNodeKeys, DockerOrchestrator, type DvmHealthResponse, type DvmNodeConfig, type EncryptedWallet, type HealthCheckOptions, type HealthResponse, type JobsByKindEntry, type JobsRecentPayload, type LoggingConfig, type MetricsPayload, type MetricsPeerEntry, type MetricsResponse, type MillNodeConfig, type MillSwapsRecentPayload, type NodeDetail, type NodeHealthPayload, type NodeInfo, type NodeKeyInfo, type NodeKeys, type NodeState, type NodeType$1 as NodeType, type NodesConfig, type NostrEventPayload, type OrchestratorEvents, type PacketLogEntry, type PacketLogFilter, type PacketTimeseriesPayload, type PeerEntry, type PeerStatus, type PeersResponse, type RevealRequest, type RevealResponse, type SwapByPairEntry, type TimeseriesBucket, type TownHealthPayload, type TownNodeConfig, type TownhouseConfig, type TransactionReceiptPayload, type TransportConfig, type TransportPatchRequest, type TransportPatchResponse, TransportProbe, type TransportStatusPayload, type WalletBalanceEntry, type WalletBalancesPayload, type WalletConfig, WalletManager, type WalletManagerConfig, type WalletState, type WithdrawDryRunResponse, type WithdrawRequest, type WithdrawResponse, type WithdrawSuccessResponse, type WizardInitRequest, type WizardProgressMessage, type WizardStatePayload, type WsBatchMessage, type WsConnectorRestartedMessage, type WsConnectorRestartingMessage, type WsHeartbeatMessage, type WsMessage, type WsMetricsMessage, type WsNodeStateMessage, type WsRelayEventsMessage, createApiServer, createWizardApiServer, decryptWallet, encryptWallet, getDefaultConfig, loadComposeTemplate, loadConfig, loadWallet, materializeComposeTemplate, saveConfig, saveWallet, validateConfig };
+/**
+ * Hourly earnings snapshot writer (Story 47.3).
+ *
+ * Persists `claimsReceivedTotal` per (peerId × assetCode) — plus apex
+ * `connectorFees[]` rows under `peerId: '__apex__'` — to
+ * `${dirname(configPath)}/earnings-snapshots.jsonl` once per hour. Consumed
+ * by `snapshot-reader.ts`'s `DeltaComputer` factory. Failure mode: any
+ * per-tick error is logged via `logger.warn` and swallowed (the writer NEVER
+ * throws into the apex event loop) — the next tick retries cleanly. Pruning
+ * runs after each successful append (entries older than 13 months are
+ * rewritten atomically). File mode is `0o600` on every write.
+ *
+ * @module
+ * @since 47.3
+ */
+
+/**
+ * One JSONL row in `earnings-snapshots.jsonl`.
+ *
+ * NOTE: apex routing-fee rows use `peerId: '__apex__'`. The field name
+ * `claimsReceivedTotal` is technically a misnomer for apex rows — those
+ * are connector routing fees, not received claims — but the uniform column
+ * name keeps the JSONL schema simple and the reader doesn't need a special
+ * case.
+ */
+interface SnapshotEntry {
+    /** ISO-8601 UTC timestamp of the tick boundary (e.g. '2026-05-12T15:00:00.000Z'). */
+    ts: string;
+    /** Connector peerId, OR the literal `'__apex__'` for apex routing-fee rows. */
+    peerId: string;
+    assetCode: string;
+    /** Decimal-string cumulative (claims received for peers, routing-fee total for apex). */
+    claimsReceivedTotal: string;
+}
+interface SnapshotWriterOptions {
+    connectorAdmin: ConnectorAdminClient;
+    /** Absolute path to `earnings-snapshots.jsonl`. */
+    snapshotPath: string;
+    /** Tick interval (ms). Default 3_600_000 (1 hour). */
+    tickIntervalMs?: number;
+    /** Injected clock for tests. Default `() => new Date()`. */
+    now?: () => Date;
+    /** Retention window in months. Default 13. */
+    retentionMonths?: number;
+    /** pino/Fastify-compatible logger; warn-only. */
+    logger?: {
+        warn(obj: object, msg?: string): void;
+    };
+    /**
+     * Fire one tick immediately on `start()` instead of waiting for the first
+     * interval. Default `false` (production). Tests set this to `true` to
+     * assert append behavior without advancing fake timers.
+     */
+    fireOnStart?: boolean;
+}
+declare class SnapshotWriter {
+    private readonly opts;
+    private timer;
+    private tickPending;
+    constructor(opts: SnapshotWriterOptions);
+    start(): void;
+    stop(): void;
+    /** Exposed for test ergonomics — runs one full append+prune cycle. */
+    tick(): Promise<void>;
+    private runTick;
+    private appendEntries;
+    private pruneIfNeeded;
+}
+
+/**
+ * `nodes.yaml` schema + read/write helpers (Story 46.1).
+ *
+ * `~/.townhouse/nodes.yaml` is the operator-managed source of truth for
+ * enabled child nodes. The reconciler (see `../reconciler.ts`) converges
+ * connector peer state to this file on every `townhouse hs up`.
+ *
+ * Architectural rule (Epic 46.2 dependency): yaml writes happen BEFORE
+ * connector registration. The drift window resolves in the safe direction —
+ * a yaml entry without a connector peer is re-registered on next boot; a
+ * connector peer without a yaml entry is treated as `'external'` and left
+ * alone.
+ */
+
+declare const NodesYamlEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["town", "mill", "dvm"]>;
+    peerId: z.ZodString;
+    ilpAddress: z.ZodString;
+    derivationIndex: z.ZodNumber;
+    enabledAt: z.ZodString;
+    lastSeenAt: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "town" | "mill" | "dvm";
+    id: string;
+    peerId: string;
+    ilpAddress: string;
+    derivationIndex: number;
+    enabledAt: string;
+    lastSeenAt: string | null;
+}, {
+    type: "town" | "mill" | "dvm";
+    id: string;
+    peerId: string;
+    ilpAddress: string;
+    derivationIndex: number;
+    enabledAt: string;
+    lastSeenAt: string | null;
+}>;
+declare const NodesYamlSchema: z.ZodEffects<z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["town", "mill", "dvm"]>;
+        peerId: z.ZodString;
+        ilpAddress: z.ZodString;
+        derivationIndex: z.ZodNumber;
+        enabledAt: z.ZodString;
+        lastSeenAt: z.ZodNullable<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        type: "town" | "mill" | "dvm";
+        id: string;
+        peerId: string;
+        ilpAddress: string;
+        derivationIndex: number;
+        enabledAt: string;
+        lastSeenAt: string | null;
+    }, {
+        type: "town" | "mill" | "dvm";
+        id: string;
+        peerId: string;
+        ilpAddress: string;
+        derivationIndex: number;
+        enabledAt: string;
+        lastSeenAt: string | null;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    entries: {
+        type: "town" | "mill" | "dvm";
+        id: string;
+        peerId: string;
+        ilpAddress: string;
+        derivationIndex: number;
+        enabledAt: string;
+        lastSeenAt: string | null;
+    }[];
+}, {
+    entries: {
+        type: "town" | "mill" | "dvm";
+        id: string;
+        peerId: string;
+        ilpAddress: string;
+        derivationIndex: number;
+        enabledAt: string;
+        lastSeenAt: string | null;
+    }[];
+}>, {
+    entries: {
+        type: "town" | "mill" | "dvm";
+        id: string;
+        peerId: string;
+        ilpAddress: string;
+        derivationIndex: number;
+        enabledAt: string;
+        lastSeenAt: string | null;
+    }[];
+}, {
+    entries: {
+        type: "town" | "mill" | "dvm";
+        id: string;
+        peerId: string;
+        ilpAddress: string;
+        derivationIndex: number;
+        enabledAt: string;
+        lastSeenAt: string | null;
+    }[];
+}>;
+type NodesYamlEntry = z.infer<typeof NodesYamlEntrySchema>;
+type NodesYaml = z.infer<typeof NodesYamlSchema>;
+/**
+ * Read and validate `nodes.yaml` at the given path.
+ *
+ * Returns `{ entries: [] }` if the file does not exist (graceful first-run).
+ * Throws a `ZodError` with a useful path if the file is present but invalid.
+ */
+declare function readNodesYaml(path: string): Promise<NodesYaml>;
+/**
+ * Write `nodes.yaml` atomically with file mode `0o600`.
+ *
+ * Atomic = write to `<path>.tmp` then `fs.rename`. On POSIX, rename is
+ * atomic when source + destination live on the same filesystem (always true
+ * for `~/.townhouse/nodes.yaml`). Prevents partial-write corruption if the
+ * process is killed mid-write.
+ */
+declare function writeNodesYaml(path: string, data: NodesYaml): Promise<void>;
+
+/**
+ * `PeerTypeResolver` (Story 46.1).
+ *
+ * The connector is a generic ILP router — it has no concept of
+ * `'town' | 'mill' | 'dvm'`. Townhouse owns the type concept entirely
+ * via this resolver, which is the single translation layer between
+ * connector `peerId` values and operator-meaningful node types.
+ *
+ * Architectural rule (Epic 46 planning §Architectural Layering):
+ * downstream consumers (Epic 47 aggregator, Epic 48 TUI, Epic 49 telemetry)
+ * MUST call through this resolver — they never hardcode peer-to-type
+ * mappings.
+ *
+ * The resolver is rebuilt from a `NodesYaml` snapshot — prefer immutable
+ * rebuild (re-instantiate) over mutable update for testability.
+ */
+
+declare class PeerTypeResolver {
+    private readonly map;
+    constructor(yaml: NodesYaml);
+    /**
+     * 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: string): NodeType$1 | 'external';
+}
+
+/**
+ * Earnings aggregator (Story 47.2).
+ *
+ * Aggregates connector-reported earnings into the canonical
+ * `{ status, apex, peers }` shape consumed by the host-API
+ * `/api/earnings` endpoint.
+ *
+ * Source of truth: `connectorAdmin.getEarnings()` (Story 47.1).
+ * Peer-type attribution via `PeerTypeResolver` (Story 46.1); the resolver
+ * buckets unmatched peerIds as `'external'` (enforcement lives in the
+ * resolver, not here — we trust its contract).
+ *
+ * Failure mode: if `getEarnings()` throws (network, 503-when-disabled,
+ * shape drift), returns the empty payload with
+ * `status: 'connector_unavailable'`. The route returns 200 either way;
+ * operators see zeros plus a UI banner rather than a 5xx. An injected
+ * `logger.warn` (Fastify / pino-compatible) is called on failure so ops
+ * can distinguish "connector outage" from "no earnings yet."
+ *
+ * @module
+ * @since 47.2
+ */
+
+/**
+ * Per-asset cumulative + delta breakdown. `lifetime` is the connector's
+ * cumulative `claimsReceivedTotal` (decimal-string bigint at `assetScale`
+ * decimals). `today` / `month` / `year` are deltas computed by Story 47.3's
+ * snapshot-reader; until the `deltaComputer` dep is provided, they stub
+ * to '0'. Asset-scale interpretation (USD: 6, ETH: 18, sats: 0) is the
+ * dashboard's job — the aggregator never collapses to a unit.
+ */
+interface PerAsset {
+    lifetime: string;
+    today: string;
+    month: string;
+    year: string;
+}
+/** Per-peer earnings entry in the aggregator output. */
+interface NodeEarnings {
+    id: string;
+    type: NodeType$1 | 'external';
+    byAsset: Record<string, PerAsset>;
+    /** Max `lastClaimAt` across this peer's assets, or `null` if none. Added in 47.4. */
+    lastClaimAt: string | null;
+}
+/**
+ * Wire-level status for the aggregator response.
+ *
+ * `'ok'` — `getEarnings()` succeeded; payload reflects connector state.
+ * `'connector_unavailable'` — `getEarnings()` threw (network, 503, shape
+ * drift); apex + peers are empty. The dashboard renders a banner.
+ */
+type AggregatedEarningsStatus = 'ok' | 'connector_unavailable';
+/** Top-level aggregator output. Extended in 47.4 with dashboard fields. */
+interface AggregatedEarnings {
+    status: AggregatedEarningsStatus;
+    apex: {
+        routingFees: Record<string, PerAsset>;
+    };
+    peers: NodeEarnings[];
+    /** Pass-through from connector `recentClaims`. Empty array on connector outage. */
+    recentClaims: RecentClaim[];
+    /** Sum of `getMetrics().peers[].packetsForwarded` PLUS `packetsLocallyDelivered`
+     *  (connector v3.7.0+, toon-protocol/connector#73 — counts events that landed
+     *  via the self-delivery route, where the connector's in-process relay accepts
+     *  the event locally rather than forwarding to a remote peer). 0 on connector
+     *  outage or metrics failure. */
+    eventsRelayed: number;
+    /** From `getMetrics().uptimeSeconds`. 0 on connector outage or metrics failure. */
+    uptimeSeconds: number;
+}
+/** Resolves TODAY / MONTH / YEAR deltas for a (scope, assetCode) tuple. */
+type DeltaComputer = (params: {
+    /** Either a connector peerId or the literal `'__apex__'` for routing-fee rows. */
+    scope: string;
+    assetCode: string;
+    /** Current cumulative (matches the lifetime value in the response). */
+    currentLifetime: string;
+}) => Promise<{
+    today: string;
+    month: string;
+    year: string;
+}>;
+/**
+ * Minimal logger contract; Fastify `request.log` and pino satisfy it.
+ * Kept narrow so tests can pass a `{ warn: vi.fn() }` stub.
+ */
+interface AggregatorLogger {
+    warn(obj: object, msg?: string): void;
+}
+interface AggregateEarningsInput {
+    connectorAdmin: ConnectorAdminClient;
+    peerTypeResolver: PeerTypeResolver;
+    /**
+     * Optional delta computer (Story 47.3). When omitted, all PerAsset
+     * `today` / `month` / `year` fields stub to '0'. The route layer (47.4)
+     * wires the snapshot-backed implementation. A rejection on a single
+     * asset stubs that asset's deltas to '0' and emits `logger.warn`; one
+     * bad asset never breaks the aggregate.
+     */
+    deltaComputer?: DeltaComputer;
+    /**
+     * Optional logger. When provided, `getEarnings()` failures and
+     * `deltaComputer` rejections are surfaced via `logger.warn` so ops can
+     * distinguish a connector outage from "no earnings yet."
+     */
+    logger?: AggregatorLogger;
+}
+
+/**
+ * Snapshot reader + `DeltaComputer` factory (Story 47.3).
+ *
+ * Reads `earnings-snapshots.jsonl` and computes TODAY/MONTH/YEAR deltas vs.
+ * UTC boundaries (midnight, 1st-of-month, 1st-of-year). Tolerates malformed
+ * lines (skip) and clock-skewed snapshots (filter `ts > now`). Returns `'0'`
+ * when no boundary snapshot exists yet.
+ *
+ * @module
+ * @since 47.3
+ */
+
+/** ISO of the most recent UTC midnight <= ref. */
+declare function utcDayBoundary(ref: Date): string;
+/** ISO of the first instant of the current calendar month in UTC. */
+declare function utcMonthBoundary(ref: Date): string;
+/** ISO of the first instant of the current calendar year in UTC. */
+declare function utcYearBoundary(ref: Date): string;
+/**
+ * Construct a `DeltaComputer` (Story 47.2's type) backed by the snapshot
+ * file at `snapshotPath`. The returned function is the one wired into
+ * `aggregateEarnings({ ..., deltaComputer })` by Story 47.4's route.
+ *
+ * Reads the snapshot file once per DeltaComputer call (single-pass), then
+ * resolves all three boundaries (today/month/year) in-memory from the parsed
+ * map. No cross-call cache in v1 — see Open Question 6 in story notes.
+ */
+declare function createDeltaComputer(opts: {
+    snapshotPath: string;
+    /** Optional clock injection for tests. Default `() => new Date()`. */
+    now?: () => Date;
+}): DeltaComputer;
+
+/**
+ * Image manifest reader for Townhouse (Story 46.2).
+ *
+ * `~/.townhouse/image-manifest.json` is materialized by `compose-loader.ts`
+ * during `townhouse hs up`. It maps node types to their digest-pinned image
+ * refs, consumed by `POST /api/nodes` step 2 (pull image).
+ */
+
+declare const ImageManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    townhouseVersion: z.ZodString;
+    builtAt: z.ZodString;
+    images: z.ZodObject<{
+        'townhouse-api': z.ZodObject<{
+            name: z.ZodString;
+            tag: z.ZodString;
+            digest: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            tag: string;
+            digest: string;
+        }, {
+            name: string;
+            tag: string;
+            digest: string;
+        }>;
+        town: z.ZodObject<{
+            name: z.ZodString;
+            tag: z.ZodString;
+            digest: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            tag: string;
+            digest: string;
+        }, {
+            name: string;
+            tag: string;
+            digest: string;
+        }>;
+        mill: z.ZodObject<{
+            name: z.ZodString;
+            tag: z.ZodString;
+            digest: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            tag: string;
+            digest: string;
+        }, {
+            name: string;
+            tag: string;
+            digest: string;
+        }>;
+        dvm: z.ZodObject<{
+            name: z.ZodString;
+            tag: z.ZodString;
+            digest: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            tag: string;
+            digest: string;
+        }, {
+            name: string;
+            tag: string;
+            digest: string;
+        }>;
+        connector: z.ZodObject<{
+            name: z.ZodString;
+            tag: z.ZodString;
+            digest: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            tag: string;
+            digest: string;
+        }, {
+            name: string;
+            tag: string;
+            digest: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        town: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        mill: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        dvm: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        'townhouse-api': {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        connector: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+    }, {
+        town: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        mill: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        dvm: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        'townhouse-api': {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        connector: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+    }>;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: 1;
+    townhouseVersion: string;
+    builtAt: string;
+    images: {
+        town: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        mill: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        dvm: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        'townhouse-api': {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        connector: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+    };
+}, {
+    schemaVersion: 1;
+    townhouseVersion: string;
+    builtAt: string;
+    images: {
+        town: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        mill: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        dvm: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        'townhouse-api': {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+        connector: {
+            name: string;
+            tag: string;
+            digest: string;
+        };
+    };
+}>;
+type ImageManifest = z.infer<typeof ImageManifestSchema>;
+/**
+ * Read and validate `image-manifest.json` at the given path.
+ *
+ * Throws ENOENT if the file is missing — there is no graceful fallback for a
+ * missing manifest; it means `townhouse hs up` was not run first.
+ * Throws `ZodError` with a useful path if the file is present but invalid.
+ */
+declare function readImageManifest(path: string): Promise<ImageManifest>;
+
+/**
+ * Boot reconciler (Story 46.1).
+ *
+ * Converges connector peer state to `~/.townhouse/nodes.yaml` (truth) on
+ * every `townhouse hs up`. Reads yaml + connector peers, diffs them,
+ * re-registers any yaml entries missing from the connector, and logs
+ * connector peers without yaml entries as `'external'` (left alone).
+ *
+ * Container lifecycle is OUT of scope — that lives in Epic 46.2.
+ */
+
+/** Action recorded for a single divergence. */
+type DivergenceAction = 'reregistered' | 'reregister-failed' | 'external';
+/** A single divergence record for the reconciler log. */
+interface DivergenceLog {
+    timestamp: string;
+    peerId: string;
+    action: DivergenceAction;
+    detail?: string;
+}
+/** Summary returned by `reconcile()` so callers can surface partial-failure counts. */
+interface ReconcileSummary {
+    reregistered: number;
+    failed: number;
+    external: number;
+}
+declare class BootReconciler {
+    private readonly adminClient;
+    private readonly nodesYamlPath;
+    private readonly reconcilerLogPath;
+    private logDirEnsured;
+    private logFileChmodEnsured;
+    constructor(adminClient: Pick<ConnectorAdminClient, 'getPeers' | 'registerPeer'>, nodesYamlPath: string, reconcilerLogPath: string);
+    /**
+     * 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.
+     */
+    reconcile(): Promise<ReconcileSummary>;
+    /**
+     * Compute divergences without mutating the connector. Exposed for
+     * testability — production callers use `reconcile()`.
+     */
+    private diff;
+    /**
+     * 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.
+     */
+    private tryAppendLog;
+    /**
+     * 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.
+     */
+    private appendLog;
+}
+
+export { type AggregateEarningsInput, type AggregatedEarnings, type AggregatedEarningsStatus, type AggregatorLogger, type ApiDeps, type ApiServer, type BandwidthPayload, BandwidthStats, BootReconciler, ComposeProfile, ConfigValidationError, ConnectorAdminClient, ConnectorConfigGenerator, type ConnectorRuntimeConfig, DEFAULT_ATOR_PROXY, type DeltaComputer, type DepositAddressEntry, type DepositAddressesPayload, type DivergenceAction, type DivergenceLog, DockerOrchestrator, type DvmHealthResponse, EncryptedWallet, HealthCheckOptions, type HealthResponse, type HsHostnameResponse, type ImageManifest, ImageManifestSchema, type JobsByKindEntry, type JobsRecentPayload, type MetricsPayload, type MetricsPeerEntry, type MetricsResponse, type MillSwapsRecentPayload, type NodeDetail, type NodeEarnings, type NodeHealthPayload, type NodeInfo, type NodeState, NodeType$1 as NodeType, type NodesYaml, type NodesYamlEntry, NodesYamlEntrySchema, NodesYamlSchema, type NostrEventPayload, OrchestratorError, type PacketLogEntry, type PacketLogFilter, type PacketTimeseriesPayload, type PeerEntry, type PeerStatus, PeerTypeResolver, type PeersResponse, type PerAsset, type ReconcileSummary, type RevealRequest, type RevealResponse, type SnapshotEntry, SnapshotWriter, type SnapshotWriterOptions, type SwapByPairEntry, type TimeseriesBucket, type TownHealthPayload, TownhouseConfig, type TransactionReceiptPayload, type TransportPatchRequest, type TransportPatchResponse, TransportProbe, type TransportStatusPayload, type WalletBalanceEntry, type WalletBalancesPayload, WalletManager, type WithdrawDryRunResponse, type WithdrawRequest, type WithdrawResponse, type WithdrawSuccessResponse, type WizardInitRequest, type WizardProgressMessage, type WizardStatePayload, type WsBatchMessage, type WsConnectorRestartedMessage, type WsConnectorRestartingMessage, type WsHeartbeatMessage, type WsMessage, type WsMetricsMessage, type WsNodeStateMessage, type WsRelayEventsMessage, createApiServer, createDeltaComputer, createWizardApiServer, decryptWallet, encryptWallet, getDefaultConfig, loadConfig, loadWallet, readImageManifest, readNodesYaml, saveConfig, saveWallet, utcDayBoundary, utcMonthBoundary, utcYearBoundary, validateConfig, writeNodesYaml };