kijito-tools 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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/monitor/CHANGELOG.md

@@ -3,6 +3,19 @@
 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.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=04bb12ae11fc882d14c30ac36a9220591b5fab65
+tree=101419def29ffc023991a6f5aace5933d042768a
+tag=v0.5.6
 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 8d92a7f3d76e6802faed79328e349b6b7786b87e 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 fffa8bd23749a321285bd942a3f4f4a98936129c com.kijito.inbox-monitor.plist.template
 file=100644 30519b1ad6098541083648392f344da68e688246 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 5038ff752d4b936e5b9bfab5642f38e7622fd4a4 kijito_inbox_monitor.py
+file=100644 5e682088a3dafbe9526761c87f9a16573c3bbdc9 package.json
+file=100644 6f90a103962a6ee2fa985f8356ff8c95cb93a6a7 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 ea22077c22b25d53d6719af4b0e7d9e719aeea7d 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/kijito_inbox_monitor.py

@@ -33,7 +33,7 @@ try:
 except ImportError:  # pragma: no cover - Windows
     fcntl = None
 
-__version__ = "0.5.5"
+__version__ = "0.5.6"
 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
@@ -1858,6 +1858,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."""
@@ -2022,8 +2031,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:

package/providers/monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-inbox-monitor",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "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.6"
 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,82 @@ 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)