kijito-tools 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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/claude/scripts/kijito-persona-lib.sh

@@ -54,7 +54,11 @@ kijito_stream_for_persona() {
   done
   [ -n "$km" ] && safe=$("$km" --safe-persona "$want" 2>/dev/null)
   if [ -n "$safe" ]; then
-    for cand in "$HOME/.kijito-monitor/$safe.jsonl" "$HOME/.cache/kijito-inbox-monitor/events.$safe.ndjson"; do
+    # THREE layouts: the fleet's systemd units, the launchd plist, and the monitor's own shipped systemd
+    # template (~/.local/state, XDG state) - the last one was missing until row M313's follow-up, so a
+    # Linux user who installed the unit from the monitor repo had a stream nothing here would find.
+    for cand in "$HOME/.kijito-monitor/$safe.jsonl" "$HOME/.cache/kijito-inbox-monitor/events.$safe.ndjson" \
+                "$HOME/.local/state/kijito-inbox-monitor/events.$safe.ndjson"; do
       [ -e "$cand" ] && { printf '%s' "$cand"; return 0; }
     done
   fi
@@ -63,7 +67,8 @@ kijito_stream_for_persona() {
 import glob, json, os, sys
 want = os.environ["KJ_WANT"].casefold(); home = os.path.expanduser("~"); hits = []
 for pat in (os.path.join(home, ".kijito-monitor", "*.jsonl"),
-            os.path.join(home, ".cache", "kijito-inbox-monitor", "events.*.ndjson")):
+            os.path.join(home, ".cache", "kijito-inbox-monitor", "events.*.ndjson"),
+            os.path.join(home, ".local", "state", "kijito-inbox-monitor", "events.*.ndjson")):
     for path in glob.glob(pat):
         try:
             with open(path, "rb") as fh:

package/providers/claude/scripts/session-catchup-hint.sh

@@ -100,7 +100,8 @@ want = os.environ["KJ_PERSONA"].casefold()
 home = os.path.expanduser("~")
 hits = []
 for pat in (os.path.join(home, ".kijito-monitor", "*.jsonl"),
-            os.path.join(home, ".cache", "kijito-inbox-monitor", "events.*.ndjson")):
+            os.path.join(home, ".cache", "kijito-inbox-monitor", "events.*.ndjson"),
+            os.path.join(home, ".local", "state", "kijito-inbox-monitor", "events.*.ndjson")):
     for path in glob.glob(pat):
         try:
             with open(path, "rb") as fh:
@@ -174,6 +175,10 @@ fi
 # supervisor definition is the next-best evidence. uname is the last resort, not the first test.
 _mac_events="$HOME/.cache/kijito-inbox-monitor/events.${_safe}.ndjson"
 _lnx_events="$HOME/.kijito-monitor/${_safe}.jsonl"
+# The monitor repo's OWN shipped systemd template writes here (XDG state). A third layout, and until row
+# M313's follow-up this script did not know it: a user who installed the unit from the monitor README got
+# "nothing is collecting your mail" while their producer was writing mail into this file.
+_tpl_events="$HOME/.local/state/kijito-inbox-monitor/events.${_safe}.ndjson"
 if   [ "$_rule" = by-content ] || [ "$_rule" = stale-stream ]; then
   # The producer's own output named this file. It outranks every derivation below, because it is the
   # only one of them that was written by the process we are asking about.
@@ -183,18 +188,21 @@ if   [ "$_rule" = by-content ] || [ "$_rule" = stale-stream ]; then
   # an empty component that looks like a path and names nothing. The producer line says it is stale;
   # the arming block should still point at the file that will come back when it restarts.
   _events="$_found"
-  case "$_events" in *.jsonl) _sup="systemd" ;; *) _sup="launchd" ;; esac
+  case "$_events" in *.jsonl|*/.local/state/*) _sup="systemd" ;; *) _sup="launchd" ;; esac
 elif [ -n "$_safe" ] && [ -e "$_lnx_events" ]; then _events="$_lnx_events"; _sup="systemd"
 elif [ -n "$_safe" ] && [ -e "$_mac_events" ]; then _events="$_mac_events"; _sup="launchd"
+elif [ -n "$_safe" ] && [ -e "$_tpl_events" ]; then _events="$_tpl_events"; _sup="systemd"
 elif [ -d "$HOME/.kijito-monitor" ]; then          _events="$_lnx_events"; _sup="systemd"
+elif [ -d "$HOME/.local/state/kijito-inbox-monitor" ]; then _events="$_tpl_events"; _sup="systemd"
 elif [ -d "$HOME/.cache/kijito-inbox-monitor" ]; then _events="$_mac_events"; _sup="launchd"
 elif [ -f "$HOME/Library/LaunchAgents/com.kijito.inbox-monitor.plist" ]; then _events="$_mac_events"; _sup="launchd"
 elif [ "$(uname -s 2>/dev/null)" = "Darwin" ]; then _events="$_mac_events"; _sup="launchd"
 else _events="$_lnx_events"; _sup="systemd"; fi
 # The generic (no-marker) branch cannot name a file, so it shows the directory shape instead.
-case "$_sup" in
-  launchd) _events_tmpl="\$HOME/.cache/kijito-inbox-monitor/events.<persona>.ndjson" ;;
-  *)       _events_tmpl="\$HOME/.kijito-monitor/<persona>.jsonl" ;;
+case "$_sup:$_events" in
+  launchd:*)            _events_tmpl="\$HOME/.cache/kijito-inbox-monitor/events.<persona>.ndjson" ;;
+  *:*/.local/state/*)   _events_tmpl="\$HOME/.local/state/kijito-inbox-monitor/events.<persona>.ndjson" ;;
+  *)                    _events_tmpl="\$HOME/.kijito-monitor/<persona>.jsonl" ;;
 esac
 
 # Producer health, PER PERSONA — because "a producer is running" and "YOUR mail is being collected"

package/providers/codex/release-manifest.json

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

package/providers/monitor/CHANGELOG.md

@@ -3,6 +3,63 @@
 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.4] - 2026-09-24
+
+### Fixed
+- **The systemd unit no longer decides file names.** `kijito-inbox-monitor@.service.template` spelled
+  systemd's `%i` into `--state-file`, `--events-file` and `--token-file`. `%i` is the ESCAPED instance
+  name, so for any persona that is not already lowercase ASCII (`Loom`, `name (purpose)`, `Ωmega`) the unit
+  named its files differently from the producer and from the launchd plist, and passed the escaped
+  string as the persona itself. The unit now passes `--persona %I` (unescaped) and the producer fills in
+  every path from `{persona}` with the same rule `--safe-persona` prints. For names that are already
+  lowercase ASCII the paths are byte-identical to before, so upgrading moves nothing.
+
+### Added
+- `--state-file-template` and `--token-file-template`, the `{persona}` counterparts of `--state-file` and
+  `--token-file`.
+- `scripts/migrate-systemd-unit.sh` migrates a deployed unit: dry run by default, `--apply` to act,
+  idempotent, keeps the old unit file, refuses to rewrite until the installed producer supports the new
+  flags, and for an instance whose files do move keeps the old event path working (hard link) so a
+  running `tail -F` consumer is not cut off.
+
+## [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,33 @@ 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>`.
+
+## Re-import 2026-09-24 (row M313) — v0.5.4
+
+| role | SHA | tree |
+|---|---|---|
+| imported (tag `v0.5.4`) | see `providers/monitor/UPSTREAM` (`scripts/import-monitor.sh v0.5.4`) | idem |
+
+v0.5.4: the shipped systemd unit passes `--persona %I` and the producer names every file
+(`--state-file-template`, `--token-file-template`, `--events-file-template`), plus
+`scripts/migrate-systemd-unit.sh` for deployed units.

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/README.md

@@ -545,6 +545,9 @@ four sat above it. Only the newest page's count answers the question "is there u
 | `--events-file PATH` | Write NDJSON events to an owned, size-rotated file (survives rotation) instead of stdout. Consumers `tail -F` it. |
 | `--events-file-template PATH` | Per-persona owned, rotated files, e.g. `events.{persona}.ndjson`; each session consumes its own. Must contain `{persona}`. Mutually exclusive with `--events-file`. |
 | `--state-file PATH` | Persist and resume cursor/liveness; single-writer locked. Persona targets derive one file per persona. Recommended under a supervisor. |
+| `--state-file-template PATH` | Like `--state-file`, with `{persona}` filled in by the producer (the component `--safe-persona` prints). Use it in a supervisor unit so the unit never spells a persona into a path. |
+| `--token-file-template PATH` | Like `--token-file`, with `{persona}` filled in by the producer for the one `--persona` target. |
+| `--safe-persona NAME` | Print the filename component the producer uses for NAME, then exit. Anything that needs to name a persona's files should ask this rather than re-implement the rule. |
 | `--wait N` | Long-poll hold (s) requested from the server so new mail wakes the watcher near-instantly at ~the same request rate (default 50; `0` disables). Falls back to interval polling against a server that doesn't support it, and auto-upgrades when it does. |
 | `--poll-seconds N` | Interval between polls when long-poll is off/unsupported (default 60). |
 | `--alert-after N` | Consecutive failures before an `alert` (default 3, min 1). A single transient failure is normal. |

package/providers/monitor/UPSTREAM

@@ -0,0 +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=1bdc0ced989bf9c10d4a62fa4140b1cf97b7fa2e
+tree=732bef3a3b72279fb4d1111314a6eb7ecb266097
+tag=v0.5.4
+file=100644 8d88ccb0fd09b9144505f985b4f882db278fac1f .github/workflows/publish-npm.yml
+file=100644 19ce3471a2cffa689be9d261049c1e74e3e7a25e .github/workflows/publish-pypi.yml
+file=100644 4534290a5dd36d18d07a782b784b6b0ad5ee38fc .gitignore
+file=100644 6191d5c9b75c3d5198168a6422c854cd56e0426e CHANGELOG.md
+file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
+file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
+file=100644 86f816d7ac9ef4a5a7242376d642f59be8554e2b 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 4f5e53a8633e60e6c57c451e28546f8af8783fe8 kijito-inbox-monitor@.service.template
+file=100644 8ad5159d6659a05c33756abc901f7cf4dcd5c9c7 kijito_inbox_monitor.py
+file=100644 4f1d402533247b1453d3b670c9dc746d3941a576 package.json
+file=100644 bc6f7c99e94c83fc89c5ceb1b1c2bfebf203e015 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 f7272d96cd1b3b0235aa79debbb6568a67063d6e test_kijito_monitor.py

package/providers/monitor/kijito-inbox-monitor@.service.template

@@ -10,12 +10,15 @@
 #                ~/.config/systemd/user/kijito-inbox-monitor@.service
 #             systemctl --user daemon-reload
 #   run:      systemctl --user enable --now kijito-inbox-monitor@YOURPERSONA
+#             (a persona with spaces, parentheses or non-ASCII: escape it for systemd -
+#              systemctl --user enable --now "kijito-inbox-monitor@$(systemd-escape 'Name (dev)').service")
 #   check:    systemctl --user status kijito-inbox-monitor@YOURPERSONA
 #   logs:     journalctl --user -u kijito-inbox-monitor@YOURPERSONA -f
 #
-# BEFORE IT WILL START, create the token file for that persona (0600):
-#   install -m600 /dev/null ~/.config/kijito-inbox-monitor/token.YOURPERSONA
-#   printf '%s' "$YOUR_KIJITO_API_TOKEN" > ~/.config/kijito-inbox-monitor/token.YOURPERSONA
+# BEFORE IT WILL START, create the token file for that persona (0600). Its name uses the
+# producer's filename component for the persona, which you get from the producer itself:
+#   f=~/.config/kijito-inbox-monitor/token.$(kijito-inbox-monitor --safe-persona YOURPERSONA)
+#   install -m600 /dev/null "$f"; printf '%s' "$YOUR_KIJITO_API_TOKEN" > "$f"
 # A missing token is FATAL and says so - the producer will not start half-configured.
 #
 # ⚠️ THIS CAPTURES; IT DOES NOT WAKE. The unit appends one JSON event per new message
@@ -41,7 +44,7 @@
 # different claims, and so are an ENABLED unit and a unit that survives your logout.
 
 [Unit]
-Description=Kijito inbox monitor (persona: %i)
+Description=Kijito inbox monitor (persona: %I)
 Documentation=https://github.com/KijitoAI/kijito-inbox-monitor
 # Start after the network is genuinely up, not merely configured: the producer's first
 # act is an HTTPS poll, and a DNS failure at boot is an avoidable alert.
@@ -60,13 +63,19 @@ Type=simple
 # that skip is at least ANNOUNCED as a `baseline_skipped` diagnostic instead of
 # happening in silence - but announced-and-skipped is still skipped.)
 # ⇒ state lives under ~/.local/state (XDG_STATE_HOME: persists between restarts).
+# ⛔ THE UNIT NEVER SPELLS A PERSONA INTO A PATH (row M313). It passes the persona (%I, the
+# UNESCAPED instance name - %i is systemd's escaped form, so 'Name (dev)' would arrive as
+# 'Name\x20\x28dev\x29' and watch a persona that does not exist), and every file name is
+# filled in by the producer from `{persona}` using the SAME rule `--safe-persona` prints and
+# the launchd plist uses. For a name that is already a safe component (lowercase ASCII),
+# the paths are byte-identical to the older %i form, so upgrading moves nothing.
 ExecStart=%h/.local/bin/kijito-inbox-monitor \
-  --persona %i \
-  --token-file %h/.config/kijito-inbox-monitor/token.%i \
+  --persona %I \
+  --token-file-template %h/.config/kijito-inbox-monitor/token.{persona} \
   --poll-seconds 30 \
   --wait 60 \
-  --state-file %h/.local/state/kijito-inbox-monitor/%i.state \
-  --events-file %h/.local/state/kijito-inbox-monitor/events.%i.ndjson \
+  --state-file-template %h/.local/state/kijito-inbox-monitor/{persona}.state \
+  --events-file-template %h/.local/state/kijito-inbox-monitor/events.{persona}.ndjson \
   --no-content \
   --heartbeat 900
 

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.4"
 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
@@ -1813,6 +1841,17 @@ def make_opener_for(url):
     return build_opener(pinned)
 
 
+def _persona_path(template, persona):
+    """Fill a `{persona}` path template with the producer's OWN filename component for PERSONA (row M313).
+
+    Every per-persona path a supervisor needs - events, state, token - goes through here, so the unit file
+    (systemd `%i`, a plist, a shell script) never spells a filename itself. `%i` is systemd's ESCAPED
+    instance name and passes a persona's raw case through, so a unit that interpolated it disagreed with
+    the producer for any name that is not already a safe component ('Loom', 'name (purpose)', 'Ωmega').
+    """
+    return template.replace("{persona}", _state_safe_persona(persona))
+
+
 def _state_path_for_persona(base_path, persona):
     if not base_path or not persona:
         return base_path
@@ -1963,7 +2002,8 @@ class WatchTarget:
         cp = urllib.parse.urlsplit(url)
         self.unread_persona = dict(urllib.parse.parse_qsl(cp.query)).get("persona") or persona
 
-        state_path = _state_path_for_persona(args.state_file, persona)
+        state_path = (_persona_path(args.state_file_template, persona) if args.state_file_template
+                      else _state_path_for_persona(args.state_file, persona))
         if state_path:
             self.state_file = StateFile(state_path, self.identity)
             if not args.self_test:
@@ -2341,7 +2381,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 +3090,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 +3159,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 +3310,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 +3340,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))
@@ -3548,6 +3618,11 @@ def build_parser():
     p.add_argument("--state-file",
                    help="Persist+resume cursor/FSM; single-writer locked. Kijito persona targets derive one "
                         "file per persona from this base path. Recommended w/ a supervisor.")
+    p.add_argument("--state-file-template",
+                   help="Per-persona state file named by the PRODUCER, e.g. ~/.local/state/kijito-inbox-monitor/"
+                        "{persona}.state; '{persona}' is replaced by the same filename component --safe-persona "
+                        "prints. Use it in a supervisor unit instead of spelling the persona into --state-file "
+                        "(row M313). Mutually exclusive with --state-file.")
     p.add_argument("--heartbeat", type=int, help="Emit a heartbeat event every N seconds (external dead-man's-switch).")
     p.add_argument("--activity-file",
                    help="Publish who AUTHORED mail most recently, as JSON, refreshed each tick. Lets a "
@@ -3574,6 +3649,10 @@ def build_parser():
                         "(reported verbatim, so a reader can judge magnitude). Default 1.")
     p.add_argument("--auth-header", help="Header NAME for the token (default Authorization: Bearer).")
     p.add_argument("--token-file", help="File holding the auth token (wins over $KIJITOMON_TOKEN).")
+    p.add_argument("--token-file-template",
+                   help="Like --token-file, with '{persona}' replaced by the producer's filename component for the "
+                        "ONE --persona target (row M313), e.g. ~/.config/kijito-inbox-monitor/token.{persona}. "
+                        "Mutually exclusive with --token-file.")
     p.add_argument("--no-fast-path", action="store_true",
                    help="Disable the /api/notify/pending unread pre-check; always full-poll the inbox list.")
     p.add_argument("--resync-every", type=int, default=10,
@@ -3615,6 +3694,19 @@ def validate_args(args):
         raise FatalConfig("--events-file-template must contain the '{persona}' placeholder")
     if (args.events_file or args.events_file_template) and args.emit != "stdout-jsonl":
         sys.stderr.write("kijito-inbox-monitor: WARNING --events-file/-template ignored (emit mode is %s)\n" % args.emit)
+    # Row M313: the persona-named paths come from the producer's rule, never from the supervisor.
+    if args.state_file and args.state_file_template:
+        raise FatalConfig("--state-file and --state-file-template are mutually exclusive")
+    if args.state_file_template and "{persona}" not in args.state_file_template:
+        raise FatalConfig("--state-file-template must contain the '{persona}' placeholder")
+    if args.token_file and args.token_file_template:
+        raise FatalConfig("--token-file and --token-file-template are mutually exclusive")
+    if args.token_file_template:
+        if "{persona}" not in args.token_file_template:
+            raise FatalConfig("--token-file-template must contain the '{persona}' placeholder")
+        if len(args.persona or []) != 1 or args.personas or args.all_personas:
+            raise FatalConfig("--token-file-template needs exactly one --persona target (one token file per unit)")
+        args.token_file = _persona_path(args.token_file_template, args.persona[0])
     if args.seed_at is not None:
         single = len(args.persona or []) == 1 and not args.personas and not args.all_personas
         if not single:

package/providers/monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-inbox-monitor",
-  "version": "0.5.0",
+  "version": "0.5.4",
   "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.4"
 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/scripts/migrate-systemd-unit.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Migrate a DEPLOYED kijito-inbox-monitor systemd user unit to producer-derived file names (row M313).
+#
+#   scripts/migrate-systemd-unit.sh            # DRY RUN: says what it would change, changes nothing
+#   scripts/migrate-systemd-unit.sh --apply    # do it
+#   options: --unit NAME (default kijito-inbox-monitor)   --bin PATH (default ~/.local/bin/kijito-inbox-monitor)
+#            --unit-dir DIR (default ~/.config/systemd/user)
+#
+# WHAT CHANGES. Older units spelled the persona into paths with systemd's `%i` - the ESCAPED instance name -
+# so the unit, not the producer, decided file names, and a persona like 'Loom' or 'name (purpose)' got a
+# different file than the producer (and the launchd plist) would give it. The rewritten unit passes
+# `--persona %I` and turns every `--state-file/--events-file/--token-file ...%i...` into the matching
+# `-template ...{persona}...` flag, so the producer names every file with the rule `--safe-persona` prints.
+#
+# WHAT MOVES. For a persona that is already a safe component (lowercase ASCII - every persona on a normal
+# fleet) the new paths are BYTE-IDENTICAL to the old ones: nothing moves and no consumer has to re-arm.
+# Only an instance whose old and new paths differ is touched, and then (instance stopped first):
+#   state   copied to the new name (the old file is kept)          - the cursor survives
+#   token   copied to the new name, mode kept (the old file is kept)
+#   events  HARD-LINKED under the new name - the old name is never removed, so a consumer running
+#           `tail -F <old path>` notices nothing and keeps receiving every event the producer now appends
+#           under the new name (same file). It stays that way until the producer next ROTATES the stream
+#           (default 5 MB), after which only the new name moves on: re-arm consumers on the new path.
+#           (Measured, GNU tail 9.4: a SYMLINK at the old path is refused as "untailable", and a rename
+#           followed by a relink makes tail re-read the whole file - a replay of every old event.)
+#
+# SAFE TO RE-RUN. A unit with no `%i` left in ExecStart is reported as already migrated; files are only
+# copied/moved when the new one does not exist yet. The old unit file is kept as <unit>.pre-m313.<time>.
+# REFUSES to rewrite the unit while the installed producer lacks --state-file-template (it would not start).
+# ANNOUNCE TO YOUR FLEET BEFORE --apply on a shared seat: instances restart, for a few seconds each.
+set -eu
+UNIT=kijito-inbox-monitor
+BIN="$HOME/.local/bin/kijito-inbox-monitor"
+UNIT_DIR="$HOME/.config/systemd/user"
+APPLY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --apply) APPLY=1; shift ;;
+    --unit) UNIT=$2; shift 2 ;;
+    --bin) BIN=$2; shift 2 ;;
+    --unit-dir) UNIT_DIR=$2; shift 2 ;;
+    -h|--help) sed -n '2,30p' "$0"; exit 0 ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+FILE="$UNIT_DIR/$UNIT@.service"
+[ -f "$FILE" ] || { echo "no unit file at $FILE - nothing to migrate"; exit 0; }
+say() { printf '%s\n' "$*"; }
+[ "$APPLY" = 1 ] && say "== APPLY: $FILE ==" || say "== DRY RUN (pass --apply to act): $FILE =="
+
+# The rewrite, as a pure text transform of the unit file (also used to compute the new paths).
+rewrite() {
+  sed -E \
+    -e '/^ExecStart=/,/[^\\]$/ s/--persona %i/--persona %I/' \
+    -e '/^ExecStart=/,/[^\\]$/ s/--(state-file|events-file|token-file)([ =])([^ ]*)%i([^ ]*)/--\1-template\2\3{persona}\4/g' \
+    -e 's/^(Description=.*)%i/\1%I/' "$1"
+}
+exec_line() { tr -d '\r' < "$1" | sed -e ':a' -e '/\\$/N; s/\\\n//; ta' | grep '^ExecStart='; }
+flag_value() { printf '%s\n' "$1" | tr ' ' '\n' | awk -v f="$2" 'p{print; exit} $0==f{p=1}'; }
+
+old_exec=$(exec_line "$FILE")
+case "$old_exec" in
+  *%i*) ;;
+  *) say "already migrated: ExecStart spells no %i (the producer names every file)"; exit 0 ;;
+esac
+tmp_unit=$(mktemp); trap 'rm -f "$tmp_unit"' EXIT
+rewrite "$FILE" > "$tmp_unit"
+new_exec=$(exec_line "$tmp_unit")
+case "$new_exec" in *%i*) say "REFUSING: could not rewrite every %i in ExecStart:"; say "  $new_exec"; exit 1 ;; esac
+say "ExecStart now:  ${old_exec#ExecStart=}"
+say "ExecStart after: ${new_exec#ExecStart=}"
+
+have_flags=0
+"$BIN" --help 2>/dev/null | grep -q -- '--state-file-template' && have_flags=1
+if [ "$have_flags" = 0 ]; then
+  say "REFUSING to rewrite: $BIN does not support --state-file-template (needs kijito-inbox-monitor >= 0.5.4)."
+  say "Upgrade the producer first, then re-run. (For persona names that are already lowercase ASCII the"
+  say "old unit is correct as it is: this migration changes no file for them.)"
+  [ "$APPLY" = 1 ] && exit 1
+fi
+
+H=$HOME
+changed=(); to_start=()
+# Every instance: loaded ones, plus enabled ones that are not loaded right now (a stopped template
+# instance drops out of list-units, and its files must migrate too).
+instances=$( { systemctl --user list-units --all --plain --no-legend "$UNIT@*.service" 2>/dev/null | awk '{print $1}'
+               for w in "$UNIT_DIR"/*.wants/"$UNIT"@*.service; do [ -e "$w" ] || [ -L "$w" ] && basename "$w"; done
+             } | sort -u)
+while IFS= read -r inst; do
+  [ -n "$inst" ] || continue
+  esc=${inst#"$UNIT@"}; esc=${esc%.service}
+  raw=$(systemd-escape --unescape -- "$esc")
+  if [ "$have_flags" = 1 ]; then
+    safe=$("$BIN" --safe-persona "$raw")
+  else
+    # Without an upgraded producer there is no --safe-persona to ask, and this script must not guess the
+    # rule (row M290). A name that is already lowercase [a-z0-9._-] is its own component; say so for it,
+    # and say plainly that anything else cannot be judged yet.
+    case "$raw" in
+      *[!a-z0-9._-]*) say "  $raw: cannot tell yet which files would move - needs the upgraded producer's --safe-persona"; continue ;;
+    esac
+    safe=$raw
+  fi
+  moves=""
+  for f in --state-file --events-file --token-file; do
+    o=$(flag_value "${old_exec#ExecStart=}" "$f"); [ -n "$o" ] || continue
+    case "$o" in *%i*) ;; *) continue ;; esac
+    # Parameter expansion, NOT sed: an escaped instance name carries backslashes ('name\x20\x28dev\x29')
+    # and GNU sed would decode them in a replacement - the old path would then name a file that never
+    # existed. (Caught by this script's own test against real systemd.)
+    op=${o//%h/$H}; op=${op//%i/$esc}
+    np=${o//%h/$H}; np=${np//%i/$safe}
+    [ "$op" = "$np" ] || moves="$moves$f|$op|$np"$'\n'
+  done
+  if [ -z "$moves" ]; then
+    say "  $raw: paths unchanged (already a safe component) - nothing moves, consumers need not re-arm"
+    continue
+  fi
+  changed+=("$inst")
+  while IFS='|' read -r f op np; do
+    [ -n "$f" ] && say "  $raw: ${f#--} $op -> $np"
+  done <<EOF
+$moves
+EOF
+  [ "$APPLY" = 1 ] && [ "$have_flags" = 1 ] || continue
+  was_active=0; systemctl --user is-active --quiet "$inst" && was_active=1
+  systemctl --user stop "$inst"
+  while IFS='|' read -r f op np; do
+    [ -n "$f" ] && [ -e "$op" ] || continue
+    [ -e "$np" ] && { say "    ${f#--}: $np already exists - left as is"; continue; }
+    mkdir -p "$(dirname "$np")"
+    case "$f" in
+      --events-file) ln "$op" "$np" && say "    events: $np hard-linked to the live stream; $op still works until the next rotation" ;;
+      *) cp -p "$op" "$np" && say "    ${f#--} copied (old file kept)" ;;
+    esac
+  done <<EOF
+$moves
+EOF
+  [ "$was_active" = 1 ] && to_start+=("$inst")
+done <<EOF
+$instances
+EOF
+
+[ "$APPLY" = 1 ] || { say "(dry run: nothing changed)"; exit 0; }
+cp -p "$FILE" "$FILE.pre-m313.$(date +%Y%m%dT%H%M%S)"
+cp "$tmp_unit" "$FILE"
+systemctl --user daemon-reload
+# The instances this script stopped are started again BY NAME (they are no longer listed once stopped);
+# every other running instance is restarted so it picks up the rewritten ExecStart (same paths).
+for inst in "${to_start[@]+"${to_start[@]}"}"; do systemctl --user start "$inst"; done
+while IFS= read -r inst; do
+  [ -n "$inst" ] || continue
+  case " ${to_start[*]+"${to_start[*]}"} " in *" $inst "*) continue ;; esac
+  systemctl --user is-active --quiet "$inst" && systemctl --user restart "$inst"
+done <<EOF
+$instances
+EOF
+say "migrated: unit rewritten (old copy kept next to it); ${#changed[@]} instance(s) had files moved"

package/providers/monitor/test_kijito_monitor.py

@@ -1,6 +1,7 @@
 import io
 import json
 import os
+import re
 import subprocess
 import sys
 import tempfile
@@ -757,7 +758,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 +924,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
@@ -1663,6 +1716,7 @@ class BoundedWindowEndToEndTest(unittest.TestCase):
     class FullArgs:
         persona = personas = None
         all_personas = False
+        state_file_template = None
         alert_after = 3
         poll_seconds = 60
         heartbeat = 0
@@ -2289,9 +2343,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 +2356,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 +2472,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 +4513,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 +5691,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):
@@ -5607,3 +5852,146 @@ class OpaqueOutputEnforcementTest(unittest.TestCase):
     def test_systemd_template_enforces_no_content(self):
         with open(os.path.join(self._HERE, "kijito-inbox-monitor@.service.template"), encoding="utf-8") as fh:
             self.assertIn("--no-content", fh.read())
+
+
+class SupervisorPersonaPathParityTest(unittest.TestCase):
+    """Row M313. The systemd unit used to interpolate `%i` - systemd's ESCAPED instance name - into
+    --state-file / --events-file / --token-file, so the UNIT decided the file names and disagreed with the
+    producer (and with the launchd plist) for any persona that is not already a safe component. Now the
+    unit passes the persona (%I, unescaped) and the producer fills every `{persona}` path from its own
+    rule. These tests expand BOTH shipped templates the way their supervisors do and require every
+    persona-named file to carry exactly the component `--safe-persona` prints."""
+
+    NAMES = ["argus", "Loom", "name (purpose)", "\u03a9mega", "two words", "Claude-chat"]
+    HOME = "/HOMEDIR"
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+
+    def _systemd_argv_home(self, persona, home):
+        saved, self.HOME = self.HOME, home
+        try:
+            return self._systemd_argv(persona)
+        finally:
+            self.HOME = saved
+
+    def _systemd_argv(self, persona):
+        with open(os.path.join(self._HERE, "kijito-inbox-monitor@.service.template"), encoding="utf-8") as fh:
+            text = fh.read().replace("\\\n", " ")
+        line = next(l for l in text.splitlines() if l.startswith("ExecStart="))
+        self.assertNotIn("%i", line, "the unit must not spell the escaped instance name into ExecStart")
+        # systemd's own expansion: %h = home, %I = the UNESCAPED instance name (measured on systemd 255:
+        # an instance escaped by systemd-escape expands %i to 'Name\\x20...' and %I to 'Name ...').
+        # It is ONE argv word even with spaces in it - systemd splits the line before substituting.
+        words = line[len("ExecStart="):].split()
+        return [w.replace("%h", self.HOME).replace("%I", persona) for w in words][1:]
+
+    def _launchd_events_template(self):
+        with open(os.path.join(self._HERE, "com.kijito.inbox-monitor.plist.template"), encoding="utf-8") as fh:
+            strings = re.findall(r"<string>([^<]*)</string>", fh.read())
+        return strings[strings.index("--events-file-template") + 1].replace("__HOME__", self.HOME)
+
+    def test_every_persona_named_file_uses_the_producers_component_on_both_supervisors(self):
+        for name in self.NAMES:
+            with self.subTest(persona=name):
+                safe = km._state_safe_persona(name)
+                args = km.build_parser().parse_args(self._systemd_argv(name))
+                km.validate_args(args)
+                self.assertEqual(args.persona, [name], "the unit must hand the producer the REAL persona")
+                events = km._persona_path(args.events_file_template, name)
+                state = km._persona_path(args.state_file_template, name)
+                self.assertEqual(os.path.basename(events), "events.%s.ndjson" % safe)
+                self.assertEqual(os.path.basename(state), "%s.state" % safe)
+                self.assertEqual(os.path.basename(args.token_file), "token.%s" % safe)
+                launchd = km._persona_path(self._launchd_events_template(), name)
+                self.assertEqual(os.path.basename(events), os.path.basename(launchd),
+                                 "launchd and systemd must name a persona's event stream identically")
+
+    def test_upgrading_a_safe_named_unit_moves_nothing(self):
+        # Every persona on a real fleet today is lowercase ASCII; for those the new unit resolves to the
+        # SAME paths the %i form did, so an upgrade needs no migration and no consumer re-arm.
+        args = km.build_parser().parse_args(self._systemd_argv("argus"))
+        km.validate_args(args)
+        base = self.HOME + "/.local/state/kijito-inbox-monitor/"
+        self.assertEqual(km._persona_path(args.events_file_template, "argus"), base + "events.argus.ndjson")
+        self.assertEqual(km._persona_path(args.state_file_template, "argus"), base + "argus.state")
+        self.assertEqual(args.token_file, self.HOME + "/.config/kijito-inbox-monitor/token.argus")
+
+    def test_the_state_file_template_reaches_the_watch_target(self):
+        d = tempfile.mkdtemp()
+
+        class A(BoundedWindowEndToEndTest.FullArgs):
+            state_file = None
+            state_file_template = os.path.join(d, "{persona}.state")
+            seed_at = None
+        t = km.WatchTarget("Loom", "http://x/api/inbox?persona=Loom", None, {}, A(),
+                           BoundedWindowEndToEndTest.RecordingEmitter())
+        self.addCleanup(t.state_file.unlock)
+        self.assertEqual(t.state_file.path, os.path.join(d, "loom.state"))
+
+    def test_template_flags_are_validated(self):
+        def err(argv):
+            try:
+                km.validate_args(km.build_parser().parse_args(argv))
+            except km.FatalConfig as e:
+                return str(e)
+            return None
+        self.assertIn("mutually exclusive", err(["--persona", "a", "--state-file", "x", "--state-file-template", "{persona}"]))
+        self.assertIn("placeholder", err(["--persona", "a", "--state-file-template", "x.state"]))
+        self.assertIn("mutually exclusive", err(["--persona", "a", "--token-file", "x", "--token-file-template", "t.{persona}"]))
+        self.assertIn("placeholder", err(["--persona", "a", "--token-file-template", "tok"]))
+        self.assertIn("exactly one --persona", err(["--persona", "a", "--persona", "b", "--token-file-template", "t.{persona}"]))
+        self.assertIsNone(err(["--persona", "A b", "--token-file-template", "/t.{persona}"]))
+
+
+class SystemdUnitMigrationRewriteTest(unittest.TestCase):
+    """Row M313: scripts/migrate-systemd-unit.sh rewrites a DEPLOYED pre-M313 unit into the producer-named
+    form. Its end-to-end behaviour (files moved, stopped instances restarted, an old-path `tail -F` kept
+    alive) was proven against real systemd when it was written; this pins the REWRITE, which is the part
+    that must stay right on every machine, by running the script's dry run on the pre-M313 unit text."""
+
+    OLD = ("[Unit]\nDescription=Kijito inbox monitor (persona: %i)\n[Service]\n"
+           "ExecStart=%h/.local/bin/kijito-inbox-monitor \\\n  --persona %i \\\n"
+           "  --token-file %h/.config/kijito-inbox-monitor/token.%i \\\n  --poll-seconds 30 \\\n"
+           "  --state-file %h/.local/state/kijito-inbox-monitor/%i.state \\\n"
+           "  --events-file %h/.local/state/kijito-inbox-monitor/events.%i.ndjson \\\n  --heartbeat 900\n")
+
+    def _run(self, unit_text):
+        d = tempfile.mkdtemp()
+        with open(os.path.join(d, "kjt-m313-rewrite-test@.service"), "w") as fh:
+            fh.write(unit_text)
+        here = os.path.dirname(os.path.abspath(__file__))
+        return subprocess.run(["bash", os.path.join(here, "scripts", "migrate-systemd-unit.sh"),
+                               "--unit", "kjt-m313-rewrite-test", "--unit-dir", d, "--bin", "/nonexistent"],
+                              capture_output=True, text=True)
+
+    def test_every_percent_i_path_becomes_a_producer_template(self):
+        r = self._run(self.OLD)
+        after = next(l for l in r.stdout.splitlines() if l.startswith("ExecStart after:"))
+        self.assertNotIn("%i", after)
+        self.assertIn("--persona %I", after)
+        for flag, path in (("--token-file-template", "token.{persona}"),
+                           ("--state-file-template", "{persona}.state"),
+                           ("--events-file-template", "events.{persona}.ndjson")):
+            self.assertRegex(after, re.escape(flag) + r" \S*" + re.escape(path))
+        self.assertIn("--poll-seconds 30", after)          # everything else untouched
+        self.assertIn("REFUSING to rewrite", r.stdout)       # /nonexistent lacks the new flags
+        self.assertEqual(r.returncode, 0, "a dry run never fails")
+
+    def test_the_rewritten_unit_resolves_to_the_same_paths_the_shipped_template_does(self):
+        r = self._run(self.OLD)
+        after = next(l for l in r.stdout.splitlines() if l.startswith("ExecStart after:"))
+        argv = [w.replace("%h", "/h").replace("%I", "Loom") for w in after.split()[3:]]
+        args = km.build_parser().parse_args(argv)
+        km.validate_args(args)
+        shipped = km.build_parser().parse_args(SupervisorPersonaPathParityTest()._systemd_argv_home("Loom", "/h"))
+        km.validate_args(shipped)
+        self.assertEqual(args.token_file, shipped.token_file)
+        self.assertEqual(args.state_file_template, shipped.state_file_template)
+        self.assertEqual(args.events_file_template, shipped.events_file_template)
+
+    def test_an_already_migrated_unit_is_left_alone(self):
+        # The shipped template IS the migrated form, so running the script on it must be a no-op report.
+        here = os.path.dirname(os.path.abspath(__file__))
+        with open(os.path.join(here, "kijito-inbox-monitor@.service.template"), encoding="utf-8") as fh:
+            r = self._run(fh.read())
+        self.assertIn("already migrated", r.stdout)
+        self.assertNotIn("ExecStart after:", r.stdout)