fix(savings): credit heeded nudge→compaction recoveries across the hook boundary

The quality-nudge follow-through now carries its fire timestamp and fill snapshot
across the UserPromptSubmit→PostCompact process boundary via the per-session
quality cache, so a compaction that follows a low-quality nudge is measured and
credited (verified). The credit is consume-then-credit: fire-state is cleared and
persisted before the credit is logged and only when that clear succeeds, making it
idempotent and conservative under process failure. The cross-process carry set is
centralized as _CARRY_KEYS, and the follow-through degrades safely on a corrupt
cache. Ships as 5.9.3.

Author: alexgreensh

.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "token-optimizer",
       "source": "./",
       "description": "Audit, fix, and monitor Claude Code context window usage. Find the ghost tokens.",
-      "version": "5.9.2",
+      "version": "5.9.3",
       "author": {
         "name": "Alex Greenshpun",
         "url": "https://linkedin.com/in/alexgreensh"

.claude-plugin/plugin.json

@@ -7,7 +7,7 @@
   },
   "homepage": "https://github.com/alexgreensh/token-optimizer",
   "repository": "https://github.com/alexgreensh/token-optimizer",
-  "version": "5.9.2",
+  "version": "5.9.3",
   "license": "PolyForm-Noncommercial-1.0.0",
   "keywords": ["token", "optimization", "context", "audit", "cost", "coach"]
 }

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-optimizer",
-  "version": "5.9.2",
+  "version": "5.9.3",
   "description": "Audit, monitor, and reduce Codex context waste with continuity helpers and explicit outline tools.",
   "skills": "./skills/",
   "interface": {

CHECKSUMS.sha256

@@ -1,6 +1,6 @@
-f2794075c039e00370a99d3d2bd2b3f02eda3c2efcd9856eed7eea634c57a654  .claude-plugin/marketplace.json
-7cc4940ba79d29029ea67df156b9efac4ff358739b013fe70705d6fc8a7b5d72  .claude-plugin/plugin.json
-0cb56ebdf3193717707c4c091111539bd855096d8fdbcbcfeb4552c3e124cbfa  .codex-plugin/plugin.json
+eabe0fa3ee227142a1e1bcd5c7d5ced2ab89af99aeee4b00f5179282b408a66d  .claude-plugin/marketplace.json
+64e61ab6705f6cf0d99e521f2425304ba261e36ef6d559de9c74732b6711ea56  .claude-plugin/plugin.json
+9f0833202940cf758ae4f747413e0671dd062df0c24bbd41ecc71c74c541090d  .codex-plugin/plugin.json
 42a3d02dfdc46f985e877cc37e9f947ff0c082deeb991db958b339c90bdeef82  hooks/hooks.json
 d7a8cff0f7af65bc38c274b5b4bd5251cb333b8503cf31b2fb97af18342d919a  hooks/python-launcher.sh
 848cf5672e1d4ca2036a05569748344429618933264143a24c8a7d61c69585ba  hooks/run.py
@@ -80,7 +80,7 @@ b8345d767a48f40d275480973681baf56dc76329d8f3eaa6260966d6d6b787cd  skills/token-o
 fef4a2385caf3c9495987007d16edf73a022cddbd0aecf2293025e3d9599996d  skills/token-optimizer/scripts/detectors/websearch_routing.py
 6f023687c905db9be267aafcf2a85f08739bee8c0aae42b58eeae4b8889690b1  skills/token-optimizer/scripts/hook_io.py
 f647eabc7067499b74f72c4ba5c55738fdc18c6539a7a5b99c65d03126016d8d  skills/token-optimizer/scripts/injection.py
-4c3cc853ae83fb7f05462c2e0b0fb5a37a647830f8131d6796f4954969cf802a  skills/token-optimizer/scripts/measure.py
+fd960e8d0421dd29e4d1520e690721c7300eae308c77159061fbb3c7a67443a0  skills/token-optimizer/scripts/measure.py
 bd27835f85c5fd45c9cf67cb8b969038489249c56182ec2638a4f1223799b98f  skills/token-optimizer/scripts/outline.py
 7e996f6c5d3c36ea0f0d70b8eec18080d0582c0155790637ac34abbd0b3e5057  skills/token-optimizer/scripts/plugin_env.py
 f115076cb26824fff4616c89f00d5542c76a2d2f0181cb6af3920cea40f647db  skills/token-optimizer/scripts/read_cache.py

plugins/token-optimizer/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-optimizer",
-  "version": "5.9.2",
+  "version": "5.9.3",
   "description": "Audit, monitor, and reduce Codex context waste with continuity helpers and explicit outline tools.",
   "skills": "./skills/",
   "interface": {

plugins/token-optimizer/skills/token-optimizer/scripts/measure.py

@@ -10005,7 +10005,7 @@ def setup_hook(dry_run=False):
 
 # ========== Persistent Dashboard Daemon ==========
 
-TOKEN_OPTIMIZER_VERSION = "5.9.2"  # Keep in sync with plugin.json + marketplace.json
+TOKEN_OPTIMIZER_VERSION = "5.9.3"  # Keep in sync with plugin.json + marketplace.json
 _DASHBOARD_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
 _DAEMON_RUNTIME = detect_runtime()
 _DAEMON_RUNTIME_SUFFIX = "codex" if _DAEMON_RUNTIME == "codex" else "claude"
@@ -17210,6 +17210,24 @@ def _maybe_progressive_checkpoint(fill_pct, cache_path, result, filepath):
 _LOOP_SESSION_CAP = 2
 _LOOP_LAST_MESSAGES = 4
 
+# Transient nudge/loop/warning state that must survive across the separate
+# UserPromptSubmit and PostCompact hook processes. compute_quality_score() builds
+# a fresh result each run, so quality_cache() carries these forward from the prior
+# on-disk cache. Any new "_nudge_*"/"_loop_*"/warning-dedup key set in _maybe_nudge
+# or _maybe_loop_warning MUST be registered here — a sibling key silently missing
+# from this set is exactly what broke the nudge follow-through credit (A6).
+_CARRY_KEYS = (
+    "_nudge_fill_pct_at_fire",
+    "_nudge_fire_epoch",
+    "_nudge_count",
+    "_nudge_last_epoch",
+    "_nudge_previous_score",
+    "_loop_warning_count",
+    "progressive_bands_captured",
+    "_last_fill_warn_level",
+    "_last_tool_call_warn_level",
+)
+
 
 def _check_realtime_loops(quality_data):
     """Lightweight loop detection using already-parsed quality_data.
@@ -17565,10 +17583,7 @@ def quality_cache(throttle_seconds=120, warn_threshold=70, quiet=False, session_
 
     _session_id = Path(cache_path).stem.replace("quality-cache-", "", 1) if cache_path else None
     result = compute_quality_score(quality_data, session_id=_session_id)
-    for carry_key in ("_nudge_fill_pct_at_fire", "_nudge_count", "_nudge_last_epoch",
-                       "_nudge_previous_score", "_loop_warning_count",
-                       "progressive_bands_captured", "_last_fill_warn_level",
-                       "_last_tool_call_warn_level"):
+    for carry_key in _CARRY_KEYS:
         if carry_key in prev_result and carry_key not in result:
             result[carry_key] = prev_result[carry_key]
     result["total_messages"] = len(quality_data["messages"])
@@ -17687,33 +17702,53 @@ def quality_cache(throttle_seconds=120, warn_threshold=70, quiet=False, session_
     # Nudge follow-through: if PostCompact triggered this run (force=True)
     # and a nudge preceded the compact, measure the actual fill_pct recovery.
     if force and result.get("fill_pct", 0) > 0:
-        nudge_fill = result.get("_nudge_fill_pct_at_fire", 0)
-        if nudge_fill > 0:
-            current_fill = result["fill_pct"]
-            fill_delta = nudge_fill - current_fill
-            ft_sid = Path(cache_path).stem.replace("quality-cache-", "", 1) if cache_path else None
-            # A2 temporal gate: only credit a compaction that followed the nudge
-            # within the window. A compaction long after the nudge was not its
-            # follow-through, so it must not borrow the nudge's credit.
-            fire_epoch = result.get("_nudge_fire_epoch", 0)
-            within_window = fire_epoch and (time.time() - fire_epoch) <= _NUDGE_FOLLOWTHROUGH_WINDOW_SECONDS
-            # A2 dedup: if a checkpoint_restore already credited this session's
-            # recovery for this compaction (same SessionStart cycle), the nudge
-            # must not double-credit the same tokens.
-            already_credited = _checkpoint_restore_credited_recently(ft_sid)
-            if fill_delta > 5 and within_window and not already_credited:
-                context_size = detect_context_window()[0]
-                measured_tokens_recovered = int(context_size * fill_delta / 100)
-                _log_compression_event(
-                    feature="quality_nudge",
-                    original_text=" " * (measured_tokens_recovered * 4),
-                    compressed_text=f"nudge_followthrough:fill={nudge_fill}->{current_fill}",
-                    session_id=ft_sid,
-                    detail=f"measured_recovery: fill {nudge_fill}%->{current_fill}% = {measured_tokens_recovered} tokens on {context_size} context",
-                    verified=True,
-                )
-            result.pop("_nudge_fill_pct_at_fire", None)
-            result.pop("_nudge_fire_epoch", None)
+        # A6: the nudge fires during a prior UserPromptSubmit process; this
+        # follow-through runs in a SEPARATE PostCompact process. Fire-state reaches
+        # us via the atomic per-session quality cache (carried forward at the top of
+        # this function). Fall back to prev_result directly in case the carry did not
+        # run, so a heeded session is never misclassified as ignored. Wrapped so a
+        # corrupt cache value can never crash the host hook — it degrades to "no
+        # credit", not a traceback.
+        try:
+            nudge_fill = result.get("_nudge_fill_pct_at_fire") or prev_result.get("_nudge_fill_pct_at_fire", 0)
+            if nudge_fill > 0:
+                current_fill = result["fill_pct"]
+                fill_delta = nudge_fill - current_fill
+                ft_sid = Path(cache_path).stem.replace("quality-cache-", "", 1) if cache_path else None
+                # A2 temporal gate: only credit a compaction that followed the nudge
+                # within the window. A compaction long after the nudge was not its
+                # follow-through, so it must not borrow the nudge's credit.
+                fire_epoch = result.get("_nudge_fire_epoch") or prev_result.get("_nudge_fire_epoch", 0)
+                within_window = fire_epoch and (time.time() - fire_epoch) <= _NUDGE_FOLLOWTHROUGH_WINDOW_SECONDS
+                # A2 dedup: if a checkpoint_restore already credited this session's
+                # recovery for this compaction (same SessionStart cycle), the nudge
+                # must not double-credit the same tokens.
+                already_credited = _checkpoint_restore_credited_recently(ft_sid)
+                should_credit = fill_delta > 5 and within_window and not already_credited
+                # Consume the fire-state FIRST, then credit only if the consume was
+                # actually persisted. The fire-state lives in exactly one place (this
+                # per-session cache), so once it is cleared from disk no later
+                # PostCompact can re-enter this block for the same nudge — that makes
+                # the credit idempotent without a second DB query. If the process
+                # dies between here and the credit, or the clear-write fails, we skip
+                # the credit (a conservative under-count) rather than risk a
+                # double-count that would inflate the savings number.
+                result.pop("_nudge_fill_pct_at_fire", None)
+                result.pop("_nudge_fire_epoch", None)
+                consumed = _write_quality_cache(cache_path, result)
+                if should_credit and consumed:
+                    context_size = detect_context_window()[0]
+                    measured_tokens_recovered = int(context_size * fill_delta / 100)
+                    _log_compression_event(
+                        feature="quality_nudge",
+                        original_text=" " * (measured_tokens_recovered * 4),
+                        compressed_text=f"nudge_followthrough:fill={nudge_fill}->{current_fill}",
+                        session_id=ft_sid,
+                        detail=f"measured_recovery: fill {nudge_fill}%->{current_fill}% = {measured_tokens_recovered} tokens on {context_size} context",
+                        verified=True,
+                    )
+        except Exception:
+            pass
 
     # Progressive checkpoints (v3.0)
     if _PROGRESSIVE_ENABLED and result.get("fill_pct", 0) > 0:

skills/token-optimizer/scripts/measure.py

@@ -10005,7 +10005,7 @@ def setup_hook(dry_run=False):
 
 # ========== Persistent Dashboard Daemon ==========
 
-TOKEN_OPTIMIZER_VERSION = "5.9.2"  # Keep in sync with plugin.json + marketplace.json
+TOKEN_OPTIMIZER_VERSION = "5.9.3"  # Keep in sync with plugin.json + marketplace.json
 _DASHBOARD_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
 _DAEMON_RUNTIME = detect_runtime()
 _DAEMON_RUNTIME_SUFFIX = "codex" if _DAEMON_RUNTIME == "codex" else "claude"
@@ -17210,6 +17210,24 @@ def _maybe_progressive_checkpoint(fill_pct, cache_path, result, filepath):
 _LOOP_SESSION_CAP = 2
 _LOOP_LAST_MESSAGES = 4
 
+# Transient nudge/loop/warning state that must survive across the separate
+# UserPromptSubmit and PostCompact hook processes. compute_quality_score() builds
+# a fresh result each run, so quality_cache() carries these forward from the prior
+# on-disk cache. Any new "_nudge_*"/"_loop_*"/warning-dedup key set in _maybe_nudge
+# or _maybe_loop_warning MUST be registered here — a sibling key silently missing
+# from this set is exactly what broke the nudge follow-through credit (A6).
+_CARRY_KEYS = (
+    "_nudge_fill_pct_at_fire",
+    "_nudge_fire_epoch",
+    "_nudge_count",
+    "_nudge_last_epoch",
+    "_nudge_previous_score",
+    "_loop_warning_count",
+    "progressive_bands_captured",
+    "_last_fill_warn_level",
+    "_last_tool_call_warn_level",
+)
+
 
 def _check_realtime_loops(quality_data):
     """Lightweight loop detection using already-parsed quality_data.
@@ -17565,10 +17583,7 @@ def quality_cache(throttle_seconds=120, warn_threshold=70, quiet=False, session_
 
     _session_id = Path(cache_path).stem.replace("quality-cache-", "", 1) if cache_path else None
     result = compute_quality_score(quality_data, session_id=_session_id)
-    for carry_key in ("_nudge_fill_pct_at_fire", "_nudge_count", "_nudge_last_epoch",
-                       "_nudge_previous_score", "_loop_warning_count",
-                       "progressive_bands_captured", "_last_fill_warn_level",
-                       "_last_tool_call_warn_level"):
+    for carry_key in _CARRY_KEYS:
         if carry_key in prev_result and carry_key not in result:
             result[carry_key] = prev_result[carry_key]
     result["total_messages"] = len(quality_data["messages"])
@@ -17687,33 +17702,53 @@ def quality_cache(throttle_seconds=120, warn_threshold=70, quiet=False, session_
     # Nudge follow-through: if PostCompact triggered this run (force=True)
     # and a nudge preceded the compact, measure the actual fill_pct recovery.
     if force and result.get("fill_pct", 0) > 0:
-        nudge_fill = result.get("_nudge_fill_pct_at_fire", 0)
-        if nudge_fill > 0:
-            current_fill = result["fill_pct"]
-            fill_delta = nudge_fill - current_fill
-            ft_sid = Path(cache_path).stem.replace("quality-cache-", "", 1) if cache_path else None
-            # A2 temporal gate: only credit a compaction that followed the nudge
-            # within the window. A compaction long after the nudge was not its
-            # follow-through, so it must not borrow the nudge's credit.
-            fire_epoch = result.get("_nudge_fire_epoch", 0)
-            within_window = fire_epoch and (time.time() - fire_epoch) <= _NUDGE_FOLLOWTHROUGH_WINDOW_SECONDS
-            # A2 dedup: if a checkpoint_restore already credited this session's
-            # recovery for this compaction (same SessionStart cycle), the nudge
-            # must not double-credit the same tokens.
-            already_credited = _checkpoint_restore_credited_recently(ft_sid)
-            if fill_delta > 5 and within_window and not already_credited:
-                context_size = detect_context_window()[0]
-                measured_tokens_recovered = int(context_size * fill_delta / 100)
-                _log_compression_event(
-                    feature="quality_nudge",
-                    original_text=" " * (measured_tokens_recovered * 4),
-                    compressed_text=f"nudge_followthrough:fill={nudge_fill}->{current_fill}",
-                    session_id=ft_sid,
-                    detail=f"measured_recovery: fill {nudge_fill}%->{current_fill}% = {measured_tokens_recovered} tokens on {context_size} context",
-                    verified=True,
-                )
-            result.pop("_nudge_fill_pct_at_fire", None)
-            result.pop("_nudge_fire_epoch", None)
+        # A6: the nudge fires during a prior UserPromptSubmit process; this
+        # follow-through runs in a SEPARATE PostCompact process. Fire-state reaches
+        # us via the atomic per-session quality cache (carried forward at the top of
+        # this function). Fall back to prev_result directly in case the carry did not
+        # run, so a heeded session is never misclassified as ignored. Wrapped so a
+        # corrupt cache value can never crash the host hook — it degrades to "no
+        # credit", not a traceback.
+        try:
+            nudge_fill = result.get("_nudge_fill_pct_at_fire") or prev_result.get("_nudge_fill_pct_at_fire", 0)
+            if nudge_fill > 0:
+                current_fill = result["fill_pct"]
+                fill_delta = nudge_fill - current_fill
+                ft_sid = Path(cache_path).stem.replace("quality-cache-", "", 1) if cache_path else None
+                # A2 temporal gate: only credit a compaction that followed the nudge
+                # within the window. A compaction long after the nudge was not its
+                # follow-through, so it must not borrow the nudge's credit.
+                fire_epoch = result.get("_nudge_fire_epoch") or prev_result.get("_nudge_fire_epoch", 0)
+                within_window = fire_epoch and (time.time() - fire_epoch) <= _NUDGE_FOLLOWTHROUGH_WINDOW_SECONDS
+                # A2 dedup: if a checkpoint_restore already credited this session's
+                # recovery for this compaction (same SessionStart cycle), the nudge
+                # must not double-credit the same tokens.
+                already_credited = _checkpoint_restore_credited_recently(ft_sid)
+                should_credit = fill_delta > 5 and within_window and not already_credited
+                # Consume the fire-state FIRST, then credit only if the consume was
+                # actually persisted. The fire-state lives in exactly one place (this
+                # per-session cache), so once it is cleared from disk no later
+                # PostCompact can re-enter this block for the same nudge — that makes
+                # the credit idempotent without a second DB query. If the process
+                # dies between here and the credit, or the clear-write fails, we skip
+                # the credit (a conservative under-count) rather than risk a
+                # double-count that would inflate the savings number.
+                result.pop("_nudge_fill_pct_at_fire", None)
+                result.pop("_nudge_fire_epoch", None)
+                consumed = _write_quality_cache(cache_path, result)
+                if should_credit and consumed:
+                    context_size = detect_context_window()[0]
+                    measured_tokens_recovered = int(context_size * fill_delta / 100)
+                    _log_compression_event(
+                        feature="quality_nudge",
+                        original_text=" " * (measured_tokens_recovered * 4),
+                        compressed_text=f"nudge_followthrough:fill={nudge_fill}->{current_fill}",
+                        session_id=ft_sid,
+                        detail=f"measured_recovery: fill {nudge_fill}%->{current_fill}% = {measured_tokens_recovered} tokens on {context_size} context",
+                        verified=True,
+                    )
+        except Exception:
+            pass
 
     # Progressive checkpoints (v3.0)
     if _PROGRESSIVE_ENABLED and result.get("fill_pct", 0) > 0: