clauderipple 0.9.5 → 0.11.0

package/dist/router/src/remote-host.js

@@ -0,0 +1,320 @@
+// A remote (SSH) host that runs Claude Code for a Claude Desktop session (issue #67).
+//
+// Desktop's Code tab can run a session on a Linux host over SSH. Claude Code then runs *there*,
+// reads that host's `~/.claude/settings.json`, and has no route to this router: 127.0.0.1 on the
+// remote is the remote. Desktop opens its SSH connection with the bundled ssh2 library, which only
+// forwards local→remote and never reads `RemoteForward` from ~/.ssh/config, so the router holds its
+// own reverse tunnel (remote-tunnel.ts) and this module puts on the remote what a session there
+// needs: the CA certificate, the env that points Claude Code at the tunnel, and the worker agent
+// files. See docs/ARCHITECTURE.md "Remote (SSH) sessions".
+//
+// Everything on the remote is done by POSIX `sh` scripts fed to `ssh <host> sh -s` on stdin. No
+// node or python there, no quoting of a command line through whatever login shell the remote user
+// has, and the host name only ever travels as its own argv element — never through a local shell.
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/** The remote port the tunnel listens on (remote 127.0.0.1) unless `--port` says otherwise. */
+export const DEFAULT_REMOTE_PORT = 18791;
+/** Our directory under the remote home: the CA copy and the record of what we put there. */
+export const REMOTE_DIR = ".clauderipple-remote";
+/** The remote settings.json is copied here once, before the first time we change it. */
+export const SETTINGS_BACKUP_SUFFIX = ".clauderipple-backup";
+/**
+ * Why `host` cannot be handed to ssh, or null when it can. An ssh alias or `user@host`, nothing
+ * else: a leading `-` would be read as an option (`-oProxyCommand=…` runs a command), and anything
+ * outside a hostname's characters has no business in one.
+ */
+export function hostProblem(host) {
+    if (typeof host !== "string" || host === "")
+        return "an ssh host is required (an ssh alias or user@host)";
+    if (host.length > 255)
+        return "the ssh host is longer than 255 characters";
+    if (host.startsWith("-"))
+        return `"${host}" starts with "-", which ssh would read as an option`;
+    if (!/^[A-Za-z0-9_.@:-]+$/.test(host))
+        return `"${host}" is not an ssh alias or user@host (letters, digits and . _ @ : - only)`;
+    return null;
+}
+export function portProblem(port) {
+    return Number.isInteger(port) && port > 0 && port < 65536 ? null : `port must be an integer from 1 to 65535`;
+}
+/** The OpenSSH client: Windows ships it as an optional feature in System32\OpenSSH. */
+export function sshExecutable() {
+    if (process.platform !== "win32")
+        return "ssh";
+    const builtIn = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "OpenSSH", "ssh.exe");
+    return fs.existsSync(builtIn) ? builtIn : "ssh.exe";
+}
+/**
+ * Extra ssh arguments from `CLAUDERIPPLE_SSH_OPTIONS` (a JSON array of strings), placed before the
+ * host. Exists for the end-to-end test, which points ssh at a throwaway sshd with its own key and
+ * known_hosts instead of the user's ssh setup; nothing in the product sets it.
+ */
+export function extraSshOptions() {
+    const raw = process.env.CLAUDERIPPLE_SSH_OPTIONS;
+    if (!raw)
+        return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || parsed.some((a) => typeof a !== "string"))
+        throw new Error("CLAUDERIPPLE_SSH_OPTIONS must be a JSON array of strings");
+    return parsed;
+}
+/** Never ask: a prompt nobody can answer would hang the router or the CLI. */
+export const BATCH_OPTIONS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10"];
+export const SSH_MISSING = "ssh was not found. Install the OpenSSH client (on Windows: Settings → System → Optional features → OpenSSH Client).";
+export const spawnSsh = (args, opts = {}) => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const done = (r) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(r);
+    };
+    const child = spawn(sshExecutable(), args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        done({ code: null, stdout, stderr, error: `ssh timed out after ${Math.round((opts.timeoutMs ?? 60_000) / 1000)}s` });
+    }, opts.timeoutMs ?? 60_000);
+    child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+    child.stdin.on("error", () => { }); // ssh gone before reading its input: the exit says why
+    child.on("error", (e) => done({ code: null, stdout, stderr, error: e.code === "ENOENT" ? SSH_MISSING : e.message }));
+    child.on("close", (code) => done({ code, stdout, stderr }));
+    child.stdin.end(opts.input ?? "");
+});
+/** The last non-empty line ssh printed, which is where it says what went wrong. */
+function lastLine(text) {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).pop() ?? "";
+}
+/** Run a POSIX sh script on `host` and return its stdout. Throws with ssh's own words on failure. */
+export async function runRemoteScript(run, host, script, timeoutMs = 60_000) {
+    const problem = hostProblem(host);
+    if (problem)
+        throw new Error(problem);
+    const r = await run([...BATCH_OPTIONS, ...extraSshOptions(), host, "sh", "-s"], { input: script, timeoutMs });
+    if (r.error)
+        throw new Error(r.error);
+    if (r.code === 255)
+        throw new SshConnectError(host, lastLine(r.stderr) || "ssh exited with 255");
+    if (r.code !== 0)
+        throw new Error(`script on ${host} failed (exit ${r.code}): ${lastLine(r.stderr) || "no message"}`);
+    return r.stdout;
+}
+/** ssh itself could not connect or authenticate (exit 255), as opposed to our script failing. */
+export class SshConnectError extends Error {
+    host;
+    detail;
+    constructor(host, detail) {
+        super(`cannot reach ${host} over ssh: ${detail}`);
+        this.host = host;
+        this.detail = detail;
+    }
+}
+const AGENT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+export function remoteCaPath(home) {
+    return `${home}/${REMOTE_DIR}/ca.pem`;
+}
+export function remoteProxyUrl(port) {
+    return `http://127.0.0.1:${port}`;
+}
+export async function inspectRemote(run, host) {
+    const m = `@@cr-${crypto.randomBytes(6).toString("hex")}`;
+    const script = [
+        `m='${m}'`,
+        `f="$HOME/.claude/settings.json"`,
+        `printf '%s home\\n' "$m"; printf '%s\\n' "$HOME"`,
+        `printf '%s settings\\n' "$m"`,
+        `if [ -e "$f" ]; then printf 'present\\n'; cat "$f" || exit 1; printf '\\n'; else printf 'missing\\n'; fi`,
+        `printf '%s sum\\n' "$m"`,
+        `if [ -e "$f" ]; then cksum < "$f" || exit 1; fi`,
+        `printf '%s backup\\n' "$m"`,
+        `if [ -e "$f${SETTINGS_BACKUP_SUFFIX}" ]; then printf 'yes\\n'; else printf 'no\\n'; fi`,
+        `printf '%s record\\n' "$m"`,
+        `if [ -e "$HOME/${REMOTE_DIR}/agents.json" ]; then cat "$HOME/${REMOTE_DIR}/agents.json"; printf '\\n'; fi`,
+        `printf '%s agents\\n' "$m"`,
+        `for x in "$HOME/.claude/agents"/*.md; do if [ -e "$x" ]; then basename "$x" .md; fi; done`,
+        `printf '%s end\\n' "$m"`,
+        `exit 0`,
+        "",
+    ].join("\n");
+    const out = await runRemoteScript(run, host, script);
+    const sections = new Map();
+    let current = null;
+    for (const line of out.split("\n")) {
+        if (line.startsWith(`${m} `)) {
+            current = [];
+            sections.set(line.slice(m.length + 1).trim(), current);
+        }
+        else
+            current?.push(line);
+    }
+    if (!sections.has("end"))
+        throw new Error(`unexpected answer from ${host} (is its shell POSIX sh?)`);
+    const text = (name) => (sections.get(name) ?? []).join("\n");
+    const home = text("home").trim();
+    if (!home.startsWith("/"))
+        throw new Error(`${host} reported HOME="${home}"; a remote host must be Linux or another POSIX system`);
+    const settingsLines = sections.get("settings") ?? [];
+    const present = settingsLines[0] === "present";
+    let record = null;
+    const recordText = text("record").trim();
+    if (recordText) {
+        try {
+            const parsed = JSON.parse(recordText);
+            record = {
+                agents: Array.isArray(parsed.agents) ? parsed.agents.filter((a) => typeof a === "string" && AGENT_NAME.test(a)) : [],
+                ...(typeof parsed.proxyUrl === "string" ? { proxyUrl: parsed.proxyUrl } : {}),
+                ...(typeof parsed.caPath === "string" ? { caPath: parsed.caPath } : {}),
+            };
+        }
+        catch {
+            record = { agents: [] }; // ours but unreadable: nothing in it can be trusted as a delete list
+        }
+    }
+    return {
+        home,
+        settings: present ? settingsLines.slice(1).join("\n") : null,
+        settingsSum: present ? text("sum").trim() || null : null,
+        backup: text("backup").trim() === "yes",
+        record,
+        agentFiles: text("agents").split("\n").map((l) => l.trim()).filter(Boolean),
+    };
+}
+// ---- Writing to the remote ----------------------------------------------------------------
+/** `"$HOME/<rel>"` for a path we built ourselves; refuses anything a shell could read differently. */
+function homePath(rel) {
+    if (!/^[A-Za-z0-9._/-]+$/.test(rel) || rel.split("/").includes(".."))
+        throw new Error(`refusing remote path "${rel}"`);
+    return `"$HOME/${rel}"`;
+}
+/**
+ * Lines that replace `$HOME/<rel>` with `content`: a quoted heredoc into a temp file, then `mv`, so
+ * a reader sees the old file or the new one. A quoted delimiter means the shell expands nothing in
+ * the body. A heredoc always ends in a newline, so content without one gains one.
+ */
+export function writeFileLines(rel, content) {
+    const body = content.endsWith("\n") ? content.slice(0, -1) : content;
+    let delim = "";
+    do
+        delim = `CLAUDERIPPLE_EOF_${crypto.randomBytes(8).toString("hex")}`;
+    while (body.split("\n").includes(delim));
+    const target = homePath(rel);
+    const tmp = homePath(`${rel}.clauderipple-tmp`);
+    return [`cat > ${tmp} <<'${delim}' || exit 1`, body, delim, `mv -f ${tmp} ${target} || exit 1`];
+}
+/**
+ * Stops the script (exit 3) when the remote settings.json is no longer the file `state` read. Put
+ * first in a script that will write it, so a refusal leaves nothing half done.
+ */
+export function settingsGuardLine(state) {
+    const f = `"$HOME/.claude/settings.json"`;
+    return state.settingsSum === null
+        ? `if [ -e ${f} ]; then echo "~/.claude/settings.json appeared while it was being edited; run the command again" >&2; exit 3; fi`
+        : `if [ "$(cksum < ${f})" != '${state.settingsSum.replace(/'/g, "")}' ]; then echo "~/.claude/settings.json changed while it was being edited; run the command again" >&2; exit 3; fi`;
+}
+/**
+ * Lines that write the remote settings.json, but only if it is still the file `state` read: a
+ * session or the user may have changed it in between, and that change must not be overwritten.
+ * The first time we change it, the original is copied to `settings.json.clauderipple-backup`.
+ */
+export function settingsWriteLines(state, content) {
+    const f = `"$HOME/.claude/settings.json"`;
+    return [
+        `mkdir -p "$HOME/.claude" || exit 1`,
+        settingsGuardLine(state),
+        `if [ -e ${f} ] && [ ! -e "$HOME/.claude/settings.json${SETTINGS_BACKUP_SUFFIX}" ]; then cp -p ${f} "$HOME/.claude/settings.json${SETTINGS_BACKUP_SUFFIX}" || exit 1; fi`,
+        ...writeFileLines(".claude/settings.json", content),
+    ];
+}
+/**
+ * The router's CA certificate — the file the local install points NODE_EXTRA_CA_CERTS at,
+ * `<home>/ca.pem` (cli/src/settings.ts via certPaths) — and the agent files this router generated,
+ * as `<home>/generated-agents.json` lists them (agents.ts). Only the public certificate: the file
+ * is checked to be one, so a key can never travel by mistake.
+ */
+export function readLocalAssets(opts) {
+    const caFile = path.join(opts.home, "ca.pem");
+    let caPem;
+    try {
+        caPem = fs.readFileSync(caFile, "utf8");
+    }
+    catch {
+        throw new Error(`no CA certificate at ${caFile}; run \`clauderipple install\` first`);
+    }
+    if (!caPem.includes("-----BEGIN CERTIFICATE-----") || /PRIVATE KEY/.test(caPem))
+        throw new Error(`${caFile} is not a certificate; refusing to copy it`);
+    let names = [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(opts.home, "generated-agents.json"), "utf8"));
+        if (Array.isArray(parsed.agents))
+            names = parsed.agents.filter((a) => typeof a === "string" && AGENT_NAME.test(a));
+    }
+    catch {
+        /* no generated agents yet */
+    }
+    const agents = [];
+    for (const name of [...names].sort()) {
+        try {
+            agents.push({ name, content: fs.readFileSync(path.join(opts.agentDir, `${name}.md`), "utf8") });
+        }
+        catch {
+            /* listed but gone: the router removes it from the manifest on its next sync */
+        }
+    }
+    return { caPem, agents };
+}
+/** Changes whenever what a remote should hold changes; a tunnel re-syncs only on a new value. */
+export function assetsFingerprint(a) {
+    const h = crypto.createHash("sha256").update(a.caPem);
+    for (const agent of a.agents)
+        h.update(`\0${agent.name}\0${agent.content}`);
+    return h.digest("hex");
+}
+/**
+ * Which agent files to write and remove on the remote. A remote file of the same name that we did
+ * not put there is someone's own agent and is left alone; a file we put there whose worker is no
+ * longer generated here goes.
+ */
+export function planAgents(local, state) {
+    const ours = new Set(state.record?.agents ?? []);
+    const present = new Set(state.agentFiles);
+    const write = local.filter((n) => !present.has(n) || ours.has(n));
+    const skipped = local.filter((n) => present.has(n) && !ours.has(n));
+    const remove = [...ours].filter((n) => !local.includes(n));
+    return { write, skipped, remove };
+}
+/** Lines that put the CA and the planned agent files on the remote and record what we own. */
+export function assetLines(assets, plan, record) {
+    const lines = [`mkdir -p "$HOME/${REMOTE_DIR}" "$HOME/.claude/agents" || exit 1`, ...writeFileLines(`${REMOTE_DIR}/ca.pem`, assets.caPem)];
+    for (const name of plan.write) {
+        const agent = assets.agents.find((a) => a.name === name);
+        if (agent && AGENT_NAME.test(name))
+            lines.push(...writeFileLines(`.claude/agents/${name}.md`, agent.content));
+    }
+    for (const name of plan.remove)
+        if (AGENT_NAME.test(name))
+            lines.push(`rm -f ${homePath(`.claude/agents/${name}.md`)}`);
+    const next = { agents: [...plan.write].sort(), ...record };
+    lines.push(...writeFileLines(`${REMOTE_DIR}/agents.json`, JSON.stringify(next, null, 2) + "\n"));
+    return lines;
+}
+export function script(lines) {
+    return ["umask 077", ...lines, "exit 0", ""].join("\n");
+}
+/**
+ * Bring the CA and agent files on `host` in step with this machine. What the tunnel runs each time
+ * it comes up and whenever the router regenerates the agent files; settings.json is not touched
+ * (that is `remote add`'s job, once).
+ */
+export async function syncRemoteAssets(run, host, assets) {
+    const state = await inspectRemote(run, host);
+    const plan = planAgents(assets.agents.map((a) => a.name), state);
+    const { agents: _agents, ...kept } = state.record ?? { agents: [] };
+    await runRemoteScript(run, host, script(assetLines(assets, plan, kept)));
+    return { home: state.home, plan };
+}

package/dist/router/src/remote-tunnel.js

@@ -0,0 +1,320 @@
+// Reverse SSH tunnels to remote hosts that run Claude Code for Claude Desktop (issue #67).
+//
+// Each configured host gets one long-lived `ssh -N -R 127.0.0.1:<remote port>:127.0.0.1:<proxy
+// port> <host>`, owned by the router because the router is what launchd / the Windows supervisor /
+// systemd already keeps alive. A tunnel that exits is started again with capped backoff; each time
+// one comes up the CA and agent files on that host are brought up to date (remote-host.ts), and
+// again when the router regenerates the agent files.
+//
+// Children are killed when the router exits, and their pids are recorded: a router that died
+// without killing them (SIGKILL) would otherwise leave an orphan holding the remote port, and every
+// new tunnel would then fail `ExitOnForwardFailure` for as long as the orphan lives.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { BATCH_OPTIONS, SSH_MISSING, extraSshOptions, sshExecutable } from "./remote-host.js";
+/**
+ * The tunnel's argv. `-v` is there for one line: `remote forward success for: listen …` is how
+ * ssh says the remote port is actually bound (measured, OpenSSH 10.3). Every other debug line is
+ * dropped before the log; `ExitOnForwardFailure` makes a forward that cannot bind an exit.
+ */
+export function tunnelArgs(host, port, target) {
+    return [
+        "-N",
+        "-v",
+        ...BATCH_OPTIONS,
+        "-o", "ExitOnForwardFailure=yes",
+        "-o", "ServerAliveInterval=15",
+        "-o", "ServerAliveCountMax=3",
+        "-R", `127.0.0.1:${port}:${target.host}:${target.port}`,
+        ...extraSshOptions(),
+        host,
+    ];
+}
+/** The connection target a router listening on `host` is reached at: a wildcard bind means loopback. */
+export function proxyConnectHost(listenHost) {
+    return listenHost === "0.0.0.0" || listenHost === "::" || listenHost === "" ? "127.0.0.1" : listenHost;
+}
+function defaultProcessCommand(pid) {
+    try {
+        if (process.platform === "win32") {
+            const out = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+            return out.trim() || null;
+        }
+        const out = execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 5_000 });
+        return out.trim() || null;
+    }
+    catch {
+        return null; // ps exits 1 when no such process
+    }
+}
+export class RemoteTunnels {
+    entries = new Map();
+    deps;
+    backoff;
+    closed = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.backoff = deps.backoff ?? { baseMs: 1_000, maxMs: 60_000, stableMs: 60_000 };
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
+    }
+    /**
+     * Kill ssh children a previous router left running. Only a pid whose command line is still our
+     * tunnel for that host and port is killed: a pid the OS has since given to something else is not.
+     */
+    cleanupStale() {
+        let records = [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.deps.pidFile, "utf8"));
+            if (Array.isArray(parsed.tunnels))
+                records = parsed.tunnels.filter((r) => !!r && typeof r.pid === "number" && typeof r.host === "string" && typeof r.port === "number");
+        }
+        catch {
+            return 0;
+        }
+        const lookup = this.deps.processCommand ?? defaultProcessCommand;
+        const kill = this.deps.kill ?? ((pid) => process.kill(pid, "SIGTERM"));
+        let killed = 0;
+        for (const r of records) {
+            if (r.pid === process.pid)
+                continue;
+            const cmd = lookup(r.pid);
+            if (!cmd || !/\bssh(\.exe)?\b/i.test(cmd) || !cmd.includes(`127.0.0.1:${r.port}:`) || !cmd.includes(r.host))
+                continue;
+            try {
+                kill(r.pid);
+                killed++;
+                this.deps.log.info(`remote ${r.host}: killed tunnel pid ${r.pid} left by a previous router`);
+            }
+            catch (e) {
+                this.deps.log.warn(`remote ${r.host}: cannot kill stale tunnel pid ${r.pid}: ${e.message}`);
+            }
+        }
+        this.writePids();
+        return killed;
+    }
+    /** Start tunnels for new hosts, stop removed ones, restart one whose port or target changed. */
+    reconcile(hosts) {
+        if (this.closed)
+            return;
+        const target = this.deps.proxyTarget();
+        const wanted = new Map(hosts.map((h) => [h.host, h]));
+        for (const [host, entry] of this.entries) {
+            const want = wanted.get(host);
+            if (!want || want.port !== entry.port || entry.target.host !== target.host || entry.target.port !== target.port) {
+                this.stop(entry);
+                this.entries.delete(host);
+                this.deps.log.info(`remote ${host}: tunnel stopped${want ? " (port changed)" : " (host removed)"}`);
+            }
+        }
+        for (const h of hosts) {
+            if (this.entries.has(h.host))
+                continue;
+            const entry = {
+                host: h.host, port: h.port, target, child: null, state: "starting", since: this.now(), upAt: null, lastError: null,
+                attempt: 0, restarts: 0, timer: null, settle: null, stopped: false, synced: null, syncedPrint: null, syncing: false,
+            };
+            this.entries.set(h.host, entry);
+            this.start(entry);
+        }
+        this.writePids();
+    }
+    status() {
+        return [...this.entries.values()].map((e) => ({
+            host: e.host,
+            port: e.port,
+            state: e.state,
+            since: new Date(e.since).toISOString(),
+            lastError: e.lastError,
+            pid: e.child?.pid ?? null,
+            restarts: e.restarts,
+            synced: e.synced === null ? null : new Date(e.synced).toISOString(),
+        }));
+    }
+    /** The agent files or the CA changed here: copy them to every host whose tunnel is up. */
+    assetsChanged() {
+        if (!this.deps.fingerprint)
+            return;
+        const print = this.deps.fingerprint();
+        for (const e of this.entries.values())
+            if (e.state === "up" && e.syncedPrint !== print)
+                void this.sync(e);
+    }
+    /** Kill every tunnel. Synchronous, so it can run from an `exit` handler. */
+    stopAll() {
+        this.closed = true;
+        for (const e of this.entries.values())
+            this.stop(e);
+        this.entries.clear();
+        this.writePids();
+    }
+    setState(e, state) {
+        if (e.state !== state)
+            e.since = this.now();
+        e.state = state;
+    }
+    start(e) {
+        if (e.stopped || this.closed)
+            return;
+        e.timer = null;
+        this.setState(e, "starting");
+        let child;
+        try {
+            child = (this.deps.spawn ?? ((cmd, args) => spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"], windowsHide: true })))(sshExecutable(), tunnelArgs(e.host, e.port, e.target));
+        }
+        catch (err) {
+            this.gone(e, null, err.message);
+            return;
+        }
+        e.child = child;
+        this.writePids();
+        this.deps.log.info(`remote ${e.host}: starting tunnel 127.0.0.1:${e.port} on the host → ${e.target.host}:${e.target.port}${child.pid ? ` (pid ${child.pid})` : ""}`);
+        let buffered = "";
+        let said = null; // this child's own last word, not an earlier one's
+        child.stderr?.on("data", (d) => {
+            buffered += d.toString();
+            let i;
+            while ((i = buffered.indexOf("\n")) >= 0) {
+                const line = buffered.slice(0, i).replace(/\r$/, "");
+                buffered = buffered.slice(i + 1);
+                if (e.child === child)
+                    said = this.stderrLine(e, line) ?? said;
+            }
+        });
+        child.on("error", (err) => {
+            if (e.child !== child)
+                return;
+            this.gone(e, child, err.code === "ENOENT" ? SSH_MISSING : err.message, err.code === "ENOENT");
+        });
+        // `close`, not `exit`: it comes after stderr has been read to the end, so the reason ssh gave
+        // for leaving is in `said` by then.
+        child.on("close", (code, signal) => {
+            if (e.child !== child)
+                return;
+            this.gone(e, child, said ?? `ssh exited (${signal ?? `code ${code}`})`);
+        });
+        const settleMs = this.deps.settleMs ?? 15_000;
+        e.settle = setTimeout(() => {
+            if (e.child === child && e.state === "starting")
+                this.up(e);
+        }, settleMs);
+        e.settle.unref?.();
+    }
+    /** Returns the line when it is something ssh said to a person (an error, a warning). */
+    stderrLine(e, line) {
+        if (!line.trim())
+            return null;
+        if (/^debug\d?: remote forward success for: listen/.test(line)) {
+            this.up(e);
+            return null;
+        }
+        if (/^debug\d?:/.test(line))
+            return null; // `-v` noise
+        // `-v` also lets through ssh's verbose-level notices, which carry no prefix (measured: the
+        // "Authenticated to … using "publickey"" line on every connect). They are not errors.
+        if (/^(Authenticated to |Transferred: |Bytes per second|Warning: Permanently added )/.test(line)) {
+            this.deps.log.info(`remote ${e.host}: ${line.trim()}`);
+            return null;
+        }
+        e.lastError = line.trim();
+        this.deps.log.warn(`remote ${e.host}: ${line.trim()}`);
+        return line.trim();
+    }
+    up(e) {
+        if (e.state === "up")
+            return;
+        if (e.settle)
+            clearTimeout(e.settle);
+        e.settle = null;
+        this.setState(e, "up");
+        e.upAt = this.now();
+        e.lastError = null;
+        this.deps.log.info(`remote ${e.host}: tunnel up (127.0.0.1:${e.port} on the host)`);
+        // Each (re)start copies again: the host may have lost or changed the files while we were away.
+        e.syncedPrint = null;
+        void this.sync(e);
+    }
+    async sync(e) {
+        if (!this.deps.sync || e.syncing)
+            return;
+        e.syncing = true;
+        const print = this.deps.fingerprint?.() ?? null;
+        try {
+            await this.deps.sync(e.host);
+            e.synced = this.now();
+            e.syncedPrint = print;
+            this.deps.log.info(`remote ${e.host}: CA and agent files synced`);
+        }
+        catch (err) {
+            this.deps.log.warn(`remote ${e.host}: sync failed: ${err.message}`);
+        }
+        finally {
+            e.syncing = false;
+        }
+        // Something changed while this one ran: catch up once.
+        if (this.deps.fingerprint && e.state === "up" && e.syncedPrint !== null && this.deps.fingerprint() !== e.syncedPrint)
+            void this.sync(e);
+    }
+    gone(e, child, reason, sshMissing = false) {
+        if (child && e.child !== child)
+            return;
+        e.child = null;
+        if (e.settle)
+            clearTimeout(e.settle);
+        e.settle = null;
+        this.writePids();
+        if (e.stopped || this.closed) {
+            this.setState(e, "down");
+            return;
+        }
+        if (e.upAt !== null && this.now() - e.upAt >= this.backoff.stableMs)
+            e.attempt = 0;
+        e.upAt = null;
+        e.lastError = reason;
+        const delay = sshMissing ? this.backoff.maxMs : Math.min(this.backoff.maxMs, this.backoff.baseMs * 2 ** e.attempt);
+        e.attempt++;
+        this.setState(e, sshMissing ? "down" : "backoff");
+        this.deps.log.warn(`remote ${e.host}: tunnel ${sshMissing ? "cannot start" : "down"}: ${reason}; retrying in ${Math.round(delay / 1000)}s`);
+        e.timer = setTimeout(() => {
+            e.restarts++;
+            this.start(e);
+        }, delay);
+        e.timer.unref?.();
+    }
+    stop(e) {
+        e.stopped = true;
+        if (e.timer)
+            clearTimeout(e.timer);
+        if (e.settle)
+            clearTimeout(e.settle);
+        e.timer = e.settle = null;
+        const child = e.child;
+        e.child = null;
+        this.setState(e, "down");
+        if (child) {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    writePids() {
+        const tunnels = [];
+        for (const e of this.entries.values())
+            if (e.child?.pid)
+                tunnels.push({ pid: e.child.pid, host: e.host, port: e.port });
+        if (tunnels.length === 0 && !fs.existsSync(this.deps.pidFile))
+            return; // a router with no remote hosts leaves no file
+        try {
+            fs.mkdirSync(path.dirname(this.deps.pidFile), { recursive: true });
+            fs.writeFileSync(this.deps.pidFile, JSON.stringify({ tunnels }, null, 2) + "\n");
+        }
+        catch (err) {
+            this.deps.log.warn(`remote: cannot record tunnel pids in ${this.deps.pidFile}: ${err.message}`);
+        }
+    }
+}