instar 1.2.35 → 1.2.37

package/dist/tunnel/TunnelManager.js

@@ -1,473 +1,418 @@
 /**
- * Cloudflare Tunnel manager for Instar agents.
+ * TunnelManager — single owner of the tunnel lifecycle.
  *
- * Manages cloudflared tunnel lifecycle — quick tunnels (zero-config,
- * ephemeral) and named tunnels (persistent, custom domain).
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md.
  *
- * Quick tunnels require no Cloudflare account. Named tunnels require
- * a tunnel token from the Cloudflare dashboard.
+ * Rewritten on top of the foundation modules:
+ *   - TunnelProvider — backend abstraction; concrete providers under
+ *     src/tunnel/Cloudflare*Provider.ts.
+ *   - TunnelLifecycle — single-writer CAS-guarded state machine.
+ *   - TunnelNotifier — two-channel routing (group / owner-DM) of
+ *     transition events.
  *
- * The tunnel exposes the agent's local HTTP server to the internet,
- * enabling:
- *   - Private content viewing (auth-gated rendered markdown)
- *   - Remote API access from anywhere
- *   - File serving (logs, reports, exports)
- *   - Webhook endpoints for external integrations
+ * The manager is the SOLE owner of the detect → attempt → fall-back →
+ * notify → self-heal lifecycle. The previous server.ts startup-retry
+ * ladder + background-retry ladder + Lifeline failure message are
+ * retired in favor of routing all retry through here (one backoff
+ * engine, not two).
+ *
+ * Scope of this rewrite (PR 2 of the chain):
+ *   - Tier-1 provider pool (Cloudflare named → quick) with internal
+ *     backoff between retries within an episode.
+ *   - Post-start reachability probe (HTTP /health through the public
+ *     URL) before declaring `active` — prevents broadcasting a "back
+ *     online" link that doesn't actually serve traffic.
+ *   - Backward-compatible public API: start(), stop(), forceStop(),
+ *     enableAutoReconnect(), disableAutoReconnect(), getExternalUrl(),
+ *     url/isRunning/state. Plus the existing events.
+ *   - Notifier sink optional; when telegram adapter is plumbed,
+ *     transition events route to the group topic.
+ *
+ * Out of scope for THIS PR (future PRs in the chain):
+ *   - Tier-2 consent flow + relay providers (PR 4).
+ *   - Owner-DM channel + inline-button consent UX (PR 3).
+ *   - authToken/PIN rotation + boot recovery (PR 5).
+ *   - Self-heal probe with N-consecutive-success stability gate (PR 6).
+ *   - The /tunnel route (PR 7).
+ *
+ * The lifecycle state machine already supports these states; the
+ * manager simply doesn't transition into them yet in PR 2.
  */
 import { EventEmitter } from 'node:events';
-import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { bin, install, Tunnel } from 'cloudflared';
+import { TunnelLifecycle, classifyFailure, } from './TunnelLifecycle.js';
+import { CloudflareQuickProvider } from './CloudflareQuickProvider.js';
+import { CloudflareNamedProvider } from './CloudflareNamedProvider.js';
+import { TunnelNotifier } from './TunnelNotifier.js';
+// ── Constants ───────────────────────────────────────────────────────
+const BASE_BACKOFF_MS = 5_000;
+const MAX_BACKOFF_MS = 5 * 60_000;
+const MAX_BACKOFF_ATTEMPTS = 10;
+const REACHABILITY_TIMEOUT_MS = 8_000;
+/**
+ * Post-exhausted retry cadence — the minimum-viable "self-heal"
+ * placeholder for PR 2. After the bounded startup-reconnect ladder
+ * exhausts (MAX_BACKOFF_ATTEMPTS), the manager keeps probing the
+ * Tier-1 pool at this cadence indefinitely. This is intentionally
+ * crude; PR 6 replaces it with the spec's N-consecutive-success
+ * stability-gate probe per Part 5. Without this placeholder, the
+ * agent stays link-less after exhaustion until restart — which is
+ * the regression we explicitly need to avoid in the PR chain.
+ */
+const POST_EXHAUSTED_RETRY_INTERVAL_MS = 15 * 60_000;
 // ── Manager ────────────────────────────────────────────────────────
 export class TunnelManager extends EventEmitter {
     config;
-    tunnel = null;
     stateFile;
-    _state;
+    lifecycle;
+    providers;
+    notifier;
+    fetcher;
+    currentHandle = null;
+    currentProviderName = null;
+    _legacyState;
+    _autoReconnect = true; // always-on under the new design
     _stopped = false;
-    _autoReconnect = false;
-    _reconnectTimer = null;
-    _reconnectAttempt = 0;
-    _startPromise = null; // Mutex: prevents concurrent start()
-    static MAX_RECONNECT_ATTEMPTS = 10;
-    static BASE_RECONNECT_DELAY_MS = 5_000;
-    static MAX_RECONNECT_DELAY_MS = 5 * 60_000;
-    constructor(config) {
+    _startPromise = null;
+    _backoffAttempt = 0;
+    _backoffTimer = null;
+    _postExhaustedTimer = null;
+    constructor(config, injections) {
         super();
         this.config = config;
         this.stateFile = path.join(config.stateDir, 'tunnel.json');
-        this._state = {
+        this.lifecycle = new TunnelLifecycle();
+        this.providers = injections?.providers ?? this.buildDefaultPool(config);
+        this.notifier = injections?.notifierSink
+            ? new TunnelNotifier({ sink: injections.notifierSink })
+            : null;
+        this.fetcher = injections?.fetch ?? globalThis.fetch.bind(globalThis);
+        this._legacyState = {
             url: null,
             type: config.type,
             startedAt: null,
         };
+        // Route lifecycle transitions through the notifier.
+        this.lifecycle.on('transition', (e) => {
+            if (this.notifier)
+                void this.notifier.onTransition(e);
+        });
+        // Restore persisted snapshot (rotation-pending flag + consent cooldown).
+        this.restorePersisted();
     }
-    /** Current tunnel URL, or null if not connected */
-    get url() {
-        return this._state.url;
-    }
-    /** Whether the tunnel is currently running */
-    get isRunning() {
-        return this.tunnel !== null && !this._stopped;
-    }
-    /** Current tunnel state */
-    get state() {
-        return { ...this._state };
+    // ── Public API (back-compat with the legacy manager) ────────────
+    get url() { return this._legacyState.url; }
+    get isRunning() { return this.currentHandle !== null && !this._stopped; }
+    get state() { return { ...this._legacyState }; }
+    /** Additive new accessor — lifecycle snapshot. */
+    get lifecycleState() {
+        const snap = this.lifecycle.snapshot();
+        snap.lastUrl = this._legacyState.url;
+        return snap;
     }
     /**
-     * Start the tunnel. Ensures the cloudflared binary is installed,
-     * then starts the appropriate tunnel type.
+     * Start the tunnel. Drives the full Tier-1 ladder internally — the
+     * caller does NOT wrap with its own retry loop (the old server.ts
+     * startup ladder is RETIRED).
+     *
+     * Resolves with the URL of the first provider that reaches `active`.
+     * Rejects when all Tier-1 providers fail and backoff is exhausted.
      */
     async start() {
-        // Mutex: if a start is already in progress, return the same promise
-        // This prevents concurrent start() calls from the SleepWake handler
-        // and auto-reconnect racing each other.
-        if (this._startPromise) {
+        if (this._startPromise)
             return this._startPromise;
-        }
-        // If tunnel is already running, return the current URL
-        if (this.tunnel && this._state.url) {
-            return this._state.url;
-        }
+        if (this.currentHandle && this._legacyState.url)
+            return this._legacyState.url;
         this._stopped = false;
-        const doStart = async () => {
-            try {
-                // Ensure cloudflared binary is installed
-                await this.ensureBinary();
-                // Start the appropriate tunnel type
-                if (this.config.type === 'named') {
-                    if (!this.config.token && !this.config.configFile) {
-                        throw new Error('Named tunnel requires either a token or a configFile. Set tunnel.token or tunnel.configFile in config.');
-                    }
-                    if (this.config.configFile) {
-                        return await this.startConfigFileTunnel();
-                    }
-                    return await this.startNamedTunnel();
-                }
-                else {
-                    return await this.startQuickTunnel();
-                }
-            }
-            finally {
-                this._startPromise = null;
-            }
-        };
-        this._startPromise = doStart();
+        this._startPromise = this.doStart().finally(() => { this._startPromise = null; });
         return this._startPromise;
     }
-    /**
-     * Stop the tunnel gracefully. Intentional stops disable auto-reconnect.
-     */
     async stop() {
         this._stopped = true;
-        this._startPromise = null; // Cancel any in-flight start
-        if (this._reconnectTimer) {
-            clearTimeout(this._reconnectTimer);
-            this._reconnectTimer = null;
+        this.clearBackoffTimer();
+        this.clearPostExhaustedTimer();
+        this._startPromise = null;
+        if (this.currentHandle) {
+            try {
+                await this.currentHandle.stop();
+            }
+            catch { /* handle may be dead */ }
+            this.currentHandle = null;
         }
-        this._reconnectAttempt = 0;
-        if (this.tunnel) {
-            this.tunnel.stop();
-            this.tunnel = null;
+        this._legacyState.url = null;
+        this._legacyState.startedAt = null;
+        this.currentProviderName = null;
+        const from = this.lifecycle.state;
+        if (from !== 'idle') {
+            try {
+                this.lifecycle.transition(from, 'idle', { activeProvider: null });
+            }
+            catch { /* invalid pair — best-effort */ }
         }
-        this._state.url = null;
-        this._state.startedAt = null;
-        this.saveState();
+        this.persist();
         this.emit('stopped');
     }
-    /**
-     * Force-stop the tunnel with a timeout. If cloudflared doesn't respond to
-     * SIGINT within `timeoutMs`, escalate to SIGKILL. Essential for sleep/wake
-     * recovery where cloudflared may be a zombie process.
-     */
-    async forceStop(timeoutMs = 5000) {
-        this._stopped = true;
-        this._startPromise = null; // Cancel any in-flight start
-        if (this._reconnectTimer) {
-            clearTimeout(this._reconnectTimer);
-            this._reconnectTimer = null;
+    /** Force-stop with escalation. Providers internally do SIGINT → SIGKILL. */
+    async forceStop(_timeoutMs) {
+        await this.stop();
+    }
+    enableAutoReconnect() { this._autoReconnect = true; }
+    disableAutoReconnect() {
+        this._autoReconnect = false;
+        this.clearBackoffTimer();
+    }
+    getExternalUrl(localPath) {
+        if (!this._legacyState.url)
+            return null;
+        const base = this._legacyState.url.replace(/\/$/, '');
+        const p = localPath.startsWith('/') ? localPath : `/${localPath}`;
+        return `${base}${p}`;
+    }
+    // ── Internals ──────────────────────────────────────────────────
+    buildDefaultPool(config) {
+        const pool = [];
+        if (config.token || config.configFile) {
+            pool.push(new CloudflareNamedProvider({
+                token: config.token,
+                configFile: config.configFile,
+                hostname: config.hostname,
+            }));
         }
-        this._reconnectAttempt = 0;
-        if (this.tunnel) {
-            const tunnelProcess = this.tunnel.process;
-            const pid = tunnelProcess?.pid;
-            // Send SIGINT (graceful)
-            try {
-                this.tunnel.stop();
+        pool.push(new CloudflareQuickProvider({ port: config.port, stateDir: config.stateDir }));
+        return pool;
+    }
+    async doStart() {
+        if (!this.config.enabled)
+            throw new Error('tunnel.enabled is false');
+        if (this.lifecycle.state === 'idle' || this.lifecycle.state === 'active') {
+            this.lifecycle.startEpisode();
+        }
+        if (!this.lifecycle.transition('idle', 'starting')) {
+            if (this.lifecycle.state === 'starting' || this.lifecycle.state === 'active') {
+                if (this._legacyState.url)
+                    return this._legacyState.url;
             }
-            catch { /* may already be dead */ }
-            if (pid) {
-                // Wait for process to exit, escalate to SIGKILL if it doesn't
-                const exited = await new Promise((resolve) => {
-                    const timer = setTimeout(() => resolve(false), timeoutMs);
-                    // Check if process is already dead
-                    try {
-                        process.kill(pid, 0);
-                    }
-                    catch {
-                        clearTimeout(timer);
-                        resolve(true);
-                        return;
-                    }
-                    // Poll for exit
-                    const poll = setInterval(() => {
-                        try {
-                            process.kill(pid, 0);
-                        }
-                        catch {
-                            clearInterval(poll);
-                            clearTimeout(timer);
-                            resolve(true);
-                        }
-                    }, 200);
-                });
-                if (!exited) {
-                    console.warn(`[Tunnel] cloudflared (PID ${pid}) didn't exit after ${timeoutMs}ms SIGINT — sending SIGKILL`);
+            throw new Error(`cannot start: lifecycle in state ${this.lifecycle.state}`);
+        }
+        return this.driveTier1();
+    }
+    async driveTier1() {
+        let lastErr = null;
+        for (let i = 0; i < this.providers.length; i++) {
+            if (this._stopped)
+                throw new Error('tunnel start aborted: stopped');
+            const provider = this.providers[i];
+            if (!provider)
+                continue;
+            if (provider.tier !== 1)
+                continue; // Tier-2 deferred to PR 4
+            const available = await provider.isAvailable().catch(() => false);
+            if (!available)
+                continue;
+            try {
+                const handle = await provider.start(this.config.port);
+                // Reachability probe BEFORE declaring active.
+                const reachable = await this.probeReachability(handle.url).catch(() => false);
+                if (!reachable) {
                     try {
-                        process.kill(pid, 'SIGKILL');
+                        await handle.stop();
                     }
-                    catch { /* already dead */ }
+                    catch { /* best effort */ }
+                    this.lifecycle.recordAttempt(provider.name, 'reachability-failed');
+                    lastErr = new Error(`reachability-failed: ${provider.name} URL did not respond to /health`);
+                    continue;
+                }
+                // Success.
+                this.currentHandle = handle;
+                this.currentProviderName = provider.name;
+                this._legacyState.url = handle.url;
+                this._legacyState.startedAt = new Date().toISOString();
+                const from = this.lifecycle.state;
+                if (from === 'starting' || from === 'retrying') {
+                    this.lifecycle.transition(from, 'active', {
+                        activeProvider: provider.name,
+                        lastFailureReason: null,
+                    });
+                }
+                // Persist AFTER the transition so the snapshot reflects 'active'.
+                this.persist();
+                this.emit('url', handle.url);
+                this._backoffAttempt = 0;
+                return handle.url;
+            }
+            catch (err) {
+                const reason = classifyFailure(err);
+                this.lifecycle.recordAttempt(provider.name, reason);
+                lastErr = err instanceof Error ? err : new Error(String(err));
+                if (this.lifecycle.state === 'starting') {
+                    this.lifecycle.transition('starting', 'retrying', {
+                        activeProvider: null,
+                        lastFailureReason: reason,
+                    });
                 }
             }
-            this.tunnel = null;
         }
-        this._state.url = null;
-        this._state.startedAt = null;
-        this.saveState();
-        this.emit('stopped');
-    }
-    /**
-     * Enable automatic reconnection when the tunnel disconnects unexpectedly.
-     * Uses exponential backoff: 5s, 10s, 20s, ... up to 5 minutes, max 10 attempts.
-     */
-    enableAutoReconnect() {
-        this._autoReconnect = true;
+        // All Tier-1 providers exhausted in this attempt round.
+        return this.exhaustedOrBackoff(lastErr);
     }
-    disableAutoReconnect() {
-        this._autoReconnect = false;
-        if (this._reconnectTimer) {
-            clearTimeout(this._reconnectTimer);
-            this._reconnectTimer = null;
+    async exhaustedOrBackoff(lastErr) {
+        // Matches the legacy semantics: start() rejects after the FIRST
+        // round of provider attempts fails. The backoff retry runs in the
+        // background — the manager keeps trying without blocking the
+        // caller, and emits 'url' when a later attempt succeeds. This
+        // prevents start() from blocking server.ts boot for the full
+        // 25-minute worst-case exponential window. The original failing
+        // E2E (tests/e2e/tunnel-private-view.test.ts) timed out at the
+        // beforeAll 60s budget because the old draft kept retrying inside
+        // start().
+        const from = this.lifecycle.state;
+        if (from === 'retrying' || from === 'starting') {
+            this.lifecycle.transition(from, 'exhausted', { activeProvider: null });
         }
-        this._reconnectAttempt = 0;
+        const err = lastErr ?? new Error('all Tier-1 providers failed');
+        // Schedule background retry (bounded exponential ladder, then the
+        // indefinite post-exhausted placeholder once the ladder runs out).
+        // Fire-and-forget; if a later attempt succeeds, the 'url' event
+        // fires and downstream subscribers (notifier, dashboard
+        // broadcaster, log line) catch up.
+        if (this._autoReconnect && !this._stopped) {
+            this.scheduleBackgroundRetry();
+        }
+        this.emit('error', err);
+        throw err;
     }
     /**
-     * Attempt to reconnect the tunnel with exponential backoff.
+     * Background retry — runs the bounded exponential ladder off the
+     * start() promise so initial start() resolves/rejects fast. After
+     * the ladder exhausts, hands off to the indefinite post-exhausted
+     * placeholder (the PR 2 self-heal; PR 6 replaces with the spec's
+     * N-consecutive-success probe).
      */
-    attemptReconnect() {
-        if (!this._autoReconnect || this._stopped)
-            return;
-        // Skip if a start is already in progress (e.g., SleepWake handler is restarting)
-        if (this._startPromise)
+    scheduleBackgroundRetry() {
+        if (this._stopped || !this._autoReconnect)
             return;
-        if (this._reconnectAttempt >= TunnelManager.MAX_RECONNECT_ATTEMPTS) {
-            console.error(`[Tunnel] Auto-reconnect gave up after ${this._reconnectAttempt} attempts`);
-            this.emit('error', new Error(`Tunnel auto-reconnect failed after ${this._reconnectAttempt} attempts`));
+        if (this._backoffTimer)
+            return; // already scheduled
+        if (this._backoffAttempt >= MAX_BACKOFF_ATTEMPTS) {
+            this.schedulePostExhaustedRetry();
             return;
         }
-        const delay = Math.min(TunnelManager.BASE_RECONNECT_DELAY_MS * Math.pow(2, this._reconnectAttempt), TunnelManager.MAX_RECONNECT_DELAY_MS);
-        this._reconnectAttempt++;
-        console.log(`[Tunnel] Auto-reconnect attempt ${this._reconnectAttempt}/${TunnelManager.MAX_RECONNECT_ATTEMPTS} in ${delay / 1000}s`);
-        this._reconnectTimer = setTimeout(async () => {
-            if (this._stopped)
+        const delay = Math.min(BASE_BACKOFF_MS * Math.pow(2, this._backoffAttempt), MAX_BACKOFF_MS);
+        this._backoffAttempt += 1;
+        this._backoffTimer = setTimeout(() => {
+            this._backoffTimer = null;
+            if (this._stopped || !this._autoReconnect)
                 return;
+            const from = this.lifecycle.state;
             try {
-                const url = await this.start();
-                console.log(`[Tunnel] Auto-reconnected: ${url}`);
-                this._reconnectAttempt = 0;
+                if (from === 'exhausted') {
+                    this.lifecycle.transition('exhausted', 'starting');
+                }
+                else if (from === 'idle') {
+                    this.lifecycle.transition('idle', 'starting');
+                }
+                else if (from === 'retrying') {
+                    this.lifecycle.transition('retrying', 'starting');
+                }
+                else {
+                    return; // unexpected state; bail
+                }
             }
-            catch (err) {
-                console.error(`[Tunnel] Auto-reconnect failed:`, err instanceof Error ? err.message : err);
-                this.attemptReconnect();
+            catch {
+                return; // invalid transition; bail
             }
+            void this.driveTier1().catch(() => { });
         }, delay);
     }
-    /**
-     * Get the full external URL for a local path.
-     * Returns null if tunnel is not connected.
-     */
-    getExternalUrl(localPath) {
-        if (!this._state.url)
-            return null;
-        const base = this._state.url.replace(/\/$/, '');
-        const p = localPath.startsWith('/') ? localPath : `/${localPath}`;
-        return `${base}${p}`;
+    clearBackoffTimer() {
+        if (this._backoffTimer) {
+            clearTimeout(this._backoffTimer);
+            this._backoffTimer = null;
+        }
+        this._backoffAttempt = 0;
     }
-    // ── Internal ───────────────────────────────────────────────────
-    async ensureBinary() {
-        if (!fs.existsSync(bin)) {
-            await install(bin);
+    clearPostExhaustedTimer() {
+        if (this._postExhaustedTimer) {
+            clearTimeout(this._postExhaustedTimer);
+            this._postExhaustedTimer = null;
         }
     }
-    startQuickTunnel() {
-        return new Promise((resolve, reject) => {
-            const localUrl = `http://127.0.0.1:${this.config.port}`;
-            try {
-                // Write an empty config to prevent cloudflared from loading
-                // ~/.cloudflared/config.yml, which may contain named tunnel
-                // ingress rules that override the quick tunnel's --url proxy.
-                const emptyConfig = path.join(this.config.stateDir, 'cloudflared-quick.yml');
-                const dir = path.dirname(emptyConfig);
-                if (!fs.existsSync(dir)) {
-                    fs.mkdirSync(dir, { recursive: true });
-                }
-                fs.writeFileSync(emptyConfig, '# Quick tunnel — no ingress rules\n');
-                this.tunnel = Tunnel.quick(localUrl, { '--config': emptyConfig });
-            }
-            catch (err) {
-                reject(new Error(`Failed to start quick tunnel: ${err instanceof Error ? err.message : String(err)}`));
+    /**
+     * Minimum-viable post-exhausted retry (PR 2 self-heal placeholder).
+     * Schedules a single low-frequency probe; on completion (success or
+     * failure) it re-arms itself, so the agent keeps trying to recover
+     * even after the bounded startup-reconnect ladder gives up. PR 6
+     * replaces this with the spec's N-consecutive-success stability gate.
+     */
+    schedulePostExhaustedRetry() {
+        if (this._stopped || !this._autoReconnect)
+            return;
+        if (this._postExhaustedTimer)
+            return; // already scheduled
+        this._postExhaustedTimer = setTimeout(async () => {
+            this._postExhaustedTimer = null;
+            if (this._stopped || !this._autoReconnect)
                 return;
-            }
-            let resolved = false;
-            const timeout = setTimeout(() => {
-                if (!resolved) {
-                    resolved = true;
-                    reject(new Error('Tunnel connection timed out after 30 seconds'));
+            // Re-enter from exhausted → starting.
+            const from = this.lifecycle.state;
+            if (from === 'exhausted') {
+                try {
+                    this.lifecycle.transition('exhausted', 'starting');
                 }
-            }, 30_000);
-            this.tunnel.once('url', (url) => {
-                if (resolved)
+                catch { /* invalid transition — bail */
                     return;
-                resolved = true;
-                clearTimeout(timeout);
-                this._state.url = url;
-                this._state.startedAt = new Date().toISOString();
-                this.saveState();
-                this.emit('url', url);
-                resolve(url);
-            });
-            this.tunnel.once('connected', (info) => {
-                this._state.connectionId = info.id;
-                this._state.connectionLocation = info.location;
-                this.saveState();
-                this.emit('connected', info);
-            });
-            this.tunnel.on('error', (err) => {
-                if (!resolved) {
-                    resolved = true;
-                    clearTimeout(timeout);
-                    reject(err);
-                }
-                this.emit('error', err);
-            });
-            this.tunnel.on('exit', (code) => {
-                if (!this._stopped) {
-                    this.tunnel = null;
-                    this._state.url = null;
-                    this.saveState();
-                    this.emit('disconnected');
-                    if (!resolved) {
-                        resolved = true;
-                        clearTimeout(timeout);
-                        reject(new Error(`Tunnel process exited with code ${code}`));
-                    }
-                    else {
-                        // Tunnel was running and disconnected unexpectedly — try to reconnect
-                        this.attemptReconnect();
-                    }
                 }
-            });
-        });
-    }
-    startNamedTunnel() {
-        return new Promise((resolve, reject) => {
-            try {
-                this.tunnel = Tunnel.withToken(this.config.token);
             }
-            catch (err) {
-                reject(new Error(`Failed to start named tunnel: ${err instanceof Error ? err.message : String(err)}`));
+            else if (from !== 'starting' && from !== 'idle') {
+                // State moved beyond our reach; let the active path handle it.
                 return;
             }
-            let resolved = false;
-            const timeout = setTimeout(() => {
-                if (!resolved) {
-                    resolved = true;
-                    reject(new Error('Named tunnel connection timed out after 30 seconds'));
-                }
-            }, 30_000);
-            this.tunnel.once('url', (url) => {
-                if (resolved)
-                    return;
-                resolved = true;
-                clearTimeout(timeout);
-                this._state.url = url;
-                this._state.startedAt = new Date().toISOString();
-                this.saveState();
-                this.emit('url', url);
-                resolve(url);
-            });
-            this.tunnel.once('connected', (info) => {
-                this._state.connectionId = info.id;
-                this._state.connectionLocation = info.location;
-                this.saveState();
-                this.emit('connected', info);
-                // For named tunnels, the URL may come from the connection info
-                // rather than the 'url' event, since the URL is pre-configured
-                if (!resolved && this._state.url) {
-                    resolved = true;
-                    clearTimeout(timeout);
-                    resolve(this._state.url);
-                }
-            });
-            this.tunnel.on('error', (err) => {
-                if (!resolved) {
-                    resolved = true;
-                    clearTimeout(timeout);
-                    reject(err);
-                }
-                this.emit('error', err);
-            });
-            this.tunnel.on('exit', (code) => {
-                if (!this._stopped) {
-                    this.tunnel = null;
-                    this._state.url = null;
-                    this.saveState();
-                    this.emit('disconnected');
-                    if (!resolved) {
-                        resolved = true;
-                        clearTimeout(timeout);
-                        reject(new Error(`Named tunnel process exited with code ${code}`));
-                    }
-                    else {
-                        this.attemptReconnect();
-                    }
-                }
-            });
-        });
+            this._backoffAttempt = 0;
+            this.driveTier1().then(() => { }, () => { });
+        }, POST_EXHAUSTED_RETRY_INTERVAL_MS);
     }
-    startConfigFileTunnel() {
-        return new Promise((resolve, reject) => {
-            const configFile = this.config.configFile;
-            const hostname = this.config.hostname;
-            if (!fs.existsSync(configFile)) {
-                reject(new Error(`Tunnel config file not found: ${configFile}`));
-                return;
-            }
-            // Spawn cloudflared directly with the config file
-            const child = spawn(bin, ['tunnel', '--config', configFile, 'run'], {
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
-            let resolved = false;
-            let stderrBuffer = '';
-            const timeout = setTimeout(() => {
-                if (!resolved) {
-                    resolved = true;
-                    // Named tunnels with config files don't emit a URL — the URL is the hostname
-                    if (hostname) {
-                        const url = `https://${hostname}`;
-                        this._state.url = url;
-                        this._state.startedAt = new Date().toISOString();
-                        this.saveState();
-                        this.emit('url', url);
-                        resolve(url);
-                    }
-                    else {
-                        reject(new Error('Named tunnel timed out and no hostname configured'));
-                    }
-                }
-            }, 15_000);
-            // Watch stderr for connection established messages
-            child.stderr.on('data', (data) => {
-                const line = data.toString();
-                stderrBuffer += line;
-                // cloudflared logs connection info to stderr
-                if (line.includes('Registered tunnel connection') || line.includes('Connection registered')) {
-                    if (!resolved && hostname) {
-                        resolved = true;
-                        clearTimeout(timeout);
-                        const url = `https://${hostname}`;
-                        this._state.url = url;
-                        this._state.startedAt = new Date().toISOString();
-                        this.saveState();
-                        this.emit('url', url);
-                        resolve(url);
-                    }
-                }
-            });
-            child.on('error', (err) => {
-                if (!resolved) {
-                    resolved = true;
-                    clearTimeout(timeout);
-                    reject(new Error(`Failed to start config-file tunnel: ${err.message}`));
-                }
-            });
-            child.on('exit', (code) => {
-                if (!this._stopped) {
-                    this.tunnel = null;
-                    this._state.url = null;
-                    this.saveState();
-                    this.emit('disconnected');
-                    if (!resolved) {
-                        resolved = true;
-                        clearTimeout(timeout);
-                        const errContext = stderrBuffer.slice(-500);
-                        reject(new Error(`Config-file tunnel exited with code ${code}: ${errContext}`));
-                    }
-                    else {
-                        this.attemptReconnect();
-                    }
-                }
+    /** HTTP probe through the public URL — confirms the link actually serves. */
+    async probeReachability(url) {
+        try {
+            const controller = new AbortController();
+            const t = setTimeout(() => controller.abort(), REACHABILITY_TIMEOUT_MS);
+            const res = await this.fetcher(`${url.replace(/\/$/, '')}/health`, {
+                signal: controller.signal,
             });
-            // Store reference for cleanup — wrap in a Tunnel-like interface
-            this.tunnel = {
-                stop: () => { child.kill('SIGTERM'); },
-                once: () => { },
-                on: () => { },
-                emit: () => false,
-            };
-        });
+            clearTimeout(t);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
     }
-    saveState() {
+    // ── Persistence ──────────────────────────────────────────────────
+    persist() {
         try {
             const dir = path.dirname(this.stateFile);
-            if (!fs.existsSync(dir)) {
+            if (!fs.existsSync(dir))
                 fs.mkdirSync(dir, { recursive: true });
+            const snap = this.lifecycle.snapshot();
+            snap.lastUrl = this._legacyState.url;
+            fs.writeFileSync(this.stateFile, JSON.stringify(snap, null, 2));
+        }
+        catch {
+            // Non-critical.
+        }
+    }
+    restorePersisted() {
+        try {
+            if (!fs.existsSync(this.stateFile))
+                return;
+            const raw = fs.readFileSync(this.stateFile, 'utf-8');
+            const snap = JSON.parse(raw);
+            if (snap && typeof snap === 'object') {
+                this.lifecycle.restoreFrom(snap);
             }
-            fs.writeFileSync(this.stateFile, JSON.stringify(this._state, null, 2));
         }
         catch {
-            // Non-critical — don't crash if state save fails
+            // Corrupted state file — start fresh.
         }
     }
 }