instar 1.3.71 → 1.3.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.71",
+  "version": "1.3.72",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-28T23:21:16.520Z",
-  "instarVersion": "1.3.71",
+  "generatedAt": "2026-05-29T01:04:44.834Z",
+  "instarVersion": "1.3.72",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "c410faa704330138b3bb15f71c78506ee86da3b1a7838328dea59888cd7f451a",
+      "contentHash": "cf0c9bfcfa78083bb0a5f6cd2e0f1f175b16204178f373c95cca674e33eae52a",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.72.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Topic-spam, locked down structurally.** A second Telegram topic-flood (after
+the 2026-05-22 sentinel flood) hit a live agent: a housekeeping feature raised one
+attention item per failed peer-resolution every sweep, and because
+`createAttentionItem` spawns a brand-new forum topic per item, that became a wall
+of topics. PR #495 already fixed *that feature* (a per-peer escalation cooldown).
+This change adds the **structural backstop** so the *class* of bug can't recur no
+matter which feature misbehaves next.
+
+**`AttentionTopicGuard` — a per-source + global circuit breaker** at the one
+chokepoint, `TelegramAdapter.createAttentionItem`. If a single attention
+`sourceContext` exceeds its topic budget within a rolling window (default 3 / 10
+min) — or, via a **global ceiling**, all sources collectively exceed it — further
+**non-critical** items are COALESCED into ONE reused "notices coalesced" topic and
+recorded in `state/attention-suppressed.jsonl` — never a wall. Invariants:
+HIGH/URGENT/CRITICAL items are **never** coalesced (critical messages always get
+their own topic), and **no item is dropped** — only its per-item topic is withheld;
+the item is still in the attention store. The global ceiling makes the protection
+hold even when a feature varies its `sourceContext` per item to dodge a per-source
+budget. Ships **enabled by default in code**, so every fleet agent is protected on
+the dist update with zero config.
+
+## What to Tell Your User
+
+- The "wall of topics popping up out of nowhere" problem is now fixed at its root.
+  If any background feature ever tries to flood the chat again, it's capped
+  automatically: a few topics at most, then everything folds into one quiet
+  "notices coalesced" topic, with the detail kept in the logs. Genuinely critical
+  alerts (HIGH/URGENT) are never affected — they always come through on their own.
+- No action or config needed; it's on by default.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Attention topic-flood circuit breaker | Automatic, on by default. Tune via `messaging[].config.attentionTopicGuard` = `{ "enabled": true, "windowMs": 600000, "maxTopicsPerSource": 3, "maxTopicsGlobal": 8 }`. |
+| Suppressed-notice audit trail | When a source is coalesced, each item is logged to `state/attention-suppressed.jsonl` (size-capped). Read it to answer "why are my notices grouped / where did topic X go?" |
+
+## Migration Notes
+
+Pure `src/` logic, **default-ON in code** (`AttentionTopicGuard` +
+`TelegramAdapter`) — no agent-installed file changed, so every agent receives the
+protection through the normal dist update with nothing to patch. A
+`migrateClaudeMd()` entry backfills the **Topic-Flood Guard** awareness section
+into existing agents' CLAUDE.md (idempotent). The redrive-specific offender fix
+shipped separately in PR #495.
+
+## Evidence
+
+- Unit: `tests/unit/AttentionTopicGuard.test.ts` (11) — budget / global-cap /
+  critical-bypass (case-insensitive) / per-source isolation / sustained-flood
+  single episode / post-silence reset / config-validation / key-eviction;
+  `tests/unit/PostUpdateMigrator-topicFloodGuard.test.ts` (2) — migrator backfill
+  + idempotency.
+- Integration: `tests/integration/attention-topic-flood-guard.test.ts` (4) — REAL
+  `TelegramAdapter`: a flooding source is capped at budget+1 topics, HIGH
+  bypasses, concurrent coalesced items create ONE topic, a different source is
+  unaffected, no item dropped, audit log populated.
+- E2E: `tests/e2e/attention-topic-flood-guard-lifecycle.test.ts` (1) — fleet
+  default (NO config) still caps a flood exactly (migration-parity guarantee).

package/upgrades/side-effects/attention-topic-flood-guard.md

@@ -0,0 +1,74 @@
+# Side-Effects Review — Attention Topic-Flood Guard
+
+**Spec:** `docs/specs/attention-topic-flood-guard.md` (converged, 4-reviewer panel)
+**Change:** per-source + global forum-topic circuit breaker at
+`TelegramAdapter.createAttentionItem` (the structural backstop). The redrive
+offender fix shipped separately in PR #495 (merged); the redrive edits originally
+bundled here were dropped to defer to it.
+**Files:** `src/messaging/AttentionTopicGuard.ts` (new),
+`src/messaging/TelegramAdapter.ts`, `src/core/PostUpdateMigrator.ts`, tests,
+`tests/unit/feature-delivery-completeness.test.ts`, `upgrades/NEXT.md`.
+
+## Phase 4 — the seven questions
+
+1. **Over-block.** The guard never blocks an agent action or drops an item — it
+   only changes *delivery form* (own topic vs. one coalesced topic + a log line)
+   for **non-critical** items. The one legitimate behavior it changes: a
+   non-critical source raising >3 items / 10 min has the surplus coalesced. That
+   is the *intended* behavior (the operator asked for exactly this) and is tunable
+   per adapter. HIGH/URGENT are never affected. No agent capability is rejected.
+
+2. **Under-block.** Before the global ceiling was added, a source varying its
+   `sourceContext` per item would have dodged the per-source budget — the review
+   caught this; the global cap + key eviction now bound it regardless of source
+   cardinality. Remaining under-block: a flood composed entirely of HIGH/URGENT
+   items is not coalesced (by design — critical items must always be visible). A
+   feature mis-marking routine noise as HIGH would still flood; that is a
+   mis-classification bug in that feature, not in the guard, and is the correct
+   place to fix it.
+
+3. **Level-of-abstraction fit.** Correct layer: the breaker sits at the single
+   chokepoint (`createAttentionItem`) where every attention item becomes a topic,
+   so it covers all current and future callers. It is deliberately *below* the
+   tone-gate authority on the `/attention` route (a transport-mechanics
+   rate-counter, not a content-judgment filter). The per-feature redrive fix
+   (PR #495) is at the feature layer; the guard is the substrate backstop — two
+   layers, by intent.
+
+4. **Signal vs authority.** Compliant. The guard holds no blocking authority over
+   agent behavior or information flow; it is a delivery *shaper* (the rate-counter
+   / transport-dedup carve-out in `docs/signal-vs-authority.md`), the same class as
+   `SentinelNotifier`. It never withholds a critical notice and never drops an
+   item.
+
+5. **Interactions.** Audited against `SentinelNotifier` (separate path → the
+   single reused system topic; no collision — it never flows through the guard) and
+   the `agent-attention-topic` (not registered in the attention maps, untouched).
+   Restart interaction (coalesced items vs. `loadAttentionItems` reverse-map
+   corruption) and concurrency (double-create race) were both found by review and
+   fixed. `updateAttentionStatus` no longer closes a shared topic when one
+   coalesced sibling resolves (coalesced items aren't in the per-item maps).
+
+6. **External surfaces.** User-visible change: a flooding source now produces one
+   "🔁 …: notices coalesced (flood guard)" topic instead of a wall; the rest goes
+   to `state/attention-suppressed.jsonl`. Fleet-wide via dist update, default-ON,
+   no config. No new network calls; no new external dependency. The CLAUDE.md
+   awareness section is backfilled to existing agents (idempotent migrator).
+
+7. **Rollback cost.** Cheap. Single config flag:
+   `messaging[].config.attentionTopicGuard.enabled = false` restores per-item-topic
+   behavior. No data migration, no agent-state repair (the guard holds only
+   in-memory counters). Worst case is a `src/` revert + patch release.
+
+## Phase 5 — second-pass review (REQUIRED: touches a "guard" + outbound messaging)
+
+An independent four-reviewer convergence panel (adversarial/security, integration,
+architecture, scalability) audited the change against the diff. It raised 7
+material concerns (global-cap dodge, `/ack`+shared-topic-close, case-sensitive
+critical bypass, double-create race, hex plaintext to unverified address, NaN
+config disable, unbounded audit log) plus framing notes. **6 of the 7 were fixed
+in code this iteration; the 7th (hex plaintext) was a finding on the redrive edits
+that are now deferred to the merged PR #495.** Full record:
+`docs/specs/attention-topic-flood-guard.convergence.md`. **Concur with the review —
+the design after this iteration addresses every raised concern; no blocking
+authority on brittle logic remains.**