kijito-tools 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Installer for kijito-tools: copies the context-tracking, session catch-up, and self-clear scripts plus the Kijito skills into ~/.claude.",
   "license": "Apache-2.0",
   "type": "commonjs",

package/providers/_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/session-catchup-hint.sh

@@ -297,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
@@ -308,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
@@ -320,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",
+    "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,32 @@
 All notable changes to kijito-inbox-monitor are documented in this file.
 The format is based on Keep a Changelog, and this project follows Semantic Versioning.
 
+## [0.5.6] - 2026-09-25
+
+### Fixed
+- **The launchd template names the state file the producer actually writes (row M289).** It passed a base
+  (`--state-file <dir>/hive.json`) that the producer turned into `hive.<persona>.json`, so anyone reading the
+  template looked for a file that never existed. It now passes `--state-file-template <dir>/hive.{persona}.json`,
+  which resolves to the SAME file as before, so upgrading moves nothing. The README's multi-persona example
+  likewise names `state.{persona}.json`. A new `_state_path_from_args()` is the one place the producer
+  decides a persona's state file, and `StateFileNameAgreementTest` derives the name from the template's own
+  argv through it.
+- **A negative persisted `consecutive_failures` makes the state file CORRUPT.** A count below zero was
+  resumed as-is and silently postponed the dead-man alert by that many polls.
+
+## [0.5.5] - 2026-09-24
+
+### Added
+- **`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

package/providers/monitor/README.md

@@ -269,7 +269,7 @@ owned, rotated event file, and each agent session consumes only its own:
 ```sh
 kijito-inbox-monitor --all-personas \
   --events-file-template ~/.local/state/kijito-inbox-monitor/events.{persona}.ndjson \
-  --state-file ~/.local/state/kijito-inbox-monitor/state.json
+  --state-file-template ~/.local/state/kijito-inbox-monitor/state.{persona}.json
 ```
 
 Each session then wakes on its own `events.<persona>.ndjson` using the recipe in
@@ -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`,

package/providers/monitor/UPSTREAM

@@ -1,26 +1,26 @@
 # The upstream release providers/monitor is a byte-exact copy of (row M314).
 # Written by scripts/import-monitor.sh; verified by tests/vendored_monitor_test.sh. Never hand-edit.
 repo=KijitoAI/kijito-inbox-monitor
-sha=1bdc0ced989bf9c10d4a62fa4140b1cf97b7fa2e
-tree=732bef3a3b72279fb4d1111314a6eb7ecb266097
-tag=v0.5.4
+sha=04bb12ae11fc882d14c30ac36a9220591b5fab65
+tree=101419def29ffc023991a6f5aace5933d042768a
+tag=v0.5.6
 file=100644 8d88ccb0fd09b9144505f985b4f882db278fac1f .github/workflows/publish-npm.yml
 file=100644 19ce3471a2cffa689be9d261049c1e74e3e7a25e .github/workflows/publish-pypi.yml
 file=100644 4534290a5dd36d18d07a782b784b6b0ad5ee38fc .gitignore
-file=100644 6191d5c9b75c3d5198168a6422c854cd56e0426e CHANGELOG.md
+file=100644 8d92a7f3d76e6802faed79328e349b6b7786b87e CHANGELOG.md
 file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
 file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
-file=100644 86f816d7ac9ef4a5a7242376d642f59be8554e2b README.md
+file=100644 73d2bf5a5d5d6cb622db014285cd9ada4c705724 README.md
 file=100644 72f0c148f1e721ac1bb4a38e5cae690355774314 RELEASING.md
 file=100755 fca1203267cb726736b0c8f239e2d74c40a7a895 arm-hive-monitor.sh
 file=100755 bbe3f07de13dab8a8a7a4798481156ae4a46ab8f bin/cli.js
-file=100644 23e088613c314bf86b384640639b545de60ea9d0 com.kijito.inbox-monitor.plist.template
-file=100644 0ec3f23c29bb26d2890b9083d1014840a48cd2c3 docs/DESIGN.md
+file=100644 fffa8bd23749a321285bd942a3f4f4a98936129c com.kijito.inbox-monitor.plist.template
+file=100644 30519b1ad6098541083648392f344da68e688246 docs/DESIGN.md
 file=100644 4f5e53a8633e60e6c57c451e28546f8af8783fe8 kijito-inbox-monitor@.service.template
-file=100644 8ad5159d6659a05c33756abc901f7cf4dcd5c9c7 kijito_inbox_monitor.py
-file=100644 4f1d402533247b1453d3b670c9dc746d3941a576 package.json
-file=100644 bc6f7c99e94c83fc89c5ceb1b1c2bfebf203e015 pyproject.toml
+file=100644 5038ff752d4b936e5b9bfab5642f38e7622fd4a4 kijito_inbox_monitor.py
+file=100644 5e682088a3dafbe9526761c87f9a16573c3bbdc9 package.json
+file=100644 6f90a103962a6ee2fa985f8356ff8c95cb93a6a7 pyproject.toml
 file=100755 b34a5c775385ecfaefd4b374c1fc1aa082a85d14 scripts/migrate-systemd-unit.sh
 file=100755 22acef6d6875395a81c701eb535030d0a78b0df1 scripts/mutation-check.py
 file=100755 acba6196213736922fc4f7135749386d85d172a6 scripts/prepublish-gate.sh
-file=100644 f7272d96cd1b3b0235aa79debbb6568a67063d6e test_kijito_monitor.py
+file=100644 ea22077c22b25d53d6719af4b0e7d9e719aeea7d test_kijito_monitor.py

package/providers/monitor/com.kijito.inbox-monitor.plist.template

@@ -37,8 +37,8 @@
     <string>__PROGRAM__</string>
     <string>--token-file</string>
     <string>__HOME__/.config/kijito-inbox-monitor/token</string>
-    <string>--state-file</string>
-    <string>__HOME__/.cache/kijito-inbox-monitor/hive.json</string>
+    <string>--state-file-template</string>
+    <string>__HOME__/.cache/kijito-inbox-monitor/hive.{persona}.json</string>
     <string>--events-file-template</string>
     <string>__HOME__/.cache/kijito-inbox-monitor/events.{persona}.ndjson</string>
     <string>--heartbeat</string>

package/providers/monitor/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.py

@@ -33,7 +33,7 @@ try:
 except ImportError:  # pragma: no cover - Windows
     fcntl = None
 
-__version__ = "0.5.4"
+__version__ = "0.5.6"
 SOURCE = "kijito-inbox"
 # A named User-Agent is REQUIRED: api.kijito.ai is fronted by a WAF that 403s the default Python-urllib UA.
 USER_AGENT = "kijito-inbox-monitor/%s" % __version__
@@ -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:
@@ -1537,7 +1543,7 @@ class StateFile:
                              "%s\n" % self.path)
             return CORRUPT_STATE
         if not ((cursor is None or _is_int(cursor)) and state in ("UP", "DOWN")
-                and _is_int(failures)):
+                and _is_int(failures) and failures >= 0):   # a failure COUNT is never negative
             sys.stderr.write("kijito-inbox-monitor: WARNING state-file has a valid envelope but invalid "
                              "fields; refusing to baseline over it: %s\n" % self.path)
             return CORRUPT_STATE
@@ -1852,6 +1858,29 @@ def _persona_path(template, persona):
     return template.replace("{persona}", _state_safe_persona(persona))
 
 
+def _state_path_from_args(args, persona):
+    """THE state file a persona's watch target opens (row M289): the `{persona}` template when given, else the
+    per-persona derivation of the `--state-file` base. One function, so a supervisor template, the docs and a
+    test can ask the producer which file it will write instead of re-deriving the name and drifting."""
+    if getattr(args, "state_file_template", None):
+        return _persona_path(args.state_file_template, persona)
+    return _state_path_for_persona(getattr(args, "state_file", None), persona)
+
+
+def _created_epoch(created):
+    """A message's `created` as epoch seconds, or None if it cannot be read. The server writes naive UTC
+    ('2026-09-24 21:34:24.943580'); an explicit offset or 'Z' is honoured when present."""
+    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
@@ -2002,8 +2031,7 @@ class WatchTarget:
         cp = urllib.parse.urlsplit(url)
         self.unread_persona = dict(urllib.parse.parse_qsl(cp.query)).get("persona") or persona
 
-        state_path = (_persona_path(args.state_file_template, persona) if args.state_file_template
-                      else _state_path_for_persona(args.state_file, persona))
+        state_path = _state_path_from_args(args, persona)
         if state_path:
             self.state_file = StateFile(state_path, self.identity)
             if not args.self_test:
@@ -2154,6 +2182,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
@@ -2579,6 +2670,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
@@ -3655,6 +3747,13 @@ def build_parser():
                         "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).")
@@ -3688,6 +3787,10 @@ 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:

package/providers/monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-inbox-monitor",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Pointer to the Python package kijito-inbox-monitor. A zero-dependency watcher that wakes a running agent when new Kijito inbox mail arrives. Install the real tool with pipx/uv/pip.",
   "license": "Apache-2.0",
   "type": "commonjs",

package/providers/monitor/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kijito-inbox-monitor"
-version = "0.5.4"
+version = "0.5.6"
 description = "Zero-dependency watcher that wakes a running agent when new Kijito inbox mail arrives."
 readme = "README.md"
 requires-python = ">=3.9"

package/providers/monitor/test_kijito_monitor.py

@@ -5995,3 +5995,201 @@ class SystemdUnitMigrationRewriteTest(unittest.TestCase):
             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"]))
+
+
+class StateFileNameAgreementTest(unittest.TestCase):
+    """Row M289 (second half): the launchd template, the docs and the producer must agree on the state file's
+    NAME. The template used to pass a base (`--state-file <dir>/hive.json`) that the producer silently turned
+    into `hive.<persona>.json`, so a reader of the template looked for a file that never existed. Now the
+    template names the file with a `{persona}` template and this test derives the name from the template's
+    OWN argv, through the producer's OWN parser and `_state_path_from_args` - one constant, no second copy."""
+
+    NAMES = ["argus", "Loom", "name (purpose)", "Ωmega", "two words", "Claude-chat"]
+    HOME = "/HOMEDIR"
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+
+    def _launchd_argv(self):
+        with open(os.path.join(self._HERE, "com.kijito.inbox-monitor.plist.template"), encoding="utf-8") as fh:
+            text = fh.read()
+        block = re.search(r"<key>ProgramArguments</key>\s*<array>(.*?)</array>", text, re.S).group(1)
+        words = [w.replace("__HOME__", self.HOME) for w in re.findall(r"<string>([^<]*)</string>", block)]
+        return words[words.index("__PROGRAM__") + 1:]
+
+    def _args(self):
+        args = km.build_parser().parse_args(self._launchd_argv())
+        km.validate_args(args)
+        return args
+
+    def test_the_launchd_template_names_exactly_the_state_file_the_producer_writes(self):
+        args = self._args()
+        self.assertIsNotNone(args.state_file_template, "the template must NAME the per-persona file, not a base")
+        for name in self.NAMES:
+            with self.subTest(persona=name):
+                path = km._state_path_from_args(args, name)
+                self.assertEqual(os.path.basename(path), "hive.%s.json" % km._state_safe_persona(name))
+
+    def test_existing_launchd_installs_keep_their_state_file(self):
+        # The old template's base `hive.json` was derived to `hive.<safe>.json`; the new template must land on
+        # the SAME file, or an upgrade would baseline over every persona's cursor (skipping its backlog).
+        args = self._args()
+        legacy = self.HOME + "/.cache/kijito-inbox-monitor/hive.json"
+        for name in self.NAMES:
+            with self.subTest(persona=name):
+                self.assertEqual(km._state_path_from_args(args, name), km._state_path_for_persona(legacy, name))
+
+    def test_the_producer_opens_the_path_state_path_from_args_returns(self):
+        # Pins that the watch target uses THIS function, so the test above speaks for the running producer.
+        with open(os.path.join(self._HERE, "kijito_inbox_monitor.py"), encoding="utf-8") as fh:
+            src = fh.read()
+        self.assertIn("state_path = _state_path_from_args(args, persona)", src)
+
+    def test_the_readme_multi_persona_example_writes_the_file_it_documents(self):
+        with open(os.path.join(self._HERE, "README.md"), encoding="utf-8") as fh:
+            readme = fh.read()
+        m = re.search(r"--all-personas \\\n(?:.*\\\n)*?\s*--state-file-template (\S+)", readme)
+        self.assertIsNotNone(m, "the multi-persona example must name its state file with a {persona} template")
+        args = km.build_parser().parse_args(["--all-personas", "--state-file-template", m.group(1)])
+        self.assertEqual(os.path.basename(km._state_path_from_args(args, "argus")), "state.argus.json")
+        self.assertIn("state.<persona>.json", readme)
+
+
+class NegativeFailureCountStateTest(unittest.TestCase):
+    """A persisted `consecutive_failures` below zero is not a count: resumed as-is it would postpone the
+    dead-man edge by that many polls, silently. `_is_int` alone accepted it (a negative is a real integer)."""
+
+    def _load(self, failures):
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "s.json")
+            with open(p, "w") as f:
+                json.dump({"identity": "idx", "cursor": 100, "state": "UP", "consecutive_failures": failures}, f)
+            err, sys.stderr = sys.stderr, io.StringIO()
+            try:
+                return km.StateFile(p, "idx").load()
+            finally:
+                sys.stderr = err
+
+    def test_a_negative_count_is_CORRUPT(self):
+        for bad in (-1, -1000):
+            self.assertIs(self._load(bad), km.CORRUPT_STATE, "consecutive_failures=%r must not be resumed" % bad)
+
+    def test_zero_still_loads(self):
+        self.assertIsNot(self._load(0), km.CORRUPT_STATE)