instar 1.3.376 → 1.3.378

package/upgrades/side-effects/mesh-cold-call-resilience.md

@@ -0,0 +1,63 @@
+# Side-Effects Review — Mesh cold-call resilience (live-matrix T1)
+
+**Version / slug:** `mesh-cold-call-resilience`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Per-call `{ timeoutMs }` override on `MeshRpcClient.send` (default unchanged);
+the working-set pull send uses 30s and the commitment-mutate forward 15s; the
+working-set puller adds ONE bounded immediate re-send on transport failure.
+Closes live-matrix finding T1: the 5s flat default was measured aborting the
+first call over an idle tunnel three times in one afternoon, degrading pulls
+and forwards to their minutes-later fallback paths.
+
+## Decision-point inventory
+
+Two: (1) which verbs get a longer budget — only the two measured-failing heavy
+verbs; every other caller keeps the 5s default. (2) when the puller re-sends —
+exactly once per verb call on a thrown transport error; a second consecutive
+failure propagates.
+
+## 1. Over-block
+
+Nothing new is blocked. Longer timeouts only widen acceptance windows.
+
+## 2. Under-block
+
+A genuinely-down peer now takes up to 30s (pull) / 15s (forward) to be
+declared unreachable instead of 5s, plus one re-send. Bounded worst-case added
+latency before the fallback path engages: ~60s for a pull verb. The fallback
+paths themselves (pending-pull ledger, queued mutation with opKey) are
+unchanged and still catch everything.
+
+## 3. Level-of-abstraction fit
+
+The override lives at the client (per-call concern); the budgets live at the
+call sites (caller knowledge of payload weight); the re-send lives in the
+puller's existing retry funnel (`sendWithBusyRetry`) beside the busy-retry
+policy it mirrors.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No authority added. Pure transport robustness; all refusal/queue semantics
+unchanged.
+
+## 5. Interactions
+
+- Pending-pull ledger: strictly fewer entries (cold flakes masked); failure
+  path identical.
+- Queued commitment mutations: same — the ambiguous-outcome (B24) queue with
+  same-opKey re-fire is untouched and still covers a timeout at 15s.
+- Busy-retry: the re-send shares the loop but its budget is separate (one per
+  verb call) — busy responses never consume the cold-retry and vice versa.
+- P19 (No Unbounded Loops): the re-send is a single bounded attempt; tests
+  assert two consecutive failures propagate.
+
+## 6. External surfaces
+
+None. No routes, no config, no notifications. Internal mesh transport only.

package/upgrades/side-effects/sessionmonitor-ctx-ledger-persistence.md

@@ -0,0 +1,58 @@
+# Side-Effects Review — SessionMonitor ctx-notified ledger persistence
+
+**Version / slug:** `sessionmonitor-ctx-ledger-persistence`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (SMALL, single-component, both-sides tested)`
+
+## Summary of the change
+
+The once-per-death-episode dedup map in SessionMonitor (`ctxNotifiedSessions`,
+added by #914) was in-memory only — every server restart re-announced already-
+announced dead sessions, once per boot (2026-06-06 residual, topics 16566 +
+19437; operator pick 1Y approved persisting it). The map is now persisted to
+`state/session-monitor-ctx-notified.json` (atomic tmp+rename), loaded at
+construction with a 7-day prune, and updated on both mutation sites (notify →
+set, successful recovery → delete).
+
+## Decision-point inventory
+
+- Load: missing file → empty; corrupt file → warn + empty (never throws);
+  entry older than 7 days or malformed → dropped. All arms tested.
+- Persist: write failure → one-time warn, monitoring continues (degrades to
+  pre-persistence behavior). statePath absent → feature inert (tested).
+
+## 1. Over-block
+
+A persisted episode could suppress a notice the user wanted if the SAME
+topic+sessionName genuinely dies twice without an intervening recovery or
+respawn — but the same was already true in-memory within one server lifetime;
+persistence only extends the existing semantics across boots. The 7-day prune
+bounds the suppression horizon.
+
+## 2. Under-block / residual risk
+
+- A respawn that reuses the SAME tmux session name after a fresh death still
+  notifies (sessionName equality is the episode key — unchanged semantics).
+- Multi-machine: the ledger is machine-local (registered as such); a topic
+  transferred to another machine starts a fresh episode there. Acceptable —
+  the post-transfer closeout kills the old session anyway.
+
+## 3. Level-of-abstraction fit
+
+Persistence lives inside SessionMonitor next to the map it persists; the path
+is injected via deps (testable, inert when absent); wiring at the single
+construction site in server.ts; the new state file is declared in
+`src/data/state-coherence-registry.json` (machine-local / single-writer / none)
+so the state-registry lint passes at birth.
+
+## Rollback
+
+Revert the PR; the orphaned state file is inert (nothing reads it) and ≤ a few
+hundred bytes.
+
+## Blast radius
+
+Server-side only; no agent-installed files, no hooks, no config defaults, no
+template changes → no Migration Parity obligations. New state file is created
+lazily on first notify.