instar 1.3.648 → 1.3.650

package/upgrades/side-effects/dashboard-health-signal-polish.md

@@ -0,0 +1,59 @@
+# Side-Effects Review — Dashboard health-signal polish (3 pre-existing fixes)
+
+**Version / slug:** `dashboard-health-signal-polish`
+**Date:** `2026-06-23`
+**Author:** Echo (autonomous)
+**Tier:** 1 (three contained, low-risk fixes — two client-side dashboard guards + one health-status windowing on an endpoint whose `status` field does not gate restarts on this agent)
+**Second-pass reviewer:** not-required (Tier 1; small contained fixes, the server-side change covered by new unit tests)
+
+## Summary of the change
+
+Three minor, pre-existing dashboard issues found while verifying the dashboard-freeze fix (#1253). None affect the dashboard connection; all are noise/cosmetic.
+
+1. **WhatsApp QR poll spam.** `pollWaQr()` polls `/whatsapp/qr` every 3s. When WhatsApp isn't configured the route returns 503, but the poll loop was never stopped — so the browser console accumulated ~20 503s/min for the whole session. Fix: call `stopWaPolling()` on the 503 (adapter absent).
+2. **Null-deref TypeError on load.** A parse-time block attached a `'message'` listener to `ws`, guarded by `if (typeof ws !== 'undefined')`. `ws` is a declared `let` that is **null** at parse time (`connectWebSocket()` runs later in a `.then()`), and `typeof null === 'object' !== 'undefined'`, so the guard passed and `ws.onmessage` threw `Cannot read properties of null (reading 'onmessage')` on every load. The block was the only place paste WebSocket events refreshed the drop-zone — so the feature was also effectively dead. Fix: fold `paste_delivered` / `paste_acknowledged` into the main `handleMessage` switch (where it survives reconnects) and remove the broken parse-time block.
+3. **Stale "Degraded" badge.** The vital-signs badge renders `/health`'s `status`, which is `degraded` whenever `DegradationReporter.getEvents().length > 0`. Degradation events are append-only and never self-clear, so a single transient/benign fallback pins the badge red for the entire process lifetime even after recovery. Fix: `/health` now uses a new `DegradationReporter.getRecentEvents()` (30-min window) for status + the reported count/summary — a persistent problem keeps re-reporting so it stays visible; a one-off ages out.
+
+## The change
+
+- `dashboard/index.html` — (1) `stopWaPolling()` on 503; (2) paste cases added to `handleMessage`, broken parse-time block removed.
+- `src/monitoring/DegradationReporter.ts` — new `getRecentEvents(windowMs = HEALTH_WINDOW_MS, now = Date.now())` + `static HEALTH_WINDOW_MS = 30min`. Filters by event `timestamp`; an unparseable timestamp is KEPT (fail-safe: surface, never hide). `getEvents()` (full log) is unchanged.
+- `src/server/routes.ts` — `/health` calls `getRecentEvents()` instead of `getEvents()` for the `degradations` list that feeds `status` + `degradations` count + `degradationSummary`.
+- `tests/unit/degradation-reporter.test.ts` — 3 new tests (recent kept / old aged out / unparseable kept).
+
+## Side effects & risk
+
+- **`/health` status semantics.** `status` flips back to `ok` once degradations age past 30 min without recurring. Reviewed consumers: the **Telegram lifeline** derives `serverHealthy` from the supervisor's process status, NOT from `/health.status`, so this never affects restart behavior on a Telegram agent (Echo). `SlackLifeline` keys on `status === 'ok'` only to detect the unhealthy→healthy *recovery* transition (a log/notify), not to trigger restarts. The change makes status MORE truthful (reflects current health), and is the safe direction (a real, recurring problem keeps re-reporting and stays visible).
+- **The full degradation log is untouched.** `getEvents()`, `getUnreportedEvents()`, mark-reported, and persistence all still see every event — only the /health *status view* is windowed.
+- **Client-side fixes are isolated** to the dashboard static asset; no server behavior changes; the dashboard isn't in the typecheck/test suite, so both were syntax-checked with `node --check`.
+- **Risk:** low. No new config, no new route, no migration (the dashboard asset + core source ship with the package on update). Reversible (revert the three edits).
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+This change touches `dashboard/index.html`. It alters **background behavior**, not layout or primary actions — so it adds no new operator-facing controls or content. Against the four criteria:
+
+1. **Leads with the primary action?** Unchanged — the dashboard still leads with the session list + vital-signs strip. No new primary action is introduced; nothing is moved, collapsed, or pushed below the fold.
+2. **Zero raw internals as primary content?** Yes — the change adds NO displayed content. It REMOVES noise (the WhatsApp console 503 spam) and an on-load TypeError, and makes the existing plain-language health badge ("Healthy" / uptime vs "Degraded") accurate. No JSON/UUID/fingerprint/hash is shown.
+3. **Destructive actions de-emphasized?** N/A — no destructive control is added or touched.
+4. **Plain language + phone width?** Yes — the only user-visible behavioral change is the top-of-dashboard badge now correctly reads "Healthy" when the box is healthy (it was stuck on "Degraded"). Plain wording, same layout, same width — no new elements, so no phone-width regression.
+
+(The dashboard's pre-existing raw-input field — the PIN/token unlock — already carries the co-located `operator-surface-power-user` marker and is untouched here.)
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** The vital-signs badge reads THIS machine's `/health`; each machine's `DegradationReporter` and health state are local, per-machine observability (a degradation on machine A is machine A's concern). The dashboard already exposes pool-wide state through separate `?scope=pool` surfaces (sessions, guards, attention, …), which this change does not touch. The WhatsApp poll and the paste WS handler are pure client-side, per-browser-tab.
+
+- **User-facing notices?** None emitted — no one-voice gating concern.
+- **Durable state strand on topic transfer?** No durable state added; nothing strands.
+- **Generated URLs?** None.
+
+## Verification
+
+- `tsc --noEmit`: 0 errors.
+- `tests/unit/degradation-reporter.test.ts`: 20/20 (incl. 3 new windowing tests).
+- `tests/unit/{routes-degradations-mark-reported,degradation-never-silent,degradation-reporter-reentrancy-wedge}.test.ts`: 14/14 (no regression on the mark-reported / never-silent paths).
+- `dashboard/index.html` embedded script: `node --check` passes.
+
+## Rollout
+
+No flag, no migration. Three additive fixes that surface previously-hidden console errors and make the health badge truthful. The genuinely-stale `systemReview` *panel* (last ran 2026-06-20, never re-runs) is a SEPARATE, more-involved concern (re-running 16 probes on a cadence is cost-bearing) — explicitly NOT bundled here; tracked for follow-up.

package/upgrades/side-effects/systemreview-onboot-refresh.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — SystemReviewer on-boot refresh (fix stale "Degraded" panel)
+
+**Version / slug:** `systemreview-onboot-refresh`
+**Date:** `2026-06-23`
+**Author:** Echo (autonomous)
+**Tier:** 1 (one added on-boot review timer on a self-scheduling monitor; behavior-additive, behind a default-on flag, covered by 4 new unit tests)
+**Second-pass reviewer:** not-required (Tier 1)
+
+## Summary of the change
+
+The SystemReviewer (the probe-health "system review" surfaced in `/health`, rendered as the dashboard health panel) runs a full review every `scheduleMs` (default 6h). But `start()` only set up the interval — it ran NO review on boot. On an agent that restarts more often than 6h (updates, recovery bounces, the dashboard-freeze restarts), the 6h timer resets on every boot and never fires, so the displayed review stays frozen at the last pre-restart boot. Observed live: the systemReview in `/health` was stuck at `2026-06-20T11:51` (the meltdown) — days stale, showing "critical / 11-of-16 probes passed" long after the box recovered.
+
+## The change
+
+- `src/monitoring/SystemReviewer.ts` — `start()` now schedules ONE on-boot review (`setTimeout`, default 30s delay, unref'd) in addition to the interval, gated by `shouldRunInitialReview()`: it runs only when the last persisted review is absent or older than `initialReviewStaleAfterMs` (default 1h), so a restart loop doesn't pile up reviews. An unparseable timestamp is treated as stale (run it — fail toward fresh). New config: `reviewOnStart` (default true), `initialReviewDelayMs` (30s), `initialReviewStaleAfterMs` (1h). `stop()` clears the new timer.
+- `src/commands/server.ts` — forwards the three new config fields to the SystemReviewer so `reviewOnStart: false` is honored as an off-switch.
+- `src/core/types.ts` — the three new optional fields on `monitoring.systemReview`.
+- `tests/unit/SystemReviewer.test.ts` — 4 new tests (no-prior→runs, stale→runs, fresh→skips, reviewOnStart:false→never).
+
+## Side effects & risk
+
+- **Cost: one extra review per boot, only when stale.** The probes are LOCAL checks (no LLM, no network — verified by reading the probe sources), so a review is cheap. The freshness guard means even a rapid restart loop triggers at most one review per `initialReviewStaleAfterMs` window, not one per boot.
+- **Boot is not slowed.** The review is on a 30s `setTimeout`, unref'd, and `review()` is already async — it never blocks startup.
+- **Default-on, with an off-switch.** `monitoring.systemReview.reviewOnStart: false` disables it. Existing agents get the default (true) via the constructor's DEFAULT config — no migration needed (a code-side default, not a persisted-config requirement).
+- **Failure is contained.** An on-boot review error goes to the existing dead-letter path (the same `writeDeadLetter` the interval uses), independent of DegradationReporter by design.
+- **Risk:** low. Additive timer on a self-scheduling monitor; reversible (flag or revert); covered by tests.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** Each machine runs its own SystemReviewer over its own probes and persists to its own `review-history.jsonl`; the `/health` systemReview reflects THIS machine's health. The on-boot review is per-machine local behavior — no cross-machine state, no notice emitted, no URL generated. A pool already surfaces each machine's health via that machine's own `/health`.
+
+## Verification
+
+- `tsc --noEmit`: 0 errors.
+- `tests/unit/SystemReviewer.test.ts`: 128/128 (124 existing + 4 new on-start tests covering both sides of the staleness boundary).
+
+## Rollout
+
+No migration. Default-on (the stale panel is a clear bug); off-switch via `monitoring.systemReview.reviewOnStart: false`.

package/upgrades/side-effects/worktree-monitor-async-git.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — WorktreeMonitor async git scans
+
+**Version / slug:** `worktree-monitor-async-git`
+**Date:** `2026-06-23`
+**Author:** Echo (autonomous)
+**Tier:** 1 (behavior-preserving async refactor — no new feature, no decision points, no dark-gate, no migration)
+**Second-pass reviewer:** not-required (Tier 1; small, low-risk, fully covered by existing unit tests)
+
+## Summary of the change
+
+`WorktreeMonitor.scanWorktrees()` issues several git commands — `git worktree list --porcelain` plus per-worktree `rev-list`/`diff` — through a private `gitCommand()` that used **`spawnSync('/bin/sh', ['-c', 'git …'])`**. On a repository with many worktrees (Echo accumulated ~282) `git worktree list` alone takes seconds, and the scan ran on BOTH a 5-minute periodic timer AND on every `sessionComplete` event. Each scan therefore blocked the **server event loop** synchronously for seconds.
+
+That freeze was invisible on `localhost` (the dashboard websocket reconnects instantly), but over the Cloudflare tunnel (`echo.dawn-tunnel.dev`) a 1–2s freeze times out in-flight requests, dropping the dashboard websocket and failing its polls → the user-visible "Disconnected / 0 sessions / Mem 0%". This is the residual event-loop-block cause behind the dashboard "disconnected" reports, after the sync-READ fixes in #1247–#1251.
+
+## The change
+
+Convert `gitCommand` from `spawnSync` to async `execFile` (promisified), and propagate `await` through the scan call graph so the event loop stays responsive while git runs in the background.
+
+Files modified:
+- `src/monitoring/WorktreeMonitor.ts` — `gitCommand` → `async` (execFile, stdout-on-nonzero-exit/timeout semantics preserved to exactly match the old `spawnSync result.stdout ?? ''`); `listWorktrees`, `checkUnmergedWork`, `findOrphanBranches`, `getDefaultBranch`, `getWorktreeAge`, `scanWorktrees` → `async`; `periodicScan` resolves worktree ages with `Promise.all` before filtering; `formatPeriodicAlert` → `async`.
+- `src/server/routes.ts` — `GET /hooks/worktrees` handler → `async`, awaits `scanWorktrees()`.
+- `tests/unit/worktree-monitor.test.ts` — the 13 tests that called the now-async methods updated to `await` them.
+
+## Side effects & risk
+
+- **Behavior preserved.** The scans still run on the same triggers and the same 5-minute interval; only the blocking changed to non-blocking. `gitCommand`'s return contract (stdout even on a non-zero exit / timeout) is kept identically, so callers see the same strings.
+- **No external surface change.** `GET /hooks/worktrees` returns the same JSON; the periodic + post-session alert paths are unchanged.
+- **Concurrency.** Scans are serialized per the existing event flow (no new parallelism introduced beyond `Promise.all` over `getWorktreeAge`, which is read-only `git show` per worktree).
+- **Risk:** low. A behavior-preserving async conversion, fully covered by the existing 22 unit tests (updated to await) + the serendipity-routes integration tests, both green.
+
+## Verification
+
+- `tsc --noEmit`: 0 errors.
+- `tests/unit/worktree-monitor.test.ts`: 22/22 pass.
+- `tests/integration/serendipity-routes.test.ts`: 22/22 pass.
+
+## Rollout
+
+No flag, no migration — the fix is strictly better behavior on the existing code path and ships on the next release. (A shadow-dist hotpatch — disabling both scan triggers — relieved the freeze immediately on the affected agent; this PR is the durable replacement that keeps the feature working without blocking.)