@serfab/cadre-host 1.13.0 → 1.14.0

package/dist/bin/host.js

@@ -2,44 +2,39 @@
 /**
  * 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 { Command } from 'commander';
-import { parseDuration } from '../auth/duration.js';
+import { Command, InvalidArgumentError } from 'commander';
 import { Installer } from '../installer/index.js';
-import { readHostConfig, updateHostConfig, hostOwnsCadre } from '../installer/config.js';
-import { configPath as resolveConfigPath, defaultDataDir, defaultHostJs, defaultServiceDir, identityPath as resolveIdentityPath, } from '../installer/paths.js';
+import { readHostConfig, updateHostConfig } from '../installer/config.js';
+import { configPath as resolveConfigPath, defaultDataDir, defaultHostJs, defaultServiceDir, } 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, } from '../donation/index.js';
+import { HostedNodeService, HostedNodeStore, HostedNodeSupervisor, HOSTED_NODE_REAP_SWEEP_MS, HOSTED_NODE_SPAWNING_TTL_MS, } from '../hosted/index.js';
 import { NatService } from '../nat/index.js';
 import { createSecretsStore } from '../nat/secrets/index.js';
 import { resolvePushCredentials, setFcmSecret, setApnsSecret, clearPushSecret, pushStatus, } from '../push/index.js';
-import { StrandService } from '../strands/index.js';
-import { OwnerNodeClient } from '../owner/index.js';
 import { createLocalUiServer, HostSettingsStore } from '../server/index.js';
 import { openBrowser } from '../installer/browser.js';
+import { printForwardResult, printNatStatus } from './nat-output.js';
+import { printClaimPayload, printClaimed, printInvitationOutcome, printNodeList, } 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'];
-function looksLikePeerId(id) {
-    return PEER_ID_PREFIXES.some((p) => id.startsWith(p));
-}
 function resolvePort(raw) {
     const n = Number(raw);
     if (!Number.isFinite(n) || n <= 0 || n > 65535) {
@@ -62,11 +57,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`)')
@@ -77,11 +69,8 @@ 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,
             system: Boolean(opts.system),
             ...(opts.nodePath ? { nodePath: opts.nodePath } : {}),
             noService: opts.service === false,
@@ -96,9 +85,6 @@ 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);
-        }
         process.exit(0);
     }
     catch (err) {
@@ -118,8 +104,8 @@ program
     .action(async (opts) => {
     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) {
@@ -128,7 +114,7 @@ program
                 return;
             }
             const dataDir = opts.dataDir ?? '(default data directory)';
-            const confirmed = await confirmDestructive(`This will permanently delete ${dataDir} (identity, trust circle, NAT state). Continue? [y/N] `);
+            const confirmed = await confirmDestructive(`This will permanently delete ${dataDir} (node identities, hosted-node records, NAT state). Continue? [y/N] `);
             if (!confirmed) {
                 console.error('uninstall aborted.');
                 process.exit(1);
@@ -168,7 +154,7 @@ program
     }
 });
 // ============================================================================
-// start — load config + identity, bind management API listener, wait
+// start — load config, bind management API listener, wait
 // ============================================================================
 program
     .command('start')
@@ -188,12 +174,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.
         // The local-UI ticket (6.5) wires the handlers into HTTP routes; here we
@@ -232,162 +212,84 @@ program
         // Don't block startup on the network round-trip — call and forget.
         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 = {};
         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.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,
         });
-        // 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 donationService
-                .reapStaleAwaitingSeed(DONATION_AWAITING_SEED_TTL_MS)
-                .catch((err) => console.error(`donation reap failed: ${err.message}`));
-            void donationService
-                .reapStaleProvisioning(DONATION_PROVISIONING_TTL_MS)
-                .catch((err) => console.error(`donation provisioning reap failed: ${err.message}`));
+            void hostedNodes
+                .reapStuckSpawning(HOSTED_NODE_SPAWNING_TTL_MS)
+                .catch((err) => console.error(`hosted node reap failed: ${err.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;
-        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.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.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.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.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.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();
@@ -397,17 +299,14 @@ program
         console.log(`cadre-host local UI: ${url}`);
         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();
+            await natService.stop();
         }
         catch { /* ignore */ }
         updateService.stop();
@@ -494,321 +393,162 @@ async function confirmDestructive(message) {
         rl.close();
     }
 }
-const requireForQr = createRequire(import.meta.url);
-function printEnrollmentInvite(invite) {
-    // 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');
-        qr.generate(invite.encodedInvite, { small: true }, (rendered) => {
-            console.log(rendered);
-        });
-    }
-    catch (err) {
-        console.error(`(qrcode-terminal unavailable: ${err.message})`);
-    }
-    console.log(`  ${invite.encodedInvite}`);
-    if (invite.expiresAt) {
-        console.log(`  (expires ${invite.expiresAt})`);
-    }
-}
-function printGrantToken(token, withQr) {
-    if (withQr) {
-        // Best-effort QR render — fall back to the bare token if the lib chokes.
-        try {
-            const qr = requireForQr('qrcode-terminal');
-            qr.generate(token, { small: true }, (rendered) => {
-                console.error(rendered);
-            });
-        }
-        catch (err) {
-            console.error(`(qrcode-terminal unavailable: ${err.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 = 60000;
+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 = 2000;
 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, opts) => {
-    let ttlMs;
-    try {
-        ttlMs = parseDuration(opts.ttl);
-    }
-    catch (err) {
-        console.error(`Invalid --ttl: ${err.message}`);
-        process.exit(1);
-        return;
-    }
-    const port = resolvePort(opts.port);
-    const url = `http://${opts.host}:${port}/auth/invites`;
-    let 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.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();
-    if (!body.encodedInvite) {
-        console.error('cadre-host returned malformed response (missing encodedInvite)');
-        process.exit(1);
-        return;
-    }
-    console.log(body.encodedInvite);
-    if (body.expiresAt) {
-        console.error(`(expires at ${body.expiresAt})`);
+    .action(async (opts) => {
+    const base = `http://${opts.host}:${resolvePort(opts.port)}`;
+    if (opts.invitation !== undefined) {
+        const { node } = await callApi(`${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(`${base}/api/hosted-nodes`, 'POST', {});
+    await showClaimAndWait(base, node, opts);
     process.exit(0);
 });
-const trust = program
-    .command('trust')
-    .description('Manage the trust circle (list members, revoke invites/members)');
-trust
-    .command('list')
-    .description('List trust-circle members and pending invites')
-    .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) => {
-    const url = `http://${opts.host}:${resolvePort(opts.port)}/auth/trust-circle`;
-    let response;
-    try {
-        response = await fetch(url);
-    }
-    catch (err) {
-        console.error(`Failed to reach cadre-host at ${url}: ${err.message}`);
-        process.exit(2);
+/**
+ * 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, node, opts) {
+    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;
-    }
-    if (!response.ok) {
-        console.error(`cadre-host returned ${response.status}: ${response.statusText}`);
+    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);
-        return;
     }
-    const body = await response.json();
-    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}`);
+    printClaimed(settled);
+}
+/**
+ * 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, node, opts) {
+    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;
+}
+/** Poll `GET …/:id/claim` until the child answers (503 meanwhile), up to `CLAIM_DETAILS_WAIT_MS`. */
+async function waitForClaimDetails(base, id) {
+    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()).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);
         }
+        await sleep(CLAIM_DETAILS_POLL_MS);
     }
-    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, opts) => {
-    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;
-    try {
-        response = await fetch(`${base}${path}`, { method: 'DELETE' });
-    }
-    catch (err) {
-        console.error(`Failed to reach cadre-host at ${base}: ${err.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;
+}
+/** Poll `GET …/:id` until the node is `joined` or `error`. */
+async function waitUntilSettled(base, id) {
+    const url = `${base}/api/hosted-nodes/${encodeURIComponent(id)}`;
+    while (true) {
+        const { node } = await callApi(url, 'GET');
+        if (node.status === 'joined' || node.status === 'error')
+            return node;
+        await sleep(CLAIM_WAIT_POLL_MS);
     }
-    console.log(`revoked ${kind}: ${id}`);
-    process.exit(0);
-});
+}
 // ============================================================================
-// grant subcommands — donation grant tokens (who may ask this host for a node)
+// node subcommands — the nodes this host runs
 // ============================================================================
-//
-// 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')
+const node = program
+    .command('node')
+    .description('List, remove, reset or retry the nodes this host runs');
+node
+    .command('list')
+    .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 (label, opts) => {
-    const payload = { 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.message}`);
-            process.exit(1);
-            return;
-        }
-    }
-    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
-    let 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.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();
-    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'})`);
+    .action(async (opts) => {
+    const base = `http://${opts.host}:${resolvePort(opts.port)}`;
+    const { nodes } = await callApi(`${base}/api/hosted-nodes`, 'GET');
+    printNodeList(nodes);
     process.exit(0);
 });
-grant
-    .command('list')
-    .description('List issued grant tokens')
+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 (opts) => {
-    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
-    let response;
-    try {
-        response = await fetch(url);
-    }
-    catch (err) {
-        console.error(`Failed to reach cadre-host at ${url}: ${err.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();
-    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, opts) => {
+    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, opts) => {
+    .action(async (id, opts) => {
     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();
-    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(`${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, opts) => {
     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(`${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, path) {
-    let response;
-    try {
-        response = await fetch(`${base}${path}`, { method: 'DELETE' });
-    }
-    catch (err) {
-        console.error(`Failed to reach cadre-host at ${base}: ${err.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) {
+    return new Promise((res) => setTimeout(res, ms));
 }
 // ============================================================================
 // nat subcommands
@@ -852,19 +592,14 @@ 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 (UPnP toggle)')
+    .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) => {
     const url = `http://${opts.host}:${resolvePort(opts.port)}/nat/settings`;
     const patch = {};
-    if (opts.externalPort)
-        patch.externalPort = resolvePort(opts.externalPort);
-    if (opts.internalPort)
-        patch.internalPort = resolvePort(opts.internalPort);
     // Commander assigns `upnp: false` when `--no-upnp` is passed.
     if (opts.upnp === false)
         patch.upnpEnabled = false;
@@ -874,6 +609,56 @@ nat
     printNatStatus(body);
     process.exit(0);
 });
+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, opts) => {
+    const patch = forwardPatchFrom(opts);
+    const url = `http://${opts.host}:${resolvePort(opts.port)}/nat/nodes/${encodeURIComponent(nodeId)}/forward`;
+    const body = await callJson(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) {
+    const patch = {};
+    const clears = { tcp: opts.clearTcp === true, ws: opts.clearWs === true };
+    for (const kind of ['tcp', 'ws']) {
+        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) {
+    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');
@@ -946,8 +731,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')
     .description('Configure FCM/APNs push credentials for mobile strand-wake delivery');
@@ -968,7 +752,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);
 });
 push
@@ -995,7 +779,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);
 });
 push
@@ -1039,7 +823,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);
 });
 push
@@ -1101,55 +885,67 @@ async function postJson(url, body) {
 async function putJson(url, body) {
     return await callJson(url, 'PUT', body);
 }
-async function callJson(url, method, body) {
-    let response;
-    try {
-        const init = { method };
-        if (body !== undefined) {
-            init.headers = { 'content-type': 'application/json' };
-            init.body = JSON.stringify(body);
-        }
-        response = await fetch(url, init);
-    }
-    catch (err) {
-        console.error(`Failed to reach cadre-host at ${url}: ${err.message}\n` +
-            `Hint: is cadre-host running? Try \`cadre-host start\`.`);
-        process.exit(2);
-        throw err;
+/**
+ * One request to an `/api/*` route, unwrapping its `{ ok, data }` envelope.
+ * Exits on failure as `callJson` does; a 204 answers `undefined`.
+ */
+async function callApi(url, method, body, describeError) {
+    const envelope = await callJson(url, method, body, describeError);
+    return envelope?.data;
+}
+/**
+ * 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(url, method, body, describeError) {
+    const init = { 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(() => '');
-        console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
+        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 {};
+        return undefined;
     return await response.json();
 }
-function printNatStatus(s) {
-    console.log(`Port mapping: ${s.portMode ?? '?'} (external ${s.externalPort ?? '?'} → internal ${s.internalPort ?? '?'})`);
-    if (s.routerExternalIp) {
-        console.log(`Router IP:    ${s.routerExternalIp}`);
+/** `fetch`, exiting 2 with a hint when cadre-host cannot be reached at all. */
+async function fetchOrExit(url, init) {
+    try {
+        return await fetch(url, init);
     }
-    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}`);
+    catch (err) {
+        console.error(`Failed to reach cadre-host at ${url}: ${err.message}\n` +
+            `Hint: is cadre-host running? Try \`cadre-host start\`.`);
+        process.exit(2);
+        throw err;
     }
-    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}` : ''}`);
-        }
+}
+/** The typed error in a `{ ok: false, error: { code, message } }` body (`server/error-handler.ts`), or null. */
+function apiErrorOf(response, text) {
+    if (!response.headers.get('content-type')?.includes('application/json'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
     }
-    else {
-        console.log('\nDDNS: not configured');
+    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). */
 function readSecretLine(prompt) {