@serfab/cadre-host 1.13.0 → 1.15.0

package/src/bin/host.ts

@@ -3,51 +3,48 @@
 /**
  * CLI entrypoint for cadre-host — the self-hosted cadre node manager.
  *
- * Most subcommands (`status`, `invite`, `trust`, `grant`, `nat`) are thin HTTP
- * clients against the running cadre-host management API on loopback — they
- * don't spin up an inline service, so cadre-host must be running.
+ * Most subcommands (`join`, `node`, `nat`) are thin HTTP clients against the
+ * running cadre-host management API on loopback — they don't spin up an inline
+ * service, so cadre-host must be running.
  *
  * The exceptions operate on disk directly and need no running service:
  * `install`, `uninstall`, `start`, `ui`, and the `push` group.
  *
  * Every command here needs a matching `### ` heading in the package README's
  * `## CLI reference`; `__tests__/cli-reference.test.ts` enforces that.
+ *
+ * NOTE: this file is ~1200 lines; `nat-output.ts` shows the split to make —
+ * when a command group's code grows, move it to its own module under `bin/`.
  */
 
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
 
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 
-import { parseDuration } from '../auth/duration.js';
 import { Installer } from '../installer/index.js';
-import { readHostConfig, updateHostConfig, hostOwnsCadre } from '../installer/config.js';
+import { packageVersion } from '../package-version.js';
+import { readHostConfig, updateHostConfig } from '../installer/config.js';
 import {
   configPath as resolveConfigPath,
   defaultDataDir,
   defaultHostJs,
   defaultServiceDir,
-  identityPath as resolveIdentityPath,
 } from '../installer/paths.js';
 import { detectPlatform } from '../installer/platform.js';
 import { createServiceHost } from '../installer/service-host/index.js';
 import { UpdateService } from '../update/index.js';
 import { HostProcessOrchestrator } from '../orchestrator/index.js';
-import { TrustCircleService, TrustCircleStore, ensureSelfLabel } from '../auth/index.js';
 import {
-  GrantService,
-  GrantStore,
-  DonationService,
-  DonationStore,
-  DonationSupervisor,
-  DONATION_AWAITING_SEED_TTL_MS,
-  DONATION_PROVISIONING_TTL_MS,
-  DONATION_REAP_SWEEP_MS,
-  type GrantListing,
-} from '../donation/index.js';
-import { NatService } from '../nat/index.js';
+  HostedNodeService,
+  HostedNodeStore,
+  HostedNodeSupervisor,
+  HOSTED_NODE_REAP_SWEEP_MS,
+  HOSTED_NODE_SPAWNING_TTL_MS,
+} from '../hosted/index.js';
+import { effectiveNetworkMode, NatService, NatStore, publicInterfaceAddress } from '../nat/index.js';
+import type { ManualForwardPatch } from '../nat/types.js';
 import { createSecretsStore } from '../nat/secrets/index.js';
 import {
   resolvePushCredentials,
@@ -56,20 +53,21 @@ import {
   clearPushSecret,
   pushStatus,
 } from '../push/index.js';
-import { StrandService } from '../strands/index.js';
-import { OwnerNodeClient } from '../owner/index.js';
-import { createLocalUiServer, HostSettingsStore, type FounderServices } from '../server/index.js';
+import { createLocalUiServer, HostSettingsStore } from '../server/index.js';
 import { openBrowser } from '../installer/browser.js';
+import { printForwardResult, printNatStatus, type NatStatusLike } from './nat-output.js';
+import { isHeadless, uiAccessLines } from './ui-access.js';
+import {
+  printClaimPayload,
+  printClaimed,
+  printInvitationOutcome,
+  printNodeList,
+  type ClaimDetailsLike,
+  type HostedNodeLike,
+} from './join-output.js';
 
 const DEFAULT_PORT = Number(process.env.CADRE_HOST_PORT ?? '8765');
 
-/** libp2p peer-ID prefixes by key type: Ed25519, secp256k1, legacy RSA. */
-const PEER_ID_PREFIXES = ['12D3Koo', '16Uiu2HAm', 'Qm'] as const;
-
-function looksLikePeerId(id: string): boolean {
-  return PEER_ID_PREFIXES.some((p) => id.startsWith(p));
-}
-
 function resolvePort(raw: string): number {
   const n = Number(raw);
   if (!Number.isFinite(n) || n <= 0 || n > 65535) {
@@ -84,7 +82,7 @@ const program = new Command();
 program
   .name('cadre-host')
   .description('Sereus cadre node manager for self-hosted basement-PC deployments')
-  .version(readPackageVersion());
+  .version(packageVersion);
 
 // ============================================================================
 // install — run the first-run wizard + register the system service
@@ -96,11 +94,8 @@ program
   .option('--non-interactive', 'Use defaults / CLI flags only; never prompt')
   .option('--data-dir <path>', 'Override the data directory')
   .option('--ui-port <port>', 'Override the management UI port', parseIntArg)
-  .option('--libp2p-port <port>', 'Override the cadre libp2p port', parseIntArg)
   .option('--no-upnp', 'Disable UPnP/NAT-PMP probing on first run')
   .option('--no-browser', 'Do not open a browser after install')
-  .option('--no-invite', 'Skip generating the first enrollment invite')
-  .option('--own-cadre', 'Also run the host\'s own personal cadre here (founder persona; default: donor-only)')
   .option('--system', 'System-wide install (not yet supported in v1)')
   .option('--node-path <path>', 'Override the node binary embedded in the service unit')
   .option('--no-service', 'Write the data dir only; register no OS service (run the host with `cadre-host start`)')
@@ -108,11 +103,8 @@ program
     nonInteractive?: boolean;
     dataDir?: string;
     uiPort?: number;
-    libp2pPort?: number;
     upnp?: boolean;
     browser?: boolean;
-    invite?: boolean;
-    ownCadre?: boolean;
     system?: boolean;
     nodePath?: string;
     service?: boolean;
@@ -123,11 +115,9 @@ program
         nonInteractive: Boolean(opts.nonInteractive),
         ...(opts.dataDir ? { dataDir: opts.dataDir } : {}),
         ...(typeof opts.uiPort === 'number' ? { uiPort: opts.uiPort } : {}),
-        ...(typeof opts.libp2pPort === 'number' ? { libp2pPort: opts.libp2pPort } : {}),
         noUpnp: opts.upnp === false,
-        openBrowser: opts.browser !== false,
-        noInvite: opts.invite === false,
-        ownCadre: opts.ownCadre === true,
+        // Headless, a browser would open nowhere the admin can see; the `ssh -L` lines below say how instead.
+        openBrowser: opts.browser !== false && !isHeadless(),
         system: Boolean(opts.system),
         ...(opts.nodePath ? { nodePath: opts.nodePath } : {}),
         noService: opts.service === false,
@@ -141,9 +131,15 @@ program
         console.log('  Service:      not registered (--no-service)');
         console.log(`  Run the host: cadre-host start --data-dir "${result.dataDir}"`);
       }
-      if (result.enrollmentInvite) {
-        printEnrollmentInvite(result.enrollmentInvite);
-      }
+      // A re-install keeps the `network` setting an earlier one recorded in nat.json.
+      const publicIp = publicInterfaceAddress();
+      const mode = effectiveNetworkMode(new NatStore(result.dataDir).load().network, publicIp);
+      console.log(mode === 'public'
+        ? `  Network:      public IP${publicIp ? ` ${publicIp}` : ''}: nodes are reached directly. Allow their ports through your firewall (the UI lists them).`
+        : '  Network:      behind a router: nodes need UPnP or a port forward (the UI shows which).');
+      console.log('');
+      for (const line of uiAccessLines(Number(new URL(result.uiUrl).port), isHeadless())) console.log(line);
+      console.log('Everything else (a public name, joining a cadre, ports) is in the UI.');
       process.exit(0);
     } catch (err) {
       console.error(`install failed: ${(err as Error).message}`);
@@ -164,8 +160,8 @@ program
   .action(async (opts: { yes?: boolean; removeData?: boolean; dataDir?: string }) => {
     const installer = new Installer();
     try {
-      // --remove-data is destructive and irreversible (identity + trust circle
-      // are wiped). Require explicit --yes when stdin isn't a TTY, and prompt
+      // --remove-data is destructive and irreversible (node identities, hosted-node
+      // records and NAT state are wiped). Require explicit --yes when stdin isn't a TTY, and prompt
       // confirmation when it is.
       if (opts.removeData && !opts.yes) {
         if (!process.stdin.isTTY) {
@@ -175,7 +171,7 @@ program
         }
         const dataDir = opts.dataDir ?? '(default data directory)';
         const confirmed = await confirmDestructive(
-          `This will permanently delete ${dataDir} (identity, trust circle, NAT state). Continue? [y/N] `,
+          `This will permanently delete ${dataDir} (node identities, hosted-node records, NAT state). Continue? [y/N] `,
         );
         if (!confirmed) {
           console.error('uninstall aborted.');
@@ -217,7 +213,7 @@ program
   });
 
 // ============================================================================
-// start — load config + identity, bind management API listener, wait
+// start — load config, bind management API listener, wait
 // ============================================================================
 
 program
@@ -240,12 +236,6 @@ program
         return;
       }
       const cfg = readHostConfig(cfgPath);
-      const idPath = resolveIdentityPath(cfg.dataDir);
-      if (!existsSync(idPath)) {
-        console.error(`cadre-host start: identity file not found at ${idPath}. Re-run \`cadre-host install\`.`);
-        process.exit(1);
-        return;
-      }
       console.log(`cadre-host starting (dataDir=${cfg.dataDir}, uiPort=${cfg.uiPort})`);
 
       // Update flow: notify-by-default; auto-apply opt-in via host.config.json.
@@ -255,7 +245,7 @@ program
       const serviceHost = createServiceHost(platform);
       const updateService = new UpdateService({
         dataDir: cfg.dataDir,
-        currentVersion: readPackageVersion(),
+        currentVersion: packageVersion,
         settings: cfg.updates,
         ...(cfg.updates.manifestUrl ? { manifestUrl: cfg.updates.manifestUrl } : {}),
         restart: async () => {
@@ -284,169 +274,91 @@ program
       void updateService.check();
       updateService.start();
 
-      // Wire the long-lived HTTP management server. cadre-host's primary role
-      // is **node donor**: it spawns generic cadre nodes for *other people's*
-      // cadres on request (the donation grant layer below) and never needs an
-      // owner node of its own for that. Running the host's **own** personal
-      // cadre here — the "founder" persona — is opt-in via `ownCadre.enabled`
-      // (see docs/cadre-host.md § Two roles: donor and founder). Only when it
-      // is enabled do we spawn the owner node and bring up trust-circle + NAT.
-      // The manager never joins the control network (docs/cadre-host.md
-      // § Control-plane separation).
+      // Wire the long-lived HTTP management server. cadre-host spawns cadre
+      // nodes for cadres that live on people's phones (the hosted-node service
+      // below); it holds no owner key and never founds a cadre. The manager
+      // never joins the control network (docs/cadre-host.md § Control-plane
+      // separation).
       // Push (FCM/APNs) credentials are resolved fresh on every node spawn so a
       // restart re-reads the secret store (rotated keys) and nothing raw is
       // persisted in state.json. The non-secret bits (bundle id / sandbox toggle,
       // cooldown/debounce) are re-read from host.config.json each call too.
       const pushSecrets = await createSecretsStore(cfg.dataDir);
+      // Each node is spawned announcing its public addresses. Read through a late-bound
+      // reference: NatService takes the orchestrator as its node source, so it is built after.
+      const addresses: { source?: NatService } = {};
       const orchestrator = new HostProcessOrchestrator({
         rootDir: join(cfg.dataDir, 'orchestrator'),
         pushResolver: () => resolvePushCredentials(pushSecrets, readHostConfig(cfgPath).push),
+        announceAddrs: (id, ports) => addresses.source?.publicAddressesFor(id, ports) ?? [],
       });
       await orchestrator.init();
 
-      // Donation grant layer — the always-on donor surface. Local-only:
-      // issue/validate/revoke are pure store ops (no node round-trip), so it
-      // needs no owner-node handle. The loopback `/grants-admin` surface is
-      // mounted by createLocalUiServer regardless of the founder persona.
-      const grantService = new GrantService({ store: new GrantStore(cfg.dataDir) });
-
-      // Donation lifecycle service — consumes a validated grant to actually
-      // spawn a donated node into the requester's cadre. Drives the
-      // grantee-facing `/grants` surface (mounted by createLocalUiServer below).
-      const donationStore = new DonationStore(cfg.dataDir);
-      const donationService = new DonationService({
+      // NAT layer: every node the host runs gets its two libp2p ports mapped
+      // on the router (or the user's manual forward recorded for them). Started
+      // before anything is spawned so the first spawns see a discovered gateway. `start()` awaits
+      // only gateway discovery and IP detection (both bounded); the mappings
+      // for re-attached nodes land in the background. Best-effort: a failure
+      // here leaves the management API up.
+      const natService = new NatService({ rootDir: cfg.dataDir, nodeSource: orchestrator });
+      addresses.source = natService;
+      try {
+        await natService.start();
+      } catch (err) {
+        console.error(`NAT start failed: ${(err as Error).message}`);
+      }
+
+      // Hosted nodes — "Join a cadre": a child started waiting to be claimed, the
+      // QR code the owner's phone scans, and the record of whose cadre it joined.
+      // Drives `/api/hosted-nodes` (mounted by createLocalUiServer below).
+      const hostedNodeStore = new HostedNodeStore(cfg.dataDir);
+      const hostedNodes = new HostedNodeService({
         orchestrator,
-        grants: grantService,
-        store: donationStore,
+        store: hostedNodeStore,
+        addresses: natService,
+        // Re-read per claim code so a Settings edit (or a hand edit) applies to the next code shown.
+        claimAddressSettings: () => readHostConfig(cfgPath).claimAddresses,
       });
 
-      // Respawn supervision — nothing else brings a donated node back. A crash,
-      // an OOM kill, or a reboot otherwise leaves the record reading `seeded`
-      // with no process behind it, costing the borrower a node and their grant a
-      // quota slot. Sweeps at startup, on every child exit, and on its own timer.
-      const donationSupervisor = new DonationSupervisor({
-        service: donationService,
-        store: donationStore,
+      // Respawn supervision — nothing else brings a hosted node back. A crash,
+      // an OOM kill, or a reboot otherwise leaves the record reading `joined`
+      // with no process behind it, costing its cadre a node. Sweeps at startup,
+      // on every child exit, and on its own timer.
+      const hostedNodeSupervisor = new HostedNodeSupervisor({
+        service: hostedNodes,
+        store: hostedNodeStore,
         orchestrator,
       });
-      donationSupervisor.start();
-
-      // Reap orphaned donations: a requester that provisioned a node but never
-      // presented a seed leaves an `awaiting_seed` child holding host ports,
-      // and a host that died between writing a `provisioning` row and finishing
-      // the spawn leaves that row stuck forever (nothing else ever revisits it).
-      // Sweep once at startup (for records recovered from disk by
+      hostedNodeSupervisor.start();
+      // Follows each node's /status: the claim, and whether it holds a connection.
+      hostedNodes.startWatching();
+
+      // A node learns its public addresses only at start, so one whose addresses
+      // changed (a mapping on another port, a forward, the DDNS hostname, the external
+      // IP) is restarted, at most once per node per 10 minutes.
+      natService.onNodeAddressesStale((id) => hostedNodeSupervisor.restart(id));
+
+      // Reap records stuck in `spawning`: a host that died between writing the
+      // row and finishing the spawn leaves it stuck forever (nothing else ever
+      // revisits it). Sweep once at startup (for records recovered from disk by
       // orchestrator.init()), then periodically.
       const reapStale = (): void => {
-        void donationService
-          .reapStaleAwaitingSeed(DONATION_AWAITING_SEED_TTL_MS)
-          .catch((err) => console.error(`donation reap failed: ${(err as Error).message}`));
-        void donationService
-          .reapStaleProvisioning(DONATION_PROVISIONING_TTL_MS)
-          .catch((err) => console.error(`donation provisioning reap failed: ${(err as Error).message}`));
+        void hostedNodes
+          .reapStuckSpawning(HOSTED_NODE_SPAWNING_TTL_MS)
+          .catch((err) => console.error(`hosted node reap failed: ${(err as Error).message}`));
       };
       reapStale();
-      const reapTimer = setInterval(reapStale, DONATION_REAP_SWEEP_MS);
+      const reapTimer = setInterval(reapStale, HOSTED_NODE_REAP_SWEEP_MS);
       reapTimer.unref();
 
-      // Founder stack (opt-in). Absent `ownCadre.enabled`, cadre-host is a pure
-      // donor: no owner node, and the /auth + /nat surfaces stay unmounted
-      // (they 404). Per-donated-node WAN reachability is deferred to
-      // backlog/feat-cadre-host-wan-grant-reachability, so v1 donor mode is
-      // loopback-only — nothing for NatService to map without an owner node.
-      let founder: FounderServices | undefined;
-      if (hostOwnsCadre(cfg)) {
-        // Spawn the owner node. Best-effort: a spawn failure leaves the
-        // management API up (trust-circle listing degrades to local labels,
-        // owner ops return 503) rather than taking down the whole process.
-        try {
-          await orchestrator.ensureOwnerNode({
-            identityPath: idPath,
-            partyId: cfg.installId,
-            libp2pPort: cfg.libp2pPort,
-          });
-          console.log('cadre-host: owner node spawned (host-own-cadre enabled)');
-        } catch (err) {
-          console.error(`owner node spawn failed: ${(err as Error).message}`);
-        }
-
-        // The client reads the admin endpoint lazily so a node restart's fresh
-        // bearer token is picked up automatically.
-        const owner = new OwnerNodeClient(() => orchestrator.getOwnerAdminEndpoint());
-
-        const trustCircleStore = new TrustCircleStore(cfg.dataDir);
-        const trustCircle = new TrustCircleService({
-          cadreNode: owner,
-          store: trustCircleStore,
-        });
-
-        const natService = new NatService({
-          rootDir: cfg.dataDir,
-          cadreNode: owner,
-        });
-
-        // Strand management is founder-only for the same reason as the trust
-        // circle: it asks the owner node, and donor-only mode has none.
-        const strandService = new StrandService({ cadreNode: owner });
-
-        // Push NAT-resolved invite addresses to the node on every NAT change.
-        // NatService.start() also fires this once as an initial push, retried
-        // until the freshly spawned owner node accepts it (bounded; the
-        // management API that mints invites comes up only after start() resolves).
-        natService.onAddressesChanged(async (addresses) => {
-          if (addresses.length === 0) return;
-          try {
-            await owner.pushInviteAddresses(addresses);
-          } catch (err) {
-            console.error(`invite-address push failed: ${(err as Error).message}`);
-          }
-        });
-
-        // Best-effort NAT start. Failures here aren't fatal — the local UI
-        // can still serve the trust circle, settings, etc.
-        try {
-          await natService.start();
-        } catch (err) {
-          console.error(`NAT start failed: ${(err as Error).message}`);
-        }
-
-        // Label the owner's own device so it shows up in the trust-circle
-        // listing (see auth/self-label.ts for why the listing can't get it for
-        // free). Runs after natService.start(), which already waits out a
-        // freshly spawned node's warm-up, so the peer ID is normally there on
-        // the first try. Best-effort: a failure logs and the next start heals
-        // it — the listing gap is cosmetic, not a security boundary.
-        try {
-          await ensureSelfLabel({ store: trustCircleStore, getPeerId: () => owner.getPeerId() });
-        } catch (err) {
-          console.error(`self trust-circle label failed: ${(err as Error).message}`);
-        }
-
-        founder = { trustCircle, nat: natService, strands: strandService };
-      } else {
-        // Donor-only. If ownCadre was toggled off after a prior founder run,
-        // orchestrator.init() re-attaches the still-running owner child (it would
-        // otherwise linger in listNodes with no trustCircle/nat wired, serving
-        // the host's own cadre despite being disabled). Reap it now so a disabled
-        // own-cadre is actually stopped — its workdir + control-DB persist on
-        // disk, so toggling ownCadre back on re-spawns it from saved config.
-        try {
-          await orchestrator.stopOwnerNode();
-        } catch (err) {
-          console.error(`owner node reap failed: ${(err as Error).message}`);
-        }
-        console.log('cadre-host: node-donor mode (host-own-cadre disabled — no owner node; /auth + /nat inactive)');
-      }
-
       const settingsStore = new HostSettingsStore({ dataDir: cfg.dataDir });
       const server = createLocalUiServer({
         uiPort: cfg.uiPort,
         dataDir: cfg.dataDir,
         orchestrator,
-        ...(founder ? { founder } : {}),
+        nat: natService,
         update: updateService,
-        grants: grantService,
-        donations: donationService,
+        hostedNodes,
         settingsStore,
       });
       const { url, port } = await server.start();
@@ -457,10 +369,10 @@ program
 
       await waitForTermination();
       clearInterval(reapTimer);
-      donationSupervisor.stop();
+      hostedNodes.stopWatching();
+      hostedNodeSupervisor.stop();
       try { await server.stop(); } catch { /* ignore */ }
-      try { await founder?.nat.stop(); } catch { /* ignore */ }
-      try { await orchestrator.stopOwnerNode(); } catch { /* ignore */ }
+      try { await natService.stop(); } catch { /* ignore */ }
       updateService.stop();
       console.log('cadre-host stopped.');
       process.exit(0);
@@ -491,6 +403,12 @@ program
       }
       const cfg = readHostConfig(cfgPath);
       const url = `http://127.0.0.1:${cfg.uiPort}`;
+      if (isHeadless()) {
+        // A browser here would open nowhere the admin can see: say how to reach it instead.
+        for (const line of uiAccessLines(cfg.uiPort, true)) console.log(line);
+        process.exit(0);
+        return;
+      }
       console.log(url);
       if (opts.browser !== false) {
         const res = openBrowser(url);
@@ -515,19 +433,6 @@ function parseIntArg(raw: string): number {
   return n;
 }
 
-function readPackageVersion(): string {
-  try {
-    // dist/bin/host.js -> ../../package.json
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkgPath = resolve(here, '..', '..', 'package.json');
-    const raw = readFileSync(pkgPath, 'utf8');
-    const parsed = JSON.parse(raw) as { version?: string };
-    return parsed.version ?? '0.0.0-unknown';
-  } catch {
-    return '0.0.0-unknown';
-  }
-}
-
 function waitForTermination(): Promise<void> {
   return new Promise<void>((resolveTerm) => {
     const done = () => resolveTerm();
@@ -547,340 +452,188 @@ async function confirmDestructive(message: string): Promise<boolean> {
   }
 }
 
-const requireForQr = createRequire(import.meta.url);
-
-function printEnrollmentInvite(invite: { encodedInvite: string; expiresAt?: string }): void {
-  // Best-effort QR render — fall back to the bare token if the lib chokes.
-  console.log('\nEnroll your first device with this invite:');
-  try {
-    const qr = requireForQr('qrcode-terminal') as { generate: (text: string, opts?: { small?: boolean }, cb?: (s: string) => void) => void };
-    qr.generate(invite.encodedInvite, { small: true }, (rendered) => {
-      console.log(rendered);
-    });
-  } catch (err) {
-    console.error(`(qrcode-terminal unavailable: ${(err as Error).message})`);
-  }
-  console.log(`  ${invite.encodedInvite}`);
-  if (invite.expiresAt) {
-    console.log(`  (expires ${invite.expiresAt})`);
-  }
-}
-
-function printGrantToken(token: string, withQr: boolean): void {
-  if (withQr) {
-    // Best-effort QR render — fall back to the bare token if the lib chokes.
-    try {
-      const qr = requireForQr('qrcode-terminal') as { generate: (text: string, opts?: { small?: boolean }, cb?: (s: string) => void) => void };
-      qr.generate(token, { small: true }, (rendered) => {
-        console.error(rendered);
-      });
-    } catch (err) {
-      console.error(`(qrcode-terminal unavailable: ${(err as Error).message})`);
-    }
-  }
-  // The token goes to stdout alone so it can be piped/copied; metadata to stderr.
-  console.log(token);
+// ============================================================================
+// join — start a node waiting to be claimed and show the QR code, or one that
+// redeems a cadre invitation
+// ============================================================================
+//
+// The host's one action. The owner's phone scans the code (or takes the pasted
+// text), claims the node, and the node joins that phone's cadre. To put up a
+// node for a friend, run it again and let the friend scan. With `--invitation`
+// the node instead redeems an invitation the owner's app copied, at whichever
+// member of the cadre it can reach. These commands are thin HTTP clients of the
+// loopback `/api/hosted-nodes` surface — no bearer (same-machine admin), same
+// posture as `nat`.
+
+/** How long `join` waits for the new child's `/status` before giving up on the claim details. */
+const CLAIM_DETAILS_WAIT_MS = 60_000;
+const CLAIM_DETAILS_POLL_MS = 500;
+/** How often `join` re-reads the node while waiting for the claim or the redemption. */
+const CLAIM_WAIT_POLL_MS = 2_000;
+
+interface JoinOptions {
+  qr?: boolean;
+  wait?: boolean;
+  invitation?: string;
+  port: string;
+  host: string;
 }
 
 program
-  .command('invite')
-  .description('Generate an invite to add a member to the trust circle')
-  .argument('<label>', 'Display label for the new member (e.g. "Mom\'s phone")')
-  .option('--ttl <duration>', 'Invite lifetime (e.g. 24h, 7d, 30m)', '24h')
+  .command('join')
+  .description('Start a node waiting to be claimed and show the code the owner\'s phone scans to add it to their cadre, or with --invitation one that redeems a cadre invitation')
+  .option('--invitation <encoded>', 'Join with a cadre invitation the owner\'s app copied instead of showing a code; a member of the cadre must be reachable from this machine')
+  .option('--no-qr', 'Print only the join text, no QR code')
+  .option('--no-wait', 'Exit once the code is shown (or the node started) instead of waiting for it to join')
   .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
   .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
-  .action(async (label: string, opts: { ttl: string; port: string; host: string }) => {
-    let ttlMs: number;
-    try {
-      ttlMs = parseDuration(opts.ttl);
-    } catch (err) {
-      console.error(`Invalid --ttl: ${(err as Error).message}`);
-      process.exit(1);
-      return;
+  .action(async (opts: JoinOptions) => {
+    const base = `http://${opts.host}:${resolvePort(opts.port)}`;
+    if (opts.invitation !== undefined) {
+      const { node } = await callApi<{ node: HostedNodeLike }>(
+        `${base}/api/hosted-nodes`, 'POST', { invitation: opts.invitation },
+        (error) => `cadre-host refused the invitation: ${error.message} (${error.code})`,
+      );
+      process.exit(await followInvitationJoin(base, node, opts));
     }
+    const { node } = await callApi<{ node: HostedNodeLike }>(`${base}/api/hosted-nodes`, 'POST', {});
+    await showClaimAndWait(base, node, opts);
+    process.exit(0);
+  });
 
-    const port = resolvePort(opts.port);
+/**
+ * Print the node's claim code once its child answers, then — unless `--no-wait`
+ * — follow the node until a phone claims it. Ctrl-C leaves the node waiting.
+ */
+async function showClaimAndWait(base: string, node: HostedNodeLike, opts: JoinOptions): Promise<void> {
+  const id = node.id ?? '';
+  console.error(`Started hosted node ${id}; waiting for it to report its addresses…`);
+  const details = await waitForClaimDetails(base, id);
+  printClaimPayload(details, { qr: opts.qr !== false });
+  if (opts.wait === false) return;
+  console.error('Waiting for a phone to claim this node (Ctrl-C leaves it waiting)…');
+  const settled = await waitUntilSettled(base, id);
+  if (settled.status === 'error') {
+    console.error(`✗ Hosted node ${id} failed: ${settled.error ?? 'unknown error'}`);
+    process.exit(1);
+  }
+  printClaimed(settled);
+}
 
-    const url = `http://${opts.host}:${port}/auth/invites`;
-    let response: Response;
-    try {
-      response = await fetch(url, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ label, ttlMs }),
-      });
-    } catch (err) {
-      console.error(
-        `Failed to reach cadre-host at ${url}: ${(err as Error).message}\n` +
-        `Hint: is cadre-host running? Try \`cadre-host start\`.`,
-      );
-      process.exit(2);
-      return;
-    }
+/**
+ * Follow a node redeeming its invitation until a member admits it or the redemption fails,
+ * unless `--no-wait`. Returns the exit code: 1 when it failed. Ctrl-C leaves the node joining.
+ */
+async function followInvitationJoin(base: string, node: HostedNodeLike, opts: { wait?: boolean }): Promise<number> {
+  console.error(`Joining cadre ${node.partyId ?? '?'} through the invitation…`);
+  if (opts.wait === false) return 0;
+  const settled = await waitUntilSettled(base, node.id ?? '');
+  printInvitationOutcome(settled);
+  return settled.status === 'joined' ? 0 : 1;
+}
 
-    if (!response.ok) {
+/** Poll `GET …/:id/claim` until the child answers (503 meanwhile), up to `CLAIM_DETAILS_WAIT_MS`. */
+async function waitForClaimDetails(base: string, id: string): Promise<ClaimDetailsLike> {
+  const url = `${base}/api/hosted-nodes/${encodeURIComponent(id)}/claim`;
+  const deadline = Date.now() + CLAIM_DETAILS_WAIT_MS;
+  while (true) {
+    const response = await fetchOrExit(url, { method: 'GET' });
+    if (response.ok) return (await response.json() as ApiEnvelope<ClaimDetailsLike>).data;
+    if (response.status !== 503 || Date.now() >= deadline) {
       const text = await response.text().catch(() => '');
       console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
       process.exit(1);
-      return;
     }
+    await sleep(CLAIM_DETAILS_POLL_MS);
+  }
+}
 
-    const body = await response.json() as { encodedInvite?: string; expiresAt?: string; token?: string };
-    if (!body.encodedInvite) {
-      console.error('cadre-host returned malformed response (missing encodedInvite)');
-      process.exit(1);
-      return;
-    }
+/** Poll `GET …/:id` until the node is `joined` or `error`. */
+async function waitUntilSettled(base: string, id: string): Promise<HostedNodeLike> {
+  const url = `${base}/api/hosted-nodes/${encodeURIComponent(id)}`;
+  while (true) {
+    const { node } = await callApi<{ node: HostedNodeLike }>(url, 'GET');
+    if (node.status === 'joined' || node.status === 'error') return node;
+    await sleep(CLAIM_WAIT_POLL_MS);
+  }
+}
 
-    console.log(body.encodedInvite);
-    if (body.expiresAt) {
-      console.error(`(expires at ${body.expiresAt})`);
-    }
-    process.exit(0);
-  });
+// ============================================================================
+// node subcommands — the nodes this host runs
+// ============================================================================
 
-const trust = program
-  .command('trust')
-  .description('Manage the trust circle (list members, revoke invites/members)');
+const node = program
+  .command('node')
+  .description('List, remove, reset or retry the nodes this host runs');
 
-trust
+node
   .command('list')
-  .description('List trust-circle members and pending invites')
+  .description('List hosted nodes: id, status, cadre, owner fingerprint, connected')
   .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
   .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
   .action(async (opts: { port: string; host: string }) => {
-    const url = `http://${opts.host}:${resolvePort(opts.port)}/auth/trust-circle`;
-    let response: Response;
-    try {
-      response = await fetch(url);
-    } catch (err) {
-      console.error(`Failed to reach cadre-host at ${url}: ${(err as Error).message}`);
-      process.exit(2);
-      return;
-    }
-    if (!response.ok) {
-      console.error(`cadre-host returned ${response.status}: ${response.statusText}`);
-      process.exit(1);
-      return;
-    }
-    const body = await response.json() as {
-      members: Array<{ peerId: string; label: string; addedAt: string; self?: boolean }>;
-      pending: Array<{ token: string; label: string; createdAt: string; expiresAt?: string }>;
-    };
-    console.log('Members:');
-    if (body.members.length === 0) {
-      console.log('  (none)');
-    } else {
-      for (const m of body.members) {
-        const self = m.self ? ' [self]' : '';
-        console.log(`  ${m.peerId}  ${m.label}${self}`);
-      }
-    }
-    console.log('\nPending invites:');
-    if (body.pending.length === 0) {
-      console.log('  (none)');
-    } else {
-      for (const p of body.pending) {
-        const expires = p.expiresAt ? ` (expires ${p.expiresAt})` : '';
-        console.log(`  ${p.token}  ${p.label}${expires}`);
-      }
-    }
-    process.exit(0);
-  });
-
-trust
-  .command('revoke')
-  .description('Revoke a pending invite (by token) or remove a member (by peerId)')
-  .argument('<id>', 'Token (pending invite) or peerId (existing member) to remove')
-  .option('--kind <kind>', 'Force interpretation: "invite" | "member" (default: auto)', 'auto')
-  .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
-  .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
-  .action(async (id: string, opts: { kind: string; port: string; host: string }) => {
     const base = `http://${opts.host}:${resolvePort(opts.port)}`;
-    const kind = opts.kind === 'auto'
-      ? (looksLikePeerId(id) ? 'member' : 'invite')
-      : opts.kind;
-    const path = kind === 'member'
-      ? `/auth/members/${encodeURIComponent(id)}`
-      : `/auth/invites/${encodeURIComponent(id)}`;
-
-    let response: Response;
-    try {
-      response = await fetch(`${base}${path}`, { method: 'DELETE' });
-    } catch (err) {
-      console.error(`Failed to reach cadre-host at ${base}: ${(err as Error).message}`);
-      process.exit(2);
-      return;
-    }
-    if (!response.ok) {
-      const text = await response.text().catch(() => '');
-      console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
-      process.exit(1);
-      return;
-    }
-    console.log(`revoked ${kind}: ${id}`);
+    const { nodes } = await callApi<{ nodes: HostedNodeLike[] }>(`${base}/api/hosted-nodes`, 'GET');
+    printNodeList(nodes);
     process.exit(0);
   });
 
-// ============================================================================
-// grant subcommands — donation grant tokens (who may ask this host for a node)
-// ============================================================================
-//
-// A grant token lets one grantee (friend/family) present a Bearer credential to
-// ask this host to donate cadre nodes, up to a per-grantee cap. These commands
-// are thin HTTP clients of the loopback `/grants-admin` admin surface — no
-// bearer (same-machine admin), same posture as `invite` / `trust`.
-
-const grant = program
-  .command('grant')
-  .description('Manage donation grant tokens (who may ask this host to donate a node)');
-
-grant
-  .command('issue')
-  .description('Issue a grant token for one grantee (prints the token + QR)')
-  .argument('<label>', 'Display label for the grantee (e.g. "Alice\'s cadre")')
-  .option('--max-nodes <n>', 'Max concurrently-live donated nodes this grant may hold', parseIntArg)
-  .option('--ttl <duration>', 'Grant lifetime (e.g. 30d, 12h); omit for no expiry')
-  .option('--no-qr', 'Print only the token, no QR code')
+node
+  .command('remove')
+  .description('Stop a hosted node and delete its data on this machine (its cadre keeps its row until the owner removes it there)')
+  .argument('<id>', 'Hosted node id (hn_…), as `cadre-host node list` shows it')
   .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
   .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
-  .action(async (label: string, opts: {
-    maxNodes?: number;
-    ttl?: string;
-    qr?: boolean;
-    port: string;
-    host: string;
-  }) => {
-    const payload: { label: string; maxNodes?: number; ttlMs?: number } = { label };
-    if (typeof opts.maxNodes === 'number') payload.maxNodes = opts.maxNodes;
-    if (opts.ttl) {
-      try {
-        payload.ttlMs = parseDuration(opts.ttl);
-      } catch (err) {
-        console.error(`Invalid --ttl: ${(err as Error).message}`);
-        process.exit(1);
-        return;
-      }
-    }
-
-    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
-    let response: Response;
-    try {
-      response = await fetch(url, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(payload),
-      });
-    } catch (err) {
-      console.error(
-        `Failed to reach cadre-host at ${url}: ${(err as Error).message}\n` +
-        `Hint: is cadre-host running? Try \`cadre-host start\`.`,
-      );
-      process.exit(2);
-      return;
-    }
-    if (!response.ok) {
-      const text = await response.text().catch(() => '');
-      console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
-      process.exit(1);
-      return;
-    }
-    const body = await response.json() as { grant?: { token?: string; maxNodes?: number; expiresAt?: string } };
-    const issued = body.grant;
-    if (!issued?.token) {
-      console.error('cadre-host returned malformed response (missing grant token)');
-      process.exit(1);
-      return;
-    }
-    printGrantToken(issued.token, opts.qr !== false);
-    console.error(`(maxNodes ${issued.maxNodes ?? '?'}${issued.expiresAt ? `, expires ${issued.expiresAt}` : ', no expiry'})`);
-    process.exit(0);
-  });
-
-grant
-  .command('list')
-  .description('List issued grant tokens')
-  .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
-  .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
-  .action(async (opts: { port: string; host: string }) => {
-    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
-    let response: Response;
-    try {
-      response = await fetch(url);
-    } catch (err) {
-      console.error(`Failed to reach cadre-host at ${url}: ${(err as Error).message}`);
-      process.exit(2);
-      return;
-    }
-    if (!response.ok) {
-      console.error(`cadre-host returned ${response.status}: ${response.statusText}`);
-      process.exit(1);
-      return;
-    }
-    const body = await response.json() as { grants: GrantListing[] };
-    console.log('Grants:');
-    if (body.grants.length === 0) {
-      console.log('  (none)');
-    } else {
-      for (const g of body.grants) {
-        const state = g.revokedAt ? ' [revoked]' : (g.expiresAt ? ` (expires ${g.expiresAt})` : '');
-        console.log(`  ${g.token}  ${g.label}  live=${g.liveNodes} max=${g.maxNodes}${state}`);
-      }
-    }
+  .action(async (id: string, opts: { port: string; host: string }) => {
+    const base = `http://${opts.host}:${resolvePort(opts.port)}`;
+    await callApi(`${base}/api/hosted-nodes/${encodeURIComponent(id)}`, 'DELETE', undefined, (error) => (error.code === 'not_found'
+      ? `No hosted node with id "${id}". Run \`cadre-host node list\` to list them.`
+      : `cadre-host refused the removal: ${error.message} (${error.code})`));
+    console.log(`removed hosted node ${id}`);
     process.exit(0);
   });
 
-grant
-  .command('revoke')
-  .description('Revoke a grant token (blocks future requests) and shut down the nodes donated under it')
-  .argument('<token>', 'Grant token to revoke')
-  .option('--keep-nodes', 'Leave the nodes already donated under this grant running')
+node
+  .command('reset')
+  .description('Remove a hosted node and start a fresh one with a new code (for a node someone else claimed, or one that failed)')
+  .argument('<id>', 'Hosted node id (hn_…) to replace')
+  .option('--no-qr', 'Print only the join text, no QR code')
+  .option('--no-wait', 'Exit once the code is shown instead of waiting for the claim')
   .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
   .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
-  .action(async (token: string, opts: { keepNodes?: boolean; port: string; host: string }) => {
+  .action(async (id: string, opts: JoinOptions) => {
     const base = `http://${opts.host}:${resolvePort(opts.port)}`;
-    const query = opts.keepNodes ? '?keepNodes=true' : '';
-    const response = await adminDelete(base, `/grants-admin/${encodeURIComponent(token)}${query}`);
-    const body = await response.json() as { terminated?: string[] };
-    console.log(`revoked grant: ${token}`);
-    console.log(opts.keepNodes
-      ? 'existing donated nodes left running'
-      : `terminated ${body.terminated?.length ?? 0} donated node(s)`);
+    const { node: fresh } = await callApi<{ node: HostedNodeLike }>(
+      `${base}/api/hosted-nodes/${encodeURIComponent(id)}/reset`, 'POST', {},
+      (error) => (error.code === 'not_found'
+        ? `No hosted node with id "${id}". Run \`cadre-host node list\` to list them.`
+        : `cadre-host refused the reset: ${error.message} (${error.code})`),
+    );
+    console.error(`Removed hosted node ${id}.`);
+    await showClaimAndWait(base, fresh, opts);
     process.exit(0);
   });
 
-grant
-  .command('terminate')
-  .description('Shut down one donated node (the id shown on the Nodes page)')
-  .argument('<donation-id>', 'Donation id (grn_…) of the node to shut down')
+node
+  .command('retry')
+  .description('Start an invitation node again after no member of its cadre could be reached, and wait until it joins or fails')
+  .argument('<id>', 'Hosted node id (hn_…) whose invitation failed')
+  .option('--no-wait', 'Exit once the node is started again instead of waiting for it to join')
   .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
   .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
-  .action(async (id: string, opts: { port: string; host: string }) => {
+  .action(async (id: string, opts: { wait?: boolean; port: string; host: string }) => {
     const base = `http://${opts.host}:${resolvePort(opts.port)}`;
-    await adminDelete(base, `/grants-admin/donations/${encodeURIComponent(id)}`);
-    console.log(`terminated donated node: ${id}`);
-    process.exit(0);
+    const { node: retried } = await callApi<{ node: HostedNodeLike }>(
+      `${base}/api/hosted-nodes/${encodeURIComponent(id)}/retry`, 'POST', {},
+      (error) => (error.code === 'not_found'
+        ? `No hosted node with id "${id}". Run \`cadre-host node list\` to list them.`
+        : `cadre-host refused the retry: ${error.message} (${error.code})`),
+    );
+    process.exit(await followInvitationJoin(base, retried, opts));
   });
 
-/**
- * DELETE against the loopback admin surface, exiting the process on failure —
- * 2 when cadre-host is unreachable, 1 on a non-OK response — so callers only
- * ever see an OK response.
- */
-async function adminDelete(base: string, path: string): Promise<Response> {
-  let response: Response;
-  try {
-    response = await fetch(`${base}${path}`, { method: 'DELETE' });
-  } catch (err) {
-    console.error(`Failed to reach cadre-host at ${base}: ${(err as Error).message}`);
-    process.exit(2);
-  }
-  if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
-    process.exit(1);
-  }
-  return response;
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
 }
 
 // ============================================================================
@@ -927,23 +680,21 @@ nat
 
 nat
   .command('settings')
-  .description('Update NAT settings (external port, UPnP toggle)')
-  .option('--external-port <port>', 'External port to map')
-  .option('--internal-port <port>', 'Internal libp2p port (defaults to external)')
-  .option('--no-upnp', 'Disable UPnP/NAT-PMP port mapping')
+  .description('Update NAT settings (network mode, UPnP toggle)')
+  .option('--network <mode>', 'auto (default: public when this machine holds a public IPv4), lan (behind a router) or public (reached directly, e.g. a VPS)')
+  .option('--upnp', 'Ask the router for port mappings over UPnP')
+  .option('--no-upnp', 'Stop asking the router for port mappings (manual forwards stay)')
   .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
   .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
   .action(async (opts: {
-    externalPort?: string;
-    internalPort?: string;
+    network?: string;
     upnp?: boolean;
     port: string;
     host: string;
   }) => {
     const url = `http://${opts.host}:${resolvePort(opts.port)}/nat/settings`;
     const patch: Record<string, unknown> = {};
-    if (opts.externalPort) patch.externalPort = resolvePort(opts.externalPort);
-    if (opts.internalPort) patch.internalPort = resolvePort(opts.internalPort);
+    if (opts.network !== undefined) patch.network = opts.network;
     // Commander assigns `upnp: false` when `--no-upnp` is passed.
     if (opts.upnp === false) patch.upnpEnabled = false;
     if (opts.upnp === true) patch.upnpEnabled = true;
@@ -953,6 +704,67 @@ nat
     process.exit(0);
   });
 
+interface ForwardOptions {
+  tcp?: number;
+  ws?: number;
+  clearTcp?: boolean;
+  clearWs?: boolean;
+  clear?: boolean;
+  port: string;
+  host: string;
+}
+
+nat
+  .command('forward')
+  .description('Tell cadre-host the external ports you forwarded on your router for one node')
+  .argument('<nodeId>', 'Node id as `cadre-host nat status` lists it')
+  .option('--tcp <port>', "External port your router forwards to the node's TCP port", parsePortArg)
+  .option('--ws <port>', "External port your router forwards to the node's WebSocket port", parsePortArg)
+  .option('--clear-tcp', 'Forget the TCP forward')
+  .option('--clear-ws', 'Forget the WebSocket forward')
+  .option('--clear', 'Forget both forwards')
+  .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
+  .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
+  .action(async (nodeId: string, opts: ForwardOptions) => {
+    const patch = forwardPatchFrom(opts);
+    const url = `http://${opts.host}:${resolvePort(opts.port)}/nat/nodes/${encodeURIComponent(nodeId)}/forward`;
+    const body = await callJson<NatStatusLike>(url, 'PUT', patch, (error) => (error.code === 'unknown_node'
+      ? `No node with id "${nodeId}" runs on this host. Run \`cadre-host nat status\` to list node ids.`
+      : `cadre-host refused the forward: ${error.message} (${error.code})`));
+    printForwardResult(nodeId, body);
+    process.exit(0);
+  });
+
+/** The route's patch: a port sets that forward, a clear flag sends `null`. Exits on conflicting or missing flags. */
+function forwardPatchFrom(opts: ForwardOptions): ManualForwardPatch {
+  const patch: ManualForwardPatch = {};
+  const clears = { tcp: opts.clearTcp === true, ws: opts.clearWs === true };
+  for (const kind of ['tcp', 'ws'] as const) {
+    const value = opts[kind];
+    const clear = opts.clear === true || clears[kind];
+    if (value !== undefined && clear) {
+      console.error(`--${kind} conflicts with ${opts.clear ? '--clear' : `--clear-${kind}`}`);
+      process.exit(1);
+    }
+    if (value !== undefined) patch[kind] = value;
+    else if (clear) patch[kind] = null;
+  }
+  if (Object.keys(patch).length === 0) {
+    console.error('Nothing to change: pass --tcp, --ws, --clear-tcp, --clear-ws or --clear.');
+    process.exit(1);
+  }
+  return patch;
+}
+
+/** Commander parser for an external port. */
+function parsePortArg(raw: string): number {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    throw new InvalidArgumentError('expected a whole number from 1 to 65535.');
+  }
+  return n;
+}
+
 const ddns = nat
   .command('ddns')
   .description('Configure dynamic DNS');
@@ -1035,8 +847,7 @@ ddns
 // do NOT go through the running management API). Private keys land in the OS
 // keychain (keytar) or the 0600 file-store fallback; the non-secret bits (APNs
 // bundle id / sandbox toggle, cooldown/debounce) land in host.config.json. New
-// credentials take effect on the next owner-node (re)spawn — run
-// `cadre-host` restart (or restart the service) to apply them immediately.
+// credentials reach a node the next time it is spawned.
 
 const push = program
   .command('push')
@@ -1065,7 +876,7 @@ push
       clientEmail: opts.clientEmail,
       privateKey,
     });
-    console.log('✓ FCM credentials stored. Restart cadre-host to apply on the owner node.');
+    console.log('✓ FCM credentials stored. A node picks them up the next time it is spawned.');
     process.exit(0);
   });
 
@@ -1102,7 +913,7 @@ push
     });
     console.log(
       `✓ APNs credentials stored (${opts.production ? 'production' : 'sandbox'}). ` +
-      `Restart cadre-host to apply on the owner node.`,
+      `A node picks them up the next time it is spawned.`,
     );
     process.exit(0);
   });
@@ -1146,7 +957,7 @@ push
         updateHostConfig(cfgPath, { push: rest });
       }
     }
-    console.log(`✓ Cleared push credentials: ${target}. Restart cadre-host to apply.`);
+    console.log(`✓ Cleared push credentials: ${target}. A node stops carrying them the next time it is spawned.`);
     process.exit(0);
   });
 
@@ -1200,46 +1011,77 @@ function readPrivateKeyArg(file: string | undefined, inline: string | undefined,
 }
 
 async function getJson(url: string): Promise<NatStatusLike> {
-  return await callJson(url, 'GET');
+  return await callJson<NatStatusLike>(url, 'GET');
 }
 
 async function postJson(url: string, body: unknown): Promise<NatStatusLike> {
-  return await callJson(url, 'POST', body);
+  return await callJson<NatStatusLike>(url, 'POST', body);
 }
 
 async function putJson(url: string, body: unknown): Promise<NatStatusLike> {
-  return await callJson(url, 'PUT', body);
+  return await callJson<NatStatusLike>(url, 'PUT', body);
+}
+
+/** The `{ code, message }` of a management-API error response. */
+interface ApiErrorBody {
+  code: string;
+  message: string;
+}
+
+/** The `/api/*` routes' success envelope. */
+interface ApiEnvelope<T> {
+  ok: true;
+  data: T;
+}
+
+/**
+ * One request to an `/api/*` route, unwrapping its `{ ok, data }` envelope.
+ * Exits on failure as `callJson` does; a 204 answers `undefined`.
+ */
+async function callApi<T = undefined>(
+  url: string,
+  method: string,
+  body?: unknown,
+  describeError?: (error: ApiErrorBody) => string,
+): Promise<T> {
+  const envelope = await callJson<ApiEnvelope<T> | undefined>(url, method, body, describeError);
+  return envelope?.data as T;
 }
 
-interface NatStatusLike {
-  portMode?: string;
-  externalPort?: number;
-  internalPort?: number;
-  externalIp?: string | null;
-  routerExternalIp?: string | null;
-  cgnatDetected?: boolean;
-  directReachability?: string;
-  lastTestedAt?: string | null;
-  mappingLeaseExpiresAt?: string | null;
-  ddns?: {
-    providerId?: string | null;
-    hostname?: string | null;
-    externallyManaged?: boolean;
-    lastUpdateAt?: string | null;
-    lastUpdateOk?: boolean | null;
-    lastError?: string | null;
-  };
+/**
+ * One request to the management API, exiting on failure: 2 when cadre-host is
+ * unreachable, 1 on a non-OK response, printed by `describeError` when the
+ * response carries a typed error and the caller has words for it.
+ */
+async function callJson<T>(
+  url: string,
+  method: string,
+  body?: unknown,
+  describeError?: (error: ApiErrorBody) => string,
+): Promise<T> {
+  const init: RequestInit = { method };
+  if (body !== undefined) {
+    init.headers = { 'content-type': 'application/json' };
+    init.body = JSON.stringify(body);
+  }
+  const response = await fetchOrExit(url, init);
+  if (!response.ok) {
+    const text = await response.text().catch(() => '');
+    const error = describeError ? apiErrorOf(response, text) : null;
+    console.error(error && describeError
+      ? describeError(error)
+      : `cadre-host returned ${response.status}: ${text || response.statusText}`);
+    process.exit(1);
+    throw new Error('non-ok');
+  }
+  if (response.status === 204) return undefined as T;
+  return await response.json() as T;
 }
 
-async function callJson(url: string, method: string, body?: unknown): Promise<NatStatusLike> {
-  let response: Response;
+/** `fetch`, exiting 2 with a hint when cadre-host cannot be reached at all. */
+async function fetchOrExit(url: string, init: RequestInit): Promise<Response> {
   try {
-    const init: RequestInit = { method };
-    if (body !== undefined) {
-      init.headers = { 'content-type': 'application/json' };
-      init.body = JSON.stringify(body);
-    }
-    response = await fetch(url, init);
+    return await fetch(url, init);
   } catch (err) {
     console.error(
       `Failed to reach cadre-host at ${url}: ${(err as Error).message}\n` +
@@ -1248,38 +1090,21 @@ async function callJson(url: string, method: string, body?: unknown): Promise<Na
     process.exit(2);
     throw err;
   }
-  if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
-    process.exit(1);
-    throw new Error('non-ok');
-  }
-  if (response.status === 204) return {} as NatStatusLike;
-  return await response.json() as NatStatusLike;
 }
 
-function printNatStatus(s: NatStatusLike): void {
-  console.log(`Port mapping: ${s.portMode ?? '?'} (external ${s.externalPort ?? '?'} → internal ${s.internalPort ?? '?'})`);
-  if (s.routerExternalIp) {
-    console.log(`Router IP:    ${s.routerExternalIp}`);
-  }
-  console.log(`External IP:  ${s.externalIp ?? '(unknown)'}${s.cgnatDetected ? '  [CGNAT detected]' : ''}`);
-  console.log(`Reachability: ${s.directReachability ?? 'unknown'}${s.lastTestedAt ? `  (tested ${s.lastTestedAt})` : ''}`);
-  if (s.mappingLeaseExpiresAt) {
-    console.log(`Lease expires: ${s.mappingLeaseExpiresAt}`);
-  }
-  const ddns = s.ddns ?? {};
-  if (ddns.providerId || ddns.hostname) {
-    console.log(`\nDDNS:`);
-    console.log(`  Provider:   ${ddns.providerId ?? '(none)'}${ddns.externallyManaged ? '  [externally managed]' : ''}`);
-    console.log(`  Hostname:   ${ddns.hostname ?? '(unset)'}`);
-    if (ddns.lastUpdateAt) {
-      const ok = ddns.lastUpdateOk ? 'OK' : 'FAIL';
-      console.log(`  Last update: ${ok} at ${ddns.lastUpdateAt}${ddns.lastError ? `  — ${ddns.lastError}` : ''}`);
-    }
-  } else {
-    console.log('\nDDNS: not configured');
+/** The typed error in a `{ ok: false, error: { code, message } }` body (`server/error-handler.ts`), or null. */
+function apiErrorOf(response: Response, text: string): ApiErrorBody | null {
+  if (!response.headers.get('content-type')?.includes('application/json')) return null;
+  let parsed: { error?: { code?: unknown; message?: unknown } };
+  try {
+    parsed = JSON.parse(text) as typeof parsed;
+  } catch {
+    // Malformed JSON: the caller prints the raw text instead.
+    return null;
   }
+  const { code, message } = parsed.error ?? {};
+  if (typeof code !== 'string') return null;
+  return { code, message: typeof message === 'string' ? message : '' };
 }
 
 /** Read a single line from stdin with echo suppressed (TTY only). */