instar 1.3.382 → 1.3.384

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/quota-collector-polling-independence.md

@@ -0,0 +1,62 @@
+# Side-Effects Review — Quota collector polling independence (finding A1)
+
+**Version / slug:** `quota-collector-polling-independence`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The QuotaManager/collector/accountSwitcher pipeline was hoisted out of the
+`if (telegramConfig && !skipTelegram && !isStandbyTelegram && !lifelineOwnsPolling)`
+block to top scope (after the scheduler exists), gated only on quotaTracker.
+On lifeline-owns-polling agents the collector never started → fail-open
+placement (finding A1).
+
+## Decision-point inventory
+
+One: WHERE the pipeline runs. Now: top scope, after scheduler, gated on
+quotaTracker. Before: inside the server-owns-polling block.
+
+## 1. Over-block
+
+None. The pipeline now runs in MORE cases (send-only servers too), never fewer.
+
+## 2. Under-block
+
+The collector still no-ops for non-claude-code frameworks (unchanged) and when
+quotaTracking is off (unchanged). A missing OAuth credential still degrades to
+JSONL estimation inside QuotaCollector (unchanged).
+
+## 3. Level-of-abstraction fit
+
+Quota collection is independent of Telegram-polling ownership; placing it with
+the other top-scope monitoring setup (after scheduler, beside telemetry
+heartbeat) is the correct layer. accountSwitcher moves with it; its later
+consumer (wireTelegramCallbacks, inside the polling block) resolves it from the
+enclosing scope — verified by tsc.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No authority change. quota-aware placement remains fail-open on absent data;
+this fix simply lets the data exist.
+
+## 5. Interactions
+
+- Scheduler: the pipeline now runs after `scheduler` is constructed, so
+  setScheduler() wires a real scheduler (was already conditional on `scheduler`).
+- wireTelegramCallbacks (polling block): consumes the hoisted accountSwitcher
+  from the enclosing scope — only runs in the polling path, harmless otherwise.
+- notify(): defined at outer scope (function decl), called lazily on threshold
+  crossings — safe to construct the notifier earlier.
+- Double-start: the old in-block copy was REMOVED (test asserts a single
+  QuotaManager construction) — no risk of two pollers.
+- guard-posture tripwire: already observed quotaTracking re-enabled; this fix
+  makes that enablement actually produce data.
+
+## 6. External surfaces
+
+No new routes/config/notifications. `GET /quota` now returns real data on
+lifeline-driven agents instead of `no_data`.