instar 1.2.33 → 1.2.35

package/dist/tunnel/CloudflareQuickProvider.js

@@ -0,0 +1,201 @@
+/**
+ * CloudflareQuickProvider — Tier-1 zero-config Cloudflare quick tunnel.
+ *
+ * Extracted from the original `TunnelManager.startQuickTunnel()` so the
+ * manager can drive multiple providers through the common
+ * `TunnelProvider` interface. Behavior preserved verbatim where it
+ * doesn't conflict with the spec's single-owner mandate:
+ *
+ *   - Owns: spawning `cloudflared` with --config-isolation; resolving
+ *     when the quick-tunnel URL emits; tearing down on stop().
+ *   - Does NOT own: retry/backoff, reconnect-on-disconnect, failure
+ *     notification, episode/consent state. Those are the manager's
+ *     responsibility now (per
+ *     specs/dev-infrastructure/tunnel-failure-resilience.md Part 1's
+ *     "single-owner mandate" that retires the old in-provider reconnect
+ *     loop).
+ *
+ * Failure-mode classification is surfaced via the rejection Error's
+ * `message`; the manager parses to `ProviderFailureReason`. This module
+ * uses fixed substrings the manager recognizes:
+ *   - "rate-limited" (Cloudflare 429 / 1015 detected from cloudflared stderr)
+ *   - "binary-missing" (the bundled cloudflared binary path doesn't exist)
+ *   - "timeout" (URL didn't emit within the start budget)
+ *   - "process-exit code N" (child exited before URL emit)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { bin, install, Tunnel } from 'cloudflared';
+export class CloudflareQuickProvider {
+    name = 'cloudflare-quick';
+    tier = 1;
+    port;
+    stateDir;
+    startTimeoutMs;
+    constructor(opts) {
+        this.port = opts.port;
+        this.stateDir = opts.stateDir;
+        this.startTimeoutMs = opts.startTimeoutMs ?? 30_000;
+    }
+    async isAvailable() {
+        // The cloudflared npm package installs the binary on-demand via
+        // install(bin). availability == we can install or already have it.
+        // We don't actually do the install here; we just confirm the path
+        // is resolvable. Install happens during start().
+        return typeof bin === 'string' && bin.length > 0;
+    }
+    start(localPort) {
+        // localPort overrides constructor-time port for flexibility, but we
+        // default to the constructor value.
+        const port = localPort || this.port;
+        return new Promise((resolve, reject) => {
+            void this.startInner(port, resolve, reject);
+        });
+    }
+    async startInner(port, resolve, reject) {
+        try {
+            if (!fs.existsSync(bin)) {
+                try {
+                    await install(bin);
+                }
+                catch (installErr) {
+                    reject(new Error(`binary-missing: cloudflared install failed: ${installErr.message}`));
+                    return;
+                }
+            }
+        }
+        catch {
+            reject(new Error('binary-missing: cloudflared binary path unresolvable'));
+            return;
+        }
+        const localUrl = `http://127.0.0.1:${port}`;
+        let tunnel;
+        try {
+            // Empty config to prevent cloudflared from reading
+            // ~/.cloudflared/config.yml, whose named-tunnel ingress rules
+            // would override the quick-tunnel's --url proxy. Preserved from
+            // the original implementation.
+            const emptyConfig = path.join(this.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');
+            tunnel = Tunnel.quick(localUrl, { '--config': emptyConfig });
+        }
+        catch (err) {
+            reject(new Error(`process-exit: failed to spawn cloudflared: ${err.message}`));
+            return;
+        }
+        let resolved = false;
+        let urlEmitted = null;
+        let stderrTail = '';
+        const timeout = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                try {
+                    tunnel.stop();
+                }
+                catch { /* may already be dead */ }
+                reject(new Error('timeout: cloudflared quick tunnel did not emit a URL within the start budget'));
+            }
+        }, this.startTimeoutMs);
+        tunnel.once('url', (url) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timeout);
+            urlEmitted = url;
+            resolve({
+                url,
+                stop: () => this.stopHandle(tunnel),
+            });
+        });
+        tunnel.on('error', (err) => {
+            // Capture stderr-ish context. The cloudflared npm wrapper emits
+            // 'error' for child exit failures; we use the message as is.
+            stderrTail = (stderrTail + ' ' + (err?.message ?? '')).slice(-500);
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timeout);
+                reject(this.classifyError(err?.message ?? '', stderrTail));
+            }
+            // After resolution, we do NOT auto-reconnect. The manager owns
+            // disconnect handling per the single-owner mandate.
+        });
+        tunnel.on('exit', (code) => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timeout);
+                const msg = code === 0
+                    ? 'process-exit: cloudflared exited cleanly before URL emission'
+                    : `process-exit code ${code}: ${stderrTail || 'no stderr captured'}`;
+                reject(this.classifyError(msg, stderrTail));
+            }
+            // Post-resolution exits are surfaced to the manager via the
+            // handle's lifecycle. (The handle itself doesn't reconnect.)
+        });
+        // urlEmitted is referenced only inside the closure above; this
+        // suppresses an unused-variable lint while documenting intent.
+        void urlEmitted;
+    }
+    classifyError(msg, stderr) {
+        const haystack = `${msg} ${stderr}`.toLowerCase();
+        // Cloudflare's quick-tunnel rate-limit surfaces as 429 / error 1015.
+        // Both substrings appear in cloudflared's stderr on rate-limit.
+        if (haystack.includes('429') || haystack.includes('1015') || haystack.includes('rate limit') || haystack.includes('too many requests')) {
+            return new Error(`rate-limited: cloudflared quick-tunnel rate-limited (${msg})`);
+        }
+        if (haystack.includes('enoent') || haystack.includes('not found') || haystack.includes('binary-missing')) {
+            return new Error(`binary-missing: ${msg}`);
+        }
+        if (haystack.includes('dns') || haystack.includes('eai_again') || haystack.includes('econnrefused') || haystack.includes('network')) {
+            return new Error(`network: ${msg}`);
+        }
+        // Preserve as-is so the manager's classifier sees the original prefix.
+        return new Error(msg);
+    }
+    async stopHandle(tunnel) {
+        // Force-stop with PID escalation, mirroring TunnelManager.forceStop's
+        // SIGINT → SIGKILL pattern. This is security-load-bearing per spec
+        // Part 5 (relay teardown must guarantee the child process dies).
+        const proc = tunnel.process;
+        const pid = proc?.pid;
+        try {
+            tunnel.stop();
+        }
+        catch { /* may already be dead */ }
+        if (!pid)
+            return;
+        // Poll for exit; escalate to SIGKILL after 5s.
+        const timeoutMs = 5_000;
+        const exited = await new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), timeoutMs);
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                clearTimeout(timer);
+                resolve(true);
+                return;
+            }
+            const poll = setInterval(() => {
+                try {
+                    process.kill(pid, 0);
+                }
+                catch {
+                    clearInterval(poll);
+                    clearTimeout(timer);
+                    resolve(true);
+                }
+            }, 200);
+        });
+        if (!exited) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch { /* already dead */ }
+        }
+    }
+}
+//# sourceMappingURL=CloudflareQuickProvider.js.map

package/dist/tunnel/CloudflareQuickProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudflareQuickProvider.js","sourceRoot":"","sources":["../../src/tunnel/CloudflareQuickProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAiBnD,MAAM,OAAO,uBAAuB;IACzB,IAAI,GAAiB,kBAAkB,CAAC;IACxC,IAAI,GAAiB,CAAC,CAAC;IAEf,IAAI,CAAS;IACb,QAAQ,CAAS;IACjB,cAAc,CAAS;IAExC,YAAY,IAAoC;QAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,WAAW;QACf,gEAAgE;QAChE,mEAAmE;QACnE,kEAAkE;QAClE,iDAAiD;QACjD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,SAAiB;QACrB,oEAAoE;QACpE,oCAAoC;QACpC,MAAM,IAAI,GAAG,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC;QACpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,KAAK,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,UAAU,CACtB,IAAY,EACZ,OAA0C,EAC1C,MAA4B;QAE5B,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;gBACrB,CAAC;gBAAC,OAAO,UAAU,EAAE,CAAC;oBACpB,MAAM,CAAC,IAAI,KAAK,CAAC,+CAAgD,UAAoB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;oBAClG,OAAO;gBACT,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC,CAAC;YAC1E,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,oBAAoB,IAAI,EAAE,CAAC;QAC5C,IAAI,MAAc,CAAC;QAEnB,IAAI,CAAC;YACH,mDAAmD;YACnD,8DAA8D;YAC9D,gEAAgE;YAChE,+BAA+B;YAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,uBAAuB,CAAC,CAAC;YACtE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;YACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,CAAC;YACD,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,qCAAqC,CAAC,CAAC;YACrE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,KAAK,CAAC,8CAA+C,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC1F,OAAO;QACT,CAAC;QAED,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,UAAU,GAAkB,IAAI,CAAC;QACrC,IAAI,UAAU,GAAG,EAAE,CAAC;QAEpB,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC;gBAChB,IAAI,CAAC;oBAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;gBAC1D,MAAM,CAAC,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC,CAAC;YACpG,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAExB,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE;YACjC,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,UAAU,GAAG,GAAG,CAAC;YACjB,OAAO,CAAC;gBACN,GAAG;gBACH,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;aACpC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAChC,gEAAgE;YAChE,6DAA6D;YAC7D,UAAU,GAAG,CAAC,UAAU,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;YACnE,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC;gBAChB,YAAY,CAAC,OAAO,CAAC,CAAC;gBACtB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;YAC7D,CAAC;YACD,+DAA+D;YAC/D,oDAAoD;QACtD,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAmB,EAAE,EAAE;YACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC;gBAChB,YAAY,CAAC,OAAO,CAAC,CAAC;gBACtB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC;oBACpB,CAAC,CAAC,8DAA8D;oBAChE,CAAC,CAAC,qBAAqB,IAAI,KAAK,UAAU,IAAI,oBAAoB,EAAE,CAAC;gBACvE,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;YAC9C,CAAC;YACD,4DAA4D;YAC5D,6DAA6D;QAC/D,CAAC,CAAC,CAAC;QAEH,+DAA+D;QAC/D,+DAA+D;QAC/D,KAAK,UAAU,CAAC;IAClB,CAAC;IAEO,aAAa,CAAC,GAAW,EAAE,MAAc;QAC/C,MAAM,QAAQ,GAAG,GAAG,GAAG,IAAI,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC;QAClD,qEAAqE;QACrE,gEAAgE;QAChE,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACvI,OAAO,IAAI,KAAK,CAAC,wDAAwD,GAAG,GAAG,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACzG,OAAO,IAAI,KAAK,CAAC,mBAAmB,GAAG,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACpI,OAAO,IAAI,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,uEAAuE;QACvE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,MAAc;QACrC,sEAAsE;QACtE,mEAAmE;QACnE,iEAAiE;QACjE,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,CAAC;QACtB,IAAI,CAAC;YAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;QAC1D,IAAI,CAAC,GAAG;YAAE,OAAO;QAEjB,+CAA+C;QAC/C,MAAM,SAAS,GAAG,KAAK,CAAC;QACxB,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;YACpD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;YAC1D,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBACvB,CAAC;gBAAC,MAAM,CAAC;oBACP,aAAa,CAAC,IAAI,CAAC,CAAC;oBACpB,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,OAAO,CAAC,IAAI,CAAC,CAAC;gBAChB,CAAC;YACH,CAAC,EAAE,GAAG,CAAC,CAAC;QACV,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,CAAC;gBAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;CACF"}

package/dist/tunnel/TunnelLifecycle.d.ts

@@ -0,0 +1,190 @@
+/**
+ * TunnelLifecycle — single-owner state machine for the tunnel layer.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 2.
+ *
+ * This module owns the detect → attempt → fall-back → notify → self-heal
+ * lifecycle. The existing server.ts startup-retry ladder, background-
+ * retry ladder, and Lifeline failure message are retired in favor of
+ * routing all retry through here.
+ *
+ * Design properties:
+ *   - Single-writer transitions: every state change goes through
+ *     `transition(expectedFrom, to)`, a compare-and-swap that REJECTS
+ *     any transition whose expectedFrom doesn't match the current
+ *     state. This prevents the error+exit double-handler race that the
+ *     concurrency reviewer surfaced.
+ *   - Monotonic epoch: each guarded transition carries a `transition.id`
+ *     for downstream notification dedup. Notifications are emitted ONLY
+ *     from inside the guarded mutation, tagged with the epoch.
+ *   - Episode model: each contiguous failure→recovery cycle is an
+ *     `episode` with its own id and one-time consent nonce. All consent
+ *     state binds to (episodeId, provider, ownerId, chatId, messageId,
+ *     issuedAt).
+ *
+ * This module is provider-agnostic and notification-channel-agnostic.
+ * Providers are injected as a pool; the notifier is injected as a sink.
+ * Both responsibilities live OUTSIDE this module per the spec's
+ * separation of concerns.
+ */
+import { EventEmitter } from 'node:events';
+import type { ProviderFailureReason, ProviderName } from './TunnelProvider.js';
+export type TunnelLifecycleState = 
+/** No tunnel running and not currently trying. */
+'idle'
+/** A start attempt is in flight on some provider. */
+ | 'starting'
+/** A provider is up; URL is being served. */
+ | 'active'
+/** A Tier-1 provider failed and we are backing off / trying the next one. */
+ | 'retrying'
+/** All Tier-1 providers exhausted; awaiting owner consent for a Tier-2 relay. */
+ | 'awaiting-consent'
+/** A Tier-2 relay provider is up; URL being served via the relay. */
+ | 'relay-active'
+/** Cloudflare recovery probe verifying Tier-1 is back; switch-back imminent. */
+ | 'self-healing'
+/** All providers exhausted (or consent declined); background self-heal is the only retry mechanism. */
+ | 'exhausted';
+export interface Episode {
+    /** Stable per-failure-cycle id. Resets each time the manager enters `starting` from `idle`/`active`. */
+    episodeId: string;
+    /** When this episode began (ISO timestamp). */
+    startedAt: string;
+    /** Number of Tier-1 providers attempted in this episode. */
+    tier1Attempts: number;
+    /** Last classified failure reason (the most recent provider failure). */
+    lastFailureReason: ProviderFailureReason | null;
+    /** Which provider names have been attempted in this episode (in order). */
+    attemptedProviders: ProviderName[];
+}
+export interface ConsentRecord {
+    /** Tied to the episode that issued the prompt. */
+    episodeId: string;
+    /** Which Tier-2 provider the consent authorizes. Single-use, per-provider. */
+    provider: 'localtunnel' | 'bore';
+    /** Owner principal id (Telegram user id). Non-owner clicks are rejected. */
+    ownerId: string;
+    /** Telegram chat the consent was issued in (DM chat id). */
+    chatId: string;
+    /** Telegram message id of the inline-button prompt. */
+    messageId: string;
+    /** 128-bit CSPRNG nonce carried in callback_data. Atomic compare-and-delete on use. */
+    nonce: string;
+    /** Issued-at (ms epoch). Combined with consentTimeoutMs to expire. */
+    issuedAt: number;
+}
+export interface ConsentCooldownState {
+    /** Count of consecutive declines/timeouts feeding the exponential backoff. */
+    consecutiveRefusals: number;
+    /** When the cooldown was last extended (ms epoch). */
+    lastExtendedAt: number;
+    /** Until when the cooldown is active (ms epoch). 0 = no cooldown. */
+    activeUntil: number;
+}
+export interface PersistedTunnelState {
+    /** Schema version for safe future migrations. */
+    version: 1;
+    /** Last observed state. Used by the boot-recovery path. */
+    lastState: TunnelLifecycleState;
+    /** Last active URL (if any) — for diagnostic only; never trusted as live. */
+    lastUrl: string | null;
+    /** Name of the provider that was active when state was persisted. */
+    activeProvider: ProviderName | null;
+    /**
+     * Set to true the moment a Tier-2 relay-active state is entered. Cleared
+     * only after `authToken`/PIN rotation succeeds. If the agent crashes
+     * mid-relay-episode, this flag tells the boot-recovery path "rotate
+     * BEFORE accepting any API traffic on the new boot" — per spec Part 6.
+     */
+    rotationPending: boolean;
+    /** Cross-episode consent cooldown counter. */
+    consentCooldown: ConsentCooldownState;
+    /** Current episode, if any. */
+    episode: Episode | null;
+    /** Saved-at timestamp (ISO). */
+    savedAt: string;
+}
+export interface TransitionEvent {
+    /** Monotonic per-manager-instance epoch — never reset. Used by notifiers for dedup. */
+    epoch: number;
+    /** State BEFORE this transition. */
+    from: TunnelLifecycleState;
+    /** State AFTER this transition. */
+    to: TunnelLifecycleState;
+    /** Episode in effect at the time of the transition. */
+    episode: Episode | null;
+    /** Last classified failure (when relevant). */
+    lastFailureReason: ProviderFailureReason | null;
+    /** When (ms epoch). */
+    at: number;
+}
+export type TunnelLifecycleEvents = {
+    /** Fires on every successful guarded transition. */
+    transition: (e: TransitionEvent) => void;
+};
+/** Classify a provider failure based on the Error's `message`. */
+export declare function classifyFailure(err: unknown): ProviderFailureReason;
+/** Generate a fresh 128-bit CSPRNG nonce as hex (32 chars). */
+export declare function generateNonce(): string;
+/** Generate a fresh episode id (16-byte hex, no PII). */
+export declare function generateEpisodeId(): string;
+export declare function isValidTransition(from: TunnelLifecycleState, to: TunnelLifecycleState): boolean;
+export declare class TunnelLifecycle extends EventEmitter {
+    private _state;
+    private _epoch;
+    private _episode;
+    private _lastFailureReason;
+    private _activeProvider;
+    private _consentCooldown;
+    private _rotationPending;
+    get state(): TunnelLifecycleState;
+    get epoch(): number;
+    get episode(): Episode | null;
+    get activeProvider(): ProviderName | null;
+    get rotationPending(): boolean;
+    get consentCooldown(): ConsentCooldownState;
+    get lastFailureReason(): ProviderFailureReason | null;
+    /**
+     * Compare-and-swap transition. Returns true if the transition was
+     * accepted; false if the current state didn't match `expectedFrom`
+     * (caller MUST treat false as a race — the lifecycle moved
+     * underneath them — and re-read state).
+     *
+     * `to` must be reachable from `expectedFrom` per VALID_TRANSITIONS;
+     * an invalid pair throws (programming error, not a runtime race).
+     */
+    transition(expectedFrom: TunnelLifecycleState, to: TunnelLifecycleState, ctx?: {
+        episode?: Episode | null;
+        activeProvider?: ProviderName | null;
+        lastFailureReason?: ProviderFailureReason | null;
+        rotationPending?: boolean;
+    }): boolean;
+    /** Begin a new failure-recovery episode. Called when entering `starting` from `idle` or `active`. */
+    startEpisode(): Episode;
+    /** Close out the current episode (called when returning to `active` or `idle`). */
+    endEpisode(): void;
+    /** Record a Tier-1 provider failure attempt against the current episode. */
+    recordAttempt(provider: ProviderName, reason: ProviderFailureReason): void;
+    /** Apply an exponential consent cooldown after a decline / timeout. */
+    recordConsentRefusal(): ConsentCooldownState;
+    /** Clear cooldown — called on explicit owner opt-in or fresh post-cooldown episode. */
+    clearConsentCooldown(): void;
+    /** True if the consent prompt is currently suppressed by the cooldown. */
+    isConsentSuppressed(now?: number): boolean;
+    /** Snapshot current state for persistence to tunnel.json. */
+    snapshot(): PersistedTunnelState;
+    /**
+     * Restore from a persisted snapshot. Called at boot ONLY for the
+     * cooldown counter + rotationPending flag — the state itself is NOT
+     * resumed (every boot starts at `idle` and re-enters `starting` from
+     * scratch). The rotationPending flag triggers a rotation-before-
+     * traffic in the boot-recovery path; rotation clears the flag.
+     */
+    restoreFrom(snapshot: PersistedTunnelState): void;
+    /** Set the rotation-pending flag (entered on `relay-active`; cleared after rotation). */
+    setRotationPending(value: boolean): void;
+    /** Used by callers (manager) that need to validate a consent-reply against the active state. */
+    isAwaitingConsent(): boolean;
+}
+//# sourceMappingURL=TunnelLifecycle.d.ts.map

package/dist/tunnel/TunnelLifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelLifecycle.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAkB,qBAAqB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAI/F,MAAM,MAAM,oBAAoB;AAC9B,kDAAkD;AAChD,MAAM;AACR,qDAAqD;GACnD,UAAU;AACZ,6CAA6C;GAC3C,QAAQ;AACV,6EAA6E;GAC3E,UAAU;AACZ,iFAAiF;GAC/E,kBAAkB;AACpB,qEAAqE;GACnE,cAAc;AAChB,gFAAgF;GAC9E,cAAc;AAChB,uGAAuG;GACrG,WAAW,CAAC;AAEhB,MAAM,WAAW,OAAO;IACtB,wGAAwG;IACxG,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,iBAAiB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAChD,2EAA2E;IAC3E,kBAAkB,EAAE,YAAY,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC;IACjC,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,OAAO,EAAE,CAAC,CAAC;IACX,2DAA2D;IAC3D,SAAS,EAAE,oBAAoB,CAAC;IAChC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qEAAqE;IACrE,cAAc,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,8CAA8C;IAC9C,eAAe,EAAE,oBAAoB,CAAC;IACtC,+BAA+B;IAC/B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,mCAAmC;IACnC,EAAE,EAAE,oBAAoB,CAAC;IACzB,uDAAuD;IACvD,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,+CAA+C;IAC/C,iBAAiB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAChD,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,oDAAoD;IACpD,UAAU,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;CAC1C,CAAC;AAIF,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CAqBnE;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAgBD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,oBAAoB,EAAE,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAI/F;AAED,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,kBAAkB,CAAsC;IAChE,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,gBAAgB,CAItB;IACF,OAAO,CAAC,gBAAgB,CAAS;IAEjC,IAAI,KAAK,IAAI,oBAAoB,CAAwB;IACzD,IAAI,KAAK,IAAI,MAAM,CAAwB;IAC3C,IAAI,OAAO,IAAI,OAAO,GAAG,IAAI,CAA0B;IACvD,IAAI,cAAc,IAAI,YAAY,GAAG,IAAI,CAAiC;IAC1E,IAAI,eAAe,IAAI,OAAO,CAAkC;IAChE,IAAI,eAAe,IAAI,oBAAoB,CAAyC;IACpF,IAAI,iBAAiB,IAAI,qBAAqB,GAAG,IAAI,CAAoC;IAEzF;;;;;;;;OAQG;IACH,UAAU,CAAC,YAAY,EAAE,oBAAoB,EAAE,EAAE,EAAE,oBAAoB,EAAE,GAAG,CAAC,EAAE;QAC7E,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QACzB,cAAc,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;QACrC,iBAAiB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;QACjD,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,OAAO;IA4BX,qGAAqG;IACrG,YAAY,IAAI,OAAO;IAYvB,mFAAmF;IACnF,UAAU,IAAI,IAAI;IAIlB,4EAA4E;IAC5E,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,qBAAqB,GAAG,IAAI;IAQ1E,uEAAuE;IACvE,oBAAoB,IAAI,oBAAoB;IAa5C,uFAAuF;IACvF,oBAAoB,IAAI,IAAI;IAI5B,0EAA0E;IAC1E,mBAAmB,CAAC,GAAG,SAAa,GAAG,OAAO;IAI9C,6DAA6D;IAC7D,QAAQ,IAAI,oBAAoB;IAahC;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAOjD,yFAAyF;IACzF,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAIxC,gGAAgG;IAChG,iBAAiB,IAAI,OAAO;CAG7B"}

package/dist/tunnel/TunnelLifecycle.js

@@ -0,0 +1,222 @@
+/**
+ * TunnelLifecycle — single-owner state machine for the tunnel layer.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 2.
+ *
+ * This module owns the detect → attempt → fall-back → notify → self-heal
+ * lifecycle. The existing server.ts startup-retry ladder, background-
+ * retry ladder, and Lifeline failure message are retired in favor of
+ * routing all retry through here.
+ *
+ * Design properties:
+ *   - Single-writer transitions: every state change goes through
+ *     `transition(expectedFrom, to)`, a compare-and-swap that REJECTS
+ *     any transition whose expectedFrom doesn't match the current
+ *     state. This prevents the error+exit double-handler race that the
+ *     concurrency reviewer surfaced.
+ *   - Monotonic epoch: each guarded transition carries a `transition.id`
+ *     for downstream notification dedup. Notifications are emitted ONLY
+ *     from inside the guarded mutation, tagged with the epoch.
+ *   - Episode model: each contiguous failure→recovery cycle is an
+ *     `episode` with its own id and one-time consent nonce. All consent
+ *     state binds to (episodeId, provider, ownerId, chatId, messageId,
+ *     issuedAt).
+ *
+ * This module is provider-agnostic and notification-channel-agnostic.
+ * Providers are injected as a pool; the notifier is injected as a sink.
+ * Both responsibilities live OUTSIDE this module per the spec's
+ * separation of concerns.
+ */
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+// ── Helpers ──────────────────────────────────────────────────────────
+/** Classify a provider failure based on the Error's `message`. */
+export function classifyFailure(err) {
+    const msg = (err instanceof Error ? err.message : String(err ?? '')).toLowerCase();
+    if (msg.startsWith('rate-limited') || msg.includes('rate limit') || msg.includes('429') || msg.includes('1015')) {
+        return 'rate-limited';
+    }
+    if (msg.startsWith('binary-missing') || msg.includes('not installed') || msg.includes('enoent')) {
+        return 'binary-missing';
+    }
+    if (msg.startsWith('network') || msg.includes('dns') || msg.includes('econnrefused') || msg.includes('eai_again')) {
+        return 'network';
+    }
+    if (msg.startsWith('timeout') || msg.includes('timed out')) {
+        return 'timeout';
+    }
+    if (msg.startsWith('reachability-failed')) {
+        return 'reachability-failed';
+    }
+    if (msg.includes('process-exit') || msg.includes('exited')) {
+        return 'process-exit';
+    }
+    return 'unknown';
+}
+/** Generate a fresh 128-bit CSPRNG nonce as hex (32 chars). */
+export function generateNonce() {
+    return crypto.randomBytes(16).toString('hex');
+}
+/** Generate a fresh episode id (16-byte hex, no PII). */
+export function generateEpisodeId() {
+    return crypto.randomBytes(8).toString('hex');
+}
+// ── Single-writer state machine ─────────────────────────────────────
+/** Valid transitions per the spec's state machine. */
+const VALID_TRANSITIONS = new Map([
+    ['idle', new Set(['starting'])],
+    ['starting', new Set(['active', 'retrying', 'awaiting-consent', 'exhausted', 'idle'])],
+    ['active', new Set(['retrying', 'idle'])],
+    ['retrying', new Set(['active', 'starting', 'awaiting-consent', 'exhausted', 'idle'])],
+    ['awaiting-consent', new Set(['relay-active', 'starting', 'active', 'exhausted', 'idle'])],
+    ['relay-active', new Set(['self-healing', 'idle', 'exhausted'])],
+    ['self-healing', new Set(['active', 'relay-active', 'exhausted', 'idle'])],
+    ['exhausted', new Set(['self-healing', 'starting', 'idle'])],
+]);
+export function isValidTransition(from, to) {
+    if (from === to)
+        return false;
+    const allowed = VALID_TRANSITIONS.get(from);
+    return !!allowed && allowed.has(to);
+}
+export class TunnelLifecycle extends EventEmitter {
+    _state = 'idle';
+    _epoch = 0;
+    _episode = null;
+    _lastFailureReason = null;
+    _activeProvider = null;
+    _consentCooldown = {
+        consecutiveRefusals: 0,
+        lastExtendedAt: 0,
+        activeUntil: 0,
+    };
+    _rotationPending = false;
+    get state() { return this._state; }
+    get epoch() { return this._epoch; }
+    get episode() { return this._episode; }
+    get activeProvider() { return this._activeProvider; }
+    get rotationPending() { return this._rotationPending; }
+    get consentCooldown() { return { ...this._consentCooldown }; }
+    get lastFailureReason() { return this._lastFailureReason; }
+    /**
+     * Compare-and-swap transition. Returns true if the transition was
+     * accepted; false if the current state didn't match `expectedFrom`
+     * (caller MUST treat false as a race — the lifecycle moved
+     * underneath them — and re-read state).
+     *
+     * `to` must be reachable from `expectedFrom` per VALID_TRANSITIONS;
+     * an invalid pair throws (programming error, not a runtime race).
+     */
+    transition(expectedFrom, to, ctx) {
+        if (this._state !== expectedFrom) {
+            return false; // CAS lost
+        }
+        if (!isValidTransition(expectedFrom, to)) {
+            throw new Error(`invalid transition ${expectedFrom} → ${to}`);
+        }
+        // Apply mutation atomically (Node is single-threaded; this synchronous
+        // block IS the critical section).
+        this._state = to;
+        this._epoch += 1;
+        if (ctx?.episode !== undefined)
+            this._episode = ctx.episode;
+        if (ctx?.activeProvider !== undefined)
+            this._activeProvider = ctx.activeProvider;
+        if (ctx?.lastFailureReason !== undefined)
+            this._lastFailureReason = ctx.lastFailureReason;
+        if (ctx?.rotationPending !== undefined)
+            this._rotationPending = ctx.rotationPending;
+        const event = {
+            epoch: this._epoch,
+            from: expectedFrom,
+            to,
+            episode: this._episode,
+            lastFailureReason: this._lastFailureReason,
+            at: Date.now(),
+        };
+        this.emit('transition', event);
+        return true;
+    }
+    /** Begin a new failure-recovery episode. Called when entering `starting` from `idle` or `active`. */
+    startEpisode() {
+        const ep = {
+            episodeId: generateEpisodeId(),
+            startedAt: new Date().toISOString(),
+            tier1Attempts: 0,
+            lastFailureReason: null,
+            attemptedProviders: [],
+        };
+        this._episode = ep;
+        return ep;
+    }
+    /** Close out the current episode (called when returning to `active` or `idle`). */
+    endEpisode() {
+        this._episode = null;
+    }
+    /** Record a Tier-1 provider failure attempt against the current episode. */
+    recordAttempt(provider, reason) {
+        if (!this._episode)
+            return;
+        this._episode.tier1Attempts += 1;
+        this._episode.lastFailureReason = reason;
+        this._episode.attemptedProviders.push(provider);
+        this._lastFailureReason = reason;
+    }
+    /** Apply an exponential consent cooldown after a decline / timeout. */
+    recordConsentRefusal() {
+        this._consentCooldown.consecutiveRefusals += 1;
+        const n = this._consentCooldown.consecutiveRefusals;
+        // 1h → 4h → 24h, then 24h forever
+        const COOLDOWNS_MS = [60 * 60_000, 4 * 60 * 60_000, 24 * 60 * 60_000];
+        const idx = Math.min(n - 1, COOLDOWNS_MS.length - 1);
+        const ms = COOLDOWNS_MS[idx] ?? COOLDOWNS_MS[COOLDOWNS_MS.length - 1];
+        if (ms === undefined)
+            throw new Error('unreachable: cooldown table empty');
+        this._consentCooldown.lastExtendedAt = Date.now();
+        this._consentCooldown.activeUntil = Date.now() + ms;
+        return this.consentCooldown;
+    }
+    /** Clear cooldown — called on explicit owner opt-in or fresh post-cooldown episode. */
+    clearConsentCooldown() {
+        this._consentCooldown = { consecutiveRefusals: 0, lastExtendedAt: 0, activeUntil: 0 };
+    }
+    /** True if the consent prompt is currently suppressed by the cooldown. */
+    isConsentSuppressed(now = Date.now()) {
+        return this._consentCooldown.activeUntil > now;
+    }
+    /** Snapshot current state for persistence to tunnel.json. */
+    snapshot() {
+        return {
+            version: 1,
+            lastState: this._state,
+            lastUrl: null, // populated by the manager that knows the URL
+            activeProvider: this._activeProvider,
+            rotationPending: this._rotationPending,
+            consentCooldown: this.consentCooldown,
+            episode: this._episode ? { ...this._episode, attemptedProviders: [...this._episode.attemptedProviders] } : null,
+            savedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Restore from a persisted snapshot. Called at boot ONLY for the
+     * cooldown counter + rotationPending flag — the state itself is NOT
+     * resumed (every boot starts at `idle` and re-enters `starting` from
+     * scratch). The rotationPending flag triggers a rotation-before-
+     * traffic in the boot-recovery path; rotation clears the flag.
+     */
+    restoreFrom(snapshot) {
+        this._consentCooldown = { ...snapshot.consentCooldown };
+        this._rotationPending = snapshot.rotationPending;
+        // _state stays 'idle' by design — boot recovery rotation runs before
+        // the new lifecycle starts.
+    }
+    /** Set the rotation-pending flag (entered on `relay-active`; cleared after rotation). */
+    setRotationPending(value) {
+        this._rotationPending = value;
+    }
+    /** Used by callers (manager) that need to validate a consent-reply against the active state. */
+    isAwaitingConsent() {
+        return this._state === 'awaiting-consent';
+    }
+}
+//# sourceMappingURL=TunnelLifecycle.js.map

package/dist/tunnel/TunnelLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelLifecycle.js","sourceRoot":"","sources":["../../src/tunnel/TunnelLifecycle.ts"],"names":[],"mappings":"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"}