handmux 0.23.0 → 0.25.0

package/dist/src/cli/supervisor.js

@@ -0,0 +1,278 @@
+// The single long-running supervisor. It owns the node server (and, for a process-backed tunnel like
+// cloudflare, the tunnel) as CHILD processes, restarts them with a small backoff on exit, and records
+// the live public URL into state.json. There is only ever one daemon here — cloudflared (and, later,
+// `tunlite run`) are just its children, exactly like the server is.
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { getDriver } from './drivers.js';
+import { writeState, clearState, claudeStatePath, pushStorePath, previewStorePath, notificationsDirPath } from './state.js';
+import { initialSupervisorComponentState, reduceSupervisorComponent, } from './supervisorState.js';
+import { probeServerReadiness } from './supervisorHealth.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SERVER = path.resolve(here, '../server.js');
+const require = createRequire(import.meta.url);
+const packageInfo = require('../../package.json');
+const VERSION = typeof packageInfo === 'object' && packageInfo !== null && 'version' in packageInfo
+    && typeof packageInfo.version === 'string' ? packageInfo.version : 'unknown';
+const defaultSpawnChild = (command, args, options) => spawn(command, [...args], options);
+const errorCode = (error) => {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return null;
+    return typeof error.code === 'string' ? error.code : null;
+};
+// First non-internal IPv4 — the address a phone on the same wifi uses when there's no tunnel.
+export function lanUrl(port, ifaces = os.networkInterfaces()) {
+    for (const list of Object.values(ifaces)) {
+        for (const ni of list || []) {
+            if (ni.family === 'IPv4' && !ni.internal)
+                return `http://${ni.address}:${port}`;
+        }
+    }
+    return null;
+}
+// The token rides in the query string so the first navigation (or a QR scan) authenticates in one shot.
+export function publicUrlWithToken(base, token) {
+    if (!base)
+        return base;
+    return `${base.replace(/\/$/, '')}/?token=${encodeURIComponent(token)}`;
+}
+// Bare address with no token in it — printed/QR-encoded so a link can be shared or screenshotted without
+// leaking the secret; the token is shown separately for the user to paste in.
+export function bareUrl(base) {
+    if (!base)
+        return base;
+    return `${base.replace(/\/$/, '')}/`;
+}
+export function browserPublicOriginEnv(cfg) {
+    return {
+        ...(cfg.previewDomain ? { HANDMUX_PREVIEW_DOMAIN: cfg.previewDomain } : {}),
+        ...(cfg.publicUrl ? { HANDMUX_PUBLIC_URL: cfg.publicUrl } : {}),
+    };
+}
+export function supervise(cfg, { home, log = console, spawnChild = defaultSpawnChild, probeServerReady = () => probeServerReadiness(cfg.port), setTimer = setTimeout, now = Date.now, processRef = process, }) {
+    const driver = getDriver(cfg.tunnel);
+    const children = {};
+    let stopping = false;
+    let urlBuf = '';
+    const components = {
+        server: initialSupervisorComponentState('server'),
+        tunnel: initialSupervisorComponentState('tunnel'),
+    };
+    const state = {
+        supervisorPid: processRef.pid,
+        version: VERSION,
+        startedAt: now(),
+        tunnel: cfg.tunnel,
+        port: cfg.port,
+        host: cfg.host,
+        token: cfg.token,
+        localUrl: `http://localhost:${cfg.port}`,
+        lanUrl: lanUrl(cfg.port),
+        publicUrl: null,
+        ready: false,
+        serverPid: null,
+        tunnelPid: null,
+        components,
+        error: null,
+    };
+    const persist = () => {
+        // Keep the legacy top-level fields during migration, but derive them from the explicit component
+        // machines so `ready` can never outlive the Server process that earned it.
+        state.serverPid = components.server.pid;
+        state.tunnelPid = components.tunnel.pid;
+        state.ready = components.server.phase === 'ready';
+        writeState(state, home);
+    };
+    const transition = (name, event) => {
+        components[name] = reduceSupervisorComponent(components[name], event);
+        persist();
+    };
+    persist();
+    // Readiness belongs to the Server generation that answered the structured health probe. A bare TCP
+    // listener could be an old process or a half-initialized API with Workspace/Browser already degraded.
+    const waitReady = (serverChild) => {
+        if (stopping || children.server !== serverChild || components.server.phase === 'ready')
+            return;
+        const retry = () => {
+            if (!stopping && children.server === serverChild) {
+                setTimer(() => waitReady(serverChild), 200);
+            }
+        };
+        Promise.resolve(probeServerReady()).then((ready) => {
+            if (!ready) {
+                retry();
+                return;
+            }
+            if (!stopping && children.server === serverChild) {
+                transition('server', { type: 'ready', at: now() });
+            }
+        }, retry);
+    };
+    const startServer = () => {
+        // The server reads only process.env (no .env files) — the CLI resolved the one config file and we
+        // hand the server everything it needs here. This is the single injection point: config.json fields →
+        // the env names the server already reads (HANDMUX_* / VAPID_* / XFYUN_*).
+        const env = {
+            ...processRef.env,
+            NODE_ENV: 'handmux',
+            HANDMUX_PORT: String(cfg.port),
+            HANDMUX_HOST: cfg.host,
+            HANDMUX_TOKEN: cfg.token,
+            CLAUDE_STATE_FILE: claudeStatePath(home),
+            PUSH_STORE: pushStorePath(home),
+            PREVIEW_STORE: previewStorePath(home),
+            NOTIF_DIR: notificationsDirPath(home),
+            ...browserPublicOriginEnv(cfg),
+        };
+        if (cfg.name)
+            env.HANDMUX_APP_NAME = cfg.name;
+        if (cfg.staticDir)
+            env.HANDMUX_STATIC_DIR = cfg.staticDir;
+        if (cfg.uploadExts)
+            env.HANDMUX_UPLOAD_EXTS = cfg.uploadExts;
+        env.HANDMUX_SHORTCUTS = JSON.stringify(cfg.shortcuts);
+        if (cfg.vapid) {
+            if (cfg.vapid.public)
+                env.VAPID_PUBLIC = cfg.vapid.public;
+            if (cfg.vapid.private)
+                env.VAPID_PRIVATE = cfg.vapid.private;
+            if (cfg.vapid.subject)
+                env.VAPID_SUBJECT = cfg.vapid.subject;
+        }
+        if (cfg.xfyun) {
+            if (cfg.xfyun.appId)
+                env.XFYUN_APPID = cfg.xfyun.appId;
+            if (cfg.xfyun.apiKey)
+                env.XFYUN_APIKEY = cfg.xfyun.apiKey;
+            if (cfg.xfyun.apiSecret)
+                env.XFYUN_APISECRET = cfg.xfyun.apiSecret;
+        }
+        const c = spawnChild(processRef.execPath, [SERVER], { env, stdio: ['ignore', 'inherit', 'inherit'] });
+        children.server = c;
+        transition('server', { type: 'spawned', pid: c.pid ?? null, at: now() });
+        waitReady(c);
+        let finalized = false;
+        const finalize = (error = null) => {
+            if (finalized || children.server !== c)
+                return;
+            finalized = true;
+            delete children.server;
+            if (stopping) {
+                components.server = reduceSupervisorComponent(components.server, { type: 'stopped', at: now() });
+                return;
+            }
+            transition('server', { type: 'exited', at: now(), error });
+            backoffRestart('server', startServer);
+        };
+        c.once('error', (error) => finalize(String(error)));
+        c.once('exit', (code, signal) => finalize(code || signal ? `exit ${code ?? signal}` : null));
+    };
+    const startTunnel = () => {
+        if (!driver.needsProcess) { // 'none' — reachable directly on LAN/localhost (or a tunnel you run yourself)
+            state.publicUrl = cfg.publicUrl || state.lanUrl || state.localUrl;
+            transition('tunnel', { type: 'spawned', pid: null, at: now() });
+            transition('tunnel', { type: 'ready', at: now() });
+            return;
+        }
+        urlBuf = '';
+        const spec = driver.proc(cfg);
+        if (!spec)
+            throw new Error(`tunnel driver ${driver.name} did not provide a process`);
+        const c = spawnChild(spec.cmd, spec.args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        children.tunnel = c;
+        transition('tunnel', { type: 'spawned', pid: c.pid ?? null, at: now() });
+        const onData = (chunk) => {
+            const s = String(chunk);
+            processRef.stdout.write(s);
+            if (state.publicUrl)
+                return;
+            urlBuf = (urlBuf + s).slice(-4000);
+            const url = driver.matchUrl(urlBuf, cfg);
+            if (url) {
+                state.publicUrl = url;
+                state.error = null;
+                transition('tunnel', { type: 'ready', at: now() });
+            }
+        };
+        c.stdout.on('data', onData);
+        c.stderr.on('data', onData);
+        let finalized = false;
+        const finalize = (error = null) => {
+            if (finalized || children.tunnel !== c)
+                return;
+            finalized = true;
+            delete children.tunnel;
+            state.publicUrl = null;
+            if (stopping) {
+                components.tunnel = reduceSupervisorComponent(components.tunnel, { type: 'stopped', at: now() });
+                return;
+            }
+            transition('tunnel', { type: 'exited', at: now(), error });
+            backoffRestart('tunnel', startTunnel);
+        };
+        c.once('error', (e) => {
+            const message = errorCode(e) === 'ENOENT'
+                ? (driver.notFoundHint || `${spec.cmd} not found`)
+                : String(e);
+            state.error = message;
+            finalize(message);
+        });
+        c.once('exit', (code, signal) => finalize(code || signal ? `exit ${code ?? signal}` : null));
+    };
+    const backoffRestart = (what, fn) => {
+        const d = Math.max(0, (components[what].restartAt ?? now()) - now());
+        log.warn?.(`[handmux] ${what} exited; restarting in ${d}ms`);
+        setTimer(() => { if (!stopping)
+            fn(); }, d);
+    };
+    const shutdown = () => {
+        stopping = true;
+        const kids = Object.values(children).filter(Boolean);
+        for (const c of kids) {
+            try {
+                c.kill('SIGTERM');
+            }
+            catch { /* already dead */ }
+        }
+        clearState(home);
+        // Don't exit on a fixed timer — that orphans any child still shutting down (a SIGKILL'd or crashed
+        // supervisor was how a stray cloudflared kept running after `stop`). Poll until the children are gone,
+        // then SIGKILL any straggler so we NEVER leak a tunnel process. With --grace-period 0s, cloudflared
+        // exits near-instantly; the 3s ceiling is just a backstop.
+        const alive = () => kids.filter((child) => {
+            if (child.pid == null)
+                return false;
+            try {
+                processRef.kill(child.pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        let waited = 0;
+        const tick = () => {
+            const left = alive();
+            if (left.length === 0 || waited >= 3000) {
+                for (const c of left) {
+                    try {
+                        c.kill('SIGKILL');
+                    }
+                    catch { /* already dead */ }
+                }
+                processRef.exit(0);
+            }
+            waited += 150;
+            setTimer(tick, 150);
+        };
+        tick();
+    };
+    processRef.on('SIGTERM', shutdown);
+    processRef.on('SIGINT', shutdown);
+    startServer();
+    startTunnel();
+    return { state };
+}

package/dist/src/cli/supervisorHealth.js

@@ -0,0 +1,21 @@
+import { parseHealthReadySnapshot } from '../healthProtocol.js';
+export async function probeServerReadiness(port, { fetchImpl = fetch, timeoutMs = 500 } = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(`http://127.0.0.1:${port}/health/ready`, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return false;
+        return parseHealthReadySnapshot(await response.json())?.ready === true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/cli/supervisorLaunch.js

@@ -0,0 +1,148 @@
+import path from 'node:path';
+import { readSupervisorConfig, supervisorConfigPath, writeSupervisorConfig, } from './state.js';
+import { TUNNELS } from './options.js';
+import { normalizeShortcuts } from '../shortcutConfig.js';
+const recordOf = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value : null;
+const isTunnel = (value) => typeof value === 'string' && TUNNELS.some((candidate) => candidate === value);
+const optionalString = (value, key) => {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value !== 'string')
+        throw new Error(`invalid supervisor config: ${key} must be text`);
+    return value;
+};
+const optionalNumber = (value, key) => {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 65535) {
+        throw new Error(`invalid supervisor config: ${key} must be an integer from 1 to 65535`);
+    }
+    return value;
+};
+const stringFields = (value, keys, key) => {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const record = recordOf(value);
+    if (!record)
+        throw new Error(`invalid supervisor config: ${key} must be an object`);
+    const result = {};
+    for (const field of keys) {
+        const item = record[field];
+        if (item !== undefined) {
+            if (typeof item !== 'string')
+                throw new Error(`invalid supervisor config: ${key}.${field} must be text`);
+            result[field] = item;
+        }
+    }
+    return result;
+};
+// The persisted file and the legacy base64 argv are untrusted process boundaries. Parse them before the
+// supervisor starts so malformed or stale data fails as one explicit configuration error instead of being
+// used as partially-typed process arguments.
+export function parseSupervisorConfig(value) {
+    const record = recordOf(value);
+    if (!record)
+        throw new Error('invalid supervisor config: expected an object');
+    const tunnel = record.tunnel;
+    if (!isTunnel(tunnel)) {
+        throw new Error('invalid supervisor config: unknown tunnel');
+    }
+    const port = record.port;
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error('invalid supervisor config: port must be an integer from 1 to 65535');
+    }
+    if (typeof record.host !== 'string' || !record.host) {
+        throw new Error('invalid supervisor config: host is required');
+    }
+    if (typeof record.token !== 'string' || !record.token) {
+        throw new Error('invalid supervisor config: token is required');
+    }
+    const config = {
+        tunnel,
+        port,
+        host: record.host,
+        token: record.token,
+        shortcuts: normalizeShortcuts(record.shortcuts),
+    };
+    const name = optionalString(record.name, 'name');
+    const staticDir = optionalString(record.staticDir, 'staticDir');
+    const uploadExts = optionalString(record.uploadExts, 'uploadExts');
+    const previewDomain = optionalString(record.previewDomain, 'previewDomain');
+    const publicUrl = optionalString(record.publicUrl, 'publicUrl');
+    const cloudflaredBin = optionalString(record.cloudflaredBin, 'cloudflaredBin');
+    const cfTunnelName = optionalString(record.cfTunnelName, 'cfTunnelName');
+    const tunliteBin = optionalString(record.tunliteBin, 'tunliteBin');
+    const sshHost = optionalString(record.sshHost, 'sshHost');
+    const remotePort = optionalNumber(record.remotePort, 'remotePort');
+    const sshJump = optionalString(record.sshJump, 'sshJump');
+    const natappBin = optionalString(record.natappBin, 'natappBin');
+    const authtoken = optionalString(record.authtoken, 'authtoken');
+    const cpolarBin = optionalString(record.cpolarBin, 'cpolarBin');
+    const cpolarRegion = optionalString(record.cpolarRegion, 'cpolarRegion');
+    const vapid = stringFields(record.vapid, ['public', 'private', 'subject'], 'vapid');
+    const xfyun = stringFields(record.xfyun, ['appId', 'apiKey', 'apiSecret'], 'xfyun');
+    if (name !== undefined)
+        config.name = name;
+    if (staticDir !== undefined)
+        config.staticDir = staticDir;
+    if (uploadExts !== undefined)
+        config.uploadExts = uploadExts;
+    if (previewDomain !== undefined)
+        config.previewDomain = previewDomain;
+    if (publicUrl !== undefined)
+        config.publicUrl = publicUrl;
+    if (typeof cloudflaredBin === 'string')
+        config.cloudflaredBin = cloudflaredBin;
+    if (cfTunnelName !== undefined)
+        config.cfTunnelName = cfTunnelName;
+    if (typeof tunliteBin === 'string')
+        config.tunliteBin = tunliteBin;
+    if (sshHost !== undefined)
+        config.sshHost = sshHost;
+    if (remotePort !== undefined)
+        config.remotePort = remotePort;
+    if (sshJump !== undefined)
+        config.sshJump = sshJump;
+    if (typeof natappBin === 'string')
+        config.natappBin = natappBin;
+    if (authtoken !== undefined)
+        config.authtoken = authtoken;
+    if (typeof cpolarBin === 'string')
+        config.cpolarBin = cpolarBin;
+    if (cpolarRegion !== undefined)
+        config.cpolarRegion = cpolarRegion;
+    if (vapid !== undefined)
+        config.vapid = vapid;
+    if (xfyun !== undefined)
+        config.xfyun = xfyun;
+    return config;
+}
+export function supervisorLaunchArgs(config, { home, entry, executable = process.execPath }) {
+    writeSupervisorConfig(config, home);
+    return [executable, entry, '__supervise', '--payload-file', supervisorConfigPath(home)];
+}
+export function readSupervisorLaunchConfig({ payloadFile, legacyPayload }, home) {
+    if (payloadFile != null) {
+        const expected = path.resolve(supervisorConfigPath(home));
+        if (typeof payloadFile !== 'string' || path.resolve(payloadFile) !== expected) {
+            throw new Error('invalid supervisor config path');
+        }
+        const config = readSupervisorConfig(home);
+        if (!config)
+            throw new Error('supervisor config is missing or invalid');
+        return config;
+    }
+    if (typeof legacyPayload === 'string') {
+        // A still-loaded pre-migration service may invoke the upgraded CLI once with its old argv. The next
+        // start/service install rewrites the definition to the private config-file contract.
+        return JSON.parse(Buffer.from(legacyPayload, 'base64').toString('utf8'));
+    }
+    throw new Error('supervisor config is missing');
+}

package/dist/src/cli/supervisorProcesses.js

@@ -0,0 +1,62 @@
+// Process-table backstop for the single-instance invariant. state.json is deliberately only one record,
+// so an older restart race can leave a live supervisor that is no longer referenced there. Scan the real
+// argv instead: every packaged/manual/service supervisor has this stable signature across install paths.
+import { spawnSync } from 'node:child_process';
+export function parseSupervisorPids(psOut) {
+    const pids = [];
+    for (const line of String(psOut).split('\n')) {
+        const m = line.match(/^\s*(\d+)\s+(\S+)\s+(.*)$/);
+        const pidText = m?.[1];
+        const state = m?.[2];
+        const args = m?.[3];
+        if (!pidText || !state || !args || state[0] === 'Z')
+            continue;
+        // Anchor the executable as Node and handmux.js as its direct script argument. A shell command or test
+        // runner can contain the same words in its own command text; it is not a supervisor and must not match.
+        if (/^(?:\S*\/)?node(?:js)?\s+(?:"[^"]*(?:handmux\.js|\/handmux)"|'[^']*(?:handmux\.js|\/handmux)'|\S*(?:handmux\.js|\/handmux))\s+__supervise\s+--payload(?:-file)?(?:\s|$)/.test(args)) {
+            pids.push(Number(pidText));
+        }
+    }
+    return [...new Set(pids)].sort((a, b) => a - b);
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Terminate an initial snapshot and keep rescanning: a duplicate that was not in state.json, or one that
+// appears during cleanup, is folded into `seen` and signalled too. Pure dependencies make the race/timeout
+// behavior unit-testable without touching real processes.
+export async function terminateSupervisorPids(initialPids, { scan = scanSupervisorPids, kill = (pid) => process.kill(pid, 'SIGTERM'), waitFn = wait, now = Date.now, timeoutMs = 4500, } = {}) {
+    const seen = new Set(initialPids);
+    const signal = (pid) => { try {
+        kill(pid);
+    }
+    catch { /* raced away / not ours */ } };
+    for (const pid of seen)
+        signal(pid);
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const current = scan();
+        if (!current.ok)
+            return { ok: false, reason: 'scan', pids: [...seen], remaining: [] };
+        if (!current.pids.length)
+            return { ok: true, pids: [...seen].sort((a, b) => a - b), remaining: [] };
+        for (const pid of current.pids) {
+            seen.add(pid);
+            signal(pid);
+        }
+        if (now() >= deadline) {
+            return { ok: false, reason: 'timeout', pids: [...seen].sort((a, b) => a - b), remaining: current.pids };
+        }
+        await waitFn(100);
+    }
+}
+export function scanSupervisorPids({ run = spawnSync } = {}) {
+    try {
+        // `-x` includes this user's detached/no-TTY daemons without crossing into other users' processes.
+        const r = run('ps', ['-x', '-o', 'pid=,stat=,args='], { encoding: 'utf8' });
+        if (!r || r.status !== 0)
+            return { ok: false, pids: [] };
+        return { ok: true, pids: parseSupervisorPids(r.stdout) };
+    }
+    catch {
+        return { ok: false, pids: [] };
+    }
+}

package/dist/src/cli/supervisorState.js

@@ -0,0 +1,62 @@
+export function supervisorRestartDelay(restartAttempt, { baseMs = 500, maxMs = 15_000 } = {}) {
+    if (!Number.isSafeInteger(restartAttempt) || restartAttempt <= 0)
+        return 0;
+    return Math.min(baseMs * (2 ** Math.min(restartAttempt - 1, 30)), maxMs);
+}
+export function initialSupervisorComponentState(name) {
+    return {
+        name,
+        phase: 'stopped',
+        pid: null,
+        restartAttempt: 0,
+        restartAt: null,
+        startedAt: null,
+        readyAt: null,
+        lastExitAt: null,
+        error: null,
+    };
+}
+export function reduceSupervisorComponent(state, event, backoff) {
+    if (event.type === 'spawned') {
+        return {
+            ...state,
+            phase: 'starting',
+            pid: event.pid,
+            restartAt: null,
+            startedAt: event.at,
+            readyAt: null,
+            error: null,
+        };
+    }
+    if (event.type === 'ready') {
+        return {
+            ...state,
+            phase: 'ready',
+            restartAttempt: 0,
+            restartAt: null,
+            readyAt: event.at,
+            error: null,
+        };
+    }
+    if (event.type === 'exited') {
+        const restartAttempt = state.restartAttempt + 1;
+        return {
+            ...state,
+            phase: 'backoff',
+            pid: null,
+            restartAttempt,
+            restartAt: event.at + supervisorRestartDelay(restartAttempt, backoff),
+            readyAt: null,
+            lastExitAt: event.at,
+            error: event.error ?? null,
+        };
+    }
+    return {
+        ...state,
+        phase: 'stopped',
+        pid: null,
+        restartAt: null,
+        readyAt: null,
+        error: null,
+    };
+}

package/dist/src/cli/tmuxVersion.js

@@ -0,0 +1,53 @@
+// handmux's terminal rendering depends on `capture-pane -e -N` semantics, and those have drifted
+// across tmux versions before (e.g. how -N pads trailing whitespace). So we check the host's tmux at
+// start: absent → hard error; below the version we've validated → warn (don't block). exec injectable.
+import { spawnSync } from 'node:child_process';
+// Lowest tmux handmux has been validated against. Bump as the CI matrix (see release plan) widens.
+export const MIN_TMUX = '3.0';
+// "tmux 3.6a" / "tmux 3.4" / "tmux next-3.5" / "tmux openbsd-7.4" → {major,minor,suffix,raw}.
+export function parseTmuxVersion(out) {
+    const m = /tmux\s+(?:next-|openbsd-)?(\d+)\.(\d+)([a-z]?)/i.exec(String(out || ''));
+    if (!m)
+        return null;
+    const major = Number(m[1] ?? 0);
+    const minor = Number(m[2] ?? 0);
+    const suffix = m[3] || '';
+    return { major, minor, suffix, raw: `${major}.${minor}${suffix}` };
+}
+// v >= min, comparing major.minor only (patch letters don't change the capture behaviour we rely on).
+export function versionAtLeast(v, minStr = MIN_TMUX) {
+    if (!v)
+        return false;
+    const [maj = 0, min = 0] = minStr.split('.').map(Number);
+    return v.major > maj || (v.major === maj && v.minor >= min);
+}
+export function checkTmux(exec = spawnSync) {
+    const r = exec('tmux', ['-V'], { encoding: 'utf8' });
+    if (!r || r.status !== 0 || !r.stdout)
+        return { present: false };
+    const version = parseTmuxVersion(r.stdout);
+    return { present: true, version, ok: versionAtLeast(version), raw: version ? version.raw : String(r.stdout).trim() };
+}
+// In install-command order: probe for the package manager that's actually on this Linux box.
+const LINUX_PKG_MANAGERS = [
+    ['apt-get', 'sudo apt install tmux'],
+    ['dnf', 'sudo dnf install tmux'],
+    ['pacman', 'sudo pacman -S tmux'],
+    ['zypper', 'sudo zypper install tmux'],
+    ['apk', 'sudo apk add tmux'],
+    ['yum', 'sudo yum install tmux'],
+];
+// The exact "install tmux" command for THIS host, so a tmux-less newcomer gets a copy-paste line instead
+// of a dead end. macOS → Homebrew; Linux → whichever package manager is present; Windows → tmux is a
+// Unix tool, so point at WSL. exec/platform injectable for tests.
+export function tmuxInstallHint(exec = spawnSync, platform = process.platform) {
+    if (platform === 'darwin')
+        return 'brew install tmux';
+    if (platform === 'win32')
+        return 'tmux is a Unix tool — install WSL (`wsl --install`), then inside it: sudo apt install tmux';
+    const has = (bin) => exec('which', [bin], { encoding: 'utf8' }).status === 0;
+    for (const [bin, cmd] of LINUX_PKG_MANAGERS)
+        if (has(bin))
+            return cmd;
+    return 'install tmux with your package manager (e.g. `sudo apt install tmux`)';
+}

package/{src → dist/src}/cli/tunlite.js

@@ -5,18 +5,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLED = path.resolve(here, '../../node_modules/.bin/tunlite');
-
-export function resolveTunlite({ run = spawnSync, exists = fs.existsSync, bundled = BUNDLED } = {}) {
-  const candidate = exists(bundled) ? bundled : 'tunlite';
-  const r = run(candidate, ['--version'], { encoding: 'utf8' });
-  if (r && r.status === 0) return candidate;
-  throw new Error('tunlite not found — install it (npm i -g tunlite / npx tunlite install)');
+export function resolveTunlite({ run = spawnSync, exists = fs.existsSync, bundled = BUNDLED, } = {}) {
+    const candidate = exists(bundled) ? bundled : 'tunlite';
+    const r = run(candidate, ['--version'], { encoding: 'utf8' });
+    if (r && r.status === 0)
+        return candidate;
+    throw new Error('tunlite not found — install it (npm i -g tunlite / npx tunlite install)');
 }
-
-// 0 = passwordless SSH ready; non-zero (tunlite exit 4 = needs-auth) means key setup required.
 export function checkSshAuth(sshHost, { run = spawnSync, bin = 'tunlite' } = {}) {
-  return run(bin, ['check', sshHost], { stdio: 'ignore' }).status;
+    return run(bin, ['check', sshHost], { stdio: 'ignore' }).status;
 }