kijito-tools 0.2.0

package/providers/claude/scripts/arm-session.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Turn THIS session's autonomy on/off via INTERACTION. The agent runs this when the user says
+# "enable self-clear" / "go autonomous" (on), or "I'll manage this one" (off). It arms the current
+# tmux PANE: self-clear becomes permitted, and post-/clear SessionStarts auto-catch-up + resume.
+# Same marker claude-armed.sh uses, so launch-time and interaction-time arming are identical.
+# Resolve the shared lib NEXT TO THIS SCRIPT so the repo copy is runnable/testable in place, and
+# fall back to the installed location for a stray single-file copy. KIJITO_LC_LIB overrides both.
+_kjt_lib="${KIJITO_LC_LIB:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lifecycle-lib.sh}"
+[ -f "$_kjt_lib" ] || _kjt_lib="$HOME/.claude/lifecycle-lib.sh"
+. "$_kjt_lib"
+action="${1:-on}"
+if [ -z "${TMUX_PANE:-}" ]; then echo "not in tmux — autonomy needs a tmux pane; nothing armed."; exit 1; fi
+marker="$KIJITO_LC_DIR/arm.$TMUX_PANE"
+case "$action" in
+  # The marker carries PROVENANCE (session name + #{session_created}) and is validated against the
+  # live tmux server on every read — see lifecycle-lib.sh. A zero-byte touch would arm nothing.
+  on)     if ! lc_marker_write "$TMUX_PANE"; then
+            echo "could not arm: pane $TMUX_PANE is not a live tmux pane (or tmux did not answer). Nothing armed." >&2
+            lc_log ARM "on FAILED pane=$TMUX_PANE — no live pane fingerprint"; exit 1
+          fi
+          lc_log ARM "on pane=$TMUX_PANE"
+          echo "AUTONOMY ON (pane $TMUX_PANE): self-clear permitted; after any /clear this pane auto-catches-up + resumes. Turn off: ~/.claude/arm-session.sh off" ;;
+  # ⛔ `off` MUST NOT REPORT SUCCESS IT CANNOT DELIVER. Removing the marker disarms NOTHING while the
+  # seat-wide KIJITO_AUTOCATCHUP=1 is in force, and a process cannot unset an env var for itself.
+  # So: still remove the marker (that part is real and durable), then REFUSE LOUDLY and name the one
+  # brake that works. Non-zero exit, so a caller that checks can tell it did not get what it asked.
+  off)    rm -f "$marker"; lc_log ARM "off pane=$TMUX_PANE marker_removed"
+          if lc_env_armed; then
+            lc_log ARM "off REFUSED pane=$TMUX_PANE env=KIJITO_AUTOCATCHUP=1"
+            cat >&2 <<EOF
+⛔ STILL ARMED — 'off' COULD NOT DISARM THIS PANE.
+   The marker $marker was removed, but arming is also granted seat-wide by
+   KIJITO_AUTOCATCHUP=1 (set in the environment, typically ~/.claude/settings.json), and a
+   running session cannot unset that for itself. self-clear is STILL PERMITTED here.
+   The only brake that works:  touch $KIJITO_LC_STOP
+   (undo with:                rm -f $KIJITO_LC_STOP )
+EOF
+            exit 3
+          fi
+          echo "AUTONOMY OFF (pane $TMUX_PANE): human-managed; self-clear refused." ;;
+  # status prints BOTH inputs — a status that reports only the marker gives the wrong answer in
+  # both directions on a seat where the env var is set.
+  status) m=no; e=no
+          lc_marker_armed "$TMUX_PANE" && m=yes
+          lc_env_armed && e=yes
+          # ⚠️ "no" has three different causes and only one of them means "you never armed this".
+          # Saying which is the difference between a status and a riddle.
+          if [ "$m" = no ]; then
+            if lc_marker_legacy "$TMUX_PANE"; then
+              m="no (LEGACY marker: written before markers carried provenance, so it cannot prove it
+              belongs to THIS session — pane ids recycle. Re-arm with 'arm-session.sh on'.)"
+            elif [ -f "$marker" ]; then
+              m="no (marker exists but its session fingerprint does NOT match this pane's live tmux
+              session — it was left by a DIFFERENT session that had this pane id. Re-arm to claim it.)"
+            fi
+          fi
+          echo "pane=$TMUX_PANE marker=$m (arm.$TMUX_PANE) env=$e (KIJITO_AUTOCATCHUP=${KIJITO_AUTOCATCHUP:-unset})"
+          if lc_is_armed "$TMUX_PANE"; then
+            echo "armed (autonomous) — armed by: $( [ "$m" = yes ] && printf 'marker '; [ "$e" = yes ] && printf 'env')"
+            lc_stopped && echo "…but the kill switch is SET ($KIJITO_LC_STOP) — self-clear will refuse."
+          else
+            echo "not armed (human-managed)"
+          fi
+          exit 0 ;;   # status always exits 0 (it REPORTS; it does not assert). Read the text, not $?.
+  *)      echo "usage: arm-session.sh [on|off|status]"; exit 2 ;;
+esac

package/providers/claude/scripts/claude-armed.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Launch an ARMED Claude Code session: when in tmux it auto-sends the catch-up prompt (instigating
+# its own first turn) and continues preloaded work. Use for orchestrator/unattended panes + the
+# self-clear loop. Plain `claude` is NOT armed → never collides with you typing.
+#
+# Arming is a per-pane MARKER file (robust; doesn't depend on env reaching the hook). The marker is
+# removed when claude exits (trap). KIJITO_AUTOCATCHUP=1 is also exported as a belt-and-suspenders.
+# Resolve the shared lib NEXT TO THIS SCRIPT so the repo copy is runnable/testable in place, and
+# fall back to the installed location for a stray single-file copy. KIJITO_LC_LIB overrides both.
+_kjt_lib="${KIJITO_LC_LIB:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lifecycle-lib.sh}"
+[ -f "$_kjt_lib" ] || _kjt_lib="$HOME/.claude/lifecycle-lib.sh"
+. "$_kjt_lib" 2>/dev/null
+marker="${KIJITO_LC_DIR:-$HOME/.claude/.lifecycle}/arm.${TMUX_PANE:-nopane}"
+mkdir -p "$(dirname "$marker")" 2>/dev/null
+# ⛔ NOT `touch`. A zero-byte marker cannot prove it belongs to THIS session, and tmux pane ids
+# restart at %0 and recycle — so a bare touch is how a future session inherits an arming it never
+# performed, on the gate that authorises an irreversible /clear. lc_marker_write stamps the live
+# session fingerprint into the file and lc_marker_armed re-validates it on every read.
+if command -v lc_marker_write >/dev/null 2>&1 && [ -n "${TMUX_PANE:-}" ]; then
+  lc_marker_write "$TMUX_PANE" || echo "claude-armed: could not stamp an arm marker for $TMUX_PANE (not a live tmux pane?) — relying on KIJITO_AUTOCATCHUP" >&2
+fi
+# ── THE BACKUP HEARTBEAT STARTS WITH THE SESSION (row M291) ─────────────────────────────────────
+# It used to be a separate, manual step (wiring/README.md), so most armed panes ran without one — and
+# the heartbeat is the only thing that recovers a session whose inbox loop a usage-limit outage ended
+# silently. Idempotent: if a watchdog already watches this pane (a systemd/launchd unit, or an earlier
+# launch), it is left alone and NOT stopped on exit — only the one started here is ours to stop.
+# Opt out with KIJITO_HEARTBEAT=0.
+hb_pid=""
+if [ "${KIJITO_HEARTBEAT:-1}" != "0" ] && [ -n "${TMUX_PANE:-}" ]; then
+  hb_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/heartbeat-watchdog.sh"
+  [ -f "$hb_script" ] || hb_script="$HOME/.claude/heartbeat-watchdog.sh"
+  if [ ! -f "$hb_script" ]; then
+    echo "claude-armed: no heartbeat-watchdog.sh next to this script or in ~/.claude — running without the backup heartbeat" >&2
+  elif command -v lc_heartbeat_running >/dev/null 2>&1 && lc_heartbeat_running "$TMUX_PANE"; then
+    :   # already watched — by a supervisor unit or a previous launch
+  else
+    nohup bash "$hb_script" "$TMUX_PANE" >/dev/null 2>&1 &
+    hb_pid=$!
+  fi
+fi
+trap 'rm -f "$marker"; [ -n "$hb_pid" ] && kill "$hb_pid" 2>/dev/null' EXIT INT TERM
+
+# Hosted Kijito MCP bearer token for .mcp.json's ${KIJITO_API_TOKEN} — read from a file so it is
+# reliable inside the armed loop regardless of which shell profile did (or didn't) load. Only set it
+# if the file exists AND the var isn't already provided by the environment.
+if [ -z "${KIJITO_API_TOKEN:-}" ] && [ -r "${KIJITO_API_TOKEN_FILE:-$HOME/.claude/.kijito_api_token}" ]; then
+  export KIJITO_API_TOKEN="$(cat "${KIJITO_API_TOKEN_FILE:-$HOME/.claude/.kijito_api_token}" 2>/dev/null)"
+fi
+
+# Remote Control for armed/autonomous panes: it lets you check an unattended session from a phone,
+# which is the normal reason to arm one. RC is a per-PROCESS feature — it survives /clear but NOT a
+# fresh launch, and an agent cannot self-invoke a slash command, so it has to be set here at start.
+#
+# Both knobs are opt-OUT-able because this ships to other people's machines:
+#   KIJITO_REMOTE_CONTROL=0   → don't enable remote control at all
+#   KIJITO_RC_PREFIX=<name>   → session-name prefix; makes the pane easy to spot in the session list.
+# The prefix defaults to this project's persona (the `.kijito_persona` marker, same file the
+# SessionStart hook reads), so an armed river pane is named "river-*" and an argus one "argus-*"
+# without anyone hardcoding a name. No marker → no prefix, rather than someone else's persona.
+rc_args=()
+if [ "${KIJITO_REMOTE_CONTROL:-1}" != "0" ]; then
+  rc_args+=(--remote-control)
+  rc_prefix="${KIJITO_RC_PREFIX:-}"
+  if [ -z "$rc_prefix" ]; then
+    for d in "${CLAUDE_PROJECT_DIR:-}" "$PWD"; do
+      if [ -n "$d" ] && [ -f "$d/.kijito_persona" ]; then
+        rc_prefix=$(head -n1 "$d/.kijito_persona" | tr -d '[:space:]')
+        [ -n "$rc_prefix" ] && break
+      fi
+    done
+  fi
+  [ -n "$rc_prefix" ] && rc_args+=(--remote-control-session-name-prefix "$rc_prefix")
+fi
+# Session provenance ([18500]; Kijito #624/#627). The Claude Code MCP client forwards ONLY the
+# Authorization header from .mcp.json `headers` (measured on 2.1.265 — every other header, literal or
+# not, is dropped) and expands `${VAR}` in a server URL from the LAUNCHING environment only; it never
+# injects its own session id there. So the id is minted HERE, exported for the URL
+# (`https://api.kijito.ai/mcp/?session=${CLAUDE_CODE_SESSION_ID}`) and passed as --session-id, so the
+# transcript, the hooks and the server all name the same session. Per LAUNCH: /clear rotates the
+# harness's own id (children still see the rotated one — the harness overrides an inherited value),
+# but the MCP URL was resolved at launch, so writes after a /clear carry the launch id. An explicit
+# --session-id from the caller is honoured; an INHERITED value is ignored (a nested launch would
+# otherwise reuse a live id, which `claude` refuses as "already in use").
+kjt_sid=""
+kjt_prev=""
+for kjt_arg in "$@"; do                       # an explicit --session-id X / --session-id=X wins
+  case "$kjt_prev" in --session-id) kjt_sid="$kjt_arg";; esac
+  case "$kjt_arg" in --session-id=*) kjt_sid="${kjt_arg#--session-id=}";; esac
+  kjt_prev="$kjt_arg"
+done
+if [ -z "$kjt_sid" ]; then
+  kjt_sid=$( (uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null \
+             || python3 -c 'import uuid;print(uuid.uuid4())' 2>/dev/null) | tr 'A-Z' 'a-z' | tr -d '[:space:]')
+  if [ -n "$kjt_sid" ]; then
+    set -- --session-id "$kjt_sid" "$@"
+  else
+    echo "claude-armed: no uuid source (uuidgen / /proc / python3) — launching without a minted session id; MCP writes will carry no Session:" >&2
+  fi
+fi
+[ -n "$kjt_sid" ] && export CLAUDE_CODE_SESSION_ID="$kjt_sid"   # the URL's ${CLAUDE_CODE_SESSION_ID}
+KIJITO_AUTOCATCHUP=1 claude "${rc_args[@]+"${rc_args[@]}"}" "$@"

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

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# BACKUP heartbeat for an armed autonomous pane. (Jason, 2026-08-01: "please also setup a backup
+# heartbeat.")
+#
+#   ~/.claude/heartbeat-watchdog.sh %3 &        # or run under systemd/launchd; see WIRING below
+#
+# WHAT THE PRIMARY IS, so this stays a BACKUP and never competes with it: after a /clear the
+# SessionStart hook runs `session-autosend.sh`, which injects the catch-up prompt and restarts the
+# loop. That path owns the normal case. This covers only what it cannot — the pane going QUIET
+# WITHOUT a /clear: a turn that ended without queueing the next one, a crashed send, an agent that
+# reported and then simply stopped.
+#
+# ⛔ THE DANGER IS FIRING WHILE THE AGENT IS ALIVE, so every guard is biased toward NOT sending. A
+# spurious nudge injects a prompt into a working session; a missed nudge costs idle time. Those are
+# not symmetric.
+#   * ARMED-ONLY, FAIL CLOSED. An unarmed pane is human-managed and must never be poked; if
+#     armed-ness cannot be established, do nothing.
+#   * KILL SWITCH honoured every cycle, not just at startup.
+#   * IDLE = the pane's visible output byte-identical for QUIET_CHECKS consecutive polls (default
+#     4 x 300s = 20 min). A working session repaints constantly — spinner, tool output, streaming
+#     text — so 20 minutes unchanged is a strong signal, deliberately far above any normal gap.
+#   * ONE NUDGE PER QUIET WINDOW — not one per episode, and the distinction is deliberate. After a
+#     nudge the counter resets and the baseline is retaken, so a pane that STAYS idle is nudged
+#     again one full window later (20 min at defaults), not on every poll. That is the right
+#     behaviour for a heartbeat: if the first nudge did not restart anything, the pane is still
+#     stuck and still needs help. Measured at test speeds (POLL=1, QUIET=2): 3 nudges in 11s, i.e.
+#     one per window, which is exactly one per 20 min at production settings.
+#
+# ⚠️ THE PROMPT IT SENDS IS SAFE TO RECEIVE AT ANY MOMENT — it asks the agent to continue from its
+# own pointer, which is nearly a no-op for a session already doing that. That property is what makes
+# a false positive cheap; do not replace it with a directive that assumes idleness.
+#
+# WIRING (either host; the script itself is host-agnostic):
+#   Linux/systemd :  systemd --user unit with ExecStart=%h/.claude/heartbeat-watchdog.sh <pane>
+#   macOS/launchd :  a LaunchAgent with the same ExecStart, or simply `nohup ... &` from the pane.
+set -u
+
+PANE="${1:-}"
+POLL="${HEARTBEAT_POLL:-300}"
+QUIET_CHECKS="${HEARTBEAT_QUIET:-4}"
+# M291: how long a persona's event stream may carry unread wake events with NO consumer before this
+# says so. Default 10 min: longer than a Monitor re-arm gap, far shorter than a usage-limit outage.
+UNCONSUMED_SECS="${HEARTBEAT_UNCONSUMED_SECS:-600}"
+
+_kjt_lib="${KIJITO_LC_LIB:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lifecycle-lib.sh}"
+[ -f "$_kjt_lib" ] || _kjt_lib="$HOME/.claude/lifecycle-lib.sh"
+# shellcheck disable=SC1090
+. "$_kjt_lib" 2>/dev/null || { echo "heartbeat-watchdog: cannot source lifecycle-lib" >&2; exit 2; }
+
+_kjt_plib="$(dirname "$_kjt_lib")/kijito-persona-lib.sh"
+[ -f "$_kjt_plib" ] || _kjt_plib="$HOME/.claude/kijito-persona-lib.sh"
+# shellcheck disable=SC1090
+. "$_kjt_plib" 2>/dev/null || true      # optional: without it the stream check is skipped, not faked
+
+command -v tmux >/dev/null 2>&1 || { lc_log HEARTBEAT_SKIP "no tmux"; exit 0; }
+[ -n "$PANE" ] || { echo "usage: heartbeat-watchdog.sh <tmux-pane-id>   (e.g. %3)" >&2; exit 2; }
+
+# Change detection only — `cksum` is POSIX and present on both BSD and GNU userland, unlike md5sum
+# (absent on macOS, where it is `md5`). We need "did this differ", not a cryptographic digest.
+_pane_hash() { tmux capture-pane -p -t "$1" 2>/dev/null | tail -40 | cksum | awk '{print $1"-"$2}'; }
+
+# ── M291: THE UNCONSUMED-STREAM CHECK ────────────────────────────────────────────────────────────
+# WHY: a Claude usage-limit hit ends the agent's turn loop, and the wake-capable consumer (a Monitor
+# tail) dies or expires with it. When the limit clears NOTHING re-arms it: the producer keeps writing
+# events, nobody reads them, and the session is permanently deaf while every health signal reads
+# green (producer up, heartbeat fresh, mail landing). That is DIFFERENT from the producer's "dormant
+# inbox" notice, which is about mail nobody has READ on the server; this is about a local stream
+# nobody is CONSUMING — and it has a different fix (re-arm the consumer), so it gets its own name.
+#
+# RAISED WHEN: this pane's persona has an event stream, no `tail` consumer has been attached for
+# UNCONSUMED_SECS, AND at least one wake-worthy event was appended since the consumer went missing
+# (no events = nothing missed = nothing to alarm about; the heartbeat rows the producer writes every
+# minute are excluded by the same filter a consumer uses).
+# 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)"'
+UNCONSUMED_FLAG="$KIJITO_LC_DIR/unconsumed.$PANE"
+st_missing_since=""; st_offset=""; st_alerted=0; st_path=""
+
+_stream_check() {
+  command -v kijito_stream_for_persona >/dev/null 2>&1 || return 0
+  local dir persona path now size n
+  dir=$(tmux display-message -p -t "$PANE" '#{pane_current_path}' 2>/dev/null)
+  persona=$(kijito_persona_from_marker "$dir" 2>/dev/null) || persona=""
+  [ -n "$persona" ] || return 0
+  path=$(kijito_stream_for_persona "$persona" 2>/dev/null) || path=""
+  [ -n "$path" ] && [ -f "$path" ] || return 0
+  if kijito_stream_consumed "$path"; then
+    if [ "$st_alerted" = 1 ]; then lc_log HEARTBEAT_STREAM_CONSUMED "target_pane=$PANE persona=$persona stream=$path"; fi
+    rm -f "$UNCONSUMED_FLAG" 2>/dev/null
+    st_missing_since=""; st_offset=""; st_alerted=0; st_path=""
+    return 0
+  fi
+  now=$(lc_now); size=$(wc -c < "$path" 2>/dev/null | tr -d ' ')
+  if [ -z "$st_missing_since" ] || [ "$path" != "$st_path" ]; then
+    st_missing_since=$now; st_offset=$size; st_path=$path; return 0
+  fi
+  # the producer self-rotates its stream; a shrunken file means everything in it is new
+  [ "${size:-0}" -lt "${st_offset:-0}" ] && st_offset=0
+  [ "$st_alerted" = 0 ] || return 0
+  [ $((now - st_missing_since)) -ge "$UNCONSUMED_SECS" ] || return 0
+  n=$(tail -c +"$((st_offset + 1))" "$path" 2>/dev/null | grep -cE -- "$WAKE_EVENTS")
+  [ "${n:-0}" -gt 0 ] || return 0
+  st_alerted=1
+  lc_log HEARTBEAT_UNCONSUMED_STREAM "target_pane=$PANE persona=$persona stream=$path events=$n no_consumer_for=$((now - st_missing_since))s"
+  printf 'persona=%s\nstream=%s\nevents=%s\nsince=%s\n' "$persona" "$path" "$n" "$st_missing_since" > "$UNCONSUMED_FLAG" 2>/dev/null
+}
+
+lc_log HEARTBEAT_START "pane=$PANE poll=${POLL}s quiet=$QUIET_CHECKS"
+last=""; unchanged=0
+
+while true; do
+  sleep "$POLL"
+
+  lc_stopped && { lc_log HEARTBEAT_SKIP "kill switch"; unchanged=0; continue; }
+
+  # Uses the FIXED lc_pane_alive (it enumerates real pane ids). Before 0.1.4 this returned true for
+  # any string, so this loop would have run forever against a pane that no longer existed.
+  lc_pane_alive "$PANE" || { lc_log HEARTBEAT_EXIT "pane $PANE gone"; exit 0; }
+
+  lc_is_armed "$PANE" || { lc_log HEARTBEAT_SKIP "pane $PANE not armed"; unchanged=0; continue; }
+
+  _stream_check
+
+  cur="$(_pane_hash "$PANE")"
+  [ -n "$cur" ] || { unchanged=0; continue; }
+  if [ "$cur" = "$last" ]; then unchanged=$((unchanged+1)); else unchanged=0; last="$cur"; fi
+  [ "$unchanged" -ge "$QUIET_CHECKS" ] || continue
+
+  # ⛔ M291: NEVER TYPE INTO A MENU. The folder-trust dialog's second option is "No, exit"; an Enter
+  # there does not deliver the nudge, it can END the session. Checked AFTER the idle window so a
+  # quiet pane sitting on a dialog is logged once per window, not on every poll — and nothing is sent.
+  if lc_pane_at_menu "$PANE"; then
+    lc_log HEARTBEAT_SKIP "target_pane=$PANE shows an interactive menu (e.g. folder trust, where Enter = No, exit); not typing into it"
+    unchanged=0; last="$(_pane_hash "$PANE")"
+    continue
+  fi
+
+  # ── WAKE NONCE ────────────────────────────────────────────────────────────
+  # Every nudge carries an identity. Without one, EVERY heartbeat nudge is
+  # BYTE-IDENTICAL to every other heartbeat nudge, which breaks three things
+  # that were each reported separately as if they were different bugs:
+  #   1. D1 cannot tell nudge #1 from nudge #47, so nudges are invisible to
+  #      the wake population by construction.
+  #   2. Content-identity attribution collapses them onto one another -- the
+  #      same duplicate-payload hazard found in the D1 batch keys (L3-F2).
+  #   3. Byte-identical NUDGE log lines at the same timestamp cannot be
+  #      resolved into "two panes coinciding" vs "one pane double-firing",
+  #      so a double-fire is a real bug the log is structurally unable to
+  #      reveal (argus).
+  #
+  # RANDOM, not derived -- and this is the ONE place in the design where that
+  # is correct. The derived-nonce ruling covers producer events, which have an
+  # `event_id` to derive FROM and an equivalence class where a re-delivery is
+  # the SAME wake. A nudge has no event and no dedupe key: one EMISSION is one
+  # wake (signal-class), so a per-emission identity is the right semantics.
+  #
+  # 11 base62 chars matches the producer's wake nonce exactly: 10 chars is
+  # 59.5 bits (under the >=64-bit floor), 12 breaks the <=11 ceiling.
+  _nonce="$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom 2>/dev/null | head -c 11)"
+  if [ ${#_nonce} -ne 11 ]; then
+    # DEGRADED GENERATOR -- and it must ANNOUNCE itself. The fallback is
+    # `date+cksum`, ~36 bits, BELOW the >=64-bit floor the plan sets. A weak
+    # nonce is byte-indistinguishable from a strong one at the point of use,
+    # so a silent downgrade is the false-calm shape this whole file exists to
+    # remove: collisions would surface far downstream as two wakes that look
+    # like one, and nothing would point back here. (assay, review of 225cc0e.)
+    _nonce="$(date +%s%N | cksum | tr -dc '0-9' | head -c 11)"
+    lc_log HEARTBEAT_NONCE_DEGRADED "urandom unavailable; ~36-bit fallback nonce=$_nonce"
+  fi
+
+  # The pane goes in the MESSAGE BODY, not just the lc_log prefix: that prefix
+  # is built from $TMUX_PANE/$CLAUDE_CODE_SESSION_ID, which a systemd unit does
+  # not have, so it renders `pane=? sid=?` in production -- 147 such lines on
+  # this seat. The one context where the prefix IS populated is a hand-run,
+  # which is the one context that never runs in production.
+  #
+  # ⚠️ IT IS `target_pane=`, NOT `pane=`, AND THAT IS NOT COSMETIC (cadence,
+  # caught pre-install). lc_log ALWAYS emits `pane=` in its prefix, so a body
+  # field of the same name puts TWO `pane=` on one line:
+  #     … sid=? pane=?  HEARTBEAT_NUDGE  pane=%4 nonce=…
+  # and `grep -o 'pane=[^ ]*'` returns the PREFIX one -- `pane=?` -- because
+  # it comes first. A consumer parsing naively would read "pane unknown" on
+  # precisely the lines this change exists to make attributable. That is one
+  # label with two meanings on a single line, which is the defect class this
+  # fleet has hit repeatedly; a distinct name avoids it without touching the
+  # shared lc_log prefix, whose blast radius is every log line we emit.
+  lc_log HEARTBEAT_NUDGE "target_pane=$PANE nonce=$_nonce idle ~$((unchanged*POLL))s"
+  prompt="Backup heartbeat [wake-nonce: $_nonce]: this pane has been idle. Make sure your wake-capable inbox consumer is armed (a usage-limit outage ends it silently). Re-read your current-state pointer by ID (never by recall) and CONTINUE the active work autonomously to its DONE-WHEN. If your measured context is at or past the self-clear target, run the kijito-qa-memory skill and then self-clear. If there is genuinely no active work left, say so and stop."
+  if [ "$st_alerted" = 1 ]; then
+    prompt="Backup heartbeat [wake-nonce: $_nonce]: YOUR INBOX IS DEAF - the event stream $st_path has unread wake events and NO consumer is reading it. FIRST re-arm your wake-capable inbox consumer on that file (a usage-limit outage ends it silently), then read your inbox. Then re-read your current-state pointer by ID (never by recall) and CONTINUE the active work to its DONE-WHEN. If your measured context is at or past the self-clear target, run the kijito-qa-memory skill and then self-clear."
+  fi
+
+  # Same paste-buffer discipline as session-autosend: a gap before the Enter, then verify, because
+  # an Enter inside the TUI's ingest burst is absorbed as a newline and the nudge would sit unsent —
+  # a backup heartbeat that silently fails to fire is worse than none, since it is trusted.
+  tmux send-keys -t "$PANE" -l -- "$prompt" 2>/dev/null
+  sleep "${KIJITO_SEND_SETTLE:-1.2}"
+  probe=$(printf '%s' "$prompt" | tail -c 40)
+  for _try in 1 2 3; do
+    tmux send-keys -t "$PANE" Enter 2>/dev/null
+    sleep 1.5
+    tmux capture-pane -p -t "$PANE" 2>/dev/null | tail -6 | grep -qF -- "$probe" || break
+  done
+
+  unchanged=0
+  last="$(_pane_hash "$PANE")"
+done