instar 1.2.33 → 1.2.35

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/context-death-stop-hook.md

@@ -0,0 +1,100 @@
+# Side-effects review — context-death stop hook (B15 tone-gate rule)
+
+**Scope**: Add `B15_CONTEXT_DEATH_STOP` to `MessagingToneGate`. The
+operator explicitly asked for a structural guard against the agent's
+recurring "Context-Death Self-Stop" pattern (CLAUDE.md anti-pattern,
+multiple memory entries) because documentation alone has not eliminated
+the slip.
+
+**Files touched**:
+- `src/core/MessagingToneGate.ts` — adds `'B15_CONTEXT_DEATH_STOP'` to
+  `VALID_RULES`; adds a new `## SELF-STOP rule` section in `buildPrompt`
+  describing literal pattern markers + legitimate-stop carve-outs;
+  updates the response-format rule list to include B15.
+- `tests/unit/messaging-tone-gate-b15.test.ts` — 9 new tests covering
+  prompt-render assertions, drift-detection acceptance of B15,
+  propagation of a valid B15 response, and pass-through of completion /
+  blocker / topic-split candidates.
+- `specs/dev-infrastructure/context-death-stop-hook.md` — converged +
+  approved (single-iteration; design intent authored by operator).
+- `specs/dev-infrastructure/context-death-stop-hook.eli16.md` — plain-
+  English companion.
+- `docs/specs/reports/context-death-stop-hook-convergence.md` — report.
+
+**Under-block**: Narrow. The rule keys on the candidate message itself.
+If the agent slips into the pattern in *internal* reasoning (thought
+traces, plan files) but produces an outbound message that doesn't carry
+any of the literal markers, B15 does not fire — exactly the boundary the
+authority is supposed to enforce. That's correct: this is the outbound-
+message authority, not a thought-monitor.
+
+**Over-block**: Minimal by design. The rule has explicit
+legitimate-stop carve-outs (real question, real blocker, real error,
+real completion) AND explicit non-applicability boundaries (discussion-
+about-the-pattern, topic-split/move logistics, operator-initiated stop
+messages). The LLM gate is the existing authority that combines literal
+markers with conversational context. Failure-mode: an LLM call timeout
+or parse failure → fail-open (gate's existing semantics), so a network
+hiccup never silences a legitimate message.
+
+**Level-of-abstraction fit**: B15 lives where B1–B14 already live. No
+new authority, no new file, no new endpoint. The structural placement
+is sibling to existing rules, and the same drift-detection (rule
+citation must be in `VALID_RULES`) governs it.
+
+**Signal vs authority**: Compliant. The literal pattern markers in the
+prompt are the SIGNAL; the LLM gate (the existing authority) decides
+block/pass after combining markers with the legitimate-stop carve-outs
+and conversational context. No new authority is introduced; no signal
+becomes a blocker on its own.
+
+**Interactions**:
+- B15 does not change B1–B14 behavior. The drift-detection (any rule
+  cited must be in `VALID_RULES`) gains one entry; existing rules
+  remain valid.
+- The fail-open paths (`failedOpen: true`, `invalidRule: true`) are
+  unchanged.
+- All paths that call `MessagingToneGate.review()` automatically benefit
+  from B15 — no caller changes required. Tested implicitly by the
+  existing health-alert + attention-route tests passing without
+  modification.
+
+**External surfaces**: None. No new API endpoint, no new config field,
+no new CLI command, no change to the tone-gate's public type contract
+(`ToneReviewResult` shape unchanged). The new rule id is observable on
+the `result.rule` string, which already carries B1..B14 ids today.
+
+**Migration parity**:
+- No agent-installed file change. The tone gate runs on the agent's
+  server; existing agents pick up B15 the next time they update + the
+  server restarts.
+- CLAUDE.md template (`generateClaudeMd` and `migrateClaudeMd`) — not
+  touched in this PR. The rule fires at message-send time regardless of
+  what the agent reads at session-start; a future PR can add a one-line
+  awareness note to the template, but it isn't load-bearing here (the
+  point of the structural guard is that the agent doesn't need to
+  remember).
+
+**Rollback cost**: Trivial. Revert three files (Source edit + test +
+spec triplet). The tone-gate behavior collapses to its pre-B15 state.
+
+**Tests**: 9/9 new unit tests pass; 27/27 existing `MessagingToneGate`
+tests still pass; 8/8 `messaging-tone-gate-health-alerts.test.ts` still
+pass. `tsc --noEmit` clean. `npm run lint` clean.
+
+**Decision-point inventory**:
+1. LLM-gate rule (vs. regex hook) — chosen for the same reason the
+   existing tone gate uses LLM judgment: literal patterns under-block
+   on paraphrase and over-block on context (e.g., "we should pick this
+   up later *after lunch*" is fine).
+2. Single-iteration converge (vs. full 4-internal + 3-external) — the
+   change is a single-rule extension to a well-defined existing
+   authority with the operator-authored design intent in the topic-9984
+   conversation; the full converge ceremony is calibrated for new
+   subsystems. The rule is unit-testable in isolation and reversible
+   trivially; if the operator wants the full ceremony for parity it
+   can be a follow-up.
+3. Drop "regex pre-filter" optimization — adding a regex pre-check
+   before the LLM call would skip cheap-pass cases but introduces a
+   second authority on the same decision, contradicting the gate's
+   signal-vs-authority discipline. Rejected.

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