kijito-tools 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",
@@ -35,7 +35,7 @@
     "kijito"
   ],
   "scripts": {
-    "prepublishOnly": "npm pack --dry-run",
+    "prepublishOnly": "bash tests/vendored_monitor_test.sh && npm pack --dry-run",
     "test:n0-subject": "node providers/codex/test/n0-subject-boundary.mjs && node --test providers/codex/test/n0-subject-boundary.test.mjs",
     "test:n0": "node --test providers/codex/test/n0-harness.test.mjs && echo N0_HARNESS_BASELINE_GREEN",
     "test:n0-cli": "node --test providers/codex/test/n0-cli-refusal.test.mjs && echo N0_CLI_REFUSAL_GREEN",

package/providers/codex/release-manifest.json

@@ -14,7 +14,7 @@
   },
   "artifacts": {
     "wakeCoreSha256": "5f7b57f71fd7ae96b303195c3671af0d410668b95f6a397c97cbec275992e412",
-    "workflowSha256": "e5f82d7aa18d3b652466d53ef89642d4dedb3ae05b0e13cea0e3d1882cb29496",
+    "workflowSha256": "e411fddb3bd37d4fcf364917572f3c9d132223aa9e1dc0d522efbcae0c8fa73e",
     "planSha256": "d9d666b86ac06414f6e6a13a3e3e2115983a1dad44fcfded7eccc51b191fb451",
     "wakeHelperSha256": "838f6b4462ba037a23a14b6fdb8dc34ee8b8f4a7df258b428832bc092fac3ea4",
     "wsUdsSha256": "4da13eef89b572fb735e756cb06846a021919dec7f91c6d07989377944cc776c",

package/providers/monitor/CHANGELOG.md

@@ -3,6 +3,44 @@
 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.3] - 2026-09-24
+
+### Changed
+- **Both shipped service templates run opaque (`--no-content`).** A producer deployed from
+  `com.kijito.inbox-monitor.plist.template` or `kijito-inbox-monitor@.service.template` now writes
+  event rows that carry a message's identity, sender and timestamps but never its body. An event file
+  is a plain local file that other tools and agents read; message text does not belong in it by
+  default. To keep a bounded content preview, remove `--no-content` from your unit (or pass
+  `--content-chars N`). `OpaqueOutputEnforcementTest` pins both templates and the flag's behaviour.
+  (Previously enforced only in the copy vendored by kijito-tools; upstreamed so the two are identical.)
+
+## [0.5.2] - 2026-09-24
+
+### Added
+- **`--safe-persona PERSONA`** prints the filename component the producer derives from a persona name
+  (casefold, any Unicode alphanumeric kept) and exits. It is the one published persona->filename rule,
+  so the SessionStart hook, the inbox self-test and health tools ask the producer instead of
+  re-implementing it (three copies had drifted).
+
+### Fixed
+- **The persona `reserved` flag is honoured.** `/api/personas` marks the legacy row named after the
+  hive-wide broadcast name (`all`) as `reserved`: nobody works as it. The watcher now treats that row
+  exactly like a declared-`retired` one for alarm purposes: its urgent mail no longer fires the loud
+  "urgent-unanswered" alert (it is named once on the quiet stderr channel instead, and stays readable
+  and counted), and a never-read reserved inbox is classified as clearable debris. A server that does
+  not send the field changes nothing.
+
+## [0.5.1] - 2026-09-24
+
+### Fixed
+- **An empty first window no longer swallows message id 0.** On a first launch with nothing in the inbox
+  the watcher baselined its cursor to `0` (`max(ids, default=0)`), and every emission test is
+  `id > cursor`, so the very first hive message on a new account (the server numbers it `0`) could
+  never be emitted. The producer only logged a quiet `dormant inbox (1 unread)` notice and the agent
+  never woke. An empty first window now baselines to `-1`, the value the fail-closed corrupt-state
+  branch already produced for an empty window; a non-empty first window still baselines to its newest
+  id. Two regression tests cover both cases (`EmptyFirstWindowBaselineTest`).
+
 ## [0.5.0] - 2026-08-15
 
 ### Fixed

package/providers/monitor/IMPORT-PROVENANCE.md

@@ -66,3 +66,23 @@ Old-source transition (kijito-inbox-monitor stays the publish/pin home until fle
 P0-C7 terminal), `_shared` doorbell + authenticated consumer lease (§4.4), and F29/A29 certify+enforce
 of opaque `--no-content` output in both service templates plus the live Mac-producer gap (§4.6) are
 tracked separately and not claimed here.
+
+## Re-import 2026-09-24 (row M314) — the vendored copy is now verified, not asserted
+
+By 2026-09-24 this copy had drifted both ways from upstream: upstream had fixes it lacked (M289, the
+empty-first-window baseline), and it carried two changes upstream lacked (`--safe-persona`, row M290,
+and the opaque-output rule in `OPAQUE-OUTPUT-ENFORCEMENT.md`). Both local changes were first sent
+upstream verbatim (kijito-inbox-monitor #4 → v0.5.2, #5 → v0.5.3), so a byte-exact re-import reverts
+nothing.
+
+| role | SHA | tree |
+|---|---|---|
+| imported (tag `v0.5.3`) | `803c53da623fa2d9bd97f5a9e75f01a78571ea2e` | `0c8d80201933589363305f9e2753e7d717f348d8` |
+
+From here on **never hand-edit `providers/monitor`**:
+- `providers/monitor/UPSTREAM` records the upstream sha, its git tree id and the full file listing.
+- `tests/vendored_monitor_test.sh` recomputes the git tree id of this directory from the files on disk
+  (excluding `UPSTREAM`, this file and `OPAQUE-OUTPUT-ENFORCEMENT.md`, which belong to kijito-tools) and
+  fails on any difference. It runs in the test workflow, in both publish workflows before the package is
+  built, and in npm `prepublishOnly`, so a drifted copy cannot be published.
+- To move to a new upstream release: `scripts/import-monitor.sh <sha-or-tag>`.

package/providers/monitor/OPAQUE-OUTPUT-ENFORCEMENT.md

@@ -1,5 +1,9 @@
 # Opaque output enforcement (P0-F29/A29)
 
+> **Upstreamed 2026-09-24 (row M314):** both template edits and `OpaqueOutputEnforcementTest` now live in
+> `KijitoAI/kijito-inbox-monitor` itself (v0.5.3), and this directory is a byte-exact copy of that release.
+> The record below is kept as the history of why the rule exists.
+
 **Steward:** argus · **Date:** 2026-08-17 · **Row:** `P0-F29`/`A29`, anchor `monitor-foundation-v1`
 (clause: *opaque output*). This is the **certify + enforce** half of the row — the `--no-content`
 capability already exists in shipped code, so nothing is built here; it is made non-optional in the

package/providers/monitor/UPSTREAM

@@ -0,0 +1,25 @@
+# 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=803c53da623fa2d9bd97f5a9e75f01a78571ea2e
+tree=0c8d80201933589363305f9e2753e7d717f348d8
+tag=v0.5.3
+file=100644 8d88ccb0fd09b9144505f985b4f882db278fac1f .github/workflows/publish-npm.yml
+file=100644 19ce3471a2cffa689be9d261049c1e74e3e7a25e .github/workflows/publish-pypi.yml
+file=100644 4534290a5dd36d18d07a782b784b6b0ad5ee38fc .gitignore
+file=100644 5f0a605641efd19a9afa8d0cb0d8bed3f908e232 CHANGELOG.md
+file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
+file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
+file=100644 48038bef573e123fe4657be8a5fdb3e0293b192a 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 0ec3f23c29bb26d2890b9083d1014840a48cd2c3 docs/DESIGN.md
+file=100644 e6d72708b425b6dfaf02e126aaac7633d3584847 kijito-inbox-monitor@.service.template
+file=100644 9a1114ef2ab83cbe3b30bfa50833f3e280e2d91d kijito_inbox_monitor.py
+file=100644 a20200e3aeef01e7a19ce8833f1eea743b53949c package.json
+file=100644 1af00c40f8351d0a12b8563e7c7e865c6be0299d pyproject.toml
+file=100755 22acef6d6875395a81c701eb535030d0a78b0df1 scripts/mutation-check.py
+file=100755 acba6196213736922fc4f7135749386d85d172a6 scripts/prepublish-gate.sh
+file=100644 d54d220ab8b228e557b64cc1497509c46c70a5ee test_kijito_monitor.py

package/providers/monitor/kijito_inbox_monitor.py

@@ -33,7 +33,7 @@ try:
 except ImportError:  # pragma: no cover - Windows
     fcntl = None
 
-__version__ = "0.5.0"
+__version__ = "0.5.3"
 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__
@@ -332,6 +332,14 @@ _PERSONA_RETIRED = {}
 # so the producer can ship before the API populates the field with zero behaviour change. A boolean.
 _PERSONA_WRITE_ONLY = {}
 
+# Declared `reserved` flag per persona from /api/personas (server row M315; consumed here for row M332).
+# TRUE = a legacy row named after the hive-wide BROADCAST name ('all'): it can no longer be created, but
+# an account that minted one before the guard existed still holds it, and it is an ordinary inbox that
+# NOBODY works as. The server calls it debris and names the remedy (retire it). For alarm purposes it is
+# therefore treated exactly like a declared-`retired` row: see _is_debris. Its mail is still READ and
+# still counted - only the alarms change. Same tri-state discipline: absent/non-bool => undeclared.
+_PERSONA_RESERVED = {}
+
 
 def _row_memory_count(row):
     """Memories owned by this persona, or None if the server did not say.
@@ -387,6 +395,25 @@ def _row_write_only(row):
     return w if isinstance(w, bool) else None
 
 
+def _row_reserved(row):
+    """The persona's declared `reserved` flag as a strict bool, or None if the server did not report it.
+
+    Same tri-state discipline as _row_retired: only a genuine bool is a declaration. A server that
+    predates the field reports nothing, and the producer then behaves exactly as it did before (row M332
+    ships ahead of, or behind, the server with zero behaviour change).
+    """
+    r = row.get("reserved")
+    return r if isinstance(r, bool) else None
+
+
+def _is_debris(persona):
+    """True when the directory DECLARES that nobody works as this persona: `retired`, or `reserved`
+    (the legacy broadcast-name row, row M332). A positive declaration only (`is True`); an undeclared
+    flag is never debris. Debris is classified as clearable in the stranded tier and never fires the
+    urgent-unanswered alarm - there is no member there to be unresponsive."""
+    return _PERSONA_RETIRED.get(persona) is True or _PERSONA_RESERVED.get(persona) is True
+
+
 def fetch_personas(opener, headers):
     """Fetch the account persona directory for default/explicit all-persona mode."""
     req = urllib.request.Request(PERSONAS_URL, headers=headers, method="GET")
@@ -410,6 +437,7 @@ def fetch_personas(opener, headers):
             _PERSONA_READ_COUNTS[row["persona"]] = _row_read_count(row)
             _PERSONA_RETIRED[row["persona"]] = _row_retired(row)
             _PERSONA_WRITE_ONLY[row["persona"]] = _row_write_only(row)
+            _PERSONA_RESERVED[row["persona"]] = _row_reserved(row)
     if not personas:
         raise FatalConfig("/api/personas returned no personas")
     return personas
@@ -2341,7 +2369,14 @@ class WatchTarget:
                                                   "reason": "state file present but unusable; re-emitting the "
                                                             "visible window instead of baselining over it"})
                     elif self.cursor is None:
-                        self.cursor = max((m["id"] for m in items), default=0)
+                        # An EMPTY first window baselines BELOW id 0, not AT it. Message ids start at 0
+                        # on a new account, and every emission test is `id > cursor`, so a cursor of 0
+                        # on an empty inbox swallowed the account's very first message forever - the
+                        # producer only ever logged it as a quiet "dormant inbox (1 unread)". -1 is the
+                        # value the fail-closed branch above already produces for an empty window, so it
+                        # is a value every later comparison already tolerates. A NON-empty first window
+                        # still baselines to its newest id (never flood a new agent with history).
+                        self.cursor = max((m["id"] for m in items), default=-1)
                         # ⛔ AN ABSENT STATE FILE MEANS TWO THINGS THAT DEMAND OPPOSITE BEHAVIOUR, AND
                         # NOTHING HERE CAN TELL THEM APART. A genuine first launch must baseline - never
                         # flood a new agent with inbox history. A LOST state file must not: everything
@@ -3043,6 +3078,12 @@ _REPORTED_URGENT_QUIET = set()
 # Same once-per-member, EXACT-keyed discipline as _REPORTED_STRANDED / _REPORTED_DORMANT.
 _REPORTED_URGENT_WO = set()
 
+# DEBRIS rows (declared retired, or the reserved broadcast-name row - row M332) holding urgent unread.
+# Surfaced QUIETLY (a stderr NOTICE) once per member, never the loud alarm: "nobody is answering
+# escalated mail" presumes a member who could answer, and debris by declaration has none. Its own set so
+# no tier can gag another; re-armed by intersection_update like the others.
+_REPORTED_URGENT_DEBRIS = set()
+
 
 def urgent_unanswered(directory):
     """Directory personas holding SENDER-ESCALATED mail while showing no observed activity (§5.5).
@@ -3106,10 +3147,25 @@ def report_urgent_unanswered(directory, targets, emitter):
     # Partition by the DECLARED write_only fact, exactly as _partition_stranded does. `is True` is strict:
     # an undeclared or False flag leaves the member in the LOUD tier unchanged (graceful degradation, the
     # same tri-state _row_write_only guarantees).
+    # DEBRIS FIRST (row M332): a declared-retired row or the reserved broadcast-name row has no member to
+    # be unresponsive, so it leaves the loud tier whatever its other flags say; named quietly below.
+    debris_quiet = [(p, n) for p, n in current if _is_debris(p)]
+    current = [(p, n) for p, n in current if not _is_debris(p)]
     wo_quiet = [(p, n) for p, n in current if _PERSONA_WRITE_ONLY.get(p) is True]
     alerting = [(p, n) for p, n in current if _PERSONA_WRITE_ONLY.get(p) is not True]
     _REPORTED_URGENT_QUIET.intersection_update({p for p, _ in alerting})  # release: leaving re-arms alarm
     _REPORTED_URGENT_WO.intersection_update({p for p, _ in wo_quiet})
+    _REPORTED_URGENT_DEBRIS.intersection_update({p for p, _ in debris_quiet})
+    for persona, n in debris_quiet:
+        if persona in _REPORTED_URGENT_DEBRIS:
+            continue
+        _REPORTED_URGENT_DEBRIS.add(persona)
+        sys.stderr.write(
+            "kijito-inbox-monitor: NOTICE urgent-unanswered on debris (quiet, not alarmed) - %s (%d urgent "
+            "unread; declared %s, so nobody works as it - its mail is still readable; retire or clear it) "
+            "(further notices for %r suppressed)\n"
+            % (persona, n, "reserved (the broadcast name)" if _PERSONA_RESERVED.get(persona) is True
+               else "retired", persona))
     fresh = [(p, n) for p, n in alerting if p not in _REPORTED_URGENT_QUIET]
     fresh_wo = [(p, n) for p, n in wo_quiet if p not in _REPORTED_URGENT_WO]
     # QUIET-BUT-NAMED tier: a stderr NOTICE is a non-waking channel (the event-stream grep filters
@@ -3242,8 +3298,8 @@ def _partition_stranded(directory, counts):
         if read > 0:
             continue                             # someone is consuming it - not stranded at all
         # read == 0: this inbox has never been consumed. Partition by the DECLARED retired flag.
-        if _PERSONA_RETIRED.get(p) is True:
-            loud.append(p)                       # declared clearable debris -> loud, exactly like today
+        if _is_debris(p):
+            loud.append(p)                       # declared clearable debris (retired or reserved) -> loud
         else:
             dormant.append(p)                    # real-but-dormant -> quiet, must NOT ride the loud alarm
     return loud, dormant
@@ -3272,9 +3328,11 @@ def _stranded_detail(persona, directory, counts):
     if twin is not None:
         return "%s (%s unread; case-variant of known persona %r)" % (persona, counts.get(persona), twin)
     in_dir = persona in set(directory)
-    if in_dir and _PERSONA_READ_COUNTS.get(persona) == 0 and _PERSONA_RETIRED.get(persona) is True:
-        return ("%s (%s unread; never consumed (read 0) and declared retired, so it is clearable debris)"
-                % (persona, counts.get(persona)))
+    if in_dir and _PERSONA_READ_COUNTS.get(persona) == 0 and _is_debris(persona):
+        return ("%s (%s unread; never consumed (read 0) and declared %s, so it is clearable debris)"
+                % (persona, counts.get(persona),
+                   "reserved (the broadcast name, not an identity)" if _PERSONA_RESERVED.get(persona) is True
+                   else "retired"))
     if in_dir and _PERSONA_MEMORY_COUNTS.get(persona) == 0:
         return "%s (%s unread; registered as a recipient but owns no memories, so nobody works as it)" % (
             persona, counts.get(persona))

package/providers/monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-inbox-monitor",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "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.0"
+version = "0.5.3"
 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

@@ -757,7 +757,10 @@ class UrgentUnansweredAlarmTest(unittest.TestCase):
         km._INBOX_FLOORS.clear()
         km._REPORTED_URGENT_QUIET.clear()
         km._REPORTED_URGENT_WO.clear()
+        km._REPORTED_URGENT_DEBRIS.clear()
         km._PERSONA_WRITE_ONLY.clear()
+        km._PERSONA_RETIRED.clear()
+        km._PERSONA_RESERVED.clear()
         km._OBSERVED_SINCE = "2026-07-25T07:00:00+00:00"
 
     def tearDown(self):
@@ -920,6 +923,55 @@ class UrgentUnansweredAlarmTest(unittest.TestCase):
         self.assertNotIn("jason", alerts[0]["urgent_unanswered"])
         self.assertIn("jason", err)                                  # also on the quiet channel
 
+    # ── row M332: DEBRIS (the reserved broadcast-name row, or a retired row) never fires the loud alarm ──
+    # "Nobody is answering escalated mail" presumes a member who could answer. A reserved row (the legacy
+    # 'all' inbox the server marks `reserved`) or a retired one has none by declaration, so its urgent mail
+    # is NAMED on the quiet channel - still readable, still counted - and never wakes anyone.
+    def test_reserved_row_holding_urgent_mail_does_NOT_fire_the_loud_alarm(self):
+        km._URGENT_UNREAD.update({"all": 2})
+        km._PERSONA_RESERVED.update({"all": True})
+        self._observe([{"id": 100, "from": "river", "created": "t"}])
+        fresh, alerts, err = self._run_cap(directory=("argus", "all"))
+        self.assertEqual(fresh, [])
+        self.assertEqual(alerts, [])
+        self.assertIn("all", err)                                    # quiet, not invisible
+        self.assertIn("reserved", err)
+        self.assertIn("still readable", err)
+        self.assertEqual(km._URGENT_UNREAD["all"], 2)                # its mail is still counted
+
+    def test_reserved_is_treated_like_retired(self):
+        # The DONE-WHEN's own comparison, asserted directly: the two declarations behave the same.
+        for flag in (km._PERSONA_RESERVED, km._PERSONA_RETIRED):
+            with self.subTest(flag="reserved" if flag is km._PERSONA_RESERVED else "retired"):
+                self.setUp()
+                km._URGENT_UNREAD.update({"ghost": 1, "loom": 1})
+                flag.update({"ghost": True})
+                self._observe([{"id": 100, "from": "river", "created": "t"}])
+                fresh, alerts, err = self._run_cap(directory=("argus", "ghost", "loom"))
+                self.assertEqual(fresh, ["loom"])                    # the real member still alarms
+                self.assertEqual(alerts[0]["urgent_unanswered"], ["loom"])
+                self.assertIn("ghost", err)
+
+    def test_undeclared_or_false_reserved_still_fires_loud(self):
+        # Only a POSITIVE declaration quiets: a flag explicitly False, or absent (an older server), leaves
+        # the member on the loud alarm exactly as before.
+        km._URGENT_UNREAD.update({"loom": 1, "quill": 3})
+        km._PERSONA_RESERVED.update({"loom": False})                 # quill: no entry at all
+        self._observe([{"id": 100, "from": "river", "created": "t"}])
+        fresh, _alerts, _err = self._run_cap(directory=("argus", "loom", "quill"))
+        self.assertEqual(sorted(fresh), ["loom", "quill"])
+
+    def test_debris_quiet_notice_is_once_then_re_arms(self):
+        km._URGENT_UNREAD.update({"all": 1})
+        km._PERSONA_RESERVED.update({"all": True})
+        self._observe([{"id": 100, "from": "river", "created": "t"}])
+        self.assertIn("all", self._run_cap(directory=("argus", "all"))[2])
+        self.assertEqual(self._run_cap(directory=("argus", "all"))[2], "")   # suppressed while it holds
+        km._URGENT_UNREAD.update({"all": 0})
+        self._run_cap(directory=("argus", "all"))                            # condition clears
+        km._URGENT_UNREAD.update({"all": 1})
+        self.assertIn("all", self._run_cap(directory=("argus", "all"))[2])   # recurrence announced again
+
     def test_undeclared_or_false_write_only_still_fires_loud(self):
         # GRACEFUL DEGRADATION + the mutation discriminator: only `is True` quiets. A flag explicitly
         # False, or absent entirely, still rides the loud alarm exactly as before - and the informational
@@ -2289,9 +2341,11 @@ class M167ReadCountPartitionTest(unittest.TestCase):
         self._read = dict(km._PERSONA_READ_COUNTS)
         self._ret = dict(km._PERSONA_RETIRED)
         self._wo = dict(km._PERSONA_WRITE_ONLY)
+        self._rsv = dict(km._PERSONA_RESERVED)
         self._rs = set(km._REPORTED_STRANDED)
         self._rd = set(km._REPORTED_DORMANT)
-        for d in (km._PERSONA_MEMORY_COUNTS, km._PERSONA_READ_COUNTS, km._PERSONA_RETIRED, km._PERSONA_WRITE_ONLY):
+        for d in (km._PERSONA_MEMORY_COUNTS, km._PERSONA_READ_COUNTS, km._PERSONA_RETIRED, km._PERSONA_WRITE_ONLY,
+                  km._PERSONA_RESERVED):
             d.clear()
         km._REPORTED_STRANDED.clear()
         km._REPORTED_DORMANT.clear()
@@ -2300,7 +2354,8 @@ class M167ReadCountPartitionTest(unittest.TestCase):
         for d, saved in ((km._PERSONA_MEMORY_COUNTS, self._mem),
                          (km._PERSONA_READ_COUNTS, self._read),
                          (km._PERSONA_RETIRED, self._ret),
-                         (km._PERSONA_WRITE_ONLY, self._wo)):
+                         (km._PERSONA_WRITE_ONLY, self._wo),
+                         (km._PERSONA_RESERVED, self._rsv)):
             d.clear()
             d.update(saved)
         km._REPORTED_STRANDED.clear()
@@ -2415,6 +2470,27 @@ class M167ReadCountPartitionTest(unittest.TestCase):
         self.assertNotIn("dormant_inboxes", events[0])   # no dormant this tick
         self.assertIn("clearable debris", err)
 
+    # --- row M332: the reserved broadcast-name row is classified exactly like a retired one ------------
+    def test_reserved_row_read0_is_classified_like_retired_debris(self):
+        km._PERSONA_MEMORY_COUNTS.update({"all": 0, "argus": 40})
+        km._PERSONA_READ_COUNTS.update({"all": 0, "argus": 3})
+        km._PERSONA_RESERVED.update({"all": True})                     # NOT retired - reserved alone
+        directory = ["all", "argus"]
+        self.assertEqual(km.stranded_inboxes(directory, {"all": 1}), ["all"])
+        self.assertEqual(km.dormant_inboxes(directory, {"all": 1}), [])
+        fresh, events, err = self._report(directory, {"all": 1}, watchers=("argus",))
+        self.assertEqual(fresh, ["all"])
+        self.assertIn("reserved (the broadcast name, not an identity)", err)
+        self.assertIn("clearable debris", err)
+
+    def test_a_reserved_False_row_is_not_debris(self):
+        km._PERSONA_MEMORY_COUNTS.update({"quietone": 3, "argus": 40})
+        km._PERSONA_READ_COUNTS.update({"quietone": 0, "argus": 3})
+        km._PERSONA_RESERVED.update({"quietone": False})
+        directory = ["quietone", "argus"]
+        self.assertEqual(km.stranded_inboxes(directory, {"quietone": 1}), [])
+        self.assertEqual(km.dormant_inboxes(directory, {"quietone": 1}), ["quietone"])
+
     # --- case 2: omniview reads nothing but is NOT retired -> DORMANT/quiet, never loud -----------------
     def test_omniview_read0_not_retired_is_QUIET_dormant_not_loud(self):
         km._PERSONA_MEMORY_COUNTS.update({"omniview": 149, "argus": 40})
@@ -4435,6 +4511,40 @@ class Loom7CorruptionPinReleaseTest(unittest.TestCase):
         self.assertEqual(t.cursor, 200)
 
 
+class EmptyFirstWindowBaselineTest(unittest.TestCase):
+    """A brand-new account's first hive message carries id 0. An EMPTY first window used to baseline the
+    cursor to 0 (`max(..., default=0)`), and every emission test is `id > cursor`, so that message could
+    never be emitted: the producer logged a quiet "dormant inbox (1 unread)" and the agent never woke.
+    Measured 2026-09-18 on a fresh account with one persona and one launch of the producer."""
+
+    E2E = BoundedWindowEndToEndTest
+
+    def _fresh(self, em):
+        t = self.E2E()._target(cursor=None, emitter=em)
+        t.armed = False                              # a first launch: nothing persisted, not yet armed
+        return t
+
+    def test_an_EMPTY_first_window_baselines_BELOW_id_zero_so_message_0_is_emitted(self):
+        em = self.E2E.RecordingEmitter()
+        t = self._fresh(em)
+        self.E2E()._run(t, self.E2E()._fetch([], 0))
+        self.assertEqual(t.cursor, -1, "an empty inbox has delivered nothing, so the watermark sits below 0")
+        self.assertEqual(em.new_ids, [])
+        self.E2E()._run(t, self.E2E()._fetch([{"id": 0}], 0))
+        self.assertEqual(em.new_ids, [0], "the account's first message must wake the agent")
+        self.assertEqual(t.cursor, 0)
+
+    def test_a_NON_EMPTY_first_window_still_baselines_to_its_newest_id(self):
+        # The control: a genuine first launch onto an inbox WITH history must not flood the agent.
+        em = self.E2E.RecordingEmitter()
+        t = self._fresh(em)
+        self.E2E()._run(t, self.E2E()._fetch([{"id": 0}, {"id": 5}], 0))
+        self.assertEqual(t.cursor, 5)
+        self.assertEqual(em.new_ids, [])
+        self.E2E()._run(t, self.E2E()._fetch([{"id": 0}, {"id": 5}, {"id": 6}], 0))
+        self.assertEqual(em.new_ids, [6])
+
+
 class Loom7StateFileHygieneTest(unittest.TestCase):
     """Loom re-audit 7, item 7. The lock fd was never closed - two ResourceWarnings, and a real leak."""
 
@@ -5579,6 +5689,139 @@ class WakeClassPhase1Test(unittest.TestCase):
                 self.assertEqual(bool(old_lenient.search(line)), should_match)
         # and the field itself is the bare kind, not decorated
         self.assertEqual(self._emit("armed")["event"], "armed")
+class SharedPersonaFilenameRuleTest(unittest.TestCase):
+    """`--safe-persona` is the ONE place the persona->filename rule is published (row M290).
+
+    Three programs had each re-implemented it and drifted: this producer (correct), kijito-tools'
+    SessionStart hook (`sed 's/[^A-Za-z0-9._-]/_/g'` - no casefold, ASCII-only) and producer-health.sh
+    (no sanitising at all). A persona whose name merely contains a CAPITAL LETTER therefore got a path
+    from the hook that the producer never writes, the hook reported "your mail is not being collected",
+    and a Monitor armed on that path waited forever in silence.
+
+    ⚠️ THE REASON IT SURVIVED REVIEW, AND WHY THESE ASSERTIONS ARE SHAPED AS THEY ARE: on macOS the
+    filesystem is case-INSENSITIVE, so the hook's `[ -e ... ]` probe SUCCEEDS on the producer's
+    differently-cased file and everything looks fine. The defect is only observable on Linux. So the
+    tests below pin the RULE ITSELF (casefold; Unicode alnum survives) rather than "the file was
+    found", because the find-the-file question answers YES on the very platform most likely to be
+    running the test.
+    """
+
+    # spaces, parentheses, slashes, unicode and case - the set row M290's DONE-WHEN names, plus the
+    # ordinary name as a control (a fixture of only exotic names cannot tell "correct" from "mangles
+    # everything").
+    NAMES = [
+        "argus", "x", "dots.and_dash-ok",
+        "spaced name", "name (purpose)", "a/b", "tab\tname",
+        "Loom", "UPPER", "Claude-Chat",
+        "café", "Ωmega",
+    ]
+
+    def _run(self, argv):
+        out, err = io.StringIO(), io.StringIO()
+        real_out, real_err = sys.stdout, sys.stderr
+        sys.stdout, sys.stderr = out, err
+        try:
+            rc = km.main(argv)
+        finally:
+            sys.stdout, sys.stderr = real_out, real_err
+        return rc, out.getvalue(), err.getvalue()
+
+    def test_cli_answer_is_the_function_answer_for_every_name(self):
+        # The CLI is not a second implementation to be kept in step by hand - it must BE the function.
+        for name in self.NAMES:
+            with self.subTest(name=name):
+                rc, out, _ = self._run(["--safe-persona", name])
+                self.assertEqual(rc, 0)
+                self.assertEqual(out, km._state_safe_persona(name) + "\n")
+
+    def test_answer_is_one_bare_line_a_shell_can_capture(self):
+        # `_safe=$(kijito-inbox-monitor --safe-persona "$p")` is the calling convention, so anything
+        # else on stdout silently becomes part of a filename.
+        rc, out, _ = self._run(["--safe-persona", "name (purpose)"])
+        self.assertEqual(rc, 0)
+        self.assertEqual(out.count("\n"), 1)
+        self.assertEqual(out.strip(), "name__purpose_")
+
+    def test_needs_no_token_no_network_no_state_file(self):
+        # The hook runs at session start with none of the producer's configuration in hand. If asking
+        # for the rule required a token or a state file, every caller would go back to guessing - which
+        # is the defect. Proven by clearing the token env rather than by reading the code.
+        saved = os.environ.pop("KIJITOMON_TOKEN", None)
+        try:
+            rc, out, _ = self._run(["--safe-persona", "Loom"])
+        finally:
+            if saved is not None:
+                os.environ["KIJITOMON_TOKEN"] = saved
+        self.assertEqual(rc, 0)
+        self.assertEqual(out.strip(), "loom")
+
+    def test_empty_persona_refuses_and_prints_no_component(self):
+        # A blank answer would be interpolated into a path as an empty component, producing a plausible
+        # file that nothing writes. Refuse by name instead (the tool's could-not-do-it code).
+        rc, out, err = self._run(["--safe-persona", ""])
+        self.assertEqual(rc, 2)
+        self.assertEqual(out, "")
+        self.assertIn("--safe-persona", err)
+
+    def test_rule_casefolds_and_keeps_unicode_alphanumerics(self):
+        # ⛔ THE REGRESSION GUARD, pinned as the two PROPERTIES that actually diverged rather than as a
+        # list of observed strings: replace the rule with a hand-written ASCII filter (the hook's old
+        # `[^A-Za-z0-9._-]`) and both of these fail - the first because it would keep the capital, the
+        # second because it would blank a perfectly good Unicode letter.
+        self.assertEqual(km._state_safe_persona("Loom"), "loom")
+        self.assertEqual(km._state_safe_persona("Ωmega"), "ωmega")
+        # and the control: it still replaces what genuinely cannot be in a filename component.
+        self.assertEqual(km._state_safe_persona("a/b"), "a_b")
+
+    def test_the_rule_is_idempotent(self):
+        # Callers chain: the hook sanitises, a script re-sanitises the result. A rule that is not
+        # idempotent turns that into a third distinct filename.
+        for name in self.NAMES:
+            with self.subTest(name=name):
+                once = km._state_safe_persona(name)
+                self.assertEqual(km._state_safe_persona(once), once)
+
+
+class ReservedFlagParseTest(unittest.TestCase):
+    """Row M332: `reserved` is read from /api/personas with the same tri-state discipline as `retired`."""
+
+    def test_only_a_genuine_bool_is_a_declaration(self):
+        self.assertIs(km._row_reserved({"reserved": True}), True)
+        self.assertIs(km._row_reserved({"reserved": False}), False)
+        for junk in ({}, {"reserved": None}, {"reserved": "true"}, {"reserved": 1}):
+            with self.subTest(row=junk):
+                self.assertIsNone(km._row_reserved(junk))
+
+    def test_fetch_personas_records_it(self):
+        dicts = (km._PERSONA_RESERVED, km._PERSONA_RETIRED, km._PERSONA_WRITE_ONLY,
+                 km._PERSONA_MEMORY_COUNTS, km._PERSONA_READ_COUNTS)
+        saved = [dict(d) for d in dicts]
+        try:
+            body = json.dumps({"result": [{"persona": "all", "reserved": True, "retired": False},
+                                          {"persona": "argus", "reserved": False}]}).encode()
+
+            class Resp:
+                status = 200
+                def read(self):
+                    return body
+                def __enter__(self):
+                    return self
+                def __exit__(self, *a):
+                    return False
+
+            class Opener:
+                def open(self, req, timeout=None):
+                    return Resp()
+
+            self.assertEqual(km.fetch_personas(Opener(), {}), ["all", "argus"])
+            self.assertIs(km._PERSONA_RESERVED["all"], True)
+            self.assertIs(km._PERSONA_RESERVED["argus"], False)
+            self.assertTrue(km._is_debris("all"))
+            self.assertFalse(km._is_debris("argus"))
+        finally:
+            for d, keep in zip(dicts, saved):
+                d.clear()
+                d.update(keep)
 
 
 class OpaqueOutputEnforcementTest(unittest.TestCase):