kijito-tools 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Installer for kijito-tools: copies the context-tracking, session catch-up, and self-clear scripts plus the Kijito skills into ~/.claude.",
   "license": "Apache-2.0",
   "type": "commonjs",

package/providers/claude/scripts/kijito-persona-lib.sh

@@ -85,6 +85,32 @@ PYSCAN
   return 1
 }
 
+# kijito_unread_for_persona <persona> -> prints the persona's unread count, or nothing (row M309).
+# The producer (kijito-inbox-monitor >= 0.5.7) writes `unread` into the persona's STATE file on every poll
+# that had a count, and omits it when it had none. Nothing is printed unless a FRESH state file for this
+# persona holds one: a stale or missing figure is a confident wrong number on a pane, which is worse than none.
+# ⛔ THE FILE IS FOUND BY WHAT IT SAYS, NOT BY ITS NAME. Re-deriving the persona->filename rule here would be a
+# third copy of it (the M290 lesson); every state file records its own watched persona in `identity`, so one
+# jq pass over the known layouts asks the files instead. Newest first, and the NEWEST match decides: if it
+# holds no count (unknown), an older file's figure must not stand in for it.
+kijito_unread_for_persona() {
+  local want=${1:-} f n files=()
+  [ -n "$want" ] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  # rewritten every poll, so anything older than 10 min is a producer that has stopped writing it
+  while IFS= read -r f; do [ -n "$f" ] && files+=("$f"); done < <(
+    find "$HOME/.kijito-monitor" "$HOME/.cache/kijito-inbox-monitor" "$HOME/.local/state/kijito-inbox-monitor" \
+         -maxdepth 1 -type f \( -name '*.state' -o -name 'hive.*.json' -o -name 'state.*.json' \) -mmin -10 \
+         2>/dev/null)
+  [ "${#files[@]}" -gt 0 ] || return 1
+  # shellcheck disable=SC2012  # the paths come from find above; ls is only ordering them by mtime
+  n=$(ls -t "${files[@]}" 2>/dev/null | tr '\n' '\0' | xargs -0 jq -rn --arg w "$(printf '%s' "$want" | tr '[:upper:]' '[:lower:]')" '
+        first(inputs | select((try (.identity[4] | map(select(.[0] == "persona")) | .[0][1] | ascii_downcase)
+                               catch null) == $w)) | .unread // empty' 2>/dev/null)
+  case "$n" in ''|*[!0-9]*) return 1 ;; esac
+  printf '%s' "$n"
+}
+
 # kijito_stream_consumed <stream-path> -> 0 if a wake-capable consumer (`tail -n 0 -F …`) reads it.
 # ⚠️ ANCHOR ON WHAT THE PROCESS *IS*. An unanchored pgrep on the events path SELF-MATCHES the producer
 # (its own argv contains that path), and the harness's `bash -c … eval` wrappers carry the same argv —

package/providers/claude/scripts/statusline-context.sh

@@ -58,6 +58,14 @@ col=$(awk -v p="$pct" 'BEGIN { if (p>=80) printf "\033[31m"; else if (p>=60) pri
 if [ -n "$persona" ]; then
   printf '\033[36m%s\033[0m · ' "$(kijito_truncate "$persona" 18)"
 fi
+# ROW M309, second half: the persona's unread count, from the producer's own state file (fresh only).
+# Shown only when non-zero, so a quiet pane keeps the line it had.
+if [ -n "$persona" ]; then
+  unread=$(kijito_unread_for_persona "$persona" || true)
+  if [ -n "$unread" ] && [ "$unread" -gt 0 ]; then
+    printf '\033[33m✉ %s\033[0m · ' "$unread"
+  fi
+fi
 # ROW M291: the heartbeat watchdog raises this flag when this pane's persona has unread wake events
 # in its stream and NO consumer reading it (typically after a usage-limit outage ended the loop). It
 # is the one place a human watching the pane will see it; the watchdog removes it on re-arm.

package/providers/monitor/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to kijito-inbox-monitor are documented in this file.
 The format is based on Keep a Changelog, and this project follows Semantic Versioning.
 
+## [0.5.7] - 2026-09-25
+
+### Added
+- **The state file carries the watched persona's unread count (row M309).** The producer read every persona's
+  unread count from `/api/notify/pending` each poll and kept it only in memory, so nothing local - a status
+  line, a health check - could show one. Each poll that had a count now writes it as `unread` (a
+  non-negative integer); a poll that had no count writes no `unread`, so its absence means unknown, never
+  zero. It is written with the fast path on or off. Nothing in the producer reads it back to decide what to
+  emit. It is read as strictly as the other persisted fields: anything but a non-negative integer makes the
+  file CORRUPT. Files written by older versions, which lack the field, load as before.
+
+## [0.5.6] - 2026-09-25
+
+### Fixed
+- **The launchd template names the state file the producer actually writes (row M289).** It passed a base
+  (`--state-file <dir>/hive.json`) that the producer turned into `hive.<persona>.json`, so anyone reading the
+  template looked for a file that never existed. It now passes `--state-file-template <dir>/hive.{persona}.json`,
+  which resolves to the SAME file as before, so upgrading moves nothing. The README's multi-persona example
+  likewise names `state.{persona}.json`. A new `_state_path_from_args()` is the one place the producer
+  decides a persona's state file, and `StateFileNameAgreementTest` derives the name from the template's own
+  argv through it.
+- **A negative persisted `consecutive_failures` makes the state file CORRUPT.** A count below zero was
+  resumed as-is and silently postponed the dead-man alert by that many polls.
+
 ## [0.5.5] - 2026-09-24
 
 ### Added

package/providers/monitor/README.md

@@ -269,7 +269,7 @@ owned, rotated event file, and each agent session consumes only its own:
 ```sh
 kijito-inbox-monitor --all-personas \
   --events-file-template ~/.local/state/kijito-inbox-monitor/events.{persona}.ndjson \
-  --state-file ~/.local/state/kijito-inbox-monitor/state.json
+  --state-file-template ~/.local/state/kijito-inbox-monitor/state.{persona}.json
 ```
 
 Each session then wakes on its own `events.<persona>.ndjson` using the recipe in

package/providers/monitor/UPSTREAM

@@ -1,26 +1,26 @@
 # The upstream release providers/monitor is a byte-exact copy of (row M314).
 # Written by scripts/import-monitor.sh; verified by tests/vendored_monitor_test.sh. Never hand-edit.
 repo=KijitoAI/kijito-inbox-monitor
-sha=35b2fe6688b2f2f536a98952f40816c96057c69f
-tree=994bb014166bb65b57223a524bbb0673f57ce22d
-tag=v0.5.5
+sha=9ac160aa98d8205a9eabe05378d9fd7ac25d8273
+tree=65ee5cf22640992369c09d6d6f1707116093908b
+tag=v0.5.7
 file=100644 8d88ccb0fd09b9144505f985b4f882db278fac1f .github/workflows/publish-npm.yml
 file=100644 19ce3471a2cffa689be9d261049c1e74e3e7a25e .github/workflows/publish-pypi.yml
 file=100644 4534290a5dd36d18d07a782b784b6b0ad5ee38fc .gitignore
-file=100644 9e7c054bccb95cbcb42ea8642eb1fab76e5863d5 CHANGELOG.md
+file=100644 483f8aaa29ab3500ff421315bca2d894b3c40fc6 CHANGELOG.md
 file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
 file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
-file=100644 fa81d2fc2645a5503117825b714200e0ae642cc4 README.md
+file=100644 73d2bf5a5d5d6cb622db014285cd9ada4c705724 README.md
 file=100644 72f0c148f1e721ac1bb4a38e5cae690355774314 RELEASING.md
 file=100755 fca1203267cb726736b0c8f239e2d74c40a7a895 arm-hive-monitor.sh
 file=100755 bbe3f07de13dab8a8a7a4798481156ae4a46ab8f bin/cli.js
-file=100644 23e088613c314bf86b384640639b545de60ea9d0 com.kijito.inbox-monitor.plist.template
-file=100644 30519b1ad6098541083648392f344da68e688246 docs/DESIGN.md
+file=100644 fffa8bd23749a321285bd942a3f4f4a98936129c com.kijito.inbox-monitor.plist.template
+file=100644 fc953e43bcd3069a1dc426ddefc751d8f01cf599 docs/DESIGN.md
 file=100644 4f5e53a8633e60e6c57c451e28546f8af8783fe8 kijito-inbox-monitor@.service.template
-file=100644 a88a59eb52d45918794b46d54de826617d977ff2 kijito_inbox_monitor.py
-file=100644 8c2d292152fbe752d5ebf3445141a9d7df5576e5 package.json
-file=100644 199474330b420fa514378ab0c1211e21db9c6c41 pyproject.toml
+file=100644 db09ae46bf223a01ea0c2903cc886e6e09b21d43 kijito_inbox_monitor.py
+file=100644 9cea8637ea9c61323ac2298da3d521454eabd85a package.json
+file=100644 d0af8757fa4d3c3f4591f64a0e3d67d1637a9210 pyproject.toml
 file=100755 b34a5c775385ecfaefd4b374c1fc1aa082a85d14 scripts/migrate-systemd-unit.sh
 file=100755 22acef6d6875395a81c701eb535030d0a78b0df1 scripts/mutation-check.py
 file=100755 acba6196213736922fc4f7135749386d85d172a6 scripts/prepublish-gate.sh
-file=100644 8745e5bfe9573b9e85dd4e10f8904273d1dff864 test_kijito_monitor.py
+file=100644 8d881e5f8562d4ce6b1b22fc97bf9f1ade1d52fb test_kijito_monitor.py

package/providers/monitor/com.kijito.inbox-monitor.plist.template

@@ -37,8 +37,8 @@
     <string>__PROGRAM__</string>
     <string>--token-file</string>
     <string>__HOME__/.config/kijito-inbox-monitor/token</string>
-    <string>--state-file</string>
-    <string>__HOME__/.cache/kijito-inbox-monitor/hive.json</string>
+    <string>--state-file-template</string>
+    <string>__HOME__/.cache/kijito-inbox-monitor/hive.{persona}.json</string>
     <string>--events-file-template</string>
     <string>__HOME__/.cache/kijito-inbox-monitor/events.{persona}.ndjson</string>
     <string>--heartbeat</string>

package/providers/monitor/docs/DESIGN.md

@@ -592,7 +592,13 @@ read-state-neutral (DONE-WHEN #5 holds after self-test).
 - **Content (JSON):** `{"identity":<canonical-id>, "cursor":<int|null>, "state":"UP|DOWN",
   "consecutive_failures":<int>}`, plus the optional pin fields written only when they are in force:
   `emitted_above` (list of int), `gap_alerted` (int), `pin_forced` (true), `pin_evidence_intact` (false),
-  `state_corrupt` (true), `pin_release_at` (int).
+  `state_corrupt` (true), `pin_release_at` (int). Also `unread_hidden` (true) while the unread-not-shown alarm
+  is announced, and `unread` (non-negative int, row M309): the watched persona's unread count as of the poll that
+  wrote the file. `unread` is INFORMATIONAL - it is written for local readers (a status line, a health check) and
+  nothing in the producer reads it back to decide what to emit. It is written only by a poll whose
+  `/api/notify/pending` read succeeded (a persona missing from a good response is a real 0 - the server omits
+  personas with nothing pending); a poll without that read writes no `unread`, so its absence means UNKNOWN,
+  never zero. A reader should also judge freshness from the file's mtime: the file is rewritten every poll.
 - **Every persisted field is read STRICTLY, and anything unrecognised fails CLOSED** (Loom re-audit 7, HIGH 2).
   Booleans must be JSON booleans and integers must be real integers - a JSON `1` for `pin_forced` used to
   normalise to `false` and silently UNPIN the watermark, letting the replay cap cross the very span the pin was

package/providers/monitor/kijito_inbox_monitor.py

@@ -33,7 +33,7 @@ try:
 except ImportError:  # pragma: no cover - Windows
     fcntl = None
 
-__version__ = "0.5.5"
+__version__ = "0.5.7"
 SOURCE = "kijito-inbox"
 # A named User-Agent is REQUIRED: api.kijito.ai is fronted by a WAF that 403s the default Python-urllib UA.
 USER_AGENT = "kijito-inbox-monitor/%s" % __version__
@@ -1543,7 +1543,7 @@ class StateFile:
                              "%s\n" % self.path)
             return CORRUPT_STATE
         if not ((cursor is None or _is_int(cursor)) and state in ("UP", "DOWN")
-                and _is_int(failures)):
+                and _is_int(failures) and failures >= 0):   # a failure COUNT is never negative
             sys.stderr.write("kijito-inbox-monitor: WARNING state-file has a valid envelope but invalid "
                              "fields; refusing to baseline over it: %s\n" % self.path)
             return CORRUPT_STATE
@@ -1644,10 +1644,18 @@ class StateFile:
         # a re-announce after an upgrade costs one event and is honest about the current condition,
         # whereas defaulting to True would silence a live condition for the rest of the run.
         hidden = d.get("unread_hidden") is True
+        # `unread` (row M309) is read as strictly as every other field: a count that is not a non-negative
+        # integer is evidence the file was not written by us, and the answer to that is the same fail-closed
+        # one. Absent (an older file, or a poll with no count) is fine and means unknown.
+        unread = d.get("unread")
+        if unread is not None and not (_is_int(unread) and unread >= 0):
+            sys.stderr.write("kijito-inbox-monitor: WARNING state-file 'unread' is not a non-negative integer "
+                             "(%r); treating the whole file as CORRUPT (fail closed): %s\n" % (unread, self.path))
+            return CORRUPT_STATE
         return {"cursor": cursor, "state": state, "failures": failures, "emitted_above": emitted,
                 "gap_alerted": alerted, "pin_evidence_intact": intact,
                 "pin_forced": pin_forced, "pin_release_at": release_at,
-                "state_corrupt": state_corrupt, "unread_hidden": hidden}
+                "state_corrupt": state_corrupt, "unread_hidden": hidden, "unread": unread}
 
     def unlock(self):
         """Release the single-writer flock and close the sidecar fd.
@@ -1664,7 +1672,7 @@ class StateFile:
 
     def save(self, cursor, state, failures, emitted_above=None, gap_alerted=None,
              pin_forced=False, pin_evidence_intact=True, state_corrupt=False, pin_release_at=None,
-             unread_hidden=False):
+             unread_hidden=False, unread=None):
         """Persist the cursor. Returns True IFF the write is DURABLE (Loom re-audit 8, HIGH 3).
 
         The directory fsync used to be called and its answer thrown away, so a failure returned success
@@ -1700,6 +1708,11 @@ class StateFile:
         # act on any faster for being told twice.
         if unread_hidden:
             d["unread_hidden"] = True
+        # The persona's unread count as of this poll (row M309) - the one LOCAL place a status line or a
+        # health check can read it. INFORMATIONAL: nothing here reads it back to decide what to emit.
+        # Omitted when this poll had no count, so its absence means "unknown", never "zero".
+        if unread is not None:
+            d["unread"] = unread
         dirn = os.path.dirname(os.path.abspath(self.path)) or "."
         # BOTH OF THESE ARE INSIDE THE GUARD, and they did not used to be (drill, 2026-08-05).
         # This function builds a careful "written but not provably durable" path - _fsync_dir fails ->
@@ -1858,6 +1871,15 @@ def _persona_path(template, persona):
     return template.replace("{persona}", _state_safe_persona(persona))
 
 
+def _state_path_from_args(args, persona):
+    """THE state file a persona's watch target opens (row M289): the `{persona}` template when given, else the
+    per-persona derivation of the `--state-file` base. One function, so a supervisor template, the docs and a
+    test can ask the producer which file it will write instead of re-deriving the name and drifting."""
+    if getattr(args, "state_file_template", None):
+        return _persona_path(args.state_file_template, persona)
+    return _state_path_for_persona(getattr(args, "state_file", None), persona)
+
+
 def _created_epoch(created):
     """A message's `created` as epoch seconds, or None if it cannot be read. The server writes naive UTC
     ('2026-09-24 21:34:24.943580'); an explicit offset or 'Z' is honoured when present."""
@@ -1989,6 +2011,10 @@ class WatchTarget:
         self.armed = False
         self.fast_path = False
         self.last_unread = None
+        # What THIS poll learned about the persona's unread count, for the state file (row M309). Kept apart
+        # from `last_unread`, which is the fast-path's wake TRIGGER and only exists while the fast path is on:
+        # reusing it would publish nothing under --no-fast-path, and a status line would read that as zero.
+        self.observed_unread = None
         self.skips = 0
         self.first_poll = True
         self.last_heartbeat = _monotonic()
@@ -2022,8 +2048,7 @@ class WatchTarget:
         cp = urllib.parse.urlsplit(url)
         self.unread_persona = dict(urllib.parse.parse_qsl(cp.query)).get("persona") or persona
 
-        state_path = (_persona_path(args.state_file_template, persona) if args.state_file_template
-                      else _state_path_for_persona(args.state_file, persona))
+        state_path = _state_path_from_args(args, persona)
         if state_path:
             self.state_file = StateFile(state_path, self.identity)
             if not args.self_test:
@@ -2400,6 +2425,11 @@ class WatchTarget:
     def poll_once(self, counts_available=False, unread_counts=None):
         args = self.args
         unread_counts = unread_counts or {}
+        # A count the server did NOT give us this tick is UNKNOWN, never zero: the state file then carries no
+        # `unread` at all, so a reader shows nothing rather than a stale or invented figure. A persona missing
+        # from a GOOD response is a real zero - /api/notify/pending omits personas with nothing pending.
+        self.observed_unread = (unread_counts.get(self.unread_persona, 0)
+                                if counts_available and self.unread_persona else None)
 
         skip_full = False
         if self.armed and self.fast_path and not args.no_fast_path and self.unread_persona:
@@ -2824,7 +2854,8 @@ class WatchTarget:
                                  pin_evidence_intact=self.pin_evidence_intact,
                                  state_corrupt=self.state_corrupt,
                                  pin_release_at=self.pin_release_at,
-                                 unread_hidden=self.unread_hidden)
+                                 unread_hidden=self.unread_hidden,
+                                 unread=self.observed_unread)
             # ★ CONSUME THE ANSWER (Loom re-audit 9, MEDIUM). Round 8 taught me to RETURN a durability
             # status; this is the same defect one layer out - I produced an answer and then discarded it
             # at the call site, which is the exact thing the previous round was about. A cursor whose

package/providers/monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-inbox-monitor",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Pointer to the Python package kijito-inbox-monitor. A zero-dependency watcher that wakes a running agent when new Kijito inbox mail arrives. Install the real tool with pipx/uv/pip.",
   "license": "Apache-2.0",
   "type": "commonjs",

package/providers/monitor/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kijito-inbox-monitor"
-version = "0.5.5"
+version = "0.5.7"
 description = "Zero-dependency watcher that wakes a running agent when new Kijito inbox mail arrives."
 readme = "README.md"
 requires-python = ">=3.9"

package/providers/monitor/test_kijito_monitor.py

@@ -6114,3 +6114,163 @@ class StillUnreadBackstopTest(unittest.TestCase):
         self.assertIn(">= 0", err(["--persona", "a", "--still-unread-after", "-1"]))
         self.assertIn(">= 1", err(["--persona", "a", "--still-unread-max", "0"]))
         self.assertIsNone(err(["--persona", "a", "--still-unread-after", "0"]))
+
+
+class StateFileNameAgreementTest(unittest.TestCase):
+    """Row M289 (second half): the launchd template, the docs and the producer must agree on the state file's
+    NAME. The template used to pass a base (`--state-file <dir>/hive.json`) that the producer silently turned
+    into `hive.<persona>.json`, so a reader of the template looked for a file that never existed. Now the
+    template names the file with a `{persona}` template and this test derives the name from the template's
+    OWN argv, through the producer's OWN parser and `_state_path_from_args` - one constant, no second copy."""
+
+    NAMES = ["argus", "Loom", "name (purpose)", "Ωmega", "two words", "Claude-chat"]
+    HOME = "/HOMEDIR"
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+
+    def _launchd_argv(self):
+        with open(os.path.join(self._HERE, "com.kijito.inbox-monitor.plist.template"), encoding="utf-8") as fh:
+            text = fh.read()
+        block = re.search(r"<key>ProgramArguments</key>\s*<array>(.*?)</array>", text, re.S).group(1)
+        words = [w.replace("__HOME__", self.HOME) for w in re.findall(r"<string>([^<]*)</string>", block)]
+        return words[words.index("__PROGRAM__") + 1:]
+
+    def _args(self):
+        args = km.build_parser().parse_args(self._launchd_argv())
+        km.validate_args(args)
+        return args
+
+    def test_the_launchd_template_names_exactly_the_state_file_the_producer_writes(self):
+        args = self._args()
+        self.assertIsNotNone(args.state_file_template, "the template must NAME the per-persona file, not a base")
+        for name in self.NAMES:
+            with self.subTest(persona=name):
+                path = km._state_path_from_args(args, name)
+                self.assertEqual(os.path.basename(path), "hive.%s.json" % km._state_safe_persona(name))
+
+    def test_existing_launchd_installs_keep_their_state_file(self):
+        # The old template's base `hive.json` was derived to `hive.<safe>.json`; the new template must land on
+        # the SAME file, or an upgrade would baseline over every persona's cursor (skipping its backlog).
+        args = self._args()
+        legacy = self.HOME + "/.cache/kijito-inbox-monitor/hive.json"
+        for name in self.NAMES:
+            with self.subTest(persona=name):
+                self.assertEqual(km._state_path_from_args(args, name), km._state_path_for_persona(legacy, name))
+
+    def test_the_producer_opens_the_path_state_path_from_args_returns(self):
+        # Pins that the watch target uses THIS function, so the test above speaks for the running producer.
+        with open(os.path.join(self._HERE, "kijito_inbox_monitor.py"), encoding="utf-8") as fh:
+            src = fh.read()
+        self.assertIn("state_path = _state_path_from_args(args, persona)", src)
+
+    def test_the_readme_multi_persona_example_writes_the_file_it_documents(self):
+        with open(os.path.join(self._HERE, "README.md"), encoding="utf-8") as fh:
+            readme = fh.read()
+        m = re.search(r"--all-personas \\\n(?:.*\\\n)*?\s*--state-file-template (\S+)", readme)
+        self.assertIsNotNone(m, "the multi-persona example must name its state file with a {persona} template")
+        args = km.build_parser().parse_args(["--all-personas", "--state-file-template", m.group(1)])
+        self.assertEqual(os.path.basename(km._state_path_from_args(args, "argus")), "state.argus.json")
+        self.assertIn("state.<persona>.json", readme)
+
+
+class NegativeFailureCountStateTest(unittest.TestCase):
+    """A persisted `consecutive_failures` below zero is not a count: resumed as-is it would postpone the
+    dead-man edge by that many polls, silently. `_is_int` alone accepted it (a negative is a real integer)."""
+
+    def _load(self, failures):
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "s.json")
+            with open(p, "w") as f:
+                json.dump({"identity": "idx", "cursor": 100, "state": "UP", "consecutive_failures": failures}, f)
+            err, sys.stderr = sys.stderr, io.StringIO()
+            try:
+                return km.StateFile(p, "idx").load()
+            finally:
+                sys.stderr = err
+
+    def test_a_negative_count_is_CORRUPT(self):
+        for bad in (-1, -1000):
+            self.assertIs(self._load(bad), km.CORRUPT_STATE, "consecutive_failures=%r must not be resumed" % bad)
+
+    def test_zero_still_loads(self):
+        self.assertIsNot(self._load(0), km.CORRUPT_STATE)
+
+
+class PersistedUnreadCountTest(unittest.TestCase):
+    """Row M309: the producer knew every persona's unread count and threw it away, so nothing local - a
+    status line, a health check - could show one. The count now rides in the state file, written by every
+    poll that HAD a count, absent from every poll that did not (absent = unknown, never zero), and read as
+    strictly as every other persisted field."""
+
+    RecordingEmitter = BoundedWindowEndToEndTest.RecordingEmitter
+    FullArgs = BoundedWindowEndToEndTest.FullArgs
+    _target = BoundedWindowEndToEndTest._target
+    _fetch = BoundedWindowEndToEndTest._fetch
+
+    def setUp(self):
+        self._dir = tempfile.TemporaryDirectory()
+        self.addCleanup(self._dir.cleanup)
+        self.path = os.path.join(self._dir.name, "argus.state")
+
+    def _poll(self, counts_available, unread_counts, no_fast_path=True):
+        t = self._target(100, self.RecordingEmitter())
+        t.args.no_fast_path = no_fast_path
+        t.state_file = km.StateFile(self.path, "idx")
+        orig, km.fetch = km.fetch, self._fetch([], 0)
+        try:
+            t.poll_once(counts_available=counts_available, unread_counts=unread_counts)
+        finally:
+            km.fetch = orig
+        with open(self.path) as f:
+            return json.load(f)
+
+    def _load(self, extra):
+        d = {"identity": "idx", "cursor": 100, "state": "UP", "consecutive_failures": 0}
+        d.update(extra)
+        with open(self.path, "w") as f:
+            json.dump(d, f)
+        err, sys.stderr = sys.stderr, io.StringIO()
+        try:
+            return km.StateFile(self.path, "idx").load()
+        finally:
+            sys.stderr = err
+
+    def test_a_poll_WITH_a_count_persists_it(self):
+        self.assertEqual(self._poll(True, {"argus": 7, "river": 2})["unread"], 7)
+
+    def test_it_is_persisted_with_the_fast_path_OFF(self):
+        # The fast path's `last_unread` only exists while the fast path is on; the fleet's systemd units
+        # and every --no-fast-path user would otherwise publish nothing at all.
+        self.assertEqual(self._poll(True, {"argus": 3}, no_fast_path=True)["unread"], 3)
+        self.assertEqual(self._poll(True, {"argus": 4}, no_fast_path=False)["unread"], 4)
+
+    def test_a_persona_missing_from_a_GOOD_response_is_zero(self):
+        # /api/notify/pending omits a persona with nothing pending (measured 2026-09-25: river absent).
+        self.assertEqual(self._poll(True, {"river": 2})["unread"], 0)
+
+    def test_a_poll_WITHOUT_a_count_writes_NO_count(self):
+        # Unknown must not be published as zero, and must not leave the PREVIOUS figure standing either.
+        self._poll(True, {"argus": 9})
+        self.assertNotIn("unread", self._poll(False, {}))
+
+    def test_the_count_round_trips_through_load(self):
+        self._poll(True, {"argus": 5})
+        err, sys.stderr = sys.stderr, io.StringIO()
+        try:
+            st = km.StateFile(self.path, "idx").load()
+        finally:
+            sys.stderr = err
+        self.assertIsNot(st, km.CORRUPT_STATE)
+        self.assertEqual(st["unread"], 5)
+        self.assertEqual(st["cursor"], 100)
+
+    def test_an_OLDER_file_without_the_field_still_loads(self):
+        st = self._load({})
+        self.assertIsNot(st, km.CORRUPT_STATE)
+        self.assertIsNone(st["unread"])
+
+    def test_a_malformed_count_is_CORRUPT(self):
+        for bad in (-1, 1.5, "3", True, [], {}):
+            self.assertIs(self._load({"unread": bad}), km.CORRUPT_STATE, "unread=%r must fail closed" % (bad,))
+
+    def test_zero_loads(self):
+        self.assertEqual(self._load({"unread": 0})["unread"], 0)