instar 1.2.39 → 1.2.41

package/dist/monitoring/SocketDisconnectSentinel.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SocketDisconnectSentinel — detects Claude Code's "socket connection closed
+ * unexpectedly" message in tracked sessions and runs a bounded recovery loop.
+ *
+ * Closes the gap surfaced by the joint diagnosis on 2026-05-22: the instar
+ * repo had detectors for rate limits, quota, hundreds of patterns, but zero
+ * detectors for Claude Code's own connection-drop string. When it fires, the
+ * session freezes; nothing classifies it; no recovery runs; no user-visible
+ * alert reaches the user.
+ *
+ * Pattern mirrors `RateLimitSentinel.report` → backoff → `resumeFn` →
+ * verification → escalate, but the failure shape is simpler (no Claude
+ * Code internal retries to wait out — disconnect is immediate) so the
+ * lifecycle is shorter.
+ *
+ * Spec: docs/specs/silently-stopped-trio.md
+ *
+ * Signal-vs-authority: the regex + state machine are detectors. The
+ * notifyFn path is the existing MessagingToneGate authority (called through
+ * /attention). No new blocking authority introduced.
+ */
+import { EventEmitter } from 'node:events';
+export type SocketDisconnectStatus = 'detected' | 'recovering' | 'recovered' | 'escalated';
+export interface SocketDisconnectState {
+    sessionName: string;
+    detectedAt: number;
+    attempts: number;
+    lastInjectAt: number;
+    status: SocketDisconnectStatus;
+}
+export interface SocketDisconnectSentinelDeps {
+    /**
+     * Inject a recovery nudge into the session: typically Ctrl+C then Enter.
+     * Returns whether the injection was accepted.
+     */
+    resumeFn: (sessionName: string) => Promise<boolean>;
+    /** Route a user-facing message; server.ts owns topic routing. */
+    notifyFn: (sessionName: string, text: string) => Promise<void>;
+    /** Peek at the session's most recent tmux output. Returns a string that
+     * may be empty if the session has no recent output. */
+    getRecentOutput: (sessionName: string) => string;
+    /** Override Date.now (tests). */
+    now?: () => number;
+    /** Override timer setters (tests). */
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+export interface SocketDisconnectSentinelConfig {
+    enabled?: boolean;
+    /** Backoff staircase in ms between recovery attempts. Last value repeats. */
+    backoffScheduleMs?: number[];
+    /** Max recovery attempts before escalating. Default 4. */
+    maxAttempts?: number;
+    /** How long to wait after a nudge before declaring recovery (ms). Default 60s. */
+    verifyWindowMs?: number;
+}
+/**
+ * Patterns Claude Code uses when its connection to Anthropic drops. Broad
+ * intentionally — false-positive cost is one harmless nudge; false-negative
+ * cost is the silently-stopped failure class this sentinel exists to close.
+ */
+export declare const SOCKET_DISCONNECT_PATTERNS: readonly RegExp[];
+/**
+ * Detector — true if `text` contains any known disconnect pattern.
+ */
+export declare function detectSocketDisconnect(text: string): boolean;
+export declare class SocketDisconnectSentinel extends EventEmitter {
+    private readonly deps;
+    private readonly cfg;
+    private readonly states;
+    private readonly timers;
+    constructor(deps: SocketDisconnectSentinelDeps, cfg?: SocketDisconnectSentinelConfig);
+    /** Called by the tick loop (or by an event trigger) for each tracked session. */
+    scanSession(sessionName: string): void;
+    /**
+     * Public entry: report a detected disconnect. Idempotent — second call
+     * for the same session within an active recovery is a no-op.
+     */
+    report(sessionName: string): void;
+    isRecoveryActive(sessionName: string): boolean;
+    listActive(): SocketDisconnectState[];
+    /** Cancel any in-flight recovery for this session (test + shutdown helper). */
+    clear(sessionName: string): void;
+    /** Cancel all in-flight recovery (server shutdown). */
+    shutdown(): void;
+    private scheduleNextAttempt;
+    private runAttempt;
+    private verifyAttempt;
+    private escalate;
+    private notify;
+    private setTimer;
+    private clearTimer;
+}
+//# sourceMappingURL=SocketDisconnectSentinel.d.ts.map

package/dist/monitoring/SocketDisconnectSentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocketDisconnectSentinel.d.ts","sourceRoot":"","sources":["../../src/monitoring/SocketDisconnectSentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,sBAAsB,GAC9B,UAAU,GACV,YAAY,GACZ,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,iEAAiE;IACjE,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D;2DACuD;IACvD,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IACzE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,8BAA8B;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AASD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAKvD,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM5D;AAED,qBAAa,wBAAyB,SAAQ,YAAY;IAK5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA2C;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoD;gBAE9C,IAAI,EAAE,4BAA4B,EAAE,GAAG,GAAE,8BAAmC;IAKzG,iFAAiF;IACjF,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAQtC;;;OAGG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAsBjC,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAK9C,UAAU,IAAI,qBAAqB,EAAE;IAIrC,+EAA+E;IAC/E,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAOhC,uDAAuD;IACvD,QAAQ,IAAI,IAAI;IAQhB,OAAO,CAAC,mBAAmB;YAcb,UAAU;IA2BxB,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,QAAQ;YAaF,MAAM;IAQpB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;CAGnB"}

package/dist/monitoring/SocketDisconnectSentinel.js

@@ -0,0 +1,203 @@
+/**
+ * SocketDisconnectSentinel — detects Claude Code's "socket connection closed
+ * unexpectedly" message in tracked sessions and runs a bounded recovery loop.
+ *
+ * Closes the gap surfaced by the joint diagnosis on 2026-05-22: the instar
+ * repo had detectors for rate limits, quota, hundreds of patterns, but zero
+ * detectors for Claude Code's own connection-drop string. When it fires, the
+ * session freezes; nothing classifies it; no recovery runs; no user-visible
+ * alert reaches the user.
+ *
+ * Pattern mirrors `RateLimitSentinel.report` → backoff → `resumeFn` →
+ * verification → escalate, but the failure shape is simpler (no Claude
+ * Code internal retries to wait out — disconnect is immediate) so the
+ * lifecycle is shorter.
+ *
+ * Spec: docs/specs/silently-stopped-trio.md
+ *
+ * Signal-vs-authority: the regex + state machine are detectors. The
+ * notifyFn path is the existing MessagingToneGate authority (called through
+ * /attention). No new blocking authority introduced.
+ */
+import { EventEmitter } from 'node:events';
+const DEFAULT_CONFIG = {
+    enabled: true,
+    backoffScheduleMs: [60_000, 5 * 60_000, 15 * 60_000, 30 * 60_000],
+    maxAttempts: 4,
+    verifyWindowMs: 60_000,
+};
+/**
+ * Patterns Claude Code uses when its connection to Anthropic drops. Broad
+ * intentionally — false-positive cost is one harmless nudge; false-negative
+ * cost is the silently-stopped failure class this sentinel exists to close.
+ */
+export const SOCKET_DISCONNECT_PATTERNS = [
+    /socket connection closed unexpectedly/i,
+    /websocket.*reset by peer/i,
+    /ECONNRESET.*claude/i,
+    /connection.*closed.*unexpectedly/i,
+];
+/**
+ * Detector — true if `text` contains any known disconnect pattern.
+ */
+export function detectSocketDisconnect(text) {
+    if (!text)
+        return false;
+    for (const pat of SOCKET_DISCONNECT_PATTERNS) {
+        if (pat.test(text))
+            return true;
+    }
+    return false;
+}
+export class SocketDisconnectSentinel extends EventEmitter {
+    deps;
+    cfg;
+    states = new Map();
+    timers = new Map();
+    constructor(deps, cfg = {}) {
+        super();
+        this.deps = deps;
+        this.cfg = { ...DEFAULT_CONFIG, ...cfg };
+    }
+    /** Called by the tick loop (or by an event trigger) for each tracked session. */
+    scanSession(sessionName) {
+        if (!this.cfg.enabled)
+            return;
+        if (this.states.has(sessionName))
+            return; // already handling
+        const output = this.deps.getRecentOutput(sessionName);
+        if (!detectSocketDisconnect(output))
+            return;
+        this.report(sessionName);
+    }
+    /**
+     * Public entry: report a detected disconnect. Idempotent — second call
+     * for the same session within an active recovery is a no-op.
+     */
+    report(sessionName) {
+        if (!this.cfg.enabled)
+            return;
+        if (this.states.has(sessionName))
+            return;
+        const now = (this.deps.now ?? Date.now)();
+        const state = {
+            sessionName,
+            detectedAt: now,
+            attempts: 0,
+            lastInjectAt: 0,
+            status: 'detected',
+        };
+        this.states.set(sessionName, state);
+        // First user notice — tone-gated path via notifyFn.
+        void this.notify(sessionName, `${friendlyName(sessionName)} lost its connection to Claude Code. Trying to recover; will let you know if it can't.`);
+        this.scheduleNextAttempt(sessionName);
+    }
+    isRecoveryActive(sessionName) {
+        const s = this.states.get(sessionName);
+        return !!s && s.status !== 'recovered' && s.status !== 'escalated';
+    }
+    listActive() {
+        return Array.from(this.states.values());
+    }
+    /** Cancel any in-flight recovery for this session (test + shutdown helper). */
+    clear(sessionName) {
+        const t = this.timers.get(sessionName);
+        if (t)
+            this.clearTimer(t);
+        this.timers.delete(sessionName);
+        this.states.delete(sessionName);
+    }
+    /** Cancel all in-flight recovery (server shutdown). */
+    shutdown() {
+        for (const t of this.timers.values())
+            this.clearTimer(t);
+        this.timers.clear();
+        this.states.clear();
+    }
+    // ── Recovery loop ──────────────────────────────────────────────────
+    scheduleNextAttempt(sessionName) {
+        const state = this.states.get(sessionName);
+        if (!state)
+            return;
+        if (state.attempts >= this.cfg.maxAttempts) {
+            this.escalate(sessionName);
+            return;
+        }
+        const idx = Math.min(state.attempts, this.cfg.backoffScheduleMs.length - 1);
+        const wait = this.cfg.backoffScheduleMs[idx];
+        state.status = 'recovering';
+        const handle = this.setTimer(() => this.runAttempt(sessionName), wait);
+        this.timers.set(sessionName, handle);
+    }
+    async runAttempt(sessionName) {
+        const state = this.states.get(sessionName);
+        if (!state)
+            return;
+        const now = (this.deps.now ?? Date.now)();
+        state.attempts += 1;
+        state.lastInjectAt = now;
+        let injected = false;
+        try {
+            injected = await this.deps.resumeFn(sessionName);
+        }
+        catch (err) {
+            this.emit('recovery-error', { sessionName, err });
+            injected = false;
+        }
+        if (!injected) {
+            // Nudge couldn't be delivered — escalate immediately, this isn't
+            // something a backoff staircase can fix.
+            this.escalate(sessionName);
+            return;
+        }
+        // Schedule a verify check.
+        const handle = this.setTimer(() => this.verifyAttempt(sessionName), this.cfg.verifyWindowMs);
+        this.timers.set(sessionName, handle);
+    }
+    verifyAttempt(sessionName) {
+        const state = this.states.get(sessionName);
+        if (!state)
+            return;
+        const output = this.deps.getRecentOutput(sessionName);
+        // Heuristic: if the disconnect pattern no longer appears in the recent
+        // output, the session has progressed past the freeze.
+        if (!detectSocketDisconnect(output)) {
+            state.status = 'recovered';
+            void this.notify(sessionName, `${friendlyName(sessionName)} is reconnected and back to work.`);
+            this.emit('recovered', sessionName);
+            this.clear(sessionName);
+            return;
+        }
+        // Still stuck → next attempt.
+        this.scheduleNextAttempt(sessionName);
+    }
+    escalate(sessionName) {
+        const state = this.states.get(sessionName);
+        if (!state)
+            return;
+        state.status = 'escalated';
+        const minutes = Math.max(1, Math.round(((this.deps.now ?? Date.now)() - state.detectedAt) / 60_000));
+        void this.notify(sessionName, `${friendlyName(sessionName)} has been disconnected for about ${minutes} minutes and my recovery attempts haven't worked. Want me to dig in?`);
+        this.emit('escalated', sessionName);
+        // Keep state so a subsequent scanSession doesn't re-report the same outage.
+    }
+    async notify(sessionName, text) {
+        try {
+            await this.deps.notifyFn(sessionName, text);
+        }
+        catch (err) {
+            this.emit('notify-error', { sessionName, err });
+        }
+    }
+    setTimer(fn, ms) {
+        return (this.deps.setTimer ?? setTimeout)(fn, ms);
+    }
+    clearTimer(handle) {
+        (this.deps.clearTimer ?? clearTimeout)(handle);
+    }
+}
+/** Strip prefix conventions for user-facing copy. Keeps B12 simple. */
+function friendlyName(sessionName) {
+    return sessionName.replace(/^ai\.instar\./, '').replace(/-server$/, '').replace(/-lifeline$/, '');
+}
+//# sourceMappingURL=SocketDisconnectSentinel.js.map

package/dist/monitoring/SocketDisconnectSentinel.js.map

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

package/dist/tunnel/LocaltunnelProvider.d.ts

@@ -0,0 +1,63 @@
+/**
+ * LocaltunnelProvider — Tier-2 consent-gated relay tunnel via *.loca.lt.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 1
+ * (provider abstraction, Tier 2) and Part 7 (supply-chain hardening).
+ *
+ * SECURITY POSTURE:
+ *   - localtunnel routes the agent's local server traffic through
+ *     loca.lt servers. The relay operator (and anyone who logs the URL)
+ *     can see dashboard PIN + signed view URLs while the relay is active.
+ *     This is exactly why the spec gates Tier-2 providers behind owner
+ *     consent — see Part 3 (consent flow) and Part 6 (mandatory
+ *     credential rotation on relay-episode end).
+ *   - The agent never spins this up without an explicit per-episode
+ *     consent record bound to the owner principal — that's enforced in
+ *     TunnelManager's state machine, not in this provider.
+ *
+ * Supply-chain hardening (Part 7):
+ *   - The npm package `localtunnel` is pinned at exact version in
+ *     package.json (no caret range).
+ *   - The provider spawns the localtunnel client via its programmatic
+ *     API; a future hardening PR can switch to child-process isolation
+ *     once the spec's checksum-verified install path is added.
+ *   - `isAvailable()` resolves false if the npm package cannot be
+ *     loaded, so a missing dep degrades gracefully (provider skipped)
+ *     instead of crashing.
+ *
+ * The provider does NOT own retry/reconnect/notification — those are
+ * the manager's responsibility per the single-owner mandate (PR 2).
+ */
+import type { TunnelProvider, TunnelProviderHandle, ProviderName, ProviderTier } from './TunnelProvider.js';
+export interface LocaltunnelProviderOptions {
+    /** Local port the relay should point at. */
+    port: number;
+    /** Start timeout in milliseconds (default: 20_000). */
+    startTimeoutMs?: number;
+    /**
+     * Optional subdomain hint passed to localtunnel. When set, the
+     * service will try to allocate the requested name; when unavailable
+     * (already taken or rate-limited), localtunnel falls back to a
+     * random subdomain. NEVER use the agent's identity here — the
+     * subdomain is publicly visible on *.loca.lt.
+     */
+    subdomain?: string;
+}
+export declare class LocaltunnelProvider implements TunnelProvider {
+    readonly name: ProviderName;
+    readonly tier: ProviderTier;
+    private readonly port;
+    private readonly startTimeoutMs;
+    private readonly subdomain;
+    /**
+     * Cached dynamic-import result. The first `isAvailable()` call
+     * detects whether the npm package is present; subsequent calls reuse
+     * the cached resolution.
+     */
+    private _moduleResolved;
+    constructor(opts: LocaltunnelProviderOptions);
+    isAvailable(): Promise<boolean>;
+    start(localPort: number): Promise<TunnelProviderHandle>;
+    private loadModule;
+}
+//# sourceMappingURL=LocaltunnelProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocaltunnelProvider.d.ts","sourceRoot":"","sources":["../../src/tunnel/LocaltunnelProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,0BAA0B;IACzC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkBD,qBAAa,mBAAoB,YAAW,cAAc;IACxD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAiB;IAC5C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAK;IAEhC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAgD;gBAE3D,IAAI,EAAE,0BAA0B;IAMtC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAK/B,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;YA8D/C,UAAU;CAezB"}

package/dist/tunnel/LocaltunnelProvider.js

@@ -0,0 +1,130 @@
+/**
+ * LocaltunnelProvider — Tier-2 consent-gated relay tunnel via *.loca.lt.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 1
+ * (provider abstraction, Tier 2) and Part 7 (supply-chain hardening).
+ *
+ * SECURITY POSTURE:
+ *   - localtunnel routes the agent's local server traffic through
+ *     loca.lt servers. The relay operator (and anyone who logs the URL)
+ *     can see dashboard PIN + signed view URLs while the relay is active.
+ *     This is exactly why the spec gates Tier-2 providers behind owner
+ *     consent — see Part 3 (consent flow) and Part 6 (mandatory
+ *     credential rotation on relay-episode end).
+ *   - The agent never spins this up without an explicit per-episode
+ *     consent record bound to the owner principal — that's enforced in
+ *     TunnelManager's state machine, not in this provider.
+ *
+ * Supply-chain hardening (Part 7):
+ *   - The npm package `localtunnel` is pinned at exact version in
+ *     package.json (no caret range).
+ *   - The provider spawns the localtunnel client via its programmatic
+ *     API; a future hardening PR can switch to child-process isolation
+ *     once the spec's checksum-verified install path is added.
+ *   - `isAvailable()` resolves false if the npm package cannot be
+ *     loaded, so a missing dep degrades gracefully (provider skipped)
+ *     instead of crashing.
+ *
+ * The provider does NOT own retry/reconnect/notification — those are
+ * the manager's responsibility per the single-owner mandate (PR 2).
+ */
+export class LocaltunnelProvider {
+    name = 'localtunnel';
+    tier = 2;
+    port;
+    startTimeoutMs;
+    subdomain;
+    /**
+     * Cached dynamic-import result. The first `isAvailable()` call
+     * detects whether the npm package is present; subsequent calls reuse
+     * the cached resolution.
+     */
+    _moduleResolved;
+    constructor(opts) {
+        this.port = opts.port;
+        this.startTimeoutMs = opts.startTimeoutMs ?? 20_000;
+        this.subdomain = opts.subdomain;
+    }
+    async isAvailable() {
+        const mod = await this.loadModule();
+        return mod !== 'unavailable';
+    }
+    async start(localPort) {
+        const mod = await this.loadModule();
+        if (mod === 'unavailable') {
+            throw new Error('binary-missing: localtunnel npm package is not installed');
+        }
+        const lt = mod.default;
+        if (typeof lt !== 'function') {
+            throw new Error('binary-missing: localtunnel module did not expose the expected factory');
+        }
+        const port = localPort || this.port;
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            const timeout = setTimeout(() => {
+                if (resolved)
+                    return;
+                resolved = true;
+                reject(new Error('timeout: localtunnel did not emit a URL within the start budget'));
+            }, this.startTimeoutMs);
+            lt({ port, subdomain: this.subdomain }).then((client) => {
+                if (resolved) {
+                    try {
+                        client.close();
+                    }
+                    catch { /* best effort */ }
+                    return;
+                }
+                resolved = true;
+                clearTimeout(timeout);
+                if (!client.url) {
+                    reject(new Error('process-exit: localtunnel returned no URL'));
+                    return;
+                }
+                client.on('error', () => { });
+                resolve({
+                    url: client.url,
+                    stop: async () => {
+                        try {
+                            client.close();
+                        }
+                        catch { /* already dead */ }
+                    },
+                });
+            }, (err) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                clearTimeout(timeout);
+                const msg = (err?.message ?? '').toLowerCase();
+                if (msg.includes('rate') || msg.includes('429')) {
+                    reject(new Error(`rate-limited: localtunnel: ${err.message}`));
+                    return;
+                }
+                if (msg.includes('econnrefused') || msg.includes('dns')) {
+                    reject(new Error(`network: localtunnel: ${err.message}`));
+                    return;
+                }
+                reject(new Error(`process-exit: localtunnel start failed: ${err.message}`));
+            });
+        });
+    }
+    async loadModule() {
+        if (this._moduleResolved !== undefined)
+            return this._moduleResolved;
+        try {
+            // Dynamic specifier so TypeScript doesn't require an installed
+            // `@types/localtunnel`. The npm package itself is an optional
+            // peer-style dep — agents without it installed degrade
+            // gracefully via the catch below.
+            const specifier = 'localtunnel';
+            const mod = (await import(/* @vite-ignore */ specifier));
+            this._moduleResolved = mod;
+        }
+        catch {
+            this._moduleResolved = 'unavailable';
+        }
+        return this._moduleResolved;
+    }
+}
+//# sourceMappingURL=LocaltunnelProvider.js.map

package/dist/tunnel/LocaltunnelProvider.js.map

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

package/dist/tunnel/TunnelManager.d.ts

@@ -40,7 +40,7 @@
  */
 import { EventEmitter } from 'node:events';
 import { type PersistedTunnelState } from './TunnelLifecycle.js';
-import type { TunnelProvider, ProviderFailureReason } from './TunnelProvider.js';
+import type { TunnelProvider, ProviderName, ProviderFailureReason } from './TunnelProvider.js';
 import type { NotifierSink } from './TunnelNotifier.js';
 export interface TunnelConfig {
     /** Whether tunnel is enabled. */
@@ -110,6 +110,13 @@ export declare class TunnelManager extends EventEmitter {
     private _backoffAttempt;
     private _backoffTimer;
     private _postExhaustedTimer;
+    /**
+     * Pending consent record — populated when the manager enters
+     * `awaiting-consent` and cleared on grant / decline / timeout / stop.
+     * The nonce is the CSPRNG token sent to the owner; matching it on
+     * `grantConsent()` is the security-load-bearing check.
+     */
+    private _pendingConsent;
     constructor(config: TunnelConfig, injections?: TunnelManagerInjections);
     get url(): string | null;
     get isRunning(): boolean;
@@ -154,6 +161,42 @@ export declare class TunnelManager extends EventEmitter {
     private doStart;
     private driveTier1;
     private exhaustedOrBackoff;
+    /** First Tier-2 provider that reports available, or null. */
+    private findAvailableTier2;
+    /**
+     * Internal — called after the lifecycle transitions to
+     * `awaiting-consent`. Generates the one-time nonce, stores the
+     * pending consent record, and arms the timeout.
+     */
+    private requestConsent;
+    private clearPendingConsent;
+    /**
+     * Public — called by the consent UX layer (Telegram callback handler
+     * in PR 6) after the owner approves. Validates the nonce matches the
+     * pending consent record, starts the Tier-2 provider, and transitions
+     * to `relay-active`. Returns true on success, false if the nonce
+     * didn't match (replay, race, stale click) or the state moved beyond
+     * awaiting-consent.
+     */
+    grantConsent(nonce: string): Promise<boolean>;
+    /**
+     * Public — called by the consent UX layer when the owner declines.
+     * Validates the nonce, applies the cross-episode cooldown, and
+     * transitions to `exhausted` + background retry.
+     */
+    declineConsent(nonce: string): boolean;
+    private recordConsentDecline;
+    /**
+     * Public — the active pending-consent record (or null). Used by the
+     * consent UX layer (PR 6) to know what nonce to embed in the inline
+     * button.
+     */
+    get pendingConsent(): {
+        episodeId: string;
+        provider: ProviderName;
+        nonce: string;
+        issuedAt: number;
+    } | null;
     /**
      * Background retry — runs the bounded exponential ladder off the
      * start() promise so initial start() resolves/rejects fast. After

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

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