instar 1.2.34 → 1.2.36

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/1.2.36.md

@@ -0,0 +1,111 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = TunnelManager rewrite atop the foundation modules; no public API change -->
+
+## What Changed
+
+**feat(tunnel): TunnelManager rewrite — drive providers + lifecycle + notifier through a single owner.**
+
+This release lands PR 2 of the tunnel-failure-resilience chain
+(PR 1 was the foundation: provider abstraction + state machine + notifier).
+It rewrites `TunnelManager.ts` to drive the foundation modules and
+retires the duplicate retry machinery that previously lived in
+`server.ts`.
+
+The public API surface is preserved exactly — `start()`, `stop()`,
+`forceStop()`, `enableAutoReconnect()`, `disableAutoReconnect()`,
+`getExternalUrl()`, plus the `url` / `isRunning` / `state` accessors
+all still work as before. Callers (the SleepWake handler, the
+`server.ts` tunnel wiring) don't need changes.
+
+What's different inside:
+
+- The manager builds a Tier-1 provider pool from config (the
+  `CloudflareNamedProvider` if a token or configFile is set, then the
+  `CloudflareQuickProvider`) and drives them in order.
+- `start()` runs ONE round of provider attempts; if all fail, it
+  rejects (matching the legacy semantics) and the backoff retry runs
+  entirely in the background — `start()` does not block the caller
+  for the full exponential window.
+- A post-start HTTP probe through the public URL confirms the link
+  actually serves traffic before the manager declares `active`. A
+  provider whose URL emits but does not respond is torn down and the
+  next provider tried.
+- After the bounded startup-reconnect ladder exhausts (10 attempts
+  with exponential backoff up to 5 min), the manager schedules a
+  low-frequency 15-minute background probe until a provider connects.
+  Placeholder; replaced by the spec's N-consecutive-success
+  stability-gated probe in a later PR.
+- The single-writer CAS-guarded lifecycle state machine from PR 1 is
+  the source of truth for tunnel state. The error+exit double-handler
+  race that the concurrency reviewer surfaced cannot cause a
+  double-advance through the provider pool.
+- The `tunnel.json` state file now includes lifecycle snapshot fields
+  (`lastState`, `activeProvider`, `rotationPending`, `consentCooldown`,
+  `episode`) alongside the legacy `lastUrl`. Boot recovery reads the
+  snapshot to restore the rotation-pending flag and the cooldown
+  counter (the rotation lifecycle itself lands in a later PR).
+
+What was removed:
+
+- `server.ts` startup-retry ladder (the 5-attempt loop with 15-120s
+  exponential backoff). Deleted.
+- `server.ts` background-retry scheduler (the 5/10/20-minute
+  `scheduleRetry` callbacks). Deleted.
+- The single Lifeline failure message. Deleted. The user-facing
+  notification path will flow through the notifier once the sink is
+  wired up in the next PR.
+
+What's not yet landed (deliberate, future PRs in this chain):
+
+- Owner-DM channel + inline-button consent UX.
+- Tier-2 relay providers (localtunnel) + consent flow.
+- Auth token + PIN rotation on relay-episode end + boot recovery.
+- Full N-consecutive-success self-heal stability gate.
+- The auth-gated tunnel-state route.
+- ConfigDefaults migration for the new tunnel config fields.
+
+The lifecycle state machine already supports all of these; the manager
+just doesn't transition into the relevant states yet.
+
+## Evidence
+
+16 new unit tests in `tests/unit/tunnel-manager-rewrite.test.ts`:
+
+- Tier-1 happy path: drives the first available provider, skips
+  unavailable providers, persists the lifecycle snapshot to disk.
+- Reachability probe: rejects a provider whose URL does not pass the
+  health check, tears it down, falls through to the next provider.
+- Provider failure → next: classifies a rate-limit failure, records
+  the failed attempt against the current episode, advances to the
+  next provider.
+- Stop, forceStop, getExternalUrl, enable/disableAutoReconnect:
+  back-compat surface preserved.
+- Repeat start returns the same URL while running (mutex preserved).
+- Notifier wiring: a transition into retrying after a failure emits
+  the couldn't-reach-Cloudflare group message via the injected sink.
+- Persistence: rotation-pending flag and consent-cooldown counter
+  restored from tunnel.json; corrupted state file ignored.
+
+All 70 tunnel-related unit tests pass (16 new plus 54 foundation
+tests from PR 1). Typescript and lint clean. No existing tests
+modified.
+
+## What to Tell Your User
+
+You will not notice a behavior change yet. The internals shifted —
+your agent now has a single tidy retry engine instead of two
+overlapping ones — but your tunnel link comes up the same way it did
+before. Failure handling is also unchanged from your perspective in
+this release; the next release in the chain plugs the failure path
+into a message that goes to your Dashboard topic so you can see what
+happened when the link does not come up.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Single tunnel-lifecycle owner | Internal — your tunnel link behavior is preserved |
+| Post-start reachability probe | Automatic — prevents broadcasting a dead link |
+| Indefinite low-frequency self-heal placeholder | Automatic — agent keeps trying to recover after exhaustion without a restart |

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).

package/upgrades/side-effects/tunnel-manager-rewrite.md

@@ -0,0 +1,129 @@
+# Side-effects review — TunnelManager rewrite (PR 2 of tunnel-failure-resilience chain)
+
+**Scope (this PR — second in the chain):** Rewrite `TunnelManager.ts`
+to drive the foundation modules (provider abstraction + state machine
++ notifier) landed in PR 1, and retire the duplicate retry machinery
+in `server.ts`. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged
++ approved on main. Public API surface of `TunnelManager` is preserved
+exactly; behavior under the happy path is unchanged.
+
+**Files touched:**
+- `src/tunnel/TunnelManager.ts` — REWRITTEN. The legacy class (which
+  spawned cloudflared directly and owned its own reconnect loop) is
+  replaced with a manager that builds a Tier-1 provider pool, drives
+  it through `TunnelLifecycle`, plumbs transitions to the
+  `TunnelNotifier` (when a sink is injected), and persists the
+  lifecycle snapshot to `tunnel.json`. Public surface (`start()`,
+  `stop()`, `forceStop()`, `enableAutoReconnect()`,
+  `disableAutoReconnect()`, `getExternalUrl()`, `url` / `isRunning` /
+  `state`) preserved exactly.
+- `src/commands/server.ts` — Removed the startup-retry ladder
+  (5-attempt loop with 15-120s exponential backoff), the
+  background-retry scheduler (the 5/10/20-minute `scheduleRetry`
+  callbacks), and the single Lifeline failure message
+  ("Tunnel failed after all retries..."). Replaced with a single
+  `await tunnel.start()` call; failure is non-fatal and the manager
+  handles retry internally.
+- `tests/unit/tunnel-manager-rewrite.test.ts` — NEW. 16 tests covering
+  the happy path, reachability probe, provider-failure → next, stop
+  semantics, notifier wiring, and persistence restoration.
+
+**Under-block**: None. The new manager preserves the legacy public
+API surface; all existing callers (`SleepWake` handler, the
+construction site in `server.ts`) keep working unchanged.
+
+**Over-block**: Minor. The old `server.ts` background-retry scheduler
+fired retries at 5/10/20-minute intervals after the inner ladder gave
+up. The new manager's bounded startup-reconnect ladder is 10 attempts
+with exponential backoff (max 5-min delay between rounds), then the
+post-exhausted self-heal placeholder fires every 15 min indefinitely.
+Net effect: under sustained Cloudflare outage, the recovery cadence is
+similar but more predictable. **`start()` itself rejects after the
+FIRST round of provider attempts fails** (matching the legacy
+semantics) — the backoff retry runs entirely in the background so
+`start()` does not block the caller. This was the fix to a
+`tests/e2e/tunnel-private-view.test.ts` 60-second hook-timeout
+regression observed on the initial PR 2 CI run; the original draft
+had kept retrying synchronously inside `start()`.
+server.ts is also defensive: failure on initial `start()` is
+non-fatal and execution continues; the manager keeps trying in the
+background.
+
+**Level-of-abstraction fit**: The manager is the sole owner of
+detect → attempt → fall-back → notify per the spec's single-owner
+mandate. Provider implementations remain narrowly responsible for
+spawn + URL emission + teardown. The lifecycle module remains
+provider-agnostic and notification-agnostic; the notifier remains
+channel-agnostic. No layering violation introduced.
+
+**Signal vs authority**: Compliant. The manager classifies provider
+failures into `ProviderFailureReason` and routes them to the
+lifecycle's authoritative state machine (CAS-guarded). The notifier
+remains a read-only consumer of transition events. No new authority
+introduced at the wrong layer.
+
+**Interactions**:
+- `SleepWake` handler in `server.ts` (lines 5818-5848) is unchanged —
+  it calls `disableAutoReconnect()` / `forceStop()` /
+  `enableAutoReconnect()` / `start()` exactly as before. The new
+  manager's `forceStop()` is a thin wrapper over `stop()`, and the
+  providers' own `stop()` implementations escalate to SIGKILL — the
+  same forceful-teardown semantics the legacy `forceStop(5000)`
+  provided.
+- The `Promise.race([restart, 15s-timeout])` in SleepWake interacts
+  cleanly with the new manager's internal retry: if `start()` doesn't
+  resolve in 15s, the timeout fires, the catch re-enables
+  auto-reconnect (already always-on in the new design), and the
+  manager continues retrying internally.
+- The post-exhausted retry timer is registered with the manager's
+  own field tracking; `stop()` clears it. No timer leak across
+  episodes.
+
+**External surfaces**: None. No new API endpoint, no new CLI command,
+no new public config field, no change to the TunnelManager
+constructor's required signature (the optional `injections` parameter
+is purely additive for testability).
+
+**Migration parity**:
+- No agent-installed file change (the manager is server-side code).
+- `tunnel.json` format change: the file now carries lifecycle snapshot
+  fields. The constructor is tolerant of an old-format file (corrupted
+  parse → starts fresh) and of an absent file (no-op). No migration
+  helper needed.
+
+**Rollback cost**: Trivial. Revert two files (`TunnelManager.ts` +
+`server.ts`) + the test file. The new modules from PR 1 stay
+in tree but become unused; subsequent revert of PR 1 (also a clean
+file-delete) would restore the legacy state entirely.
+
+**Tests**:
+- 16/16 new tests in `tests/unit/tunnel-manager-rewrite.test.ts`.
+- 32/32 tests in `tests/unit/tunnel-lifecycle.test.ts` (foundation,
+  unchanged).
+- 12/12 tests in `tests/unit/tunnel-notifier.test.ts` (foundation,
+  unchanged).
+- 10/10 tests in `tests/unit/tunnel-providers.test.ts` (foundation,
+  unchanged).
+- `tsc --noEmit` clean. `npm run lint` clean.
+
+**Decision-point inventory**:
+1. Public API surface preserved exactly (vs. introducing a new class
+   name like `TunnelManagerV2` and migrating callers) — preserves the
+   "single-owner mandate" naturally and avoids a dual-implementation
+   transition window where both the legacy and new classes live in
+   tree.
+2. Reachability probe is owned by the manager (not by providers) per
+   the spec's separation of concerns. Providers cannot self-certify
+   reachability without violating the authority discipline.
+3. Post-exhausted retry placeholder lives in the manager (vs. living
+   in `server.ts` as a separate scheduler). One owner, one retry
+   engine, even for the long-tail recovery path. The placeholder will
+   be replaced by the spec's N-consecutive-success stability-gated
+   probe in a later PR; the placeholder's API is internal so the
+   replacement is non-breaking.
+4. `tunnel.json` schema extended additively (`version: 1` field
+   added, plus new fields alongside the legacy `lastUrl`). An older
+   file produces a graceful "start fresh"; a new file is unreadable
+   to a downgraded binary but the downgraded binary will simply
+   overwrite it with the legacy format — no permanent corruption.