kijito-tools 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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/_shared/wake-core.mjs

@@ -52,12 +52,14 @@ function requirePersona(persona) {
 // silently — measured live 2026-08-15: a real corrupt-state producer emitted baseline_skipped
 // into an armed stream and the helper ignored it, the exact "a diagnostic added to kill a
 // silent failure is itself silent unless the consumer's filter learned its name" class the
-// monitor documents. This is now the certified NEW_LENIENT 8-kind set. `armed` and `heartbeat`
+// monitor documents. This is now the certified NEW_LENIENT 8-kind set plus `still_unread` (row
+// M229, monitor v0.5.5: the bounded reminder for mail announced once and still unread; a
+// diagnostics-only batch already carries the reconcile-inbox peek below). `armed` and `heartbeat`
 // stay EXCLUDED deliberately — liveness kinds must never wake (heartbeat fires every 900s, and
 // armed's exclusion is why "I was not woken" does not mean "nothing arrived").
 const MAIL_KINDS = Object.freeze(["new"]);
 const DIAGNOSTIC_KINDS = Object.freeze([
-  "alert", "recovered", "state_corrupt", "baseline_skipped", "seed_ahead", "replay_capped", "persona_added",
+  "alert", "recovered", "state_corrupt", "baseline_skipped", "seed_ahead", "replay_capped", "persona_added", "still_unread",
 ]);
 
 export function parseEventLine(line, persona) {

package/providers/claude/scripts/heartbeat-watchdog.sh

@@ -74,7 +74,7 @@ _pane_hash() { tmux capture-pane -p -t "$1" 2>/dev/null | tail -40 | cksum | awk
 # SURFACED AS: an `HEARTBEAT_UNCONSUMED_STREAM` lifecycle-log line, a flag file the status line shows
 # (`unconsumed.<pane>`), and a nudge prompt that says to re-arm the consumer FIRST. Cleared (with a
 # `HEARTBEAT_STREAM_CONSUMED` line) the moment a consumer is attached again.
-WAKE_EVENTS='"event": ?"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added)"'
+WAKE_EVENTS='"event": ?"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added|still_unread)"'
 UNCONSUMED_FLAG="$KIJITO_LC_DIR/unconsumed.$PANE"
 st_missing_since=""; st_offset=""; st_alerted=0; st_path=""
 

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"
@@ -289,7 +297,7 @@ task list:
     all but one.
   • You have NO inbox Monitor (brand-new session; the tail is a sibling's or a leaked orphan that will
     NOT wake YOU) → arm exactly one for yourself:
-      Monitor(command="tail -n 0 -F $_events | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added)\"'", persistent=true)
+      Monitor(command="tail -n 0 -F $_events | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added|still_unread)\"'", persistent=true)
 Dedupe with TaskStop (agent-scoped), NOT \`pkill -f …events…\` (that can kill a sibling's or your own live consumer). $_prod
 EOF
 elif [ -n "$_safe" ]; then
@@ -300,7 +308,7 @@ background \`tail\` is CAPTURE-ONLY (it writes to a file and never re-invokes yo
 woken). Arm the wake-capable consumer with the Monitor TOOL (persistent) — it streams each event
 as a live notification. Your persona for this project is "$_persona":
 
-  Monitor(command="tail -n 0 -F $_events | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added)\"'", persistent=true)
+  Monitor(command="tail -n 0 -F $_events | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added|still_unread)\"'", persistent=true)
 
 First confirm nothing is already monitoring that stream this session (avoid double-arming). $_prod
 EOF
@@ -312,7 +320,7 @@ background \`tail\` is CAPTURE-ONLY (it writes to a file and never re-invokes yo
 woken). Arm the wake-capable consumer for YOUR persona with the Monitor TOOL (persistent) — it
 streams each event as a live notification. Substitute your persona name for <persona>:
 
-  Monitor(command="tail -n 0 -F $_events_tmpl | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added)\"'", persistent=true)
+  Monitor(command="tail -n 0 -F $_events_tmpl | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added|still_unread)\"'", persistent=true)
 
 (No .kijito_persona marker found in this project — add a one-line \`.kijito_persona\` file with your
 persona name in the project root so this resolves automatically next session.) $_prod

package/providers/claude/skills/kijito-start/SKILL.md

@@ -57,7 +57,7 @@ Run `kijito_startup(persona="<P>", project="<J>")` with the persona/project your
        "you already hit the trap" — and the remedy it prescribed would have killed a **working**
        inbox. Anchoring on `^tail` excludes the shell and returns exactly one line per monitor.
        - **prints nothing →** arm exactly ONE, wake-capable, via the Monitor tool (persistent):
-         `Monitor(command="tail -n 0 -F $STREAM | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added)\"'", persistent=true)`
+         `Monitor(command="tail -n 0 -F $STREAM | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added|still_unread)\"'", persistent=true)`
        - **prints one line →** already armed by a prior (pre-`/clear`) session; **STOP — do not start another.**
        - **prints two or more lines →** genuinely stacked; keep the newest, kill the rest:
          ```bash

package/providers/codex/release-manifest.json

@@ -13,12 +13,12 @@
     "verify": "node providers/codex/install.mjs   (default action; also runs before any skills deploy)"
   },
   "artifacts": {
-    "wakeCoreSha256": "5f7b57f71fd7ae96b303195c3671af0d410668b95f6a397c97cbec275992e412",
-    "workflowSha256": "e411fddb3bd37d4fcf364917572f3c9d132223aa9e1dc0d522efbcae0c8fa73e",
+    "wakeCoreSha256": "f6ca4f88841b371409dfb4946e3b427e83150bd511f38068b364de1090c5cd35",
+    "workflowSha256": "ec6a65c095e7011c3100c2a804e23c1dee1a63cfba0fb79f1b872aee91dd3b2d",
     "planSha256": "d9d666b86ac06414f6e6a13a3e3e2115983a1dad44fcfded7eccc51b191fb451",
     "wakeHelperSha256": "838f6b4462ba037a23a14b6fdb8dc34ee8b8f4a7df258b428832bc092fac3ea4",
     "wsUdsSha256": "4da13eef89b572fb735e756cb06846a021919dec7f91c6d07989377944cc776c",
-    "wakeHelperTestsSha256": "f74c7aae6231132b47bf14b56cebee4a336ba13d094e75ecb2a928aaeecd99a0",
+    "wakeHelperTestsSha256": "c5b6ec88eef8d84195e6c7eaa71cfb78dd6e2f743622caaa2b97a6d087718dd1",
     "wakeHelperIntegrationTestsSha256": "48f565dfe7e5b719903cd24b12ddfb3f17e1a16c532af397bfffcb39e4bfbe9b",
     "wakeHelperMockDaemonSha256": "3406bcd46d913071c0ee293e30f46b42ad5cf8c5c77f70c4000d9bb37854dd0c"
   },

package/providers/codex/skills/kijito-start/SKILL.md

@@ -111,7 +111,7 @@ session please") works with no flags and outranks this default.
        ```
        If nothing prints, arm exactly ONE persistent Monitor:
        ```
-       Monitor(command="tail -n 0 -F $STREAM | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added)\"'", persistent=true)
+       Monitor(command="tail -n 0 -F $STREAM | grep --line-buffered -E '\"event\": ?\"(new|alert|recovered|state_corrupt|baseline_skipped|seed_ahead|replay_capped|persona_added|still_unread)\"'", persistent=true)
        ```
        Report **armed-live (Claude Code fallback)**. This is not an ad-hoc
        watcher — it is the standard, battle-tested Claude Code wake path.

package/providers/codex/wake-helper/kijito-wake-helper.test.mjs

@@ -84,7 +84,7 @@ test("R2: the armed-record byte stamps equal the sha256 of the files actually lo
 // ── Gate-7 seam extension (argus 7819 conditions a/b): the NEW_LENIENT 8-kind set ──
 
 test("seam: every diagnostic kind wakes with a lifecycle key; armed/heartbeat provably never wake", () => {
-  const DIAG = ["alert", "recovered", "state_corrupt", "baseline_skipped", "seed_ahead", "replay_capped", "persona_added"];
+  const DIAG = ["alert", "recovered", "state_corrupt", "baseline_skipped", "seed_ahead", "replay_capped", "persona_added", "still_unread"];
   for (const kind of DIAG) {
     const parsed = parseEventLine(JSON.stringify({ source: "kijito-inbox", persona: "codex", event: kind, ts: "2026-08-15T08:04:46.059708+00:00" }), "codex");
     assert.equal(parsed.event?.trigger, "lifecycle", `${kind} must wake as lifecycle`);

package/providers/monitor/CHANGELOG.md

@@ -3,6 +3,38 @@
 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.5] - 2026-09-24
+
+### Added
+- **`still_unread`: a bounded reminder for mail that was announced and then left unread (row M229).**
+  The watcher announces each message once (`new`), so a message an agent looked at without marking it
+  read used to sit unread forever with nothing to bring it back. Now, when already-announced mail is still
+  unread `--still-unread-after` seconds after it was sent (default 7200; `0` turns it off), ONE
+  `still_unread` event per poll lists those messages. Each message is reminded at most once per window
+  and at most `--still-unread-max` times (default 3); retired, reserved and write_only inboxes are never
+  reminded; the first poll after a restart only takes note, so restarts do not produce a burst. It never
+  moves the cursor. Its `wake_class` is `diagnostic` (it wakes; `new` remains the only `mail`). Consumers
+  that filter by event name should add `still_unread` to their list.
+
+## [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

@@ -297,6 +297,7 @@ Each line of the events file (and each `exec-per-event` invocation) is one event
 | `new` | a new inbox message | `KIJITOMON_ID`, `KIJITOMON_FROM`, `KIJITOMON_CONTENT`, `KIJITOMON_CREATED`, `KIJITOMON_PERSONA` |
 | `alert` | the source has been unreachable for `--alert-after` polls (dead-man), **or** mail is stranded in an inbox nobody watches, **or** the server holds unread mail this window did not show (all below) | `KIJITOMON_REASON`, `KIJITOMON_FAILURES`, `KIJITOMON_STRANDED` |
 | `recovered` | the source came back after an `alert` | `KIJITOMON_CURSOR` |
+| `still_unread` | mail already announced as `new` is still **unread** `--still-unread-after` seconds (default 2 h) after it was sent. One event per poll names every such message; each message is reminded at most once per window and at most `--still-unread-max` (default 3) times; never for retired, reserved or write_only inboxes; nothing on the first poll after a restart. Read what you have handled with `mark_read=true` and it stops. | `KIJITOMON_IDS`, `KIJITOMON_OLDEST_AGE`, `KIJITOMON_REASON` |
 | `heartbeat` | optional liveness tick (`--heartbeat N`) | `KIJITOMON_CURSOR` |
 
 Every event also carries `KIJITOMON_EVENT`, `KIJITOMON_SOURCE`, `KIJITOMON_TS`, `KIJITOMON_EVENT_ID`,
@@ -545,6 +546,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=35b2fe6688b2f2f536a98952f40816c96057c69f
+tree=994bb014166bb65b57223a524bbb0673f57ce22d
+tag=v0.5.5
 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 9e7c054bccb95cbcb42ea8642eb1fab76e5863d5 CHANGELOG.md
 file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
 file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
-file=100644 48038bef573e123fe4657be8a5fdb3e0293b192a README.md
+file=100644 fa81d2fc2645a5503117825b714200e0ae642cc4 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 30519b1ad6098541083648392f344da68e688246 docs/DESIGN.md
+file=100644 4f5e53a8633e60e6c57c451e28546f8af8783fe8 kijito-inbox-monitor@.service.template
+file=100644 a88a59eb52d45918794b46d54de826617d977ff2 kijito_inbox_monitor.py
+file=100644 8c2d292152fbe752d5ebf3445141a9d7df5576e5 package.json
+file=100644 199474330b420fa514378ab0c1211e21db9c6c41 pyproject.toml
+file=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 8745e5bfe9573b9e85dd4e10f8904273d1dff864 test_kijito_monitor.py

package/providers/monitor/docs/DESIGN.md

@@ -293,6 +293,7 @@ One object per line; every event carries `event`, `source`, `ts` (emit-time UTC
 {"event":"armed",       "source":"kijito-inbox","ts":"<iso>","cursor":250}
 {"event":"alert",       "source":"kijito-inbox","ts":"<iso>","reason":"unreachable","consecutive_failures":3,"seconds":180}
 {"event":"recovered",   "source":"kijito-inbox","ts":"<iso>","cursor":250}
+{"event":"still_unread","source":"kijito-inbox","ts":"<iso>","ids":[240,246],"senders":["river"],"oldest_age_seconds":9000,"after_seconds":7200,"reason":"..."}   # M229 backstop, bounded
 {"event":"heartbeat",   "source":"kijito-inbox","ts":"<iso>","cursor":250}     # only if --heartbeat; cursor may be null
 {"event":"seed_ahead",  "source":"kijito-inbox","ts":"<iso>","seeded":600,"current_max":539}      # seed > reality (§7.0)
 {"event":"replay_capped","source":"kijito-inbox","ts":"<iso>","capped_to":539,"dropped":389}      # backlog > --max-replay (§7.0)

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.5"
 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__
@@ -952,6 +952,11 @@ _LIVENESS_KINDS = frozenset({"heartbeat", "armed"})
 # liveness is a diagnostic, INCLUDING kinds absent from this table (see _wake_class).
 _WAKE_CLASS_BY_KIND = {
     "new":              WAKE_CLASS_MAIL,
+    # Row M229: a reminder ABOUT mail (already-notified messages still unread past the threshold), not a
+    # message itself - one event names several ids and carries no body, so it is NOT `mail` (`new` stays
+    # the only mail, pinned by a test). As a diagnostic it WAKES, which is its whole job. Bounded by
+    # construction; see WatchTarget._resurface_still_unread.
+    "still_unread":     WAKE_CLASS_DIAGNOSTIC,
     "alert":            WAKE_CLASS_DIAGNOSTIC,
     "recovered":        WAKE_CLASS_DIAGNOSTIC,
     "state_corrupt":    WAKE_CLASS_DIAGNOSTIC,
@@ -1181,6 +1186,7 @@ class Emitter:
                 "capped_to": "KIJITOMON_CAPPED_TO", "dropped": "KIJITOMON_DROPPED",
                 "stranded_inboxes": "KIJITOMON_STRANDED",
                 "dormant_inboxes": "KIJITOMON_DORMANT",
+                "ids": "KIJITOMON_IDS", "oldest_age_seconds": "KIJITOMON_OLDEST_AGE",
             }
             for k, envname in keymap.items():
                 if k in event and event[k] is not None:
@@ -1841,6 +1847,31 @@ 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 _created_epoch(created):
+    """A message's `created` as epoch seconds, or None if it cannot be read. The server writes naive UTC
+    ('2026-09-24 21:34:24.943580'); an explicit offset or 'Z' is honoured when present."""
+    if not isinstance(created, str) or not created:
+        return None
+    try:
+        dt = datetime.datetime.fromisoformat(created.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=datetime.timezone.utc)
+    return dt.timestamp()
+
+
 def _state_path_for_persona(base_path, persona):
     if not base_path or not persona:
         return base_path
@@ -1991,7 +2022,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:
@@ -2142,6 +2174,69 @@ class WatchTarget:
                          "cursor below it so it is re-delivered rather than skipped (further reports "
                          "suppressed until delivery recovers)\n" % (mid, self.persona))
 
+    def _resurface_still_unread(self, items, now=None):
+        """Row M229 BACKSTOP: re-surface mail that was notified once and then left UNREAD.
+
+        The producer is edge-triggered per id - it emits `new` exactly once per message - so a message the
+        agent peeked at (mark_read=false), acted on or meant to, and never consumed sits unread and INERT:
+        never notified again, visible only to a staleness alarm. The ROOT fix is the consumer's (read
+        what you handled with mark_read=true, shipped as wake-workflow doctrine 2026-08-12); this is the
+        bounded backstop for what still slips through, and it is built so it cannot become a storm:
+          * only for ids AT OR BELOW the cursor (already notified) whose server `read` flag is False and
+            whose `created` is at least --still-unread-after seconds old;
+          * at most once per id per window (--still-unread-after), and at most --still-unread-max times per
+            id in this process - deliberately deferred mail is reminded a few times, not forever;
+          * ONE summarising `still_unread` event per poll however many ids are due (one wake, not N);
+          * never for debris (retired/reserved, row M332) or a write_only inbox;
+          * the FIRST full poll of a process only notes what is already aged and emits nothing, so every
+            restart (a deploy, a reboot) does not replay a burst of reminders.
+        The ledger is per process: a restart can remind again, at most --still-unread-max times per id.
+        It never touches the cursor - a reminder is not a delivery, and failing to emit one loses nothing.
+        """
+        after = getattr(self.args, "still_unread_after", 0) or 0
+        if after <= 0 or _is_debris(self.persona) or _PERSONA_WRITE_ONLY.get(self.persona) is True:
+            return []
+        cap = max(1, getattr(self.args, "still_unread_max", 3) or 1)
+        now = time.time() if now is None else now
+        ledger = self.__dict__.setdefault("still_unread_seen", {})     # id -> (times reminded, last at)
+        primed = self.__dict__.get("still_unread_primed", False)
+        cursor = self.cursor if isinstance(self.cursor, int) else -1
+        due, visible = [], set()
+        for m in items:
+            mid = m.get("id")
+            if not isinstance(mid, int) or isinstance(mid, bool) or mid > cursor or m.get("read") is not False:
+                continue
+            visible.add(mid)
+            born = _created_epoch(m.get("created"))
+            if born is None or now - born < after:
+                continue
+            n, last = ledger.get(mid, (0, None))
+            if not primed:
+                ledger[mid] = (n, now)          # restart: note it, remind one full window from now
+                continue
+            if n >= cap or (last is not None and now - last < after):
+                continue
+            due.append((mid, m, now - born, n))
+        for mid in list(ledger):                # read, or gone from the window: forget it
+            if mid not in visible:
+                del ledger[mid]
+        self.still_unread_primed = True
+        if not due:
+            return []
+        oldest = max(age for _, _, age, _ in due)
+        ok = self.emitter.lifecycle(
+            "still_unread", persona=self.persona,
+            ids=[mid for mid, _, _, _ in due],
+            senders=sorted({m.get("from") for _, m, _, _ in due if m.get("from")}),
+            oldest_age_seconds=int(oldest), after_seconds=int(after),
+            reason=("still-unread: %d message(s) in this inbox were notified and are still UNREAD after "
+                    "%ds or more (oldest %ds). Read what you have handled with mark_read=true; this "
+                    "reminder repeats at most %d time(s) per message." % (len(due), after, int(oldest), cap)))
+        if ok is True:
+            for mid, _, _, n in due:
+                ledger[mid] = (n + 1, now)
+        return [mid for mid, _, _, _ in due]
+
     def _delivery_recovered(self):
         if not self.delivery_blocked:
             return
@@ -2567,6 +2662,7 @@ class WatchTarget:
                     delivered = set()
                 if blocked_at is None:
                     self._delivery_recovered()
+                self._resurface_still_unread(items)
 
                 # §5.2 UNREAD MAIL WE CANNOT SEE. Fires on the FALSE->TRUE edge and releases itself when
                 # the condition clears, so it needs no ack: an ack would let someone silence "there is
@@ -3606,6 +3702,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,8 +3733,19 @@ 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("--still-unread-after", type=int, default=7200, metavar="SECONDS",
+                   help="Row M229: emit ONE `still_unread` event per poll for mail that was already notified and "
+                        "is still unread this many seconds after it was sent (default 7200; 0 disables). At most "
+                        "once per message per window, capped by --still-unread-max; never for retired/reserved or "
+                        "write_only inboxes.")
+    p.add_argument("--still-unread-max", type=int, default=3, metavar="N",
+                   help="How many times one message may be re-surfaced as still_unread per process (default 3).")
     p.add_argument("--resync-every", type=int, default=10,
                    help="Fast-path safety floor: force a full inbox poll after at most N consecutive cheap "
                         "skips, so a stale/wrong unread count can never blind the watcher (default 10, min 1).")
@@ -3667,12 +3779,29 @@ def validate_args(args):
         raise FatalConfig("--max-replay must be >= 0")
     if args.keep_logs < 1:
         raise FatalConfig("--keep-logs must be >= 1")
+    if args.still_unread_after < 0:
+        raise FatalConfig("--still-unread-after must be >= 0 (0 disables)")
+    if args.still_unread_max < 1:
+        raise FatalConfig("--still-unread-max must be >= 1")
     if args.events_file and args.events_file_template:
         raise FatalConfig("--events-file and --events-file-template are mutually exclusive")
     if args.events_file_template and "{persona}" not in args.events_file_template:
         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.5",
   "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.5"
 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,265 @@ 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)
+
+
+class StillUnreadBackstopTest(unittest.TestCase):
+    """Row M229: mail that was notified once and then left UNREAD is re-surfaced - boundedly. The producer
+    is edge-triggered per id, so without this such a message sits inert forever. These pin the bounds that
+    keep a reminder from becoming a storm: priming on start, once per id per window, a per-id cap, one
+    event per poll, and silence for debris and write_only inboxes."""
+
+    E2E = BoundedWindowEndToEndTest
+    T0 = km._created_epoch("2026-09-24 00:00:00")
+    H = 3600
+
+    def setUp(self):
+        self._saved = [dict(d) for d in (km._PERSONA_RETIRED, km._PERSONA_RESERVED, km._PERSONA_WRITE_ONLY)]
+        for d in (km._PERSONA_RETIRED, km._PERSONA_RESERVED, km._PERSONA_WRITE_ONLY):
+            d.clear()
+
+    def tearDown(self):
+        for d, keep in zip((km._PERSONA_RETIRED, km._PERSONA_RESERVED, km._PERSONA_WRITE_ONLY), self._saved):
+            d.clear()
+            d.update(keep)
+
+    def _target(self, after=7200, cap=3, cursor=10, em=None):
+        em = em or self.E2E.RecordingEmitter()
+        t = self.E2E()._target(cursor=cursor, emitter=em)
+        t.args.still_unread_after, t.args.still_unread_max = after, cap
+        return t, em
+
+    def _alerts(self, em):
+        return [f for e, f in em.events if e == "still_unread"]
+
+    ITEMS = [{"id": 5, "from": "river", "read": False, "created": "2026-09-24 00:00:00"},
+             {"id": 6, "from": "river", "read": True, "created": "2026-09-24 00:00:00"},    # already read
+             {"id": 11, "from": "river", "read": False, "created": "2026-09-24 00:00:00"}]  # not yet notified
+
+    def test_primes_on_start_then_reminds_once_per_window_up_to_the_cap(self):
+        t, em = self._target()
+        now = self.T0 + 3 * self.H
+        self.assertEqual(t._resurface_still_unread(self.ITEMS, now), [], "a restart must not burst")
+        self.assertEqual(t._resurface_still_unread(self.ITEMS, now + 60), [], "not before a full window")
+        seen = [t._resurface_still_unread(self.ITEMS, now + k * 7200) for k in range(1, 6)]
+        self.assertEqual(seen, [[5], [5], [5], [], []], "once per window, capped at 3")
+        self.assertEqual(len(self._alerts(em)), 3)
+        self.assertEqual(self._alerts(em)[0]["ids"], [5])
+        self.assertEqual(self._alerts(em)[0]["senders"], ["river"])
+
+    def test_young_mail_is_not_reminded(self):
+        t, em = self._target()
+        t.still_unread_primed = True
+        self.assertEqual(t._resurface_still_unread(self.ITEMS, self.T0 + 3000), [])
+
+    def test_several_due_messages_are_ONE_event(self):
+        items = [dict(self.ITEMS[0]), dict(self.ITEMS[0], id=7, **{"from": "assay"})]
+        t, em = self._target()
+        t.still_unread_primed = True
+        self.assertEqual(t._resurface_still_unread(items, self.T0 + 3 * self.H), [5, 7])
+        self.assertEqual(len(self._alerts(em)), 1)
+        self.assertEqual(self._alerts(em)[0]["senders"], ["assay", "river"])
+
+    def test_read_mail_leaves_the_ledger(self):
+        t, _ = self._target()
+        t.still_unread_primed = True
+        t._resurface_still_unread(self.ITEMS, self.T0 + 3 * self.H)
+        self.assertIn(5, t.still_unread_seen)
+        t._resurface_still_unread([dict(self.ITEMS[0], read=True)], self.T0 + 4 * self.H)
+        self.assertNotIn(5, t.still_unread_seen)
+
+    def test_a_failed_emit_is_retried_not_counted(self):
+        class Refusing(self.E2E.RecordingEmitter):
+            def lifecycle(self, event, **f):
+                self.events.append((event, f))
+                return False
+        t, em = self._target(em=Refusing())
+        t.still_unread_primed = True
+        now = self.T0 + 3 * self.H
+        t._resurface_still_unread(self.ITEMS, now)
+        self.assertEqual(t._resurface_still_unread(self.ITEMS, now + 1), [5], "undelivered = not reminded yet")
+
+    def test_debris_and_write_only_inboxes_are_never_reminded(self):
+        for flag in (km._PERSONA_RETIRED, km._PERSONA_RESERVED, km._PERSONA_WRITE_ONLY):
+            with self.subTest(flag=flag):
+                self.setUp()
+                flag["argus"] = True
+                t, em = self._target()
+                t.still_unread_primed = True
+                self.assertEqual(t._resurface_still_unread(self.ITEMS, self.T0 + 9 * self.H), [])
+                self.assertEqual(self._alerts(em), [])
+
+    def test_zero_disables(self):
+        t, em = self._target(after=0)
+        t.still_unread_primed = True
+        self.assertEqual(t._resurface_still_unread(self.ITEMS, self.T0 + 99 * self.H), [])
+
+    def test_it_is_wired_into_the_full_poll(self):
+        t, em = self._target(after=1, cursor=10)
+        t.still_unread_primed = True
+        old = [{"id": 5, "from": "river", "read": False, "created": "2020-01-01 00:00:00"}]
+        self.E2E()._run(t, self.E2E()._fetch(old, 0))
+        alerts = self._alerts(em)
+        self.assertEqual(len(alerts), 1)
+        self.assertEqual(alerts[0]["ids"], [5])
+        self.assertEqual(t.cursor, 10, "a reminder never moves the cursor")
+        self.assertEqual(em.new_ids, [], "and is never re-emitted as `new`")
+
+    def test_created_parsing(self):
+        self.assertEqual(km._created_epoch("2026-09-24 00:00:00"), km._created_epoch("2026-09-24T00:00:00Z"))
+        self.assertEqual(km._created_epoch("2026-09-24T02:00:00+02:00"), self.T0)
+        for junk in (None, "", "yesterday", 17):
+            self.assertIsNone(km._created_epoch(junk))
+
+    def test_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)
+        self.assertIn(">= 0", err(["--persona", "a", "--still-unread-after", "-1"]))
+        self.assertIn(">= 1", err(["--persona", "a", "--still-unread-max", "0"]))
+        self.assertIsNone(err(["--persona", "a", "--still-unread-after", "0"]))