instar 1.3.582 → 1.3.583

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-15T22:53:11.307Z",
-  "instarVersion": "1.3.582",
+  "generatedAt": "2026-06-15T23:23:58.124Z",
+  "instarVersion": "1.3.583",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.583.md

@@ -0,0 +1,51 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A short timer drift that recurs while load sits in the **1.0–1.5/core band** slipped past both
+existing guards: the load guard fires only above 1.5/core, and the consecutive burst floor resets
+whenever on-time ticks fall between drifts. Its ~2-minute cadence also outlasted the 60s cooldown.
+So each isolated drift emitted a **false `wake`**, firing the full wake-recovery cascade (tunnel
+restart, Slack reconnect, mesh-lease churn, topic failover) — the source of a class of multi-machine
+UX failures: a reply that's lost the conversation thread, messages that get no reply, and "remote
+typing is disabled" (the 2026-06-15 incident, measured at ~1.13/core).
+
+The detector now adds a **recurring-drift guard**: a short drift within `recentDriftWindowMs`
+(default 5 min) of a prior short drift, while load is oversubscribed (`> recentDriftLoadFloor`,
+default 1.0/core), is treated as recurring CPU starvation and suppressed. This generalizes the burst
+floor from *consecutive* ticks to *recent* ticks, and the load gate confines it to the
+oversubscribed band the hard guard leaves open.
+
+## What to Tell Your User
+
+- **Fewer spurious reconnects on a busy laptop**: "When my machine got busy I used to mistake the
+  slowdown for the computer going to sleep, which kicked off a disruptive recovery — dropping the
+  conversation thread, going quiet, or disabling typing. I now recognize that pattern and stay calm,
+  so those multi-machine glitches should largely stop."
+- **Real sleeps still handled**: "If the machine genuinely sleeps, I still notice and recover
+  properly — nothing changes there."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Suppress false "wake" events from CPU starvation on a loaded host | automatic |
+| Tune or disable the new guard | `monitoring.sleepWake.recentDriftWindowMs` / `.recentDriftLoadFloor` (set window to 0 to disable) |
+
+## Evidence
+
+Reproduction (live, 2026-06-15): on a host measured at loadavg ~18 on 16 cores (~1.13/core — above
+1.0 but below the 1.5 hard guard), `server.log` showed `[SleepWakeDetector] Wake detected after
+~33s/~21s sleep` recurring roughly every 2 minutes while the host was actively in use (not sleeping),
+each triggering the wake-recovery cascade. The drifts were isolated (on-time ticks between them reset
+the consecutive counter) and ~2 min apart (outlasting the 60s cooldown), so neither existing guard
+caught them.
+
+After the fix (verified by 45/45 sleep-wake unit tests across 5 files, both sides of the boundary): a
+recurring short drift in the 1.0–1.5 band is suppressed (no `wake` emitted, recorded as
+`cpu-starvation`); a genuinely isolated short drift, any drift on a light/idle host (ratio ≤ 1.0),
+and every long (real) sleep still emit; `recentDriftWindowMs: 0` restores byte-identical prior
+behavior. tsc clean.

package/upgrades/side-effects/sleepwake-recurring-drift-guard.md

@@ -0,0 +1,46 @@
+# Side-effects — SleepWakeDetector recurring-drift guard (gap #3 / CMT-1563)
+
+## What changed (3 files)
+
+- `src/core/SleepWakeDetector.ts` — new config `recentDriftWindowMs` (default 300000) +
+  `recentDriftLoadFloor` (default 1.0); new state `lastShortDriftAtMs`; a new suppression branch
+  in `start()` (after the load guard, before the cooldown) that suppresses a SHORT drift recurring
+  within the window while `loadRatio > recentDriftLoadFloor`. Reuses the existing `cpu-starvation`
+  suppression reason — the stats/telemetry type is unchanged.
+- `src/core/types.ts` — `config.monitoring.sleepWake` gains the two optional knobs (mirrors the
+  existing `maxLoadRatio` plumbing; no ConfigDefaults change, no migration).
+- `src/commands/server.ts` — the production `new SleepWakeDetector({...})` boot site forwards the
+  two new knobs from `config.monitoring.sleepWake`.
+
+## Behavioral side-effects
+
+- **On a moderately-loaded host (loadRatio in the 1.0–1.5 band):** a short timer drift that recurs
+  within 5 min of a prior short drift no longer emits a `wake` — so it no longer triggers the
+  wake-recovery cascade (tunnel restart / Slack reconnect / mesh-lease churn / topic failover). This
+  is the fix for the 2026-06-15 multi-machine UX cascade.
+- **No change** on a light/idle host (ratio ≤ 1.0): repeated short drifts still emit (the existing
+  "genuinely-isolated drifts both emit" behavior is preserved — verified by the unchanged tests).
+- **No change** for long sleeps (≥ `longSleepFloorSeconds`): always emitted, recovery preserved.
+- **No change** for an isolated short drift (no prior drift in the window): still emits.
+- The wake-reaper's cumulative-sleep accounting is unaffected — suppressed drifts were already
+  excluded from `wakeHistory`, and this branch suppresses the same way.
+
+## Risk + rollback
+
+- HIGH-risk surface (session-lifecycle / recovery trigger). Fail-safe direction: the branch only
+  ADDS suppression to a SHORT drift on an OVERSUBSCRIBED host; it can never suppress a real long
+  sleep or change light-host behavior.
+- Rollback lever: `config.monitoring.sleepWake.recentDriftWindowMs: 0` disables the guard with no
+  logic redeploy (restores exactly today's behavior).
+
+## Tests
+
+- `tests/unit/sleep-wake-starvation-guard.test.ts` — new `describe('recurring-drift guard for the
+  moderate-load band')` with 5 cases (band-suppress, light-host-emit, isolated-emit, disable-lever,
+  long-sleep-exempt). Full sleep-wake unit suite: 39/39 green. tsc clean on the touched files.
+
+## Migration parity
+
+The fix ships in the class default, so every agent gets it on update (the boot site reads optional
+config but the default is in the constructor). No `.claude`/hook/skill/CLAUDE.md template change is
+required — this is an internal monitoring guard, not an agent-facing capability or route.