v2.9.6 — 23 audit-driven bug fixes across data/security/UI

Integrity:
- Merkle hash extended to chain relics/encounter/turns/cards_offered/
  potions per floor + final deck/relics block + build_id/total_players in
  genesis. Relic swaps and encounter substitutions now caught.

Aggregate:
- Deep-copy fix: prior shallow copy corrupted in-memory aggregate via
  shared nested-dict references after merge.
- First-import inner counters now scaled proportionally with the
  clamped run_count (was: only run_count clamped, subcounts uncapped).
- Booleans excluded from sum-aggregation (isinstance(True, int) trap).

Knowledge:
- find_synergies excludes Status/Curse/Event/Token/Quest from synergy
  pool (was: Status cards offered as synergies for player cards).
- Auto-discovered enemies get act=['1','2','3'] (was: empty list, invisible
  to /enemies?act=X filter).
- Boss-type classification token-matches enemy ID suffix (was: substring
  match falsely typed SUB_BOSS_SKILLS as boss).

Saves parser:
- Empty card/relic/potion IDs filtered at parse (was: '' polluted analytics).
- character/character_id field-name harmonization between current_run and
  history files.

Routes:
- /runs/import per-field caps (500 floors / 200 deck / 100 relics) prevent
  DoS via tiny-floor flood under 1MB byte limit.
- /enemies/{id} encounter lookup uses suffix-equality (was: substring match
  collided RAT vs BIG_RAT_PACK).
- SSE counter increment moved inside generator's try/finally so pre-stream
  client disconnect can't leak slot.

App:
- _get_progress cache uses cache_time==0 sentinel (was: None response from
  no-save-file users re-ran get_progress every request).

CLI:
- python -m sts2 --browser now correctly defaults to 'serve' command.

Watcher:
- threading.Lock added around debounce check-and-set to close TOCTOU race.

Community:
- __init__ duplicate __all__ consolidated (was: dropped STS2_INDICATORS).
- extract_tips uses \b word boundaries; names <3 chars skipped (was:
  substring match flooded tips with false positives).
- reddit._fetch_reddit_json explicit raise on retries exhausted (was:
  implicit None return crashed callers).
- steam guide tier weighting uses ceil(n/2) extras for true 1.5x (was:
  even-index drift off target).

Logparser:
- Linux log dir uses Proton-prefix when present, matching save dir
  resolution (was: XDG path disagreed with save-dir).

Templates / static:
- analytics.html death-floors + floor-survival use (max or 1) divisor.
- overlay.html stops full-reloading every SSE tick — new overlay.js does
  in-place DOM diff with 10s reload cooldown (OBS browser-source stable now).
- deck.js localStorage setItem wrapped try/catch (QuotaExceededError /
  private browsing).

Version:
- pyproject + spec both 2.9.6 (verified matched).

Author: thequantumfalcon

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v2.9.6
+
+### Fixed
+
+- **Integrity Merkle hash incomplete** — `sts2/integrity.py` chained only floor/type/card_picked/damage/hp/gold per floor. Relic swaps, encounter substitutions, and turn-count edits went undetected. Hash now binds seed+character+ascension+build_id+total_players at genesis and chains encounter+monsters+turns+hp_healed+max_hp+cards_offered+potions_used+potions_gained per floor, plus a final block over relics+deck.
+- **Knowledge synergy filter included Status/Curse/Token pools** — `find_synergies` returned Status cards (e.g. Wound, Slimed) as synergies because the filter only excluded Status by `other.character`. Now also excludes Curse, Event, Token, Quest pools — only same-character + Colorless cards remain as synergy candidates.
+- **Aggregate merge shallow-copy corruption** — `merge_aggregate` did `dict(existing)` (shallow), then `merged_field[key][subkey] += val` mutated the caller's in-memory aggregate. Subsequent reads doubled stats. Now deep-copies nested dicts.
+- **Aggregate first-import inner counters uncapped** — first-import clamped `run_count` to `_MIN_IMPORT_CAP` but left per-card/per-relic counters un-scaled. A malicious file with 10k inflated subcounts passed through. Now scales inner counters proportionally.
+- **Aggregate merge treats booleans as ints** — `isinstance(True, int)` is True in Python; bools could be summed. Now explicit `isinstance(_, bool)` exclusion.
+- **Save parser empty card IDs** — malformed save entries with no `id` produced empty-string keys in deck/relics/potions, polluting `card_rankings` etc. Now filtered out at parse time in both `get_current_run` and `get_run_history`.
+- **Save parser character field-name mismatch** — `get_run_history` only looked at `character`, missing the `character_id` field used by current_run saves. Now tries `character_id` first then falls back to `character`.
+- **/runs/import unbounded floor count** — 1 MB byte cap still permitted 100k tiny floor entries (template/analyzer DoS). Now also rejects runs with >500 floors / >200 deck / >100 relics.
+- **/enemies/{id} substring match collision** — `enemy_id.split(".")[-1].lower() in enc_id.lower()` matched "RAT" against "BIG_RAT_PACK" and similar. Now exact suffix-equality.
+- **SSE connection counter leak on early disconnect** — `_sse_active += 1` happened in the request handler before the generator ran; a client disconnect between header send and body start leaked a slot. Now the increment is inside the generator's try/finally so the decrement is guaranteed.
+- **_get_progress cache treated None as uncached** — users with no save file re-ran `get_progress()` on every request. Now `cache_time == 0` is the sentinel for "never populated".
+- **analytics.html division-by-zero on zero-only data** — `death_floors` / `floor_survival` divisors could be 0. Now `(max or 1)` guard prevents 500.
+- **overlay.html full-page reload on every SSE tick** — overlay flickered every 3 seconds with full reload, breaking OBS browser-source captures. New `sts2/static/overlay.js` does in-place DOM diff with 10s reload cooldown.
+- **__main__.py treated `--browser` as a command** — `python -m sts2 --browser` errored with "Unknown command". Now picks first non-flag arg as the command.
+- **watcher.py debounce TOCTOU** — `_last_trigger` was mutated from watchdog's background thread without a lock; burst events could double-fire `call_soon_threadsafe`. Added `threading.Lock`.
+- **community/__init__.py duplicate __all__** — second assignment silently dropped `STS2_INDICATORS` and `SourceResult` from public re-exports. Now a single canonical list.
+- **community/_types extract_tips substring match pollution** — short entity names matched substrings (e.g. "rat" in "strategy"). Now anchored on `\b` word boundaries; names <3 chars skipped.
+- **community/reddit retry loop implicit None return** — control-flow could fall off the end of `_fetch_reddit_json` without raising or returning, crashing callers with `AttributeError`. Now raises explicitly.
+- **community/steam tier weight off-spec** — comment said "1.5x" but every-other-index extras averaged 0.5x only on even-length tier lists. Now `ceil(n/2)` extras for true 1.5x weighting.
+- **logparser.py Linux log dir mismatch** — `XDG_DATA_HOME`-rooted log dir disagreed with the Proton-prefix-rooted save dir from `config.py`; Steam Deck users had save watcher and log poller looking at different game installs. Now matches the save-dir Proton resolution.
+- **knowledge.py auto-discovered enemies invisible to act filter** — discovered enemies had `act=[]`, hidden by every `/enemies?act=X` filter. Now `act=["1","2","3"]` so they appear under any act filter.
+- **knowledge.py boss-type misclassification** — `"BOSS" in enemy_id.upper()` substring-matched IDs like `SUB_BOSS_SKILLS`. Now token-matches the suffix segment.
+- **deck.js localStorage uncaught QuotaExceededError** — private-browsing / full storage broke the deck builder silently. `setItem` now wrapped in try/catch.
+
 ## v2.9.5
 
 ### Fixed

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spirescope"
-version = "2.9.5"
+version = "2.9.6"
 description = "Spirescope — a local web dashboard for Slay the Spire 2. Card/relic/enemy lookup, deck analysis, live run tracking, and strategy guides."
 readme = "README.md"
 license = {text = "MIT"}

spirescope.spec

@@ -4,7 +4,7 @@
 import sys
 
 
-VERSION = "2.9.5"
+VERSION = "2.9.6"
 
 # Windows EXE version metadata (CompanyName / ProductName / FileVersion).
 # The win32 import branch only loads on Windows because the underlying

sts2/__main__.py

@@ -97,7 +97,10 @@ def main():
         print(f"Spirescope {_get_version()}")
         return
 
-    command = args[0] if args else "serve"
+    # Pick the first positional (non-flag) arg as the command so
+    # `python -m sts2 --browser` correctly defaults to "serve" instead of
+    # treating "--browser" as an unknown command.
+    command = next((a for a in args if not a.startswith("-")), "serve")
 
     if command == "update":
         from sts2.fetcher import run_fetcher

sts2/aggregate.py

@@ -1,4 +1,5 @@
 """Aggregate stats: compute and merge player-sourced data."""
+import copy
 import json
 import logging
 from pathlib import Path
@@ -78,15 +79,42 @@ def compute_aggregate_stats(runs: list[RunHistory]) -> dict:
     }
 
 
+def _scale_subcounts(d: dict, scale: float) -> dict:
+    """Scale every numeric sub-counter in a dict-of-dicts by `scale`."""
+    out = {}
+    for key, vals in d.items():
+        if not isinstance(vals, dict):
+            out[key] = vals
+            continue
+        scaled = {}
+        for subkey, subval in vals.items():
+            # Exclude bools — they're technically int but should not aggregate.
+            if isinstance(subval, bool):
+                scaled[subkey] = subval
+            elif isinstance(subval, (int, float)):
+                scaled[subkey] = int(subval * scale) if isinstance(subval, int) else subval * scale
+            else:
+                scaled[subkey] = subval
+        out[key] = scaled
+    return out
+
+
 def merge_aggregate(existing: dict, imported: dict) -> dict:
     """Weighted merge with anti-manipulation cap."""
     if not existing or existing.get("run_count", 0) == 0:
         # Apply min-cap even on first import — prevents a malicious first file
         # from seeding massive bogus stats that then anchor the future cap.
+        # Scale inner counters too so a 10k-run import doesn't sneak inflated
+        # sub-counts through under a clamped run_count.
         imported_count = imported.get("run_count", 0)
-        if imported_count > _MIN_IMPORT_CAP:
-            return {**imported, "run_count": _MIN_IMPORT_CAP}
-        return imported
+        if imported_count > _MIN_IMPORT_CAP and imported_count > 0:
+            scale = _MIN_IMPORT_CAP / imported_count
+            scaled = {"run_count": _MIN_IMPORT_CAP}
+            for field in ("card_pick_rates", "card_win_rates", "relic_win_rates",
+                          "character_stats", "ascension_stats"):
+                scaled[field] = _scale_subcounts(imported.get(field, {}), scale)
+            return scaled
+        return copy.deepcopy(imported)
 
     existing_count = existing.get("run_count", 0)
     imported_count = imported.get("run_count", 0)
@@ -96,15 +124,21 @@ def merge_aggregate(existing: dict, imported: dict) -> dict:
 
     merged = {"run_count": existing_count + imported_count}
 
-    # Merge dict-of-dicts fields
+    # Merge dict-of-dicts fields. Deep-copy nested dicts from `existing` so the
+    # caller's in-memory aggregate is not mutated when we add imported counts.
     for field in ("card_pick_rates", "card_win_rates", "relic_win_rates",
                   "character_stats", "ascension_stats"):
         ex = existing.get(field, {})
         im = imported.get(field, {})
-        merged_field = dict(ex)
+        merged_field = {k: dict(v) if isinstance(v, dict) else v for k, v in ex.items()}
         for key, vals in im.items():
-            if key in merged_field:
+            if not isinstance(vals, dict):
+                continue
+            if key in merged_field and isinstance(merged_field[key], dict):
                 for subkey, subval in vals.items():
+                    # Exclude bools — isinstance(True, int) is True.
+                    if isinstance(subval, bool):
+                        continue
                     if isinstance(subval, (int, float)):
                         merged_field[key][subkey] = merged_field[key].get(subkey, 0) + subval
             else:

sts2/app.py

@@ -141,7 +141,9 @@ def validate_csrf_token(token: str) -> bool:
 async def _get_progress():
     global _progress_cache, _progress_cache_time
     now = time.monotonic()
-    if _progress_cache is None or (now - _progress_cache_time) > _PROGRESS_CACHE_TTL:
+    # Use cache_time==0 (never populated) rather than cache is None — get_progress
+    # returns None for "no save file" which is a valid cached value.
+    if _progress_cache_time == 0 or (now - _progress_cache_time) > _PROGRESS_CACHE_TTL:
         _progress_cache = await asyncio.to_thread(get_progress)
         _progress_cache_time = now
     return _progress_cache

sts2/community/__init__.py

@@ -12,8 +12,6 @@
     STS2_INDICATORS,
     SourceResult,
 )
-
-__all__ = ["STS2_INDICATORS", "SourceResult", "merge_results"]
 from ._types import (
     compute_consensus_tier as _compute_consensus_tier,
 )
@@ -27,8 +25,13 @@
 
 log = logging.getLogger(__name__)
 
-# Re-exports for backward compatibility (tests import these from sts2.community)
+# Re-exports for backward compatibility (tests import these from sts2.community).
+# Single canonical __all__ — previous code declared it twice and silently
+# dropped STS2_INDICATORS + SourceResult on the second assignment.
 __all__ = [
+    "STS2_INDICATORS",
+    "SourceResult",
+    "merge_results",
     "run_community_scraper",
     "save_community_data",
     "apply_community_tiers",

sts2/community/_types.py

@@ -68,16 +68,23 @@ def extract_tier_ratings(text: str, existing_names: set[str]) -> dict[str, list[
 
 
 def extract_tips(text: str, entity_names: set[str]) -> dict[str, list[str]]:
-    """Extract strategy tips mentioning specific cards/relics."""
+    """Extract strategy tips mentioning specific cards/relics.
+
+    Names match on word boundaries (not substring) so short names like "rat"
+    don't collide with unrelated words like "strategy" or "fascinating".
+    Names shorter than 3 characters are skipped entirely to avoid noise.
+    """
     tips: dict[str, list[str]] = defaultdict(list)
     sentences = re.split(r"[.!?\n]+", text)
+    # Pre-compile word-boundary patterns once per call.
+    patterns = {n: re.compile(r"\b" + re.escape(n) + r"\b") for n in entity_names if len(n) >= 3}
     for sentence in sentences:
         sentence = sentence.strip()
         if len(sentence) < 20 or len(sentence) > 300:
             continue
         sentence_lower = sentence.lower()
-        for name in entity_names:
-            if name in sentence_lower:
+        for name, pat in patterns.items():
+            if pat.search(sentence_lower):
                 tips[name].append(sentence)
     return tips
 

sts2/community/reddit.py

@@ -50,6 +50,10 @@ def _fetch_reddit_json(url: str, retries: int = 2) -> dict | None:
                 time.sleep(2 * (attempt + 1))
             else:
                 raise
+    # Defensive: all retries exhausted without raising or returning. This
+    # path is unreachable under current control flow but guards against
+    # future refactors silently returning None.
+    raise urllib.error.URLError("Reddit fetch retries exhausted")
 
 
 def _fetch_subreddit_posts(subreddit: str, sort: str = "top",

sts2/community/steam.py

@@ -219,11 +219,13 @@ def _scrape_guides(existing_names: set[str], result: SourceResult) -> None:
         # Extract tier ratings and tips from guide body
         ratings = extract_tier_ratings(body_text, existing_names)
         for name_lower, tiers in ratings.items():
-            # Weight guide tier votes at 1.5x (curated content)
+            # Weight guide tier votes at 1.5x (curated content): the full
+            # list contributes 1x, plus ceil(n/2) extras contribute 0.5x.
+            # Prior code took every-other-index which only averaged 0.5x on
+            # even-length lists; on odd lists it drifted off the 1.5x target.
             result.tier_votes[name_lower].extend(tiers)
-            # Add an extra half-vote for each (round up)
-            extra = [t for i, t in enumerate(tiers) if i % 2 == 0]
-            result.tier_votes[name_lower].extend(extra)
+            half_up = (len(tiers) + 1) // 2
+            result.tier_votes[name_lower].extend(tiers[:half_up])
 
         tips = extract_tips(body_text, existing_names)
         for name_lower, tip_list in tips.items():