instar 1.2.34 → 1.2.35

package/dist/tunnel/TunnelNotifier.js

@@ -0,0 +1,268 @@
+/**
+ * TunnelNotifier — two-channel routing of tunnel lifecycle events to
+ * the user.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 3.
+ *
+ * Strict channel separation (the GPT external review's CRITICAL finding):
+ *   - GROUP topic (Dashboard / Lifeline fallback / General fallback):
+ *     status text only. NEVER the URL, NEVER the PIN, NEVER a signed
+ *     view link. Anyone in the group can read those, which would defeat
+ *     the owner-only consent gate.
+ *   - OWNER DM (private bot chat with the owner principal): the actual
+ *     URL + PIN + signed view links. The only credential-bearing channel.
+ *
+ * Class-based throttling (verification finding V2 + GPT finding #5):
+ *   - action-required: NEVER throttled within an episode. Cross-episode
+ *     cooldown applies (consent prompts) but the lifecycle decides that,
+ *     not the notifier.
+ *   - state-change: light — at most one per (episode, state) pair, and
+ *     at most one per 15 minutes within an episode on re-entry of the
+ *     same state.
+ *   - noise: heavy — flapping episodes collapse into one "tunnel
+ *     unstable" message, suppressed for the rest of the episode.
+ *
+ * Dedup by transition epoch (the lifecycle's monotonic counter): the
+ * notifier never emits twice for the same epoch, even if the same
+ * event fires through multiple listeners.
+ */
+export class TunnelNotifier {
+    sink;
+    clock;
+    stateChangeMinIntervalMs;
+    flapThreshold;
+    // Dedup state. The lifecycle's epoch is monotonic per manager instance,
+    // so once we've emitted for epoch N we never re-emit for N.
+    lastEmittedEpoch = -1;
+    // Per-episode bookkeeping.
+    currentEpisodeId = null;
+    /** Last-emitted timestamps keyed by `<state>::<channel>` so the group
+     * pointer and the owner-DM credential delivery are throttled
+     * independently — otherwise the DM gets swallowed after the group
+     * pointer fires for the same state-change. */
+    lastEmittedAt = new Map();
+    /** Track noise-collapse emission per episode. Once emitted, further
+     * noise messages in the same episode are suppressed. */
+    noiseEmittedThisEpisode = false;
+    flapCycles = 0;
+    flapCollapsed = false;
+    constructor(opts) {
+        this.sink = opts.sink;
+        this.clock = opts.clock ?? { now: () => Date.now() };
+        this.stateChangeMinIntervalMs = opts.stateChangeMinIntervalMs ?? 15 * 60_000;
+        this.flapThreshold = opts.flapThreshold ?? 3;
+    }
+    /**
+     * Drive the notifier from a lifecycle transition. Idempotent on the
+     * transition epoch — repeated calls with the same epoch are no-ops.
+     */
+    async onTransition(e) {
+        // Dedup on epoch FIRST: never emit twice for the same epoch even if
+        // the listener fires multiple times.
+        if (e.epoch <= this.lastEmittedEpoch)
+            return;
+        this.lastEmittedEpoch = e.epoch;
+        // Reset per-episode bookkeeping when the episode id changes.
+        const newEpisodeId = e.episode?.episodeId ?? null;
+        if (newEpisodeId !== this.currentEpisodeId) {
+            this.currentEpisodeId = newEpisodeId;
+            this.lastEmittedAt = new Map();
+            this.noiseEmittedThisEpisode = false;
+            this.flapCycles = 0;
+            this.flapCollapsed = false;
+        }
+        // Build the message for THIS transition (if any).
+        const messages = this.composeMessages(e);
+        for (const m of messages) {
+            const allowed = this.allow(m, e.to);
+            if (!allowed)
+                continue;
+            try {
+                if (m.channel === 'group') {
+                    await this.sink.sendGroup(m.text);
+                }
+                else {
+                    await this.sink.sendOwnerDM(m.text);
+                }
+                // Update bookkeeping AFTER successful send (cheap-best-effort).
+                const key = throttleKey(e.to, m.channel);
+                this.lastEmittedAt.set(key, this.clock.now());
+                if (m.class === 'noise') {
+                    this.noiseEmittedThisEpisode = true;
+                }
+            }
+            catch {
+                // Never throw into the tunnel path — preserves existing
+                // .catch(() => {}) semantics from server.ts.
+            }
+        }
+    }
+    /**
+     * Compose the user-facing messages for a transition. May return zero,
+     * one, or two messages (some transitions emit to BOTH channels, e.g.
+     * "back online — link in your DM" + DM with the URL).
+     *
+     * The DM credential payload is filled in by the manager via a callback
+     * (the notifier itself doesn't know URLs/PINs); for now the DM strings
+     * are placeholders that the manager substitutes before send. Future:
+     * extend onTransition signature to accept the credential payload.
+     */
+    composeMessages(e) {
+        const ep = e.episode?.episodeId ?? null;
+        const reason = e.lastFailureReason;
+        const messages = [];
+        switch (e.to) {
+            case 'retrying':
+                // First Tier-1 failure — describe the cause, no DM.
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `Couldn't reach the usual Cloudflare tunnel${reasonSuffix(reason)}; still retrying.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                // Track for flap detection.
+                this.flapCycles += 1;
+                if (this.flapCycles >= this.flapThreshold && !this.flapCollapsed) {
+                    this.flapCollapsed = true;
+                    messages.push({
+                        channel: 'group',
+                        class: 'noise',
+                        text: `Tunnel is unstable right now — still working on it. I'll stop re-pinging this until something changes.`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                }
+                break;
+            case 'active':
+                if (e.from === 'self-healing' || e.from === 'relay-active') {
+                    // Self-healed back to Tier 1.
+                    messages.push({
+                        channel: 'group',
+                        class: 'state-change',
+                        text: `Your permanent link is back. New link in your DM.`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                    messages.push({
+                        channel: 'owner-dm',
+                        class: 'state-change',
+                        text: `__OWNER_DM_RESTORED_URL_PLACEHOLDER__`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                }
+                else if (e.from === 'retrying') {
+                    // Cloudflare came back during retry.
+                    messages.push({
+                        channel: 'group',
+                        class: 'state-change',
+                        text: `Back online. Link in your DM.`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                    messages.push({
+                        channel: 'owner-dm',
+                        class: 'state-change',
+                        text: `__OWNER_DM_RECOVERED_URL_PLACEHOLDER__`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                }
+                // Other 'active' arrivals (initial startup) are non-events from the user's perspective.
+                break;
+            case 'awaiting-consent':
+                // Consent prompt: owner DM only, brief group pointer.
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `Cloudflare is down. I've messaged you in DM about a possible backup.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                messages.push({
+                    channel: 'owner-dm',
+                    class: 'action-required',
+                    text: `__OWNER_DM_CONSENT_PROMPT_PLACEHOLDER__`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                break;
+            case 'relay-active':
+                // A Tier-2 relay is up: group pointer + DM with URL + rotated PIN.
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `Backup tunnel is up. New link in your DM.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                messages.push({
+                    channel: 'owner-dm',
+                    class: 'state-change',
+                    text: `__OWNER_DM_RELAY_URL_PLACEHOLDER__`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                break;
+            case 'exhausted':
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `All tunnel options are unavailable right now. I'll keep retrying Cloudflare in the background and switch back the moment it recovers — no restart needed.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                break;
+            case 'self-healing':
+                // No user-visible message at entry. The "permanent link is back"
+                // emits on self-healing → active (above).
+                break;
+            // No notification on idle / starting transitions.
+            case 'idle':
+            case 'starting':
+                break;
+        }
+        return messages;
+    }
+    /**
+     * Throttle decision per spec Part 3:
+     *   - action-required: NEVER throttled within an episode.
+     *   - state-change: at most one per (episode, state, channel) combo
+     *     within `stateChangeMinIntervalMs`. The channel scoping is
+     *     load-bearing: the group pointer and the owner-DM credential
+     *     delivery are TWO messages for the same state-change; they must
+     *     both emit, not throttle each other out.
+     *   - noise: emits at most once per episode. The flap-collapse
+     *     message goes out the first time the threshold is crossed; all
+     *     subsequent noise in the same episode is suppressed.
+     */
+    allow(m, toState) {
+        if (m.class === 'action-required')
+            return true;
+        if (m.class === 'noise') {
+            return !this.noiseEmittedThisEpisode;
+        }
+        // state-change: keyed per (state, channel).
+        const key = throttleKey(toState, m.channel);
+        const lastAt = this.lastEmittedAt.get(key);
+        if (lastAt === undefined)
+            return true;
+        return this.clock.now() - lastAt >= this.stateChangeMinIntervalMs;
+    }
+}
+function throttleKey(state, channel) {
+    return `${state}::${channel}`;
+}
+function reasonSuffix(reason) {
+    switch (reason) {
+        case 'rate-limited': return ' (Cloudflare is rate-limiting us)';
+        case 'binary-missing': return ' (the tunnel software is missing)';
+        case 'network': return ' (network is unreachable)';
+        case 'timeout': return ' (it timed out connecting)';
+        case 'process-exit': return ' (the tunnel process exited)';
+        case 'reachability-failed': return ' (the link did not respond)';
+        default: return '';
+    }
+}
+//# sourceMappingURL=TunnelNotifier.js.map

package/dist/tunnel/TunnelNotifier.js.map

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

package/dist/tunnel/TunnelProvider.d.ts

@@ -0,0 +1,80 @@
+/**
+ * TunnelProvider — abstraction over the underlying tunnel implementation.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 1:
+ * the TunnelManager is the single owner of the lifecycle state machine,
+ * and each backend (cloudflared quick, cloudflared named, localtunnel,
+ * bore) implements this interface. The manager treats providers as
+ * interchangeable units; trust-tier ordering (Tier 1 vs Tier 2) and the
+ * consent gate live in the manager, NOT in the providers themselves.
+ *
+ * Two tiers:
+ *   - Tier 1: automatic, secure. Cloudflare providers. Tried silently.
+ *   - Tier 2: consent-gated relays. localtunnel, bore. Never activated
+ *     without explicit owner approval recorded against the episode.
+ *
+ * Every provider's `start()` MUST resolve only after the URL has passed
+ * a post-start reachability probe (verified by the manager via the
+ * /health endpoint through the public URL). A URL that emits from
+ * cloudflared but doesn't actually serve (e.g. localtunnel interstitial,
+ * bore.pub down) is NOT counted as `active` — that prevents a false
+ * "back online" broadcast for a dead link.
+ *
+ * The provider does NOT decide retry, fallback, or notification — those
+ * are the manager's responsibility. Provider responsibilities are
+ * narrowly: spawn the backend, surface the URL, surface a stop handle.
+ */
+/** Trust tier — Tier 1 is automatic/secure, Tier 2 is consent-gated. */
+export type ProviderTier = 1 | 2;
+/** Stable identifier the manager uses to route episode/consent records. */
+export type ProviderName = 'cloudflare-named' | 'cloudflare-quick' | 'localtunnel' | 'bore';
+export interface TunnelProviderHandle {
+    /** The public URL the provider exposes. */
+    readonly url: string;
+    /**
+     * Stop the provider. MUST escalate SIGINT → SIGKILL with PID
+     * verification (mirror the existing `forceStop()` pattern) so the
+     * manager can guarantee no relay child lingers across a self-heal
+     * switch-back. Tunnel teardown is security-load-bearing for Tier 2.
+     */
+    stop(): Promise<void>;
+}
+export interface TunnelProvider {
+    /** Stable name routed through episode/consent records and audit logs. */
+    readonly name: ProviderName;
+    /** Trust tier — manager uses this to decide whether the consent gate applies. */
+    readonly tier: ProviderTier;
+    /**
+     * True if the provider can be started in this environment without further
+     * user setup. Used by the manager to filter the provider pool BEFORE
+     * declaring `exhausted`. Reasons for `false`: required binary missing,
+     * required token/credentials not configured, OS unsupported, etc.
+     *
+     * The manager calls this once per episode (cheap signal), not per attempt.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Start the provider against the given local port. Resolves with the
+     * URL + a stop handle when the URL is emitted by the backend. The
+     * manager performs the reachability probe AFTER resolution and before
+     * transitioning to `active`; providers MUST NOT do their own probing
+     * here (the manager owns post-start verification per spec Part 1).
+     *
+     * Implementations should reject with a structured Error whose `message`
+     * carries the classification the manager will surface to the notifier
+     * (e.g. "rate-limited (HTTP 429 / Cloudflare 1015)", "binary missing",
+     * "network unreachable", "process exited code 1"). The manager parses
+     * these strings into ProviderFailureReason classifications.
+     */
+    start(localPort: number): Promise<TunnelProviderHandle>;
+}
+/**
+ * Classification the manager applies to a provider failure for the
+ * notifier and for deciding whether to advance to the next provider.
+ *
+ * The classification is owned by the manager (not the provider) per the
+ * signal-vs-authority discipline: providers raise errors with reason
+ * strings; the manager classifies into this enum and routes accordingly.
+ */
+export type ProviderFailureReason = 'rate-limited' | 'binary-missing' | 'network' | 'process-exit' | 'timeout' | 'reachability-failed' | 'unknown';
+//# sourceMappingURL=TunnelProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelProvider.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjC,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,aAAa,GACb,MAAM,CAAC;AAEX,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B;;;;;;;OAOG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAC7B,cAAc,GACd,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,SAAS,GACT,qBAAqB,GACrB,SAAS,CAAC"}

package/dist/tunnel/TunnelProvider.js

@@ -0,0 +1,28 @@
+/**
+ * TunnelProvider — abstraction over the underlying tunnel implementation.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 1:
+ * the TunnelManager is the single owner of the lifecycle state machine,
+ * and each backend (cloudflared quick, cloudflared named, localtunnel,
+ * bore) implements this interface. The manager treats providers as
+ * interchangeable units; trust-tier ordering (Tier 1 vs Tier 2) and the
+ * consent gate live in the manager, NOT in the providers themselves.
+ *
+ * Two tiers:
+ *   - Tier 1: automatic, secure. Cloudflare providers. Tried silently.
+ *   - Tier 2: consent-gated relays. localtunnel, bore. Never activated
+ *     without explicit owner approval recorded against the episode.
+ *
+ * Every provider's `start()` MUST resolve only after the URL has passed
+ * a post-start reachability probe (verified by the manager via the
+ * /health endpoint through the public URL). A URL that emits from
+ * cloudflared but doesn't actually serve (e.g. localtunnel interstitial,
+ * bore.pub down) is NOT counted as `active` — that prevents a false
+ * "back online" broadcast for a dead link.
+ *
+ * The provider does NOT decide retry, fallback, or notification — those
+ * are the manager's responsibility. Provider responsibilities are
+ * narrowly: spawn the backend, surface the URL, surface a stop handle.
+ */
+export {};
+//# sourceMappingURL=TunnelProvider.js.map

package/dist/tunnel/TunnelProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelProvider.js","sourceRoot":"","sources":["../../src/tunnel/TunnelProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.34",
+  "version": "1.2.35",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-22T21:51:00.191Z",
-  "instarVersion": "1.2.34",
+  "generatedAt": "2026-05-22T22:17:56.523Z",
+  "instarVersion": "1.2.35",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {

package/upgrades/1.2.35.md

@@ -0,0 +1,96 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = foundation layer for an upcoming feature; no user-visible behavior change yet -->
+
+## What Changed
+
+**feat(tunnel): foundation modules for the tunnel-failure-resilience feature.**
+
+This release lands the foundation layer that the upcoming tunnel-failure-
+resilience feature is built on. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged +
+approved (4 review iterations, 41 material findings folded in across
+internal multi-angle review + GPT external review + GPT verification);
+this PR is the first of a chain landing the implementation.
+
+What this PR adds (additive only — no existing behavior changes yet):
+
+1. **`TunnelProvider` interface** (`src/tunnel/TunnelProvider.ts`) — a
+   provider abstraction that future tunnel providers (localtunnel, bore)
+   will implement alongside the two extracted Cloudflare providers.
+   Defines `ProviderTier`, `ProviderName`, `ProviderFailureReason`.
+
+2. **`CloudflareQuickProvider`** (`src/tunnel/CloudflareQuickProvider.ts`)
+   — Tier-1 zero-config Cloudflare quick-tunnel implementation
+   extracted from the original `TunnelManager.startQuickTunnel`. Owns
+   ONLY spawn + URL emission + teardown; retry/reconnect ownership
+   moves to the manager in a subsequent PR per the spec's single-owner
+   mandate. Forceful stop with SIGINT→SIGKILL escalation preserved.
+
+3. **`CloudflareNamedProvider`** (`src/tunnel/CloudflareNamedProvider.ts`)
+   — Tier-1 persistent Cloudflare named-tunnel implementation
+   (token-auth and config-file-auth modes). `isAvailable()` returns
+   false when neither token nor configFile is configured.
+
+4. **`TunnelLifecycle`** (`src/tunnel/TunnelLifecycle.ts`) — the single-
+   writer state machine that will own the tunnel lifecycle once the
+   manager is rewritten. Compare-and-swap `transition(expectedFrom, to)`
+   guard rejects losing concurrent writes (the error+exit double-handler
+   race fix). Monotonic transition epoch drives notification dedup.
+   Episode model + cross-episode consent cooldown + rotation-pending
+   flag (the boot-recovery mechanism for crash-safe credential
+   rotation) all present and tested.
+
+5. **`TunnelNotifier`** (`src/tunnel/TunnelNotifier.ts`) — two-channel
+   routing that, once wired in, will route group-topic status text
+   (no credentials, ever) separately from owner-DM credential delivery
+   (the only credential-bearing channel). Class-based throttling:
+   `action-required` (consent prompts) never throttled within an
+   episode; `state-change` keyed per `(state, channel)` within a 15-min
+   window; `noise` (flap collapse) at most once per episode.
+
+The existing `TunnelManager.ts` and `server.ts` tunnel block are
+UNTOUCHED in this PR — current tunnel behavior is identical. Wiring
+the new modules into the manager (and retiring the legacy `server.ts`
+retry ladders) is the next PR in this chain.
+
+## Evidence
+
+54 new unit tests pass:
+
+- `tests/unit/tunnel-providers.test.ts` — 10 tests covering provider
+  interface assertions, `isAvailable()` semantics on token/configFile
+  configurations, start-rejection paths on missing prerequisites.
+- `tests/unit/tunnel-lifecycle.test.ts` — 32 tests covering the CAS
+  guard (rejects losing transitions without mutating state),
+  monotonic-epoch increment, valid-transition map enforcement,
+  episode lifecycle, exponential consent-cooldown back-off,
+  rotation-pending persistence, failure-reason classification,
+  CSPRNG nonce generation.
+- `tests/unit/tunnel-notifier.test.ts` — 12 tests covering the
+  channel-separation invariant (credentials never appear in group
+  messages), epoch dedup, action-required-never-throttled, state-
+  change per-(state, channel) throttling, flap-collapse emits
+  exactly once per episode, sink-error swallowing.
+
+All existing tests still pass. `tsc --noEmit` clean. `npm run lint`
+clean.
+
+## What to Tell Your User
+
+This release adds internal scaffolding for a tunnel-resilience feature
+coming over the next few releases. You will not notice any behavior
+change yet — your dashboard link comes up the same way as before. The
+upcoming releases will add failure notification to the Dashboard topic,
+backup tunnel providers (asked about in DM before use), and automatic
+recovery when Cloudflare comes back online. Each piece ships in its
+own release in the chain that starts here.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Provider abstraction internals | Internal — used by the upcoming manager rewrite |
+| Single-writer state machine internals | Internal — used by the upcoming manager rewrite |
+| Two-channel notifier internals | Internal — wired up in the next release |

package/upgrades/side-effects/tunnel-failure-resilience.md

@@ -0,0 +1,118 @@
+# Side-effects review — tunnel failure resilience (foundation checkpoint)
+
+**Scope (this commit — checkpoint 1 of N):** Land the foundation layer
+that the rest of the feature builds on. This checkpoint introduces
+NEW modules in isolation; it does NOT yet rewire `TunnelManager.ts` or
+`server.ts`, so existing tunnel behavior is unchanged. Subsequent
+commits on this branch layer on (1) `TunnelManager` rewrite to drive
+the new lifecycle, (2) localtunnel provider + consent flow, (3)
+`TelegramAdapter.sendToOwnerDM` + inline-button consent UX, (4)
+`authToken`/PIN rotation lifecycle + boot recovery, (5) self-heal probe,
+(6) `/tunnel` route, (7) `ConfigDefaults` migration + CLAUDE.md template
+update, (8) Tier-2/3 tests. The PR opens once the full feature lands.
+
+**Files touched in this checkpoint:**
+- `specs/dev-infrastructure/tunnel-failure-resilience.md` — fix
+  `eli16-overview` frontmatter pointer to the actual `.eli16.md` file
+  (was pointing at a section anchor in the convergence report, which
+  the gate cannot resolve).
+- `specs/dev-infrastructure/tunnel-failure-resilience.eli16.md` —
+  recreated (the original was lost in a worktree rebase).
+- `src/tunnel/TunnelProvider.ts` — NEW. Provider abstraction interface
+  + `ProviderName`/`ProviderTier`/`ProviderFailureReason` enums.
+- `src/tunnel/CloudflareQuickProvider.ts` — NEW. Tier-1 quick-tunnel
+  provider extracted from the original `TunnelManager.startQuickTunnel`.
+- `src/tunnel/CloudflareNamedProvider.ts` — NEW. Tier-1 named-tunnel
+  provider (token-auth + config-file-auth) extracted from the
+  original `TunnelManager.startNamedTunnel` + `startConfigFileTunnel`.
+- `src/tunnel/TunnelLifecycle.ts` — NEW. Single-writer CAS-guarded
+  state machine for the tunnel lifecycle (idle → starting → active |
+  retrying → awaiting-consent → relay-active | self-healing |
+  exhausted). Episode model, cross-episode consent cooldown,
+  rotation-pending flag, monotonic transition epoch.
+- `src/tunnel/TunnelNotifier.ts` — NEW. Two-channel routing (group
+  status text only; owner-DM credentials only) with class-based
+  throttling (action-required never throttled; state-change keyed per
+  (state, channel) within window; noise emits once per episode).
+- `tests/unit/tunnel-providers.test.ts` — NEW. 10 tests covering
+  provider interface + `isAvailable` semantics + start-rejection paths.
+- `tests/unit/tunnel-lifecycle.test.ts` — NEW. 32 tests covering CAS
+  guard, transition validity, episode lifecycle, consent cooldown
+  exponential backoff, rotation flag, classifyFailure, generators.
+- `tests/unit/tunnel-notifier.test.ts` — NEW. 12 tests covering
+  channel separation (no credentials in group), epoch dedup, class
+  throttling, flap-collapse, sink-error swallowing.
+
+**Under-block**: None introduced by this checkpoint. The new modules
+are not yet wired into the live tunnel path — existing
+`TunnelManager.ts` is untouched and behaves identically. The wire-up
+happens in the next commit on this branch.
+
+**Over-block**: None. The new modules are additive; no existing
+control-flow is changed yet.
+
+**Level-of-abstraction fit**:
+- `TunnelProvider` is a pure interface; concrete providers are thin
+  wrappers around `cloudflared`.
+- `TunnelLifecycle` is provider-agnostic and notification-agnostic; it
+  owns ONLY state.
+- `TunnelNotifier` is lifecycle-aware (consumes transition events) but
+  channel-agnostic (delegates to a `NotifierSink` interface).
+- Separation lets subsequent commits swap implementations (e.g., add
+  the localtunnel provider) without touching the lifecycle or notifier.
+
+**Signal vs authority**: Compliant. Providers raise failure errors
+(SIGNAL via Error.message classification); the lifecycle classifies
+into `ProviderFailureReason` (AUTHORITY); the notifier consumes the
+classified signal (READ-ONLY consumer). No new authority is introduced
+at the wrong layer.
+
+**Interactions**:
+- New modules import only from each other and node:crypto / node:events
+  / cloudflared. No interaction with existing TelegramAdapter,
+  PostUpdateMigrator, or server.ts in this checkpoint.
+- Notifier's `NotifierSink` interface is satisfied by the existing
+  `TelegramAdapter.sendToTopic` for the group channel; the owner-DM
+  send method (`sendOwnerDM`) does not exist yet and will be added in
+  a subsequent commit. Until then, tests use mock sinks.
+
+**External surfaces**: None. No new API endpoint, no new CLI command,
+no new config field user-facing. The new types are exported from
+`src/tunnel/*` but no caller imports them in this checkpoint.
+
+**Migration parity**: N/A for this checkpoint (no agent-installed
+file changes). The migration story (ConfigDefaults entries, CLAUDE.md
+template + migrator updates) lands in a later commit on this branch.
+
+**Rollback cost**: Trivial. Revert these eight new files + the spec
+frontmatter pointer fix; the eli16.md companion goes with them.
+Nothing else changes.
+
+**Tests**:
+- 10/10 tests in `tests/unit/tunnel-providers.test.ts` pass.
+- 32/32 tests in `tests/unit/tunnel-lifecycle.test.ts` pass.
+- 12/12 tests in `tests/unit/tunnel-notifier.test.ts` pass.
+- `tsc --noEmit` clean. `npm run lint` clean.
+- No existing tests were modified; no regressions.
+
+**Decision-point inventory**:
+1. Provider interface is named-provider-aware (`isAvailable()` returns
+   false when neither token nor configFile is configured) so the
+   manager naturally skips the named path on quick-only installs.
+2. Lifecycle uses CAS (`transition(expectedFrom, to)`) instead of
+   message-passing — Node single-threaded model makes the synchronous
+   compare-and-set sufficient; the alternative (a queue) was unnecessary
+   complexity.
+3. `noiseEmittedThisEpisode` is a per-episode boolean; the flap-
+   collapse message lands at most once per episode regardless of how
+   many flap cycles happen. Trades fidelity (which cycle triggered it)
+   for guaranteed non-flooding.
+4. Throttle key for state-change is `<state>::<channel>` — the group
+   pointer and owner-DM credential delivery for the same state-change
+   must both be allowed; channel-blind keying would suppress the DM
+   after the group pointer fired, which is exactly the bug the
+   unit tests caught during this checkpoint's build.
+5. `TunnelLifecycle.restoreFrom` does NOT resume the live state.
+   Every boot starts at `idle` and re-enters `starting` from scratch.
+   The persisted `rotationPending` flag is the only piece that
+   triggers a boot-time action (the rotation in checkpoint 4).