instar 1.3.383 → 1.3.385

package/upgrades/outbound-content-dedup.eli16.md

@@ -0,0 +1,32 @@
+# ELI16 — Duplicate-Message Suppression
+
+## The problem
+
+You flagged it and the logs proved it: the same status message went out to you
+THREE times — two of them byte-for-byte identical, 13.5 minutes apart. That's me
+sending the same thing twice, which is exactly as annoying as it sounds.
+
+Why did the existing safeguards miss it? There was a guard that catches "the
+exact same send retried" — but these were two SEPARATE sends with the same
+words, 13 minutes apart, so it didn't count them as the same. And the smarter
+content-check was being skipped on the very paths these went through (status
+relays, cross-machine).
+
+## What this fixes
+
+I added a dead-simple, reliable check right where messages go out: if I'm about
+to send you the SAME message text in the SAME topic that I already sent in the
+last ~15 minutes, the repeat is dropped — you just don't get pinged twice. The
+first one still goes through normally.
+
+It's deliberately careful so it never over-corrects:
+- **Short acks are exempt.** If you send me two things and I reply "Got it" to
+  both, you still see both — only longer, substantial messages get deduped.
+- **Per-conversation.** The same text in a different topic still sends.
+- **I can force a repeat** when I genuinely mean to (rare) with an explicit flag.
+- **A failed send isn't remembered**, so a real retry of something that didn't
+  go through is never swallowed.
+
+Tested both ways: identical status 13 min apart → second one dropped; two
+different messages → both sent; two short acks → both sent; cross-topic → sent.
+Run through the real send path, not just in isolation.

package/upgrades/side-effects/outbound-content-dedup.md

@@ -0,0 +1,79 @@
+# Side-Effects Review — Outbound Content-Dedup
+
+**Version / slug:** `outbound-content-dedup`
+**Date:** `2026-06-06`
+**Author:** `Echo (instar-dev agent — Justin: "We really need to work on not sending duplicate messages. Let's make this much more robust.")`
+**Second-pass reviewer:** `self-adversarial pass over the one real risk — suppressing a message the user actually needed`
+
+## Summary of the change
+
+A pure `OutboundContentDedup` (per-topic, windowed, length-gated content
+fingerprint) wired at the `/telegram/reply` route, after the delivery-id LRU and
+before the tone gate. An identical long message to the same topic within ~15min
+is suppressed (200, not re-sent); the first send still goes. Files:
+`OutboundContentDedup.ts` (new), `routes.ts` (instance + check/record),
+`PostUpdateMigrator.ts` (CLAUDE.md note), 3 test files.
+
+## Decision-point inventory
+
+- content-dedup check — **add (suppress)** — before the send.
+- length floor (minLength 40) — **add** — brief acks always pass.
+- `allowDuplicate` bypass — **reuse (existing metadata)** — caller can force a repeat.
+- record-after-success — **deliberate** — a failed send's retry isn't lost.
+
+## 1. Over-block (the real risk — suppressing a wanted message)
+
+The danger is dropping a message the user needed. Defenses, each tested:
+- **Length floor:** brief acks (the most common legitimate repeat — two "Got it"
+  for two user messages) are exempt (test: "brief acks never suppressed").
+- **Per-topic:** the same text to a different topic sends (tested).
+- **`allowDuplicate` escape hatch:** a caller that means to repeat bypasses it
+  (tested).
+- **Record-after-success:** a send that throws is never recorded, so its
+  legitimate retry (same content, new id) is not suppressed.
+- **Scope = `/telegram/reply` only:** command responses (bot command handler) and
+  sentinel/standby sends go through other paths and are untouched, so a user
+  re-running a command still gets fresh output.
+Residual: a caller that legitimately re-sends the EXACT same ≥40-char text to the
+SAME topic within 15min without `allowDuplicate` is suppressed — which is exactly
+the reported bug, and the escape hatch covers the rare intentional case.
+
+## 2. Under-block
+
+Near-duplicates (reworded status, e.g. the 21:15 variant in the incident) are
+NOT caught — only byte-identical (whitespace-normalized) text. Catching
+semantic near-dups would require an LLM and risks false suppression; the
+deterministic exact-match is the safe, robust core. The reworded-variant case is
+a separate, lower-frequency concern.
+
+## 3. Level-of-abstraction fit
+
+The dedup is a pure module in `messaging/`, instantiated once per route
+construction beside the existing delivery-id LRU (same lifecycle, same
+chokepoint). It reuses the route's existing `allowDuplicate` metadata contract.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** `docs/signal-vs-authority.md`
+
+- [x] Deterministic guard, no LLM. It removes a redundant send; it never alters
+  content and never blocks a non-duplicate. The `allowDuplicate` hatch preserves
+  caller authority for intentional repeats. Strictly subtractive on exact dups.
+
+## 5. Interactions
+
+- **Delivery-id LRU:** complementary — id-dedup catches a re-POST of the same id;
+  content-dedup catches a fresh-id re-send of the same text. Runs after it.
+- **Tone gate:** the content-dedup runs BEFORE it (so a duplicate skips the LLM
+  call entirely) and independent of it (covers the proxy/relay paths the gate
+  skips).
+- **Tokenless-standby relay:** unaffected — the dedup decides before the send;
+  the relay still carries the real messageId on a non-duplicate.
+
+## 6. External surfaces / 7. Rollback
+
+New response field `suppressedDuplicate: true` on a suppressed `/telegram/reply`
+(additive; callers `.catch`/ignore the body today). Optional config
+`outboundContentDedup` (window/minLength/maxPerTopic/enabled) with safe
+defaults; absent ⇒ defaults. One idempotent CLAUDE.md note. Rollback = revert;
+duplicates flow again.

package/upgrades/side-effects/peer-quota-propagation.md

@@ -0,0 +1,58 @@
+# Side-Effects Review — Peer quota propagation (finding A2)
+
+**Version / slug:** `peer-quota-propagation`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The peer's `quotaState` (already in its session-status response via
+getCapacity(self)) was parsed away on the receive side — same narrowing bug as
+the #931 commitmentsAdvert drop. Now carried through `fetchPeerCapacity` ->
+`PeerCapacity` -> `PeerPresencePuller.recordHeartbeat` -> pool registry, so the
+router sees a peer's quota and quota-aware placement (#804) can avoid a
+rate-limited peer (the original EXO failure).
+
+## Decision-point inventory
+
+One: carry the field or not. Carried, additively, with absent = not blocked.
+
+## 1. Over-block
+
+A correctly-reported `blocked:true` peer is now AVOIDED by placement where
+before it was silently chosen. That is the intended behavior, not over-block:
+the data is the peer's own self-report (the gemini quota-conflation lesson —
+never another machine's file; this is the peer asserting its OWN state).
+
+## 2. Under-block
+
+An old peer that omits quotaState still reads as not-blocked (fail-open,
+unchanged) — no regression, just no improvement for un-upgraded peers.
+
+## 3. Level-of-abstraction fit
+
+The field travels the SAME path the commitmentsAdvert/journalAdvert already
+travel (session-status -> fetchPeerCapacity -> puller). No new transport, no
+new endpoint. The serving side already emitted it (getCapacity spread).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+Placement remains advisory + fail-open: a hard pin still wins
+(pinned-machine-quota-blocked), all-blocked proceeds least-loaded. This change
+only feeds the existing decision real peer data.
+
+## 5. Interactions
+
+- #804 quota-aware placement: the consumer — now has peer data.
+- A1 (collector hoist): the producer — together they make placement real.
+- gemini quota-conflation lesson: respected — this is the peer's OWN
+  self-report carried verbatim, never this machine reading another's file.
+- Old peers: forward/backward compatible (optional field).
+
+## 6. External surfaces
+
+`GET /pool` now populates a peer's `quotaState` (was always null for peers).
+No new routes/config/notifications.