nterminal 1.3.13 → 1.3.14

package/dist/scripts/onboarding.js

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import https from 'node:https';
 import net from 'node:net';
 import os from 'node:os';
 import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
@@ -263,11 +264,71 @@ export function mergeEnv(existing, updates) {
     }
     return `${lines.join('\n').replace(/\n+$/, '')}\n`;
 }
-export function buildAgentRegisterPayload(name, url, token, transport = 'direct') {
+export function defaultSecondaryTransport(existing) {
+    return existing?.trim() === 'outbound' ? 'outbound' : 'direct';
+}
+export function buildAgentRegisterPayload(name, url, token, transport = 'direct', tlsCertificate) {
     const base = { name: name.trim(), token: token.trim() };
-    return transport === 'outbound'
-        ? { ...base, transport }
-        : { ...base, url: new URL(url.trim()).origin };
+    if (transport === 'outbound')
+        return { ...base, transport };
+    const parsed = new URL(url.trim());
+    if (tlsCertificate !== undefined && (parsed.protocol !== 'https:' || !tlsCertificate.trim())) {
+        throw new Error('Direct TLS registration requires an HTTPS URL and a certificate.');
+    }
+    return { ...base, url: parsed.origin, ...(tlsCertificate === undefined ? {} : { tlsCertificate }) };
+}
+// Only this temporary listener is owned by onboarding; an occupied port may
+// belong to an existing runtime or another service and must not be disturbed.
+export async function startDirectTlsProbe(identity, agentToken, host, port) {
+    const expected = crypto.createHash('sha256').update(`Bearer ${agentToken}`).digest();
+    const server = https.createServer({ key: identity.privateKey, cert: identity.certificate, minVersion: 'TLSv1.2' }, (req, res) => {
+        res.setHeader('content-type', 'application/json');
+        res.setHeader('cache-control', 'no-store');
+        if (req.method !== 'GET' || req.url !== '/api/agent/direct-tls/probe') {
+            res.writeHead(404).end(JSON.stringify({ error: 'not_found' }));
+            return;
+        }
+        const supplied = crypto.createHash('sha256').update(req.headers.authorization ?? '').digest();
+        if (!agentToken || !crypto.timingSafeEqual(expected, supplied)) {
+            res.writeHead(401).end(JSON.stringify({ error: 'unauthorized' }));
+            return;
+        }
+        res.end(JSON.stringify({ ok: true }));
+    });
+    server.requestTimeout = 8000;
+    server.headersTimeout = 8000;
+    server.setTimeout(8000, (socket) => socket.destroy());
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+    });
+    const listening = await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            if (error.code === 'EADDRINUSE')
+                resolve(false);
+            else
+                reject(error);
+        };
+        server.once('error', onError);
+        server.listen(port, host, () => {
+            server.removeListener('error', onError);
+            resolve(true);
+        });
+    });
+    if (!listening)
+        return null;
+    let closing;
+    return {
+        close() {
+            closing ??= new Promise((resolve, reject) => {
+                server.close((error) => error ? reject(error) : resolve());
+                for (const socket of sockets)
+                    socket.destroy();
+            });
+            return closing;
+        }
+    };
 }
 export function shouldBlockRootOnboarding(uid, env = process.env) {
     if (uid !== 0) {
@@ -819,9 +880,9 @@ function printStep(section, current, total, title, detail) {
 function shouldUseColor() {
     return Boolean(process.stdout.isTTY && process.env.NO_COLOR === undefined && process.env.NTERMINAL_COLOR !== '0');
 }
-async function askUrl(p, question, fallback, defaultProtocol = 'https') {
+async function askUrl(p, question, fallback) {
     for (;;) {
-        const value = normalizeUrlInput(await p.ask(question, fallback), defaultProtocol);
+        const value = normalizeUrlInput(await p.ask(question, fallback));
         if (!value) {
             console.log('A URL is required. Try again.');
             continue;
@@ -834,8 +895,12 @@ async function askUrl(p, question, fallback, defaultProtocol = 'https') {
             console.log('Invalid URL. Try again.');
             continue;
         }
-        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-            console.log('URL must start with http:// or https://. Try again.');
+        if (parsed.protocol !== 'https:') {
+            console.log('An https:// URL is required. Try again.');
+            continue;
+        }
+        if (parsed.username || parsed.password) {
+            console.log('Enter a URL without embedded credentials.');
             continue;
         }
         return value;
@@ -844,7 +909,7 @@ async function askUrl(p, question, fallback, defaultProtocol = 'https') {
 async function askSecondaryAdvertisedUrl(p, bindHost, port) {
     console.log('Checking the public IP that this machine uses for outbound internet access...');
     const publicIp = await detectPublicIp(2500);
-    const suggestion = suggestSecondaryAdvertisedUrl({ bindHost, port, publicIp });
+    const suggestion = suggestSecondaryAdvertisedUrl({ bindHost, port, publicIp, protocol: 'https' });
     console.log(`Local/interface URL: ${suggestion.localUrl}`);
     if (suggestion.publicIp) {
         console.log(`Detected public IP: ${suggestion.publicIp}`);
@@ -855,17 +920,8 @@ async function askSecondaryAdvertisedUrl(p, bindHost, port) {
     if (suggestion.warning) {
         console.log(colorText(`Warning: ${suggestion.warning}`, '33', shouldUseColor()));
     }
-    console.log('Cloud firewalls/security groups must allow the chosen port from the main server, otherwise registration can succeed but the server will show offline.');
-    for (;;) {
-        const url = await askUrl(p, 'URL the main should use to reach this secondary', suggestion.url, 'http');
-        if (new URL(url).protocol === 'https:') {
-            return url;
-        }
-        console.log(colorText('Warning: direct HTTP sends the agent token and terminal traffic without transport encryption. Use it only over a private VPN/trusted network and restrict the port to the main server.', '33', shouldUseColor()));
-        if (await p.confirm('Continue with this unencrypted direct HTTP URL?', false)) {
-            return url;
-        }
-    }
+    console.log('Cloud firewalls/security groups must allow the chosen port from the main server. Direct TLS connectivity must pass before configuration is saved.');
+    return askUrl(p, 'HTTPS URL the main should use to reach this secondary', suggestion.url);
 }
 async function askSecondaryFirewallSource(p, port) {
     console.log('\nFor secondary servers, the browser talks to the main and the main talks to this agent. This port should normally accept only the main server.');
@@ -1215,21 +1271,45 @@ async function onboardMain(p) {
     console.log(`\n${colorText('⚠', '33', shouldUseColor())} NTerminal itself is running on 127.0.0.1:${port.value}, but the public URL is not verified yet — the reverse-proxy or TLS step above was skipped or did not pass its check.`);
     console.log(`Finish the remaining commands shown above, then re-run \`${onboardingCommand()}\` to re-verify ${publicUrl}.`);
 }
+export async function prepareOnboardingDirectTlsIdentity(p, stateDir, ensure, requireExisting = false) {
+    for (;;) {
+        try {
+            return { action: 'direct', identity: await ensure(stateDir, { requireExisting }) };
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'direct_tls_identity_missing') {
+                console.error('The registered direct TLS identity is missing. Restore the original identity or explicitly re-register a replacement with the main; onboarding will not silently replace the key.');
+            }
+            if (!(error instanceof Error) || error.message !== 'direct_tls_openssl_failed')
+                throw error;
+        }
+        console.log('OpenSSL could not generate the direct TLS identity. Install or check the openssl executable on this user\'s PATH, then retry.');
+        console.log('You can choose outbound instead without generating a direct TLS certificate, or cancel without saving configuration.');
+        for (;;) {
+            const action = (await p.ask('TLS identity setup (retry / outbound / cancel)', 'retry')).trim().toLowerCase();
+            if (action === 'retry')
+                break;
+            if (action === 'outbound' || action === 'cancel')
+                return { action };
+            console.log('Choose one of the listed actions.');
+        }
+    }
+}
 async function onboardSecondary(p) {
     const updateHelperNeed = detectUpdateHelperNeed();
-    const totalSteps = 8 + (updateHelperNeed.needed ? 1 : 0);
+    const totalSteps = 7 + (updateHelperNeed.needed ? 1 : 0);
     let currentStep = 0;
     const section = 'Secondary server setup';
     const step = (title, detail) => printStep(section, ++currentStep, totalSteps, title, detail);
     console.log(`\n=== ${section} ===`);
-    step('Choose connection mode', 'Direct is best for stable reachable servers; outbound works behind NAT or changing mobile IPs.');
     const previousTransport = existingEnvValue('NTERMINAL_AGENT_TRANSPORT');
-    const transport = await chooseSecondaryTransport(p, previousTransport);
+    let transport = defaultSecondaryTransport(previousTransport);
+    console.log(transport === 'direct' ? 'Using direct HTTPS with a certificate pinned by the main.' : 'Preserving the existing outbound connection mode.');
     step('Bind local agent', transport === 'direct'
         ? 'The main server must be able to reach this host and port.'
         : 'The agent stays on loopback and opens an encrypted outbound link to the main.');
     const existingHost = existingEnvValue('NTERMINAL_HOST');
-    const host = resolveSecondaryBindHost(transport, previousTransport, existingHost);
+    let host = resolveSecondaryBindHost(transport, previousTransport, existingHost);
     printResolvedBindHost(host, transport === 'direct'
         ? 'listens on all interfaces so the main can reach this server'
         : 'loopback only; no inbound agent port is required');
@@ -1238,16 +1318,35 @@ async function onboardSecondary(p) {
     step('Name this server', transport === 'direct'
         ? 'Choose the URL the main can reach. Public IP detection is only a suggested default.'
         : 'No public IP or inbound firewall rule is needed for this connection mode.');
-    const selfUrl = transport === 'direct' ? await askSecondaryAdvertisedUrl(p, host.value, port.value) : null;
+    let selfUrl = transport === 'direct' ? await askSecondaryAdvertisedUrl(p, host.value, port.value) : null;
     const name = await p.ask('Name shown in the main', os.hostname());
     // Preserve existing secret/token on re-run so a re-registration keeps the same agent identity.
-    // Do not write the selected transport yet: an outbound registration can still fail, and
-    // persisting a half-configured outbound mode would prevent the existing runtime from restarting.
+    // Do not change runtime config until registration and direct TLS verification pass.
     const sessionSecret = existingEnvValue('NTERMINAL_SESSION_SECRET') ?? generateSessionSecret();
     const agentToken = existingEnvValue('NTERMINAL_AGENT_TOKEN') ?? generateAgentToken();
     const reusedSessionSecret = Boolean(existingEnvValue('NTERMINAL_SESSION_SECRET'));
     const reusedAgentToken = Boolean(existingEnvValue('NTERMINAL_AGENT_TOKEN'));
     const statePath = resolveRuntimeStatePath(APP_DIR, existingEnvValue('NTERMINAL_STATE_PATH'), process.env.NTERMINAL_RUNTIME_STATE_PATH);
+    let identity;
+    if (transport === 'direct') {
+        const { ensureDirectTlsIdentity } = await import(serverModuleUrl('agent/directTlsIdentity'));
+        const preparation = await prepareOnboardingDirectTlsIdentity(p, path.dirname(statePath), ensureDirectTlsIdentity, existingEnvValue('NTERMINAL_DIRECT_TLS_REQUIRED') === 'true');
+        if (preparation.action === 'cancel') {
+            p.close();
+            console.error(`\nTLS identity setup cancelled. ${ENV_PATH} was left unchanged.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (preparation.action === 'outbound') {
+            transport = 'outbound';
+            selfUrl = null;
+            host = resolveSecondaryBindHost(transport, previousTransport, existingHost);
+            printResolvedBindHost(host, 'loopback only; no inbound agent port is required');
+        }
+        else if (preparation.action === 'direct') {
+            identity = preparation.identity;
+        }
+    }
     // Firewall: when the agent is publicly bound, the main can only reach it
     // if the host firewall lets the bind port in. Loopback binds never need
     // this so we skip the prompt entirely there. Onboarding used
@@ -1255,7 +1354,9 @@ async function onboardSecondary(p) {
     // "unreachable", the operator forgets ufw is even on, and debugging
     // burns a half hour before someone runs `ufw status`.
     step('Check network access', transport === 'direct' ? 'Restrict inbound access to the main where possible.' : 'Outbound mode needs HTTPS/WebSocket egress only.');
-    if (transport === 'direct' && isPubliclyBoundHost(host.value)) {
+    const checkNetworkAccess = async () => {
+        if (!isPubliclyBoundHost(host.value))
+            return;
         const portNumber = Number(port.value);
         if (Number.isFinite(portNumber)) {
             const source = await askSecondaryFirewallSource(p, port.value);
@@ -1264,33 +1365,33 @@ async function onboardSecondary(p) {
                 await ensureFirewallAllowsPort(portNumber, p, sudoMode, source ? { source } : {});
             }
         }
+    };
+    if (transport === 'direct')
+        await checkNetworkAccess();
+    step('Register with main', 'Required for both connection modes. Direct HTTPS must also pass the main server connection check.');
+    const agent = { name, selfUrl, agentToken, transport, ...(identity ? { tlsCertificate: identity.certificate } : {}) };
+    const registration = await registerWithMain(p, agent, {
+        mainUrl: existingEnvValue('NTERMINAL_MAIN_URL') ?? '',
+        ...(identity ? { probe: { privateKey: identity.privateKey, host: host.value, port: Number(port.value) } } : {}),
+        retryNetwork: checkNetworkAccess
+    });
+    transport = agent.transport;
+    selfUrl = agent.selfUrl;
+    host = resolveSecondaryBindHost(transport, previousTransport, existingHost);
+    if (!registration.registered) {
+        p.close();
+        console.error(`\nRegistration did not complete. ${ENV_PATH} was left unchanged; fix the error and re-run onboarding.`);
+        process.exitCode = 1;
+        return;
     }
-    step('Register with main', transport === 'outbound' ? 'Required so the main can authenticate and route this outbound link.' : 'Optional, but registration is the supported way to add this server to the main.');
-    const wantRegister = transport === 'outbound' || await p.confirm('\nRegister this server with a main now?', true);
-    let registration = { registered: false, mainUrl: null, agentId: null };
-    if (wantRegister) {
-        registration = await registerWithMain(p, { name, selfUrl, agentToken, transport });
-    }
-    else {
-        console.log('Skipped registration. Re-run onboarding on this secondary when you are ready to register it with the main.');
-    }
-    if (transport === 'outbound') {
-        if (!registration.registered || !registration.mainUrl || !registration.agentId) {
-            p.close();
-            console.error(`\nOutbound registration is required before this secondary can start. ${ENV_PATH} was left unchanged; fix the registration error and re-run onboarding.`);
-            process.exitCode = 1;
-            return;
-        }
-    }
+    const registrationEnv = buildSecondaryRegistrationEnv(agent, registration);
     step('Write runtime config', `Writing the complete configuration to ${ENV_PATH}.`);
     writeEnv({
         NTERMINAL_ROLE: 'secondary',
         NTERMINAL_SESSION_SECRET: sessionSecret,
         NTERMINAL_STATE_PATH: statePath,
         NTERMINAL_AGENT_TOKEN: agentToken,
-        NTERMINAL_AGENT_TRANSPORT: transport,
-        NTERMINAL_AGENT_ID: transport === 'outbound' ? registration.agentId : '',
-        NTERMINAL_MAIN_URL: transport === 'outbound' ? registration.mainUrl : '',
+        ...registrationEnv,
         NTERMINAL_HOST: host.value,
         NTERMINAL_PORT: port.value
     });
@@ -1316,47 +1417,76 @@ async function onboardSecondary(p) {
         process.exitCode = 1;
         return;
     }
-    const registeredWithMain = registration.registered;
-    step('Finish', registeredWithMain ? 'Registered secondary is ready.' : 'Secondary is running; registration can be retried later.');
-    printSummaryBox(`${colorText('✓', '32', shouldUseColor())} Secondary "${name}" is ready`, [
+    step('Finish', deploy ? 'Registered secondary has started.' : 'Configuration saved; start this secondary to bring it online.');
+    printSummaryBox(`${colorText('✓', '32', shouldUseColor())} Secondary "${name}" ${deploy ? 'is ready' : 'is configured'}`, [
         { label: transport === 'direct' ? 'Reachable at' : 'Connection', value: selfUrl ?? `outbound to ${registration.mainUrl}` },
         { label: 'Bind', value: `${host.value}:${port.value}` },
         {
             label: 'Registered',
-            value: registeredWithMain
-                ? 'yes (logged into the main)'
-                : wantRegister
-                    ? 'no — registration did not complete'
-                    : 'no — re-run onboarding to register later'
+            value: transport === 'direct' ? 'yes (direct TLS connection verified)' : 'yes (outbound link identity saved)'
         }
-    ], registeredWithMain
-        ? [
-            'On the main, the Servers list should now show this agent',
-            'Refresh the main browser tab if the Servers list was already open'
-        ]
-        : [
-            `This secondary is listening at ${selfUrl ?? `${host.value}:${port.value}`}`,
-            ...(wantRegister
-                ? ['Fix the registration error above and re-run onboarding on this secondary']
-                : ['Re-run onboarding on this secondary and choose registration when ready'])
-        ]);
+    ], [
+        'On the main, the Servers list should now show this agent',
+        deploy ? 'Refresh the main browser tab if the Servers list was already open' : `Start the secondary with: ${controlCommand('deploy')}`
+    ]);
 }
-async function registerWithMain(p, agent) {
+export function buildSecondaryRegistrationEnv(agent, registration) {
+    if (!registration.registered || !registration.mainUrl || !registration.agentId ||
+        new URL(registration.mainUrl).protocol !== 'https:' ||
+        (agent.transport === 'direct' && (!agent.tlsCertificate || !registration.tlsSupported || !registration.connectionVerified))) {
+        throw new Error('Registration and connection verification must complete before saving runtime configuration.');
+    }
+    return {
+        NTERMINAL_AGENT_TRANSPORT: agent.transport,
+        NTERMINAL_AGENT_ID: registration.agentId,
+        NTERMINAL_MAIN_URL: registration.mainUrl,
+        NTERMINAL_DIRECT_TLS_REQUIRED: agent.transport === 'direct' ? 'true' : 'false'
+    };
+}
+export function directTlsPortRecoveryInstructions(port, appDir = APP_DIR, envPath = ENV_PATH) {
+    const control = `NTERMINAL_APP_DIR=${shellSingleQuote(appDir)} NTERMINAL_ENV_FILE=${shellSingleQuote(envPath)} bash ${shellSingleQuote(path.join(appDir, 'scripts/nterminalctl'))}`;
+    return [
+        `Port ${port} is occupied, so onboarding could not start its temporary HTTPS probe. No process was stopped or configuration changed.`,
+        'An older NTerminal process may still serve HTTP even after installing the new package. It must be restarted before direct HTTPS registration can succeed.',
+        'In another shell as the same runtime user, check the saved instance and the process listening on this port:',
+        `  ${control} status`,
+        `  lsof -nP -iTCP:${port} -sTCP:LISTEN`,
+        `  (On Linux without lsof, use: ss -ltnp 'sport = :${port}')`,
+        'The status URL comes from saved configuration; confirm that its PID matches the listener before restarting. If this is the intended old NTerminal instance, run:',
+        `  ${control} restart`,
+        'Restart uses the existing saved configuration and briefly disconnects clients. Tmux sessions survive; non-tmux terminals may end.',
+        'If another service owns the port, free it manually only if appropriate, or cancel and choose an unused port. Then select retry here; the port will be checked again without another main login.'
+    ];
+}
+async function askRegistrationRetry(p, transport) {
+    console.log(transport === 'direct'
+        ? 'Retry after resolving any local port/runtime issue, correcting the secondary HTTPS URL or opening its port in the host/cloud firewall, choose outbound (no inbound port), or cancel without saving configuration.'
+        : 'Retry registration or cancel without saving configuration.');
+    for (;;) {
+        const answer = (await p.ask(transport === 'direct' ? 'Next action (retry / outbound / cancel)' : 'Next action (retry / cancel)', 'retry')).trim().toLowerCase();
+        if (answer === 'retry' || answer === 'cancel' || (answer === 'outbound' && transport === 'direct'))
+            return answer;
+        console.log('Choose one of the listed actions.');
+    }
+}
+export async function registerWithMain(p, agent, options = {}) {
+    const result = { registered: false, mainUrl: null, agentId: null, tlsSupported: false, connectionVerified: false };
+    if (agent.transport === 'direct' && !agent.tlsCertificate?.trim()) {
+        console.log('Direct HTTPS requires a TLS identity before registration. Configuration was not saved.');
+        return result;
+    }
     let mainUrl = '';
-    let mainOrigin = '';
     for (;;) {
-        mainUrl = originOf(await askUrl(p, 'Main server URL (required, e.g. https://terminal.example.test)'));
-        mainOrigin = mainUrl;
-        if (agent.transport === 'outbound' && new URL(mainOrigin).protocol !== 'https:') {
-            console.log('Outbound mode requires an https:// main URL so agent tokens and tunneled traffic use encrypted WebSockets.');
-            continue;
-        }
+        mainUrl = originOf(await askUrl(p, 'Main server HTTPS URL (required, e.g. https://terminal.example.test)', options.mainUrl));
+        result.mainUrl = mainUrl;
         try {
-            const res = await fetch(`${mainUrl}/api/auth/session`, { signal: AbortSignal.timeout(8000) });
+            const res = await fetch(`${mainUrl}/api/auth/session`, { redirect: 'error', signal: AbortSignal.timeout(8000) });
+            if (!res.ok)
+                throw new Error(`Session check failed (${res.status})`);
             const status = (await res.json());
             if (!status.passwordSet) {
                 console.log('That main has no password set yet. Onboard the MAIN first, then re-run this on the secondary.');
-                return { registered: false, mainUrl, agentId: null };
+                return result;
             }
             break;
         }
@@ -1371,7 +1501,8 @@ async function registerWithMain(p, agent) {
         try {
             const res = await fetch(`${mainUrl}/api/auth/login`, {
                 method: 'POST',
-                headers: { 'content-type': 'application/json', origin: mainOrigin },
+                redirect: 'error',
+                headers: { 'content-type': 'application/json', origin: mainUrl },
                 body: JSON.stringify({ password, otp, rememberNetwork: false }),
                 signal: AbortSignal.timeout(8000)
             });
@@ -1381,56 +1512,129 @@ async function registerWithMain(p, agent) {
                 continue;
             }
             cookie = collectCookies(res.headers);
+            if (!cookie) {
+                console.log('Login failed (main returned no session cookie). Configuration was not saved.');
+                return result;
+            }
             break;
         }
         catch (error) {
             console.log(`Login error: ${errorText(error)}. Try again.`);
         }
     }
-    const payload = buildAgentRegisterPayload(agent.name, agent.selfUrl, agent.agentToken, agent.transport);
-    let registered = false;
-    let agentId = null;
+    let probe = null;
     try {
-        const regRes = await fetch(`${mainUrl}/api/agents`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', origin: mainOrigin, cookie },
-            body: JSON.stringify(payload),
-            signal: AbortSignal.timeout(8000)
-        });
-        if (regRes.status === 403) {
-            console.log(`Registration blocked by origin policy. Add "${mainOrigin}" to the main's NTERMINAL_ALLOWED_ORIGINS.`);
-        }
-        else if (!regRes.ok) {
-            const body = (await regRes.json().catch(() => ({})));
-            console.log(`Registration failed (${body.error ?? regRes.status}).`);
+        if (agent.transport === 'direct') {
+            try {
+                const capability = await fetch(`${mainUrl}/api/direct-tls/capabilities`, {
+                    headers: { origin: mainUrl, cookie }, redirect: 'error', signal: AbortSignal.timeout(8000)
+                });
+                const body = await capability.json().catch(() => null);
+                if (!capability.ok || body?.version !== 1) {
+                    console.log('This main does not advertise direct TLS support. Update the main before onboarding this secondary. Configuration was not saved.');
+                    return result;
+                }
+            }
+            catch (error) {
+                console.log(`Could not verify main direct TLS capabilities: ${errorText(error)}. Check connectivity and update the main before retrying. Configuration was not saved.`);
+                return result;
+            }
         }
-        else {
-            const body = (await regRes.json().catch(() => null));
-            if (typeof body?.agent?.id !== 'string' || !body.agent.id) {
-                console.log('Registration failed (main returned no agent identity).');
-                return { registered: false, mainUrl, agentId: null };
+        for (;;) {
+            let probePortOccupied = false;
+            let directProbeFailed = false;
+            try {
+                const payload = buildAgentRegisterPayload(agent.name, agent.selfUrl, agent.agentToken, agent.transport, agent.tlsCertificate);
+                if (agent.transport === 'direct' && options.probe && !probe) {
+                    probe = await startDirectTlsProbe({ certificate: agent.tlsCertificate, privateKey: options.probe.privateKey }, agent.agentToken, options.probe.host, options.probe.port);
+                    probePortOccupied = probe === null;
+                    console.log(probe ? 'Temporary HTTPS probe is listening for the main connection check.' : 'Agent port is already in use; the main will verify the existing server.');
+                }
+                const regRes = await fetch(`${mainUrl}/api/agents`, {
+                    method: 'POST',
+                    redirect: 'error',
+                    headers: { 'content-type': 'application/json', origin: mainUrl, cookie },
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(20000)
+                });
+                if (regRes.status === 403) {
+                    console.log(`Registration blocked by origin policy. Add "${mainUrl}" to the main's NTERMINAL_ALLOWED_ORIGINS.`);
+                }
+                else if (!regRes.ok) {
+                    const body = (await regRes.json().catch(() => ({})));
+                    if (regRes.status === 502 && body.error === 'tls_probe_failed') {
+                        directProbeFailed = true;
+                        console.log('The main could not verify the direct TLS connection. Check the secondary HTTPS URL and host/cloud firewall. Configuration was not saved.');
+                    }
+                    else {
+                        console.log(`Registration failed (${body.error ?? regRes.status}).`);
+                    }
+                }
+                else {
+                    const body = (await regRes.json().catch(() => null));
+                    if (agent.transport === 'direct' && body?.tlsSupported !== true) {
+                        console.log('The main did not acknowledge certificate pinning. Update the main before retrying; configuration was not saved.');
+                        return result;
+                    }
+                    if (typeof body?.agent?.id !== 'string' || !body.agent.id.trim()) {
+                        console.log('Registration failed (main returned no agent identity).');
+                    }
+                    else {
+                        result.agentId = body.agent.id;
+                        result.tlsSupported = agent.transport === 'direct' && body.tlsSupported === true;
+                        result.connectionVerified = agent.transport === 'direct' && body.connectionVerified === true;
+                        if (agent.transport === 'outbound' || result.connectionVerified) {
+                            result.registered = true;
+                            console.log(`Registered with main as "${payload.name}" (${agent.transport === 'direct' ? 'direct TLS connection verified' : 'outbound'}).`);
+                            return result;
+                        }
+                        directProbeFailed = true;
+                        console.log('The main did not verify the direct TLS connection. Configuration was not saved.');
+                    }
+                }
+            }
+            catch (error) {
+                console.log(`Registration error: ${errorText(error)}.`);
+            }
+            if (probePortOccupied && directProbeFailed && options.probe) {
+                // The control script's status URL is configuration, not proof of socket
+                // ownership. Keep restart operator-controlled rather than killing by port.
+                for (const line of directTlsPortRecoveryInstructions(options.probe.port))
+                    console.log(line);
+            }
+            const action = await askRegistrationRetry(p, agent.transport);
+            if (action === 'cancel')
+                return result;
+            if (action === 'outbound') {
+                agent.transport = 'outbound';
+                agent.selfUrl = null;
+            }
+            else if (agent.transport === 'direct') {
+                agent.selfUrl = await askUrl(p, 'HTTPS URL the main should use to reach this secondary', agent.selfUrl ?? undefined);
+                await options.retryNetwork?.();
             }
-            registered = true;
-            agentId = body.agent.id;
-            console.log(`Registered with main as "${payload.name}".`);
         }
     }
-    catch (error) {
-        console.log(`Registration error: ${errorText(error)}.`);
-    }
     finally {
         // Always clean up the CLI session + the trusted-device record it created on the main,
-        // even if registration threw.
-        await fetch(`${mainUrl}/api/auth/logout`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', origin: mainOrigin, cookie },
-            body: JSON.stringify({ closeTerminals: false }),
-            signal: AbortSignal.timeout(8000)
-        }).catch(() => undefined);
-    }
-    console.log('\nNote: this CLI creates a temporary main session for registration and removes it afterward.');
-    console.log('      Existing browser sessions and terminal/tmux sessions are left running.');
-    return { registered, mainUrl, agentId };
+        // and only our own probe, even if registration or a retry prompt threw.
+        let loggedOut = false;
+        try {
+            const logout = await fetch(`${mainUrl}/api/auth/logout`, {
+                method: 'POST',
+                redirect: 'error',
+                headers: { 'content-type': 'application/json', origin: mainUrl, cookie },
+                body: JSON.stringify({ closeTerminals: false }),
+                signal: AbortSignal.timeout(8000)
+            }).catch(() => undefined);
+            loggedOut = logout?.ok === true;
+        }
+        finally {
+            await probe?.close();
+        }
+        console.log(loggedOut ? '\nThe temporary CLI main session was closed.' : '\nCould not confirm logout of the temporary CLI main session.');
+        console.log('Existing browser and terminal/tmux sessions were left running.');
+    }
 }
 function collectCookies(headers) {
     // Node fetch exposes combined set-cookie via getSetCookie()
@@ -1467,7 +1671,7 @@ function printTopology() {
         '  ┌───────────┐',
         `  │   main    │${dim('   ← password + TOTP, fronts everything')}`,
         '  └─────┬─────┘',
-        dim('        │  agent token over LAN/VPN'),
+        dim('        │  pinned HTTPS / outbound WSS'),
         dim('        ▼'),
         '  ┌───────────┐',
         `  │ secondary │${dim('   ← additional shell hosts, registered with the main')}`,
@@ -1497,24 +1701,6 @@ async function chooseRole() {
         });
     });
 }
-async function chooseSecondaryTransport(p, existing) {
-    const current = existing === 'outbound' ? 'outbound' : 'direct';
-    if (process.stdin.isTTY) {
-        const color = shouldUseColor();
-        return pickFromList('Connect this secondary to the main using', [
-            {
-                label: `direct   ${colorText('— main connects to this server; best for stable reachable IPs/VPNs', '2', color)}`,
-                value: 'direct'
-            },
-            {
-                label: `outbound ${colorText('— this server connects to main; for NAT, mobile, or changing IPs', '2', color)}`,
-                value: 'outbound'
-            }
-        ], current === 'outbound' ? 1 : 0);
-    }
-    const answer = await p.ask('Connection mode (direct / outbound)', current);
-    return answer.trim().toLowerCase().startsWith('o') ? 'outbound' : 'direct';
-}
 async function main() {
     try {
         assertNodeRuntime();