@termfleet/core 0.1.0

package/dist/lib/exec.js

@@ -0,0 +1,134 @@
+import { spawn, spawnSync } from "node:child_process";
+export function commandExists(command) {
+    const result = spawnSync("command", ["-v", command], {
+        encoding: "utf8",
+        shell: true
+    });
+    return result.status === 0;
+}
+export function requireCommand(command, installHint) {
+    if (!commandExists(command)) {
+        const hint = installHint ? ` ${installHint}` : "";
+        throw new Error(`${command} is required but was not found on PATH.${hint}`);
+    }
+}
+export function run(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        encoding: "utf8",
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: options.timeoutMs
+    });
+    if (result.error) {
+        const message = result.error.name === "Error" && "code" in result.error && result.error.code === "ETIMEDOUT"
+            ? `${command} ${args.join(" ")} timed out after ${options.timeoutMs}ms.`
+            : result.error.message;
+        const detail = runOutputDetail(result.stdout, result.stderr);
+        if (detail) {
+            throw new Error(`${message}\n${detail}`);
+        }
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const output = runOutputDetail(result.stdout, result.stderr);
+        const detail = output ? `\n${output}` : "";
+        throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status}.${detail}`);
+    }
+    return result.stdout;
+}
+function runOutputDetail(stdout, stderr) {
+    const stderrText = outputText(stderr);
+    const stdoutText = outputText(stdout);
+    if (stderrText && stdoutText) {
+        return `stderr:\n${stderrText}\nstdout:\n${stdoutText}`;
+    }
+    if (stderrText) {
+        return `stderr:\n${stderrText}`;
+    }
+    if (stdoutText) {
+        return `stdout:\n${stdoutText}`;
+    }
+    return "";
+}
+function outputText(value) {
+    if (Buffer.isBuffer(value)) {
+        return value.toString("utf8").trim();
+    }
+    return String(value ?? "").trim();
+}
+export function runBuffer(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const stderr = Buffer.isBuffer(result.stderr) ? result.stderr.toString("utf8").trim() : String(result.stderr ?? "").trim();
+        const detail = stderr ? `\n${stderr}` : "";
+        throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status}.${detail}`);
+    }
+    return Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? "");
+}
+export function runWithInput(command, args, input, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        input,
+        stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const stderr = Buffer.isBuffer(result.stderr) ? result.stderr.toString("utf8").trim() : String(result.stderr ?? "").trim();
+        const detail = stderr ? `\n${stderr}` : "";
+        throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status}.${detail}`);
+    }
+    return Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? "");
+}
+export async function runAsync(command, args, options = {}) {
+    return await spawnAsync(command, args, options);
+}
+export async function runWithInputAsync(command, args, input, options = {}) {
+    return await spawnAsync(command, args, options, input);
+}
+async function spawnAsync(command, args, options, input) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+            stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"]
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout?.on("data", (chunk) => stdout.push(chunk));
+        child.stderr?.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code !== 0) {
+                const detail = Buffer.concat(stderr).toString("utf8").trim();
+                reject(new Error(`${command} ${args.join(" ")} failed with exit ${code}.${detail ? `\n${detail}` : ""}`));
+                return;
+            }
+            resolve(Buffer.concat(stdout).toString("utf8"));
+        });
+        if (input !== undefined && child.stdin) {
+            child.stdin.on("error", reject);
+            child.stdin.end(input);
+        }
+    });
+}
+export function spawnInherited(command, args) {
+    const child = spawn(command, args, { stdio: "inherit" });
+    child.on("exit", (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code ?? 1);
+    });
+}

package/dist/local-providers.d.ts

@@ -0,0 +1,32 @@
+export interface AdvertisedProvider {
+    baseUrl: string;
+    instanceId?: string;
+    kind?: string;
+    name?: string;
+    pid?: number;
+    advertisedAt?: string;
+}
+export interface ResolvedProvider {
+    baseUrl: string;
+    source: "flag:--url" | "env:TERMFLEET_PROVIDER_URL" | "current-context" | "auto-local";
+    label?: string;
+}
+export type ProviderResolutionCode = "no_provider" | "ambiguous_provider";
+export declare class ProviderResolutionError extends Error {
+    readonly code: ProviderResolutionCode;
+    readonly remedy: string;
+    readonly candidates?: AdvertisedProvider[];
+    constructor(code: ProviderResolutionCode, message: string, remedy: string, candidates?: AdvertisedProvider[]);
+}
+export declare function advertiseLocalProvider(record: AdvertisedProvider): void;
+export declare function withdrawLocalProvider(baseUrl: string): void;
+export declare function readAdvertisedLocalProviders(): AdvertisedProvider[];
+export declare function liveLocalProviders(timeoutMs?: number): Promise<AdvertisedProvider[]>;
+export declare function readCurrentProvider(): string | undefined;
+export declare function writeCurrentProvider(baseUrl: string): string;
+export declare function clearCurrentProvider(): void;
+export declare function resolveDefaultProvider(opts: {
+    url?: string;
+    env?: string;
+    probeTimeoutMs?: number;
+}): Promise<ResolvedProvider>;

package/dist/local-providers.js

@@ -0,0 +1,184 @@
+// Machine-global discovery for LOCAL providers, plus the default-provider
+// resolution chain shared by every CLI command.
+//
+// The problem this solves: termfleet commands used to HARD-REQUIRE
+// `--url`/`--provider`, and the only discovery path was the cloud registry —
+// whose session expires (401) and which, for local providers, was stored
+// CWD-RELATIVE (`${cwd}/.termfleet-registry.json`), so a perfectly good local
+// provider was invisible from any other directory. The result: callers (humans
+// and agents alike) constantly hit "no provider" and declared themselves
+// "blocked" when a provider was in fact running.
+//
+// The fix mirrors what tmux / gpg-agent / Docker do for local defaults: the
+// daemon SELF-ADVERTISES where it is listening to a fixed, machine-global
+// location (`~/.termfleet/providers/`), and clients read it back and verify
+// liveness. "Default local provider" therefore means *observed serving right
+// now*, never a hardcoded port that can drift.
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isLocalProviderUrl, normalizeProviderOrigin } from "./contracts/provider-url.js";
+// A resolution failure carries a machine-readable `code` and a `remedy` string
+// so an agent can branch on the cause instead of regexing prose, and a human
+// gets a copy-pasteable fix. The top-level CLI catch renders it as JSON.
+export class ProviderResolutionError extends Error {
+    code;
+    remedy;
+    candidates;
+    constructor(code, message, remedy, candidates) {
+        super(message);
+        this.name = "ProviderResolutionError";
+        this.code = code;
+        this.remedy = remedy;
+        if (candidates)
+            this.candidates = candidates;
+    }
+}
+// `~/.termfleet` is already where the CLI keeps machine-global state (the
+// registry auth token lives there). TERMFLEET_HOME overrides it — used by tests
+// to point at a scratch dir so they never touch the real home.
+function termfleetHome() {
+    return process.env.TERMFLEET_HOME ?? join(homedir(), ".termfleet");
+}
+function providersDir() {
+    return join(termfleetHome(), "providers");
+}
+function currentContextFile() {
+    return join(termfleetHome(), "current.json");
+}
+// One file per provider, named by its origin so re-advertising the same address
+// overwrites in place (idempotent) instead of piling up records.
+function recordFileName(origin) {
+    return `${origin.replace(/[^a-zA-Z0-9]+/g, "_")}.json`;
+}
+// Called by `provider serve` once it is listening. Only LOOPBACK providers
+// self-advertise here — a tunneled/LAN provider is discoverable through the
+// registry, not the local machine store.
+export function advertiseLocalProvider(record) {
+    const origin = normalizeProviderOrigin(record.baseUrl);
+    if (!isLocalProviderUrl(origin))
+        return;
+    mkdirSync(providersDir(), { mode: 0o700, recursive: true });
+    const payload = {
+        ...record,
+        advertisedAt: record.advertisedAt ?? new Date().toISOString(),
+        baseUrl: origin
+    };
+    writeFileSync(join(providersDir(), recordFileName(origin)), `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+}
+// Best-effort removal on shutdown. Stale records also self-heal: a record whose
+// /healthz no longer answers is pruned the next time anyone resolves.
+export function withdrawLocalProvider(baseUrl) {
+    try {
+        rmSync(join(providersDir(), recordFileName(normalizeProviderOrigin(baseUrl))));
+    }
+    catch {
+        /* already gone / never written — fine */
+    }
+}
+export function readAdvertisedLocalProviders() {
+    let files;
+    try {
+        files = readdirSync(providersDir()).filter((file) => file.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const file of files) {
+        try {
+            const record = JSON.parse(readFileSync(join(providersDir(), file), "utf8"));
+            if (record && typeof record.baseUrl === "string")
+                records.push(record);
+        }
+        catch {
+            /* skip a corrupt record rather than fail discovery */
+        }
+    }
+    return records;
+}
+// Liveness via the provider's own /healthz — `registered` is not `serving`.
+async function probeHealth(baseUrl, timeoutMs) {
+    const origin = normalizeProviderOrigin(baseUrl);
+    try {
+        const response = await fetch(`${origin}/healthz`, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok)
+            return undefined;
+        const health = (await response.json());
+        if (health.ok !== true)
+            return undefined;
+        return { baseUrl: origin, ...(health.provider ? { kind: health.provider } : {}), ...(health.instanceId ? { instanceId: health.instanceId } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+}
+// The advertised providers that are ACTUALLY serving right now. Dead records are
+// pruned as a side effect so the store self-cleans.
+export async function liveLocalProviders(timeoutMs = 1500) {
+    const advertised = readAdvertisedLocalProviders();
+    const probed = await Promise.all(advertised.map(async (record) => ({ live: await probeHealth(record.baseUrl, timeoutMs), record })));
+    const live = [];
+    for (const { live: health, record } of probed) {
+        if (health) {
+            live.push({ ...record, ...health });
+        }
+        else {
+            withdrawLocalProvider(record.baseUrl);
+        }
+    }
+    return live;
+}
+export function readCurrentProvider() {
+    try {
+        const parsed = JSON.parse(readFileSync(currentContextFile(), "utf8"));
+        return typeof parsed.baseUrl === "string" && parsed.baseUrl.trim() ? parsed.baseUrl : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeCurrentProvider(baseUrl) {
+    const origin = normalizeProviderOrigin(baseUrl);
+    mkdirSync(termfleetHome(), { mode: 0o700, recursive: true });
+    writeFileSync(currentContextFile(), `${JSON.stringify({ baseUrl: origin }, null, 2)}\n`, { mode: 0o600 });
+    return origin;
+}
+export function clearCurrentProvider() {
+    try {
+        rmSync(currentContextFile());
+    }
+    catch {
+        /* nothing to clear */
+    }
+}
+// THE chain. When no provider was named on the command line, resolve one in a
+// fixed, explainable order. `--provider` (a registry/alias lookup) is handled by
+// the caller before this; everything else flows through here so behavior is
+// identical across every command.
+//
+// Order rationale: an explicit flag beats everything; an env var (how agents /
+// CI inject a target) beats a human's persisted default; the persisted default
+// (`termfleet use`) beats blind auto-discovery; auto-discovery is the
+// zero-config local convenience. Ambiguity (more than one live local provider)
+// is a LOUD error with the candidates listed — never a silent "most recent"
+// guess, which would make agent behavior nondeterministic.
+export async function resolveDefaultProvider(opts) {
+    const url = opts.url?.trim();
+    if (url)
+        return { baseUrl: url, source: "flag:--url" };
+    const env = opts.env?.trim();
+    if (env)
+        return { baseUrl: env, source: "env:TERMFLEET_PROVIDER_URL" };
+    const context = readCurrentProvider();
+    if (context)
+        return { baseUrl: context, source: "current-context" };
+    const live = await liveLocalProviders(opts.probeTimeoutMs);
+    if (live.length === 1 && live[0]) {
+        return { baseUrl: live[0].baseUrl, source: "auto-local", ...(live[0].name || live[0].kind ? { label: live[0].name ?? live[0].kind } : {}) };
+    }
+    if (live.length > 1) {
+        throw new ProviderResolutionError("ambiguous_provider", `Multiple local providers are live (${live.map((provider) => provider.baseUrl).join(", ")}); cannot pick a default.`, "Pass --url/--provider, set TERMFLEET_PROVIDER_URL, or choose a default with `termfleet use <url>`.", live);
+    }
+    throw new ProviderResolutionError("no_provider", "No provider specified and no live local provider was found.", "Start one with `termfleet provider serve --kind iterm`, or pass --url/--provider, or set TERMFLEET_PROVIDER_URL.");
+}

package/dist/local-tunnel.d.ts

@@ -0,0 +1,6 @@
+type LocalTunnelOptions = {
+    tunnelId?: string;
+};
+export declare function resolveIframeSrcThroughLocalTunnel(rawSrc: string, options?: LocalTunnelOptions): Promise<string>;
+export declare function resolveProviderOriginThroughLocalTunnel(rawOrigin: string, options?: LocalTunnelOptions): Promise<string>;
+export {};

package/dist/local-tunnel.js

@@ -0,0 +1,258 @@
+import { asError } from "@termfleet/core/lib/errors.js";
+import { commandExists } from "@termfleet/core/lib/exec.js";
+import { spawn } from "node:child_process";
+import { createWriteStream, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isLocalProviderUrl } from "./contracts/provider-url.js";
+// A tunnel can fail two ways: the process exits, or it wedges (alive but no
+// longer forwarding because its control connection dropped). The first is
+// caught by the "exit" event; the second needs an out-of-band health probe,
+// since a wedged process never exits. Both trigger a respawn.
+const TUNNEL_HEALTH_INTERVAL_MS = 20_000;
+const TUNNEL_UNHEALTHY_PROBES = 2;
+const TUNNEL_RESPAWN_DELAY_MS = 1_500;
+const TUNNEL_RESPAWN_MAX_DELAY_MS = 30_000;
+const tunnelByOrigin = new Map();
+// Tunnel children are unref'd (so they don't keep the process alive) — but unref'd
+// children are NOT killed when the parent exits, so without this they orphan on a
+// console exit/restart and keep forwarding (+ hold their log fd), accumulating. Track
+// the live ones and kill them on process exit. (A SIGKILL can't be caught, so a
+// hard-killed console can still orphan one — unavoidable.)
+const liveTunnelProcesses = new Set();
+let tunnelShutdownRegistered = false;
+function registerTunnelShutdown() {
+    if (tunnelShutdownRegistered) {
+        return;
+    }
+    tunnelShutdownRegistered = true;
+    const killAll = () => {
+        for (const child of liveTunnelProcesses) {
+            try {
+                child.kill();
+            }
+            catch {
+                // already gone
+            }
+        }
+    };
+    process.once("exit", killAll);
+    process.once("SIGINT", killAll);
+    process.once("SIGTERM", killAll);
+}
+export async function resolveIframeSrcThroughLocalTunnel(rawSrc, options = {}) {
+    const src = new URL(rawSrc);
+    if (!isLocalProviderUrl(src.origin)) {
+        return src.href;
+    }
+    const handle = await ensureLocalTunnel(src, options);
+    return `${handle.publicOrigin}${src.pathname}${src.search}${src.hash}`;
+}
+export async function resolveProviderOriginThroughLocalTunnel(rawOrigin, options = {}) {
+    const origin = new URL(rawOrigin);
+    if (!isLocalProviderUrl(origin.origin)) {
+        return origin.origin;
+    }
+    const handle = await ensureLocalTunnel(origin, options);
+    return handle.publicOrigin;
+}
+async function ensureLocalTunnel(src, options) {
+    const origin = src.origin;
+    const cacheKey = `${origin}#${options.tunnelId ?? ""}`;
+    const existing = tunnelByOrigin.get(cacheKey);
+    if (existing) {
+        const handle = await existing;
+        if (!isTunnelProcessLive(handle)) {
+            tunnelByOrigin.delete(cacheKey);
+        }
+        else {
+            return handle;
+        }
+    }
+    const next = startLocalTunnel(src, options).then((handle) => {
+        superviseLocalTunnel(src, options, cacheKey, handle);
+        return handle;
+    }).catch((error) => {
+        tunnelByOrigin.delete(cacheKey);
+        throw error;
+    });
+    tunnelByOrigin.set(cacheKey, next);
+    return await next;
+}
+function startLocalTunnel(src, options) {
+    const port = Number(src.port || (src.protocol === "https:" ? 443 : 80));
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Cannot tunnel iframe URL with invalid local port: ${src.href}`);
+    }
+    const bin = process.env.TERMFLEET_LOCAL_TUNNEL_BIN ?? "volter-tunnel";
+    if (!commandExists(bin)) {
+        throw new Error(`Opening localhost iframe panels requires ${bin} on PATH. Set TERMFLEET_LOCAL_TUNNEL_BIN to your tunnel client.`);
+    }
+    const tunnelServerUrl = process.env.TUNNEL_SERVER_URL ??
+        process.env.TERMFLEET_TUNNEL_SERVER_URL ??
+        'https://volter-tunnel.aaron-0ed.workers.dev';
+    if (!tunnelServerUrl) {
+        throw new Error("Tunneling requires a tunnel server. Set TERMFLEET_TUNNEL_SERVER_URL to your tunnel server's URL (or use a standalone tunnel like ngrok/cloudflared — see the README).");
+    }
+    const args = [
+        "--port", String(port),
+        "--host", tunnelServerUrl,
+        // The tunnel layer stays in passthrough (no tunnel-level auth); the console's
+        // own remote-access gate is what requires a session for non-loopback requests.
+        // volter-tunnel's flag is --auth-not-required (there is no --no-auth).
+        "--auth-not-required"
+    ];
+    if (options.tunnelId) {
+        args.push("--tunnel-id", options.tunnelId);
+    }
+    const child = spawn(bin, args, {
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.unref();
+    liveTunnelProcesses.add(child);
+    registerTunnelShutdown();
+    child.once("exit", () => liveTunnelProcesses.delete(child));
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+    });
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Timed out starting local iframe tunnel for ${src.origin}.${stderr ? ` ${stderr.trim()}` : ""}`));
+        }, 15_000);
+        const cleanup = () => {
+            clearTimeout(timeout);
+            child.stdout.off("data", onStdout);
+            child.off("exit", onExit);
+            child.off("error", onError);
+        };
+        const onStdout = (chunk) => {
+            const text = chunk.toString();
+            const match = text.match(/https?:\/\/[^\s]+/);
+            if (!match?.[0]) {
+                return;
+            }
+            cleanup();
+            // The tunnel logs heartbeats for its whole life. Once we have the URL we
+            // stop parsing, but we must keep draining stdout/stderr — leaving either
+            // pipe unconsumed fills its ~64KB OS buffer and the tunnel blocks and dies.
+            // Pipe both to a per-tunnel log file: that drains the pipes AND makes a
+            // wedged tunnel diagnosable instead of silent.
+            child.stderr.removeAllListeners("data");
+            const logPath = openTunnelLog(options.tunnelId, child);
+            const handle = {
+                logPath,
+                origin: src.origin,
+                process: child,
+                publicOrigin: new URL(match[0]).origin,
+                tunnelId: options.tunnelId
+            };
+            resolve(handle);
+        };
+        const onExit = (code) => {
+            cleanup();
+            reject(new Error(`Local iframe tunnel for ${src.origin} exited with ${code ?? "unknown"} before returning a URL.${stderr ? ` ${stderr.trim()}` : ""}`));
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        child.stdout.on("data", onStdout);
+        child.on("exit", onExit);
+        child.on("error", onError);
+    });
+}
+function isTunnelProcessLive(handle) {
+    return handle.process.exitCode === null && handle.process.signalCode === null;
+}
+function openTunnelLog(tunnelId, child) {
+    const dir = join(homedir(), ".termfleet", "logs");
+    mkdirSync(dir, { mode: 0o700, recursive: true });
+    const logPath = join(dir, `tunnel-${tunnelId ?? "default"}.log`);
+    const stream = createWriteStream(logPath, { flags: "a", mode: 0o600 });
+    child.stdout.pipe(stream);
+    child.stderr.pipe(stream);
+    return logPath;
+}
+// Keep a tunnel alive behind its public URL. The URL is derived from the stable
+// tunnelId, so it is unchanged across restarts — callers keep their resolved
+// origin. Respawn on process exit OR on a sustained health-probe failure (the
+// wedged-but-alive case). The two paths are mutually exclusive per generation
+// via `replacing`, so a probe-triggered kill does not double-spawn through the
+// exit handler it fires.
+function superviseLocalTunnel(src, options, cacheKey, handle) {
+    let replacing = false;
+    const respawn = (reason) => {
+        if (replacing) {
+            return;
+        }
+        replacing = true;
+        clearInterval(timer);
+        console.warn(`[termfleet:tunnel] ${src.origin} ${reason}; restarting (log: ${handle.logPath})`);
+        try {
+            handle.process.kill();
+        }
+        catch {
+            // Already gone — the respawn below brings up a fresh one.
+        }
+        // Keep retrying with backoff until the tunnel is back. The tunnel server can
+        // be briefly unreachable (a slow register times the child out and it exits);
+        // a single failed respawn must not give up — and crucially must not reject
+        // into a promise nobody awaits, which surfaces as an unhandled rejection that
+        // takes the whole console down. We own the retry here and the promise always
+        // resolves (to the eventual live handle) or stays pending while we retry.
+        tunnelByOrigin.set(cacheKey, respawnWithRetry(src, options, cacheKey));
+    };
+    handle.process.once("exit", (code) => respawn(`exited (code ${code ?? "unknown"})`));
+    let failures = 0;
+    const timer = setInterval(() => {
+        void (async () => {
+            try {
+                const response = await fetch(`${handle.publicOrigin}/healthz`, { signal: AbortSignal.timeout(8_000) });
+                // Any HTTP status means the tunnel forwarded to the local app (even a
+                // 401 from the app's own auth gate). Only a tunnel-server gateway error
+                // means the tunnel itself stopped forwarding.
+                failures = response.status === 502 || response.status === 504 ? failures + 1 : 0;
+            }
+            catch {
+                failures += 1;
+            }
+            if (failures >= TUNNEL_UNHEALTHY_PROBES) {
+                respawn("stopped forwarding (wedged)");
+            }
+        })();
+    }, TUNNEL_HEALTH_INTERVAL_MS);
+    timer.unref();
+}
+// Bring a tunnel back after a failure, retrying with capped exponential backoff
+// until startLocalTunnel succeeds. Deliberately never rejects: the tunnel server
+// can be briefly unreachable (a slow register times the child out and it exits
+// before printing a URL), and a respawn that rejected into this unawaited promise
+// would surface as an unhandled rejection — which used to take the whole console
+// down, blanking the UI ("the chat never comes up"). Retrying instead lets a
+// transient outage self-heal while the console keeps serving everything else.
+// Only one retry loop runs per origin at a time: respawn() is guarded by its
+// generation's `replacing` flag, and each next generation begins only after a
+// successful start.
+async function respawnWithRetry(src, options, cacheKey) {
+    let backoff = TUNNEL_RESPAWN_DELAY_MS;
+    for (;;) {
+        await delay(backoff);
+        try {
+            const restarted = await startLocalTunnel(src, options);
+            superviseLocalTunnel(src, options, cacheKey, restarted);
+            return restarted;
+        }
+        catch (error) {
+            backoff = Math.min(backoff * 2, TUNNEL_RESPAWN_MAX_DELAY_MS);
+            console.error(`[termfleet:tunnel] ${src.origin} restart failed (retrying in ${backoff}ms): ${asError(error).message}`);
+        }
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref();
+    });
+}

package/dist/provider-access-token.d.ts

@@ -0,0 +1,11 @@
+export declare const PROVIDER_ACCESS_TOKEN_DURATION_MS: number;
+export type ProviderAccessTokenPayload = {
+    aud: "termfleet-provider";
+    exp: number;
+    iat: number;
+    org?: string;
+    provider: string;
+    sub: string;
+};
+export declare function signProviderAccessToken(payload: ProviderAccessTokenPayload, secret: string): Promise<string>;
+export declare function verifyProviderAccessTokenPayload(token: string | null | undefined, secret: string): Promise<ProviderAccessTokenPayload>;