kijito-tools 0.2.1 → 0.2.2

package/package.json

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

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": "e411fddb3bd37d4fcf364917572f3c9d132223aa9e1dc0d522efbcae0c8fa73e",
+    "workflowSha256": "ec6a65c095e7011c3100c2a804e23c1dee1a63cfba0fb79f1b872aee91dd3b2d",
     "planSha256": "d9d666b86ac06414f6e6a13a3e3e2115983a1dad44fcfded7eccc51b191fb451",
     "wakeHelperSha256": "838f6b4462ba037a23a14b6fdb8dc34ee8b8f4a7df258b428832bc092fac3ea4",
     "wsUdsSha256": "4da13eef89b572fb735e756cb06846a021919dec7f91c6d07989377944cc776c",

package/providers/monitor/CHANGELOG.md

@@ -3,6 +3,25 @@
 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

package/providers/monitor/IMPORT-PROVENANCE.md

@@ -86,3 +86,13 @@ From here on **never hand-edit `providers/monitor`**:
   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/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

@@ -1,25 +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=803c53da623fa2d9bd97f5a9e75f01a78571ea2e
-tree=0c8d80201933589363305f9e2753e7d717f348d8
-tag=v0.5.3
+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 5f0a605641efd19a9afa8d0cb0d8bed3f908e232 CHANGELOG.md
+file=100644 6191d5c9b75c3d5198168a6422c854cd56e0426e CHANGELOG.md
 file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
 file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
-file=100644 48038bef573e123fe4657be8a5fdb3e0293b192a README.md
+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 e6d72708b425b6dfaf02e126aaac7633d3584847 kijito-inbox-monitor@.service.template
-file=100644 9a1114ef2ab83cbe3b30bfa50833f3e280e2d91d kijito_inbox_monitor.py
-file=100644 a20200e3aeef01e7a19ce8833f1eea743b53949c package.json
-file=100644 1af00c40f8351d0a12b8563e7c7e865c6be0299d pyproject.toml
+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 d54d220ab8b228e557b64cc1497509c46c70a5ee test_kijito_monitor.py
+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.3"
+__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__
@@ -1841,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
@@ -1991,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:
@@ -3606,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 "
@@ -3632,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,
@@ -3673,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.3",
+  "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.3"
+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
@@ -1715,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
@@ -5850,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)