kijito-tools 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.4",
+  "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,17 @@
 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

package/providers/monitor/UPSTREAM

@@ -1,13 +1,13 @@
 # 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=04bb12ae11fc882d14c30ac36a9220591b5fab65
-tree=101419def29ffc023991a6f5aace5933d042768a
-tag=v0.5.6
+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 8d92a7f3d76e6802faed79328e349b6b7786b87e CHANGELOG.md
+file=100644 483f8aaa29ab3500ff421315bca2d894b3c40fc6 CHANGELOG.md
 file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
 file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
 file=100644 73d2bf5a5d5d6cb622db014285cd9ada4c705724 README.md
@@ -15,12 +15,12 @@ file=100644 72f0c148f1e721ac1bb4a38e5cae690355774314 RELEASING.md
 file=100755 fca1203267cb726736b0c8f239e2d74c40a7a895 arm-hive-monitor.sh
 file=100755 bbe3f07de13dab8a8a7a4798481156ae4a46ab8f bin/cli.js
 file=100644 fffa8bd23749a321285bd942a3f4f4a98936129c com.kijito.inbox-monitor.plist.template
-file=100644 30519b1ad6098541083648392f344da68e688246 docs/DESIGN.md
+file=100644 fc953e43bcd3069a1dc426ddefc751d8f01cf599 docs/DESIGN.md
 file=100644 4f5e53a8633e60e6c57c451e28546f8af8783fe8 kijito-inbox-monitor@.service.template
-file=100644 5038ff752d4b936e5b9bfab5642f38e7622fd4a4 kijito_inbox_monitor.py
-file=100644 5e682088a3dafbe9526761c87f9a16573c3bbdc9 package.json
-file=100644 6f90a103962a6ee2fa985f8356ff8c95cb93a6a7 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 ea22077c22b25d53d6719af4b0e7d9e719aeea7d test_kijito_monitor.py
+file=100644 8d881e5f8562d4ce6b1b22fc97bf9f1ade1d52fb test_kijito_monitor.py

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.6"
+__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__
@@ -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 ->
@@ -1998,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()
@@ -2408,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:
@@ -2832,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.6",
+  "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.6"
+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

@@ -6193,3 +6193,84 @@ class NegativeFailureCountStateTest(unittest.TestCase):
 
     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)