instar 1.2.34 → 1.2.36

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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"}

package/dist/tunnel/TunnelManager.d.ts

@@ -1,46 +1,68 @@
 /**
- * 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 { type PersistedTunnelState } from './TunnelLifecycle.js';
+import type { TunnelProvider, ProviderFailureReason } from './TunnelProvider.js';
+import type { NotifierSink } from './TunnelNotifier.js';
 export interface TunnelConfig {
-    /** Whether tunnel is enabled */
+    /** Whether tunnel is enabled. */
     enabled: boolean;
-    /** Tunnel type: 'quick' (ephemeral, no account) or 'named' (persistent, requires token) */
+    /** Tunnel type: 'quick' (ephemeral, no account) or 'named' (persistent, requires token). */
     type: 'quick' | 'named';
-    /** Cloudflare tunnel token (required for named tunnels using token auth) */
+    /** Cloudflare tunnel token (named, token-auth). */
     token?: string;
-    /** Config file path for named tunnels using credentials file auth */
+    /** Config file path (named, config-file-auth). */
     configFile?: string;
-    /** Public hostname for named tunnels (e.g., echo.dawn-tunnel.dev) */
+    /** Public hostname for named tunnels. */
     hostname?: string;
-    /** Local port to tunnel to */
+    /** Local port to tunnel to. */
     port: number;
-    /** State directory for persisting tunnel info */
+    /** State directory for persisting tunnel.json. */
     stateDir: string;
 }
 export interface TunnelState {
-    /** Current tunnel URL (null if not connected) */
     url: string | null;
-    /** Tunnel type */
     type: 'quick' | 'named';
-    /** When the tunnel was started */
     startedAt: string | null;
-    /** Connection info from cloudflared */
     connectionId?: string;
-    /** Connection location */
     connectionLocation?: string;
 }
 export interface TunnelEvents {
@@ -54,60 +76,75 @@ export interface TunnelEvents {
     error: (error: Error) => void;
     stopped: () => void;
 }
+/** Optional injections for testability. */
+export interface TunnelManagerInjections {
+    providers?: TunnelProvider[];
+    notifierSink?: NotifierSink;
+    fetch?: typeof fetch;
+}
 export declare class TunnelManager extends EventEmitter {
-    private config;
-    private tunnel;
-    private stateFile;
-    private _state;
-    private _stopped;
+    private readonly config;
+    private readonly stateFile;
+    private readonly lifecycle;
+    private readonly providers;
+    private readonly notifier;
+    private readonly fetcher;
+    private currentHandle;
+    private currentProviderName;
+    private _legacyState;
     private _autoReconnect;
-    private _reconnectTimer;
-    private _reconnectAttempt;
+    private _stopped;
     private _startPromise;
-    private static readonly MAX_RECONNECT_ATTEMPTS;
-    private static readonly BASE_RECONNECT_DELAY_MS;
-    private static readonly MAX_RECONNECT_DELAY_MS;
-    constructor(config: TunnelConfig);
-    /** Current tunnel URL, or null if not connected */
+    private _backoffAttempt;
+    private _backoffTimer;
+    private _postExhaustedTimer;
+    constructor(config: TunnelConfig, injections?: TunnelManagerInjections);
     get url(): string | null;
-    /** Whether the tunnel is currently running */
     get isRunning(): boolean;
-    /** Current tunnel state */
     get state(): TunnelState;
+    /** Additive new accessor — lifecycle snapshot. */
+    get lifecycleState(): PersistedTunnelState;
     /**
-     * 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.
      */
     start(): Promise<string>;
-    /**
-     * Stop the tunnel gracefully. Intentional stops disable auto-reconnect.
-     */
     stop(): Promise<void>;
-    /**
-     * 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.
-     */
-    forceStop(timeoutMs?: number): Promise<void>;
-    /**
-     * Enable automatic reconnection when the tunnel disconnects unexpectedly.
-     * Uses exponential backoff: 5s, 10s, 20s, ... up to 5 minutes, max 10 attempts.
-     */
+    /** Force-stop with escalation. Providers internally do SIGINT → SIGKILL. */
+    forceStop(_timeoutMs?: number): Promise<void>;
     enableAutoReconnect(): void;
     disableAutoReconnect(): void;
+    getExternalUrl(localPath: string): string | null;
+    private buildDefaultPool;
+    private doStart;
+    private driveTier1;
+    private exhaustedOrBackoff;
     /**
-     * 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).
      */
-    private attemptReconnect;
+    private scheduleBackgroundRetry;
+    private clearBackoffTimer;
+    private clearPostExhaustedTimer;
     /**
-     * Get the full external URL for a local path.
-     * Returns null if tunnel is not connected.
+     * 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.
      */
-    getExternalUrl(localPath: string): string | null;
-    private ensureBinary;
-    private startQuickTunnel;
-    private startNamedTunnel;
-    private startConfigFileTunnel;
-    private saveState;
+    private schedulePostExhaustedRetry;
+    /** HTTP probe through the public URL — confirms the link actually serves. */
+    private probeReachability;
+    private persist;
+    private restorePersisted;
 }
+export type { ProviderFailureReason };
 //# sourceMappingURL=TunnelManager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"TunnelManager.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQ3C,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,2FAA2F;IAC3F,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,kBAAkB;IAClB,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,kCAAkC;IAClC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,SAAS,EAAE,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAID,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAM;IACpD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACxD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAc;gBAEhD,MAAM,EAAE,YAAY;IAWhC,mDAAmD;IACnD,IAAI,GAAG,IAAI,MAAM,GAAG,IAAI,CAEvB;IAED,8CAA8C;IAC9C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,2BAA2B;IAC3B,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAyC9B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;OAIG;IACG,SAAS,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDhD;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IAI3B,oBAAoB,IAAI,IAAI;IAS5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;YASlC,YAAY;IAM1B,OAAO,CAAC,gBAAgB;IA2ExB,OAAO,CAAC,gBAAgB;IAuExB,OAAO,CAAC,qBAAqB;IAyF7B,OAAO,CAAC,SAAS;CAWlB"}
+{"version":3,"file":"TunnelManager.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelManager.ts"],"names":[],"mappings":"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"}