instar 1.2.36 → 1.2.38

package/upgrades/1.2.37.md

@@ -0,0 +1,53 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Closes the failure class that produced the b2lead-insights regression on 2026-05-22 — a recurrence of the 2026-05-20 incident two days after PR #284 shipped four of five fixes and explicitly deferred the fifth. The deferral was *"lifeline auto-restart on server upgrade — out of scope today."* This release ships that missing fifth fix, plus a structural rule that prevents future PRs from leaving similar gaps.
+
+The mechanic: when the AutoUpdater applies a server update that crosses a major.minor boundary, the running lifeline process is on the OLD major.minor and will be rejected by the new server's `/internal/telegram-forward` with HTTP 426 on every forward. Until now, only the lifeline-internal handler reacted to that 426 — but only if the lifeline was already running the post-PR-#284 code. Lifelines started before PR #284 had no such handler and crashed silently into the rate-limit cooldown.
+
+This release adds three independent channels that all write the same coordinated-restart signal at `state/lifeline-restart-requested.json`:
+
+1. **AutoUpdater** — when `crossesBreaking(previousVersion, targetVersion)` is true, writes the signal alongside the existing `restart-requested.json` server-restart flag.
+2. **Server `/internal/telegram-forward` 426 handler** — writes the same signal directly. Belt-and-suspenders: covers the case where AutoUpdater is in a deferred / weird state but the server has direct evidence of skew.
+3. **PostUpdateMigrator one-time bootstrap** — on first update post-this-release, any agent whose `lifeline-started-at.json` records a major.minor older than the installed version gets the signal written once. Unsticks every currently-stuck agent without manual SIGKILL.
+
+The signal is read by THREE independent consumers (also for redundancy):
+
+- **TelegramLifeline tick** — primary consumer; checks every 30s and calls `initiateRestart('plannedUpgrade', ...)`. New `plannedUpgrade` bucket in `rateLimitState.decide` bypasses the watchdog cooldown identically to `versionSkew`, and counts toward the shared 3-per-24h hard-skew cap.
+- **Fleet watchdog (out-of-process)** — checks every 5 min for signals older than 60s. If the lifeline's own tick failed to act, the watchdog force-restarts via `launchctl bootout/bootstrap`. This is the only channel that can break a wedged event loop (the supervisor lives inside the lifeline and shares the loop).
+- **(Future) v3 Remediator Tier-3 probe** — explicitly designed to absorb this signal-file orchestration when Tier 3 lands. <!-- tracked: topic-3079-v3-remediator -->
+
+A separate, structural fix ships alongside: the `instar-dev` pre-commit hook (`scripts/instar-dev-precommit.js`) now scans staged specs for orphan deferral language (`deferred / out of scope today / not in this PR / preemptive fix / follow-up`) and blocks the commit unless each occurrence is linked to a tracked marker (`<!-- tracked: <id> -->`) or the spec's frontmatter explicitly waves it through via `deferrals-tracked: <affirmation>`. The override `INSTAR_DEV_ALLOW_ORPHAN_DEFERRALS=1` is logged + audited.
+
+CLAUDE.md template gains a "Version-Skew Self-Recovery" section so future agents understand the "Heads up: my server auto-updated…" alert as a non-action-needed event.
+
+## What to Tell Your User
+
+- "If your agent's server auto-updates across a breaking version boundary, the lifeline now restarts automatically to match. You may see a one-time *'Heads up: my server auto-updated… ingress is paused…'* Telegram message — no action needed; recovery is automatic within 30s to 5 min. Queued messages replay on recovery."
+- "Anything currently stuck on a pre-PR-#284 lifeline self-recovers on the next update without manual intervention."
+- "Future PRs cannot ship 'tactical fix + deferred follow-ups' without explicit tracking — the pre-commit hook blocks it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Coordinated lifeline restart on major.minor server bump | Automatic; AutoUpdater writes the signal, lifeline consumes it within 30s |
+| Server-side 426 belt-and-suspenders | Automatic; server writes the same signal on its own evidence of skew |
+| PostUpdateMigrator stale-lifeline bootstrap | Automatic; one-time nudge per agent on first update post-release |
+| Fleet watchdog force-restart on wedged lifeline | Automatic; signals >60s old trigger out-of-process restart |
+| Structural no-deferrals enforcement | Automatic; pre-commit blocks unlinked deferral language in specs |
+| Version-Skew Self-Recovery awareness in CLAUDE.md | Automatic via PostUpdateMigrator on next update |
+
+## Evidence
+
+- Spec: `docs/specs/auto-updater-lifeline-coordination.md` (with ELI16 companion).
+- Side-effects review: `upgrades/side-effects/auto-updater-lifeline-coordination.md`.
+- Incident reference: b2lead-insights regression 2026-05-22, ~46h silent Telegram ingress drop. Lifeline pinned at v1.1.0 while server auto-updated through 27 minor releases to v1.2.28.
+- Tests: 43 new tests across 5 files (17 unit on version-skew module, 5 unit on rate-limit plannedUpgrade bucket, 5 unit on PostUpdateMigrator nudge, 9 unit on deferrals-check, 7 integration on the full coordinated-restart pipeline).
+
+## Rollback
+
+Every layer is independently revertable. The signal-file format is additive (writers + readers; no existing format changes). New `plannedUpgrade` bucket adds a string union member; revert renames it out. The deferrals-check defaults to mandatory in this release; reverting drops the gate without affecting any other commit path. PostUpdateMigrator's nudge writes a signal that's harmless if left behind (24h cleanup already covers it).

package/upgrades/1.2.38.md

@@ -0,0 +1,103 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = owner-DM channel + notifier sink wiring; no public API breakage -->
+
+## What Changed
+
+**feat(tunnel,telegram): owner-DM channel + two-channel notifier wired into the tunnel manager.**
+
+PR 3 of the tunnel-failure-resilience chain. Lands the owner-DM
+messaging surface that the upcoming consent UX + relay providers
+(PR 4) and credential rotation lifecycle (PR 5) depend on. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged
+and approved on main.
+
+What's new:
+
+- `TelegramAdapter.ownerUserId` config field — the single Telegram
+  user id who controls security-sensitive decisions for this
+  instance (consent gate for backup tunnels, credential exposure).
+  Separate from the broader `authorizedUserIds` allowlist per the
+  GPT external review's CRITICAL finding that consent decisions
+  must not trust the broader set. Falls back to
+  `promptGate.ownerId` for back-compat when not set explicitly.
+- `TelegramAdapter.getOwnerUserId()` — returns the configured owner
+  principal (or the back-compat fallback).
+- `TelegramAdapter.sendToOwnerDM(text)` — sends a private DM to the
+  owner's direct bot chat. Failure modes ("no owner configured",
+  "owner hasn't messaged the bot yet", network error) log a warning
+  and return null; never throw into the caller. Telegram bots can
+  only initiate a DM after the user has messaged the bot at least
+  once, so an early forbidden response is expected and non-fatal.
+- `TunnelManager.attachTelegram(adapter, dashboardPin)` — wires the
+  notifier sink. Group messages route to the Dashboard topic (with
+  Lifeline fallback); owner-DM messages route to
+  `sendToOwnerDM`. A credentialProvider callback returns the live
+  URL + current PIN at compose time, so the notifier never holds
+  stale credentials in its own state. `server.ts` calls
+  `attachTelegram` after the Dashboard topic is ensured.
+- `TunnelNotifier` composers — the four owner-DM messages
+  (recovered, restored, consent prompt, relay activated) now render
+  real English text with credentials substituted. Group-channel
+  messages continue to carry status text only — credentials NEVER
+  appear in group messages.
+
+What's NOT new yet (deliberate, future PRs in this chain):
+
+- Inline-button consent UX + callback handler (PR 4).
+- Tier-2 relay providers (localtunnel) + the actual consent-driven
+  transition into `relay-active` (PR 4).
+- `authToken` / PIN rotation on relay-episode end + boot recovery
+  (PR 5).
+- Full N-consecutive-success self-heal stability gate (PR 6).
+- The auth-gated `/tunnel` route (PR 7).
+
+The lifecycle state machine already supports all of these; the
+manager just doesn't transition into the relevant states yet.
+
+## Evidence
+
+3 new unit tests in `tests/unit/tunnel-manager-rewrite.test.ts`:
+
+- `attachTelegram` routes the "couldn't reach" group message to the
+  Dashboard topic id.
+- `attachTelegram` falls back to the Lifeline topic when no Dashboard
+  topic is configured.
+- `attachTelegram` owner-DM message carries the live URL and current
+  PIN (credential substitution at compose time).
+
+1 new + updated tests in `tests/unit/tunnel-notifier.test.ts`:
+
+- The credential-snapshot test now uses a real credentialProvider and
+  asserts the URL + PIN appear in owner-DM messages AND that they
+  NEVER appear in group messages.
+- New "renders a graceful 'link not available' placeholder when no
+  credentialProvider is wired" test for the test-injection /
+  partial-wire-up path.
+
+All 71 tunnel-related unit tests pass (32 lifecycle + 10 providers +
+13 notifier + 19 manager). Typescript and lint clean.
+
+## What to Tell Your User
+
+This release adds the plumbing for owner-only private messages from
+the agent to you, separate from the group topics where everyone
+sees the same messages. Nothing visible to you yet — the upcoming
+release uses this plumbing to message you directly when Cloudflare
+goes down and asks whether to use a backup. The release after that
+uses the same channel to send you new dashboard credentials after a
+backup tunnel finishes its work and your auth token rotates.
+
+If you want to set the owner explicitly, the relevant config field
+is your Telegram user id. The agent falls back to your prompt-gate
+owner id if it's already set, so most existing installs don't need
+to change anything.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Owner-DM channel | Automatic — the agent picks up your owner id from existing config and uses it for security-sensitive messages |
+| Live credential substitution in DMs | Automatic — when the tunnel sends you a link, the URL + PIN are always the current ones |
+| Group-vs-DM channel separation | Structural — credentials never appear in group messages regardless of how the tunnel layer wires up |

package/upgrades/side-effects/auto-updater-lifeline-coordination.md

@@ -0,0 +1,199 @@
+# Side-Effects Review — Auto-updater ↔ lifeline coordination + no-deferrals enforcement
+
+**Version / slug:** `auto-updater-lifeline-coordination`
+**Date:** 2026-05-22
+**Author:** echo
+**Second-pass reviewer:** subagent (high-risk: AutoUpdater + lifecycle + watchdog)
+**Spec:** [docs/specs/auto-updater-lifeline-coordination.md](../../docs/specs/auto-updater-lifeline-coordination.md)
+**ELI16:** [docs/specs/auto-updater-lifeline-coordination.eli16.md](../../docs/specs/auto-updater-lifeline-coordination.eli16.md)
+
+## Summary of the change
+
+Closes the failure class produced by today's b2lead-insights regression — a recurrence of the 2026-05-20 incident two days after PR #284 shipped four of five fixes and explicitly deferred the fifth. The fifth fix — *"lifeline auto-restart on server upgrade"* — is the actual prevention layer, and its deferral allowed the same outage to recur.
+
+This PR ships the missing fix in three writer channels and three reader channels (each independent for redundancy), plus a structural enforcement that prevents future deferrals from rotting.
+
+**Writers** (all write to `state/lifeline-restart-requested.json`):
+- `AutoUpdater.requestRestart` — when `crossesBreaking(prev, next)` is true, writes the signal alongside the existing server-restart signal.
+- `routes.ts /internal/telegram-forward` 426 path — writes the signal on direct evidence of skew.
+- `PostUpdateMigrator.migrateStaleLifelineSignal` — one-time bootstrap for currently-stuck agents.
+
+**Readers**:
+- `TelegramLifeline.checkLifelineRestartSignal` — primary; checks every 30s, calls `initiateRestart('plannedUpgrade', ...)`. New `plannedUpgrade` bucket in `rateLimitState.decide` bypasses watchdog cooldown identically to the existing `versionSkew` bucket.
+- Fleet watchdog (`src/templates/scripts/instar-watchdog.sh`) — checks every 5 min; force-restarts via launchctl if signal is >60s old. Out-of-process, so it can break a wedged event loop.
+- (Future) v3 Remediator Tier-3 probe — explicit absorption point, tracked separately. <!-- tracked: topic-3079-v3-remediator -->
+
+**Structural meta-fix**: `scripts/instar-dev-precommit.js` adds an orphan-deferrals scan. Every "deferred / out of scope today / NOT in this PR / preemptive fix / follow-up" mention in a spec must be linked (`<!-- tracked: <id> -->`) or the spec's frontmatter must explicitly wave it through (`deferrals-tracked: <affirmation>`). Override via `INSTAR_DEV_ALLOW_ORPHAN_DEFERRALS=1`, logged + audited.
+
+**Agent awareness**: CLAUDE.md template gains a "Version-Skew Self-Recovery" section migrated to existing agents.
+
+## Decision-point inventory
+
+- `crossesBreaking(prev, next)` — **add** — semver predicate; mechanic, no judgment.
+- `writeLifelineRestartSignal` — **add** — atomic write + idempotent skip-fresh.
+- `readLifelineRestartSignal` / `clearLifelineRestartSignal` — **add** — read with expiry check, atomic delete.
+- `AutoUpdater.requestRestart` lifeline-signal branch — **add** — fires on major.minor crossing.
+- `routes.ts /internal/telegram-forward` 426 lifeline-signal write — **add** — belt-and-suspenders.
+- `PostUpdateMigrator.migrateStaleLifelineSignal` — **add** — one-time bootstrap.
+- `TelegramLifeline.checkLifelineRestartSignal` — **add** — per-tick consumer.
+- `rateLimitState.decide` `plannedUpgrade` bucket — **add** — shares cooldown-bypass + daily-cap with `versionSkew`.
+- Fleet watchdog `check_stale_lifeline_signal` — **add** — out-of-process consumer.
+- `instar-dev-precommit.js` orphan-deferrals scan — **add** — structural enforcement.
+- CLAUDE.md "Version-Skew Self-Recovery" section — **add** (template + migrator).
+
+## Deferrals tracked
+
+Per the new enforcement rule, every potential deferral in this PR is either in-scope (and thus not a deferral) or explicitly tracked:
+
+- v3 Remediator absorption — tracked at topic 3079 with active development; absorption is mechanical when Tier 3 lands. <!-- tracked: topic-3079-v3-remediator -->
+
+No other deferrals. Tests, migration, CLAUDE.md awareness, cross-platform fleet watchdog wiring — all in this PR.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **`crossesBreaking` fail-safe.** Returns `true` on malformed inputs (missing version, non-semver string). A false-positive triggers a single harmless lifeline restart — strictly better than a false-negative which is the exact incident class. Documented in unit test.
+- **PostUpdateMigrator nudge — agent that legitimately wants the old lifeline.** If a user has pinned their lifeline at an older version on purpose (e.g. for compatibility testing), the migrator will signal a restart against their will on next update. Mitigation: a pinned-version operator would also pin the server. Same-major.minor → no signal. The corner case is "user pinned the lifeline only" — explicitly out of supported configurations.
+- **Deferrals-check false-positives on technical writing.** A spec might legitimately use "deferred" / "follow-up" in a non-prescriptive context (e.g. quoting an older spec for historical comparison). The override flag `INSTAR_DEV_ALLOW_ORPHAN_DEFERRALS=1` exists for this case, with mandatory audit logging. Practical false-positive rate from the test fixtures: zero (the regex's negation guard handles "no deferrals" / "non-deferred").
+- **Server-side 426 writer over-firing on dev/test deployments.** If a dev runs the server with the version handshake disabled (no `authToken`), the 426 path doesn't fire. If they enable auth but mismatch versions intentionally, the signal write happens — but the lifeline's tick consumer is the only one that can act on it, and a dev's lifeline can read it just as well.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Server downgrade (reviewer nit 2026-05-22, addressed).** `crossesBreaking('1.2.28', '1.1.0')` returns true (the major.minor genuinely changed). The cited "lifeline reads its own running version and skips" pathway (`TelegramLifeline.checkLifelineRestartSignal:1338`) only no-ops when `signal.targetVersion === this.lifelineVersion`. In a genuine server-downgrade scenario the lifeline is on the HIGHER version, the signal targets the LOWER version, and `lifelineVersion !== targetVersion` so the lifeline WOULD restart. After restart, the new lifeline matches the new lower server version — recovery is correct, just an extra restart on an intentional downgrade. Acceptable because downgrades through the auto-updater are not a supported flow; manual-install downgrades trip this once per downgrade, no worse than the manual-replace operator would already expect.
+- **Lifeline that's both wedged AND offline from the fleet watchdog.** If `launchctl bootout` itself hangs (rare but possible under macOS sandbox bugs), the watchdog's force-restart doesn't land. No recovery within this PR. The fleet watchdog's existing 5-min retry plus the eventual launchd ThrottleInterval re-spawn provide eventual recovery; not always sub-15-minute.
+- **Two AutoUpdater instances racing.** Idempotency-by-targetVersion handles the common case. If two AutoUpdaters write SIMULTANEOUSLY with the same target, the atomic rename ensures one wins cleanly. Different targets → second write replaces the first; either way the lifeline restarts to a coherent target.
+- **Signal corruption (truncated write, half-written JSON).** Reader returns null for corrupt JSON; next writer replaces. Worst case: one missed cycle (~30s for lifeline tick, ~5 min for watchdog).
+- **Tone gate B12 on the "Heads up" alert.** PR #284 already shipped this alert via the existing tone gate. This PR doesn't change the alert content; if a future change introduces jargon, the existing B12 ruleset blocks it and falls back to the safe template.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+- **AutoUpdater is the right writer for the proactive signal.** It KNOWS it's about to bump major.minor (it's about to install a new version). Pushing this knowledge to the lifeline via a signal file is structurally cleaner than expecting the lifeline to infer skew from forward failures.
+- **Server-side 426 writer is a defensible second channel.** The server has direct evidence (the lifeline forwarded a wrong-version request). Even if AutoUpdater somehow missed the boundary, the server can repair the situation.
+- **PostUpdateMigrator is the right home for the one-time bootstrap.** Updates flow through it; the bootstrap is a one-time correction, not an ongoing concern.
+- **Fleet watchdog (out-of-process) for the wedged-lifeline case.** The original ServerSupervisor proposal lived inside the lifeline — wrong layer, would share the wedge. Fleet watchdog has independent process lifetime + already iterates all agents.
+- **`plannedUpgrade` bucket alongside `versionSkew`.** Both are hard-incompatibility signals. Sharing the daily cap (versus separate caps) prevents bucket-hopping abuse.
+- **Deferrals check in the pre-commit hook (not in CI).** Pre-commit catches it before any commit lands; CI is the second-pass authority. Structurally consistent with the other gates in the same hook (ELI16, tracked spec, artifact integrity).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] **No — this change produces signals consumed by existing smart gates.**
+
+Detailed:
+- `crossesBreaking` is a deterministic predicate (mechanic, not judgment).
+- All three signal writers produce a candidate file; consumers decide.
+- `TelegramLifeline.checkLifelineRestartSignal` calls `initiateRestart` — the existing authority — which goes through `rateLimitState.decide`, `RestartOrchestrator.requestRestart`, etc.
+- The fleet watchdog's force-restart is a bounded recovery primitive (the principle's "Safety guards on irreversible actions" exemption — `launchctl bootout/bootstrap` is reversible by reboot but the mechanical action itself is bounded).
+- The new `plannedUpgrade` bucket bypasses watchdog cooldown — but the daily cap (3-per-24h, shared with versionSkew) is the loop-safety backstop, identical to the existing versionSkew design from PR #284.
+- The deferrals-check regex is a hard-invariant validator at the boundary (the principle's "Hard-invariant validation" exemption). Patterns are explicit, narrow, and the override flag exists for legitimate edge cases.
+
+No new judgmental gates over message content or agent intent.
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:**
+  - AutoUpdater writes both `restart-requested.json` (existing) and `lifeline-restart-requested.json` (new). Different consumers, different files. No shadow.
+  - The lifeline's existing in-process versionSkew handler (PR #284) fires on 426 response. This PR's per-tick signal-file consumer is independent — it fires on the SIGNAL FILE. Both fire on the b2lead scenario; first-wins via `initiateRestart` rate-limit and the orchestrator's pid-based serialization.
+  - Watchdog's `check_stale_lifeline_signal` runs in the healthy-PID branch before the bind-probe; on signal-hit it does an early `continue` so the bind-probe doesn't double-react.
+
+- **Double-fire:**
+  - All three writers can fire on the same boundary crossing. The `skipped-fresh` outcome in `writeLifelineRestartSignal` prevents duplicate audit-log entries.
+  - The lifeline's per-tick consumer + the watchdog's per-cycle consumer can both see the same signal. The lifeline acts first (30s cadence vs 5min); on success, it `clearLifelineRestartSignal`'s first. The watchdog's signal-readability check returns null after clear → no double-restart.
+
+- **Races:**
+  - File-write race: tmp + rename is atomic on POSIX; concurrent writers see one win cleanly.
+  - Read-then-delete race in the lifeline: a process exits between read and delete → respawned lifeline sees the signal on next tick → checks `targetVersion === lifelineVersion` → clears and no-ops. Documented in test.
+  - Fleet watchdog vs lifeline-tick race: watchdog only acts when signal is >60s old. The lifeline's 30s tick has two cracks before the watchdog touches anything.
+
+- **Feedback loops:**
+  - The "Heads up" Telegram alert (PR #284 wiring) fires once per skew episode; the lifeline restart that follows doesn't reset the alert dedupe (per-PR-#284 semantics). On recovery, no extra alert.
+  - PostUpdateMigrator runs on every update. Its bootstrap is idempotent (skip-fresh) and only writes when major.minor mismatches the just-installed version. No loop.
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** YES — the fleet watchdog now reads each agent's signal file. Read-only, no cross-agent state. The same fleet watchdog landed in PR #245 / #272 and is already cross-agent-aware.
+- **Other users of the install base:** YES — ships to every macOS agent via PostUpdateMigrator on next update. Linux/Windows users: AutoUpdater and lifeline-tick channels work the same (file-based, OS-agnostic); fleet watchdog channel is macOS launchctl-specific, so Linux users rely on the in-process consumers + the v3 Remediator absorption.
+- **External systems:**
+  - Telegram: one extra topic per affected agent during the rollout (the existing "Heads up" alert from PR #284). After this PR, that alert fires LESS often because the AutoUpdater coordination prevents many episodes from happening in the first place.
+  - launchctl: fleet watchdog now occasionally calls `bootout/bootstrap` on lifeline plists. Already-shipped behavior; this PR adds one more trigger condition.
+- **Persistent state:**
+  - New `state/lifeline-restart-requested.json` per agent — single-line JSON, max ~500 bytes, expires after 1h, cleared by readers on action. Harmless if left behind.
+  - `lifeline-started-at.json` is now READ by the migrator (in addition to its existing write by the lifeline). Format unchanged.
+- **Timing:**
+  - AutoUpdater apply gains one `writeLifelineRestartSignal` call (~5ms file write).
+  - Lifeline gains a 30s-interval `fs.statSync` + occasional JSON parse (~1ms).
+  - Server 426 path gains one signal write (~5ms) — only fires on actual version mismatches.
+
+## 7. Rollback cost
+
+- **Hot-fix:** revert each of the seven source files + the watchdog template. Independently revertable. Ship as a patch.
+- **Data migration:** none. Signal files left behind: harmless (expire in 1h, cleared by readers).
+- **Agent state repair:** none required. Reverting just disables the new behavior; existing agents continue to work via PR #284's in-process handler (which now requires post-PR-#284 lifeline code — i.e., the very thing this PR was meant to deliver).
+- **User visibility:** none. The "Heads up" alert is unchanged in tone and frequency.
+- **Estimated total:** ~30 min revert + release cycle.
+
+---
+
+## Addendum 2026-05-22 — Reviewer findings + fixes
+
+Second-pass reviewer found one structural defect plus two minor items. All three addressed before merge:
+
+**Structural — frontmatter wave-through was a loophole** (`scripts/instar-dev-precommit.js`). The original implementation honored a `deferrals-tracked:` frontmatter field as a whole-spec wave-through. A future author could write `deferrals-tracked: see below` and ship orphan deferrals undetected. **Closed:** the frontmatter wave-through is REMOVED entirely. Every body deferral mention must have its own `<!-- tracked: <id> -->` marker within 200 chars, with no spec-level escape hatch. Test added that asserts the loophole no longer exists (`tests/unit/instar-dev-precommit-deferrals.test.ts:"frontmatter deferrals-tracked is NO LONGER a wave-through"`).
+
+The bootstrap-commit-that-introduces-the-rule itself (this very PR) uses the `INSTAR_DEV_ALLOW_ORPHAN_DEFERRALS=1` env override because the spec describes the rule's vocabulary extensively for documentation purposes — and the audit log entry is the structural visibility. This pattern is documented in `skills/instar-dev/SKILL.md` Phase 4.5 as "the bootstrap-commit exception."
+
+**Minor 1 — narrow `follow-ups` negation regex.** The prior pattern excluded only "follow-ups (are) tracked" and false-alarmed on natural variants. **Broadened:** the regex now matches all "follow-up" / "follow-ups" / "followups" mentions and lets the 200-char tracker-marker check do the work uniformly. Plural "deferrals" added to coverage too — reviewer noted the singular-only pattern would miss it.
+
+**Minor 2 — Server downgrade doc nit.** The §"Under-block" paragraph cited a mitigation pathway that doesn't actually handle the downgrade case. Reasoning corrected above with the file:line reference.
+
+**Confirmed sound (no change needed):** signal-vs-authority compliance; shared `versionSkew`+`plannedUpgrade` daily cap; PR #284 + this PR's signal-consumer coexistence under the orchestrator + rate-limit; watchdog signal-deletion ordering race-safety; `crossesBreaking` fail-safe choice; the one tracked deferral (v3 Remediator at topic 3079) is genuinely separable.
+
+## Conclusion
+
+Closes the deferral that produced today's regression. Adds three writers, three readers, one structural meta-fix, and CLAUDE.md awareness — all in this PR per Justin's 2026-05-22 directive. 43 new tests cover the full pipeline. The structural deferrals-check makes the rule durable across future PRs.
+
+Clear to ship pending second-pass review.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** echo (second-pass subagent)
+**Independent read of the artifact: concern (minor — 2 items, 1 nit). Design is sound; ship after addressing item 1.**
+
+- **Frontmatter wave-through is whole-spec, not per-hit.** The artifact and spec both phrase the rule as "each instance is linked OR the frontmatter waves it through." But `scripts/instar-dev-precommit.js:372` short-circuits the entire body scan when `deferrals-tracked:` is present (`if (hasFrontmatterDeferralsTracked(fmText)) return [];`). A future author can put `deferrals-tracked: see below` in frontmatter and ship a spec full of orphan deferrals with zero per-hit verification. This spec relies on exactly that path — without it, the body's 8+ uses of "deferred" couldn't commit. **Resolution:** when frontmatter wave is present, still require the affirmation to either (a) enumerate each deferral hit's tracker ID explicitly, or (b) reference a `## Deferrals tracked` section that the gate verifies contains a `<!-- tracked: ... -->` marker for each unique deferral phrase the body emits. This spec already has §"Deferrals tracked" structured correctly; the gate just doesn't validate it.
+
+- **`follow-ups` negation is narrow.** `scripts/instar-dev-precommit.js:359` only excludes "follow-ups (are )?tracked". Natural variants — "follow-up is tracked", "follow-up has an owner", "follow-up at topic-XYZ" — false-alarm. Low harm (override flag exists), but adds friction. **Resolution:** broaden the lookahead to also accept "is tracked", "owned by", or any `<!-- tracked: ... -->` within the same line, OR drop the negation and rely solely on the within-200-char tracker-marker check that's already running for every other pattern.
+
+- **Nit — §"Under-block: Server downgrade" reasoning is wrong.** The artifact says targetVersion===currentVersion skip handles downgrades. It doesn't — for a 1.2.28 lifeline against a 1.1.0 install, those differ, and the signal fires. The actual behavior is fine (it re-aligns toward the new install), but the stated mitigation isn't the one that runs. `TelegramLifeline.ts:1338` only skips on identity.
+
+**Concur on the rest:**
+- Signal-vs-authority compliance: all three writers + `crossesBreaking` are pure mechanics; `initiateRestart` and the shared `rateLimitState.decide` are the single authority (`src/lifeline/rateLimitState.ts:121-135` correctly shares the daily cap across `versionSkew` and `plannedUpgrade` — no bucket-hopping bypass).
+- PR #284 absorption: `handleVersionSkew` (TelegramLifeline.ts:1275) and `checkLifelineRestartSignal` (TelegramLifeline.ts:1327) can both fire on the same skew episode, but the orchestrator serializes via PID and the shared 3-per-24h cap is the loop backstop. No harmful double-fire.
+- Watchdog ordering: signal deletion after `bootstrap` (instar-watchdog.sh:589) is race-safe — respawned lifeline's same-version no-op (TelegramLifeline.ts:1338) handles any read-then-delete window.
+- `crossesBreaking` fail-safe to `true` for malformed inputs is the correct choice given the false-positive cost (one harmless restart) vs false-negative cost (the exact incident class).
+- Non-goals list is genuinely separable; the one tracked deferral (v3 Remediator absorption) has a real marker (`<!-- tracked: topic-3079-v3-remediator -->`) and the absorption point is mechanical.
+- Linux/Windows coverage via in-process consumers (lifeline tick) is honest — the macOS-only fleet watchdog is the third channel, not the only one. Acceptable.
+
+Items 2 and 3 are non-blocking. Item 1 is a structural loophole in the very gate being introduced — recommend tightening before merge so the rule the artifact promises is the rule the code enforces.
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/auto-updater-lifeline-coordination.md` (with ELI16 companion).
+- Tests: 5 new test files, 43 new tests.
+- Incident reference: b2lead-insights regression 2026-05-22, ~46h silent Telegram ingress drop. Lifeline pinned at v1.1.0 while server auto-updated through 27 minor releases to v1.2.28.
+- PR #284's spec explicitly deferred "lifeline auto-restart on server upgrade" as Forward note (NOT in this PR) — this PR closes that forward note.

package/upgrades/side-effects/owner-dm-channel.md

@@ -0,0 +1,152 @@
+# Side-effects review — owner-DM channel + notifier sink wiring (PR 3 of tunnel-failure-resilience chain)
+
+**Scope (PR 3 of the chain):** Add the owner-DM messaging surface and
+wire it into the tunnel manager's two-channel notifier. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged
++ approved on main. Public API: `TelegramAdapter.getOwnerUserId()` and
+`TelegramAdapter.sendToOwnerDM(text)` are new; `TunnelManager.attachTelegram()`
+is new; the notifier now substitutes live URL + PIN credentials into
+owner-DM messages via a `credentialProvider` callback.
+
+**Files touched:**
+- `src/messaging/TelegramAdapter.ts` — adds `ownerUserId?: number` to
+  `TelegramConfig`; adds `getOwnerUserId()` accessor (falls back to
+  `promptGate?.ownerId` for back-compat); adds `sendToOwnerDM(text)`
+  which posts to the owner's private bot chat via `sendMessage` with
+  `chat_id: ownerUserId`. The DM send is fire-and-forget: failure paths
+  ("no owner configured", "owner hasn't messaged the bot", network
+  error) log-not-throw and return `null` so callers can degrade
+  gracefully.
+- `src/tunnel/TunnelNotifier.ts` — adds `credentialProvider?: () =>
+  CredentialSnapshot` to `TunnelNotifierOptions`. The four owner-DM
+  message variants (recovered, restored, consent prompt, relay
+  activated) now compose real English text with the credentials
+  substituted at compose time. The four group-channel variants
+  continue to carry status text only — credentials NEVER appear in
+  group messages.
+- `src/tunnel/TunnelManager.ts` — new `attachTelegram(adapter,
+  dashboardPin)` method builds a notifier sink from a duck-typed
+  `TunnelMessagingAdapter` (group → Dashboard topic with Lifeline
+  fallback; owner DM → `sendToOwnerDM`) and a credentialProvider that
+  returns `{ url: this.url, pin: dashboardPin() }`. Holds the notifier
+  in a mutable field so callers can wire it AFTER tunnel construction
+  (the messaging adapter is constructed later in server.ts).
+- `src/commands/server.ts` — calls `tunnel.attachTelegram(telegram,
+  () => liveConfig.get(...) || config.dashboardPin)` after the
+  Dashboard topic is ensured. The wire is non-fatal: if attachTelegram
+  throws, the catch around `ensureDashboardTopic` already swallows it.
+- `tests/unit/tunnel-notifier.test.ts` — replaces the placeholder
+  assertions with real-credential assertions: a DM with a credential
+  provider contains the URL + PIN; a DM without a provider renders a
+  graceful "link not available yet" placeholder; group messages NEVER
+  contain credentials.
+- `tests/unit/tunnel-manager-rewrite.test.ts` — 3 new tests for
+  `attachTelegram`: Dashboard-topic routing, Lifeline fallback when
+  Dashboard isn't ensured, owner-DM credential snapshot includes the
+  live URL and current PIN.
+
+**Under-block**: None. The owner-DM channel adds NEW capability;
+existing behavior is unchanged when no `ownerUserId` is configured
+(`sendToOwnerDM` logs a warning and returns null; the notifier's DM
+sink call is a no-op). Existing Telegram group flows are untouched.
+
+**Over-block**: None — but note the existing
+`config.promptGate?.ownerId` continues to serve as a back-compat
+fallback when `ownerUserId` isn't set explicitly. Operators who used
+`promptGate.ownerId` to mark their session-prompt owner will see that
+same user receiving the tunnel-DM messages, which is consistent with
+the spec's "owner principal" intent. New deployments should set
+`ownerUserId` explicitly.
+
+**Level-of-abstraction fit**:
+- TunnelManager remains the single owner of the lifecycle; the
+  notifier sink is a thin pass-through to the messaging adapter.
+- The `TunnelMessagingAdapter` duck-typed interface keeps the tunnel
+  module from importing `TelegramAdapter` directly — preserves the
+  layered architecture (tunnel does not depend on messaging type).
+- Credential substitution happens in the notifier's composer methods.
+  The notifier never holds credentials in its own state; it calls
+  the provider at compose time so the credentials are always fresh.
+
+**Signal vs authority**: Compliant. The credentialProvider returns a
+SIGNAL (current URL + PIN); the notifier remains the AUTHORITY for
+deciding when an owner-DM message goes out and what it says. The
+sink is the routing layer (executes the send); the messaging adapter
+is the platform layer. No new authority introduced at the wrong
+layer.
+
+**Interactions**:
+- `TunnelManager` constructed in server.ts BEFORE telegram, so the
+  manager initially has no notifier. The wire-up happens AFTER
+  telegram + Dashboard topic are ready (one-shot call to
+  `attachTelegram`). Until then, transitions go through the lifecycle
+  but no user-facing messages fire — preserving the boot-time
+  ordering established in PR 2.
+- The credentialProvider closes over `this._legacyState.url` and
+  the dashboardPin accessor; both are read at each compose, so a
+  PIN rotation (PR 5) will be visible to subsequent messages without
+  re-attaching.
+- `sendToOwnerDM` failure modes are absorbed inside the adapter — the
+  sink wrapper never throws into the notifier path. Preserves the
+  fire-and-forget invariant.
+
+**External surfaces**:
+- New config field: `messaging.config.ownerUserId` (number). Optional.
+  Falls back to `messaging.config.promptGate.ownerId`. Documented in
+  the spec.
+- No new API endpoint. No new CLI command.
+- `TelegramAdapter.sendToOwnerDM(text)` is a new public method but
+  intended for in-process callers only (the tunnel manager is the
+  first caller; future PRs may add more).
+
+**Migration parity**:
+- No agent-installed file change in this PR. Existing agents pick up
+  the new behavior the moment they update — the `ownerUserId` field
+  remains optional with the documented fallback.
+- A future PR in the chain (the ConfigDefaults / migration PR) will
+  add a ConfigDefaults entry for `ownerUserId` and a CLAUDE.md
+  template note so the agent surfaces the new capability
+  conversationally. For now the manager's behavior degrades
+  gracefully when the field is absent.
+
+**Rollback cost**: Trivial. Revert four source files + the test
+updates. The two new public methods (`getOwnerUserId`,
+`sendToOwnerDM`, `attachTelegram`) become unused; the
+`TunnelMessagingAdapter` interface becomes dead code. Nothing else
+breaks.
+
+**Tests**:
+- 19/19 `tests/unit/tunnel-manager-rewrite.test.ts` (3 new for
+  `attachTelegram`).
+- 13/13 `tests/unit/tunnel-notifier.test.ts` (placeholder assertions
+  replaced with credential assertions; 1 new "no-credential
+  gracefully renders 'link not available'" test).
+- 32/32 `tests/unit/tunnel-lifecycle.test.ts` (no change).
+- 10/10 `tests/unit/tunnel-providers.test.ts` (no change).
+- `tsc --noEmit` clean. `npm run lint` clean.
+
+**Decision-point inventory**:
+1. Owner principal modeled as `ownerUserId` separate from
+   `authorizedUserIds` (vs. reusing the broader set) — the GPT
+   external review specifically flagged that consent / credential
+   exposure decisions must NOT trust the broader authorized-users
+   set. A separate single-principal field is the structural fix.
+2. `sendToOwnerDM` returns null on failure (vs. throwing) — preserves
+   the fire-and-forget contract callers expect for outbound
+   messaging. The bot can't initiate a DM until the user has messaged
+   the bot first, so an early "forbidden" response is expected during
+   onboarding; treating it as fatal would block tunnel notifications
+   indefinitely.
+3. `attachTelegram` is a post-construction method (vs. constructor
+   parameter) — the messaging adapter is constructed later than the
+   tunnel manager in server.ts. Putting the sink in the constructor
+   would require restructuring boot order. The post-attach pattern
+   keeps the existing boot sequence and is testable.
+4. `TunnelMessagingAdapter` duck-typed interface (vs. direct
+   `TelegramAdapter` import) — keeps the tunnel module from depending
+   on the messaging layer's concrete types; future PRs can add Slack
+   / iMessage variants without modifying tunnel/.
+5. credentialProvider returns a snapshot (vs. holding the URL/PIN as
+   notifier state) — the notifier composes messages over time; a
+   stale PIN cached in notifier state would leak after rotation. The
+   provider pattern keeps credential freshness in one place.