kijito-tools 0.2.0

package/providers/claude/scripts/inbox-selftest.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# ── THE WARNING WHERE THE READER ACTUALLY IS ─────────────────────────────────────────────────────
+# This check's EXIT STATUS is its answer. Pipe it to `tail`/`head`/`grep` and `$?` becomes the
+# PIPE's status, not this script's — a NOT WORKING then reads as a pass. Emitted at RUN time on
+# STDERR (which does not travel down the pipe) so it still reaches a terminal.
+if [ ! -t 1 ]; then
+  printf '%s\n' "note: stdout is not a terminal. If you piped this, \$? is the LAST pipeline stage's status, NOT this check's answer. Run it unpiped." >&2
+fi
+
+# PROVE THE WAKE PATH, END TO END, BEFORE ANYONE BELIEVES THE INSTALL (row M304).
+#
+# WHY THIS EXISTS. From Jason's onboarding call with the first external operator: "Inbox didn't arm
+# properly on initial install." The installer had printed its ✓ lines and exited 0; the first real
+# message did not wake the agent; the HUMAN had to notice the silence, ask for a diagnosis, ask for
+# a repair, and only then did the agent think to mail itself as a test. Everything the installer
+# measured was true. None of it was the thing that mattered.
+#
+# ⚠️ THE FAILURE MODE IS SILENCE, WHICH IS WHY "IT INSTALLED FINE" IS NOT EVIDENCE. A wake path that
+# is broken looks exactly like a wake path with no mail on it: no error, no log line, nothing to
+# notice. The only way to tell them apart is to PUT A KNOWN MESSAGE THROUGH IT and watch each hop.
+# That is this script. It is not a status report; it is an experiment with a control.
+#
+# THE THREE HOPS, each independently observable, each named in the verdict when it is the one that
+# broke — because "your inbox isn't working" sends a new user to read all three, and two of them are
+# fine:
+#   1. PRODUCER   a producer process is running AND it covers THIS persona (not a sibling's).
+#   2. STREAM     a message sent to this persona actually LANDS in this persona's event stream.
+#   3. CONSUMER   something wake-capable is attached to that stream and would be re-invoked by it.
+#
+# ⛔ HOP 3 IS THE SESSION'S JOB, NOT THE INSTALLER'S, AND IT IS STILL PART OF THE VERDICT. A fresh
+# install legitimately has no consumer yet — no session has armed one. Reporting WORKING at that
+# point would be the exact lie this row exists to remove ("the install declared success with a dead
+# inbox"), so the verdict says PARTIAL, names the consumer hop, and prints what to run. The install
+# is then honestly described: proven as far as your stream file, not yet proven to wake you.
+#
+# EXIT: 0 WORKING · 1 NOT WORKING or PARTIAL (a hop failed — the verdict names it) · 2 COULD NOT
+# MEASURE (no token, no resolvable persona/stream: the check could not be run at all, which is not
+# the same as a failure and must never be reported as one).
+# ⚠️ RUN IT UNPIPED.
+set -eu
+
+PERSONA=""
+TIMEOUT=90
+DO_SEND=1
+CANARY=0
+# TWO CALLERS, TWO CONTRACTS, ONE VERDICT FUNCTION (river ruling, 2026-09-21).
+# The INSTALL-TIME run legitimately has no consumer — no agent session exists yet — so a missing
+# consumer there is PARTIAL with the next step, not a failed install. The AGENT-DRIVEN ONBOARDING
+# flow runs this same check AFTER the agent has armed its consumer and must report a machine-readable
+# verdict to the server; that caller needs "WORKING means all three hops" with no PARTIAL wording to
+# misread. --require-consumer selects the second contract. The HOPS are measured identically either
+# way — only what counts as passing changes, which is the only difference that should ever be
+# configurable in a check.
+REQUIRE_CONSUMER=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --persona)  PERSONA="${2:-}"; [ -n "$PERSONA" ] || { echo "ABORT: --persona needs a value" >&2; exit 2; }; shift 2 ;;
+    --timeout)  TIMEOUT="${2:-}"; shift 2 ;;
+    --no-send)  DO_SEND=0; shift ;;      # observe the hops without putting a message through
+    --require-consumer) REQUIRE_CONSUMER=1; shift ;;
+    --canary)   CANARY=1; shift ;;
+    -h|--help)  sed -n '1,40p' "$0"; exit 0 ;;
+    *)          echo "ABORT: unknown option $1" >&2; exit 2 ;;
+  esac
+done
+
+KIJITO_BASE=${KIJITO_BASE:-https://api.kijito.ai}
+# Cloudflare 403s the default python-urllib UA; a named UA is cheap insurance for any client here.
+UA=${KIJITOMON_UA:-kijito-inbox-selftest/1.0}
+
+# ── THE VERDICT IS A PURE FUNCTION OF THE THREE HOPS ─────────────────────────────────────────────
+# Kept pure so the canary can drive every combination offline, including the ones that are hard to
+# stage on a real host. A verdict that could only be produced by the live path would be a verdict
+# nobody had ever seen fail.
+verdict() {   # $1=producer_ok $2=stream_ok $3=consumer_ok (each 1/0) -> prints, returns 0/1
+  _p=$1; _s=$2; _c=$3
+  if [ "$_p" = 0 ]; then
+    printf '%s\n' "VERDICT: NOT WORKING — failing hop: PRODUCER"
+    printf '%s\n' "  Nothing is collecting ${PERSONA:-this persona}'s mail, so no message can reach you."
+    printf '%s\n' "  Run: $(restart_hint)"
+    return 1
+  fi
+  if [ "$_s" = 0 ]; then
+    printf '%s\n' "VERDICT: NOT WORKING — failing hop: STREAM FILE"
+    printf '%s\n' "  A producer is running, but the test message did not appear in this persona's"
+    printf '%s\n' "  event stream within ${TIMEOUT}s. The producer may be covering a DIFFERENT persona,"
+    printf '%s\n' "  or writing somewhere other than where this check is looking."
+    printf '%s\n' "  Run: producer-health.sh --persona ${PERSONA:-<persona>}   (unpiped)"
+    return 1
+  fi
+  if [ "$_c" = 0 ] && [ "$REQUIRE_CONSUMER" = 1 ]; then
+    printf '%s\n' "VERDICT: NOT WORKING — failing hop: CONSUMER"
+    printf '%s\n' "  Mail reaches the stream, but nothing is READING it, so nothing will wake this"
+    printf '%s\n' "  session. --require-consumer was passed, so a missing consumer is a FAILURE here"
+    printf '%s\n' "  rather than the expected state of a fresh install."
+    printf '%s\n' "  Arm a wake-capable consumer on: ${EVENTS:-<your events file>}"
+    return 1
+  fi
+  if [ "$_c" = 0 ]; then
+    printf '%s\n' "VERDICT: PARTIAL — failing hop: CONSUMER"
+    printf '%s\n' "  Mail reaches your event stream, but nothing is READING it, so nothing will wake"
+    printf '%s\n' "  you. This is the normal state immediately after an install: a session arms the"
+    printf '%s\n' "  consumer, the installer cannot. The install is proven as far as your stream file"
+    printf '%s\n' "  and NOT yet proven to wake you."
+    printf '%s\n' "  In your agent session, arm a wake-capable consumer on:"
+    printf '%s\n' "    ${EVENTS:-<your events file>}"
+    printf '%s\n' "  then re-run this check. A background \`tail\` that only writes to a file is NOT a"
+    printf '%s\n' "  consumer: it captures without re-invoking you, which is indistinguishable from"
+    printf '%s\n' "  silence for as long as it lasts."
+    return 1
+  fi
+  printf '%s\n' "VERDICT: WORKING — a message sent to ${PERSONA} reached the stream and a consumer is attached."
+  return 0
+}
+
+restart_hint() {
+  if [ -d "$HOME/.kijito-monitor" ] || command -v systemctl >/dev/null 2>&1; then
+    printf 'systemctl --user enable --now kijito-inbox-monitor@%s' "${PERSONA:-<persona>}"
+  else
+    printf 'launchctl kickstart -k gui/$(id -u)/com.kijito.inbox-monitor'
+  fi
+}
+
+# ── CANARY: prove each hop is NAMED when it is the one that broke ────────────────────────────────
+# ⛔ The point is not that a broken pipe produces SOME error — it is that the verdict points at the
+# right hop. A check that said "not working" for all three would pass a naive test and send every
+# new user to read all three sections of the docs.
+if [ "$CANARY" = 1 ]; then
+  fail=0
+  PERSONA="canary"; EVENTS="/tmp/canary-events"
+  expect() {   # $1=label $2=expected-substring $3..=hop states
+    _lbl=$1; _want=$2; shift 2
+    out=$(verdict "$@" || true)
+    if printf '%s' "$out" | grep -q "$_want"; then
+      printf '  ok    %s\n' "$_lbl"
+    else
+      printf '  FAIL  %s: verdict did not name it\n%s\n' "$_lbl" "$out"; fail=1
+    fi
+  }
+  expect "producer down names PRODUCER"            "failing hop: PRODUCER"     0 0 0
+  expect "producer down outranks the later hops"   "failing hop: PRODUCER"     0 1 1
+  expect "stream silent names STREAM FILE"         "failing hop: STREAM FILE"  1 0 0
+  expect "stream silent outranks the consumer hop" "failing hop: STREAM FILE"  1 0 1
+  expect "no consumer names CONSUMER"              "failing hop: CONSUMER"     1 1 0
+  expect "no consumer is PARTIAL by default"       "VERDICT: PARTIAL"          1 1 0
+  # ...and the SECOND CONTRACT: the same missing hop must read as a flat failure for the caller that
+  # has already armed a consumer. Both are asserted, because a mode that silently behaved like the
+  # default would be worse than no mode at all — the onboarding flow would report verified=true on a
+  # session that cannot be woken.
+  REQUIRE_CONSUMER=1
+  expect "with --require-consumer it is NOT WORKING" "VERDICT: NOT WORKING"     1 1 0
+  expect "and it still names the CONSUMER hop"       "failing hop: CONSUMER"    1 1 0
+  if verdict 1 1 1 | grep -q "VERDICT: WORKING"; then
+    printf '  ok    --require-consumer still says WORKING when all three are green\n'
+  else
+    printf '  FAIL  --require-consumer broke the all-green verdict\n'; fail=1
+  fi
+  REQUIRE_CONSUMER=0
+  expect "all three green says WORKING"            "VERDICT: WORKING"          1 1 1
+  # ⛔ AND THE DIRECTION THAT MATTERS MOST: WORKING must require ALL THREE. A verdict that said
+  # WORKING with a dead hop is the defect this row was opened for, stated exactly.
+  for combo in "0 0 0" "0 0 1" "0 1 0" "0 1 1" "1 0 0" "1 0 1" "1 1 0"; do
+    # shellcheck disable=SC2086
+    if verdict $combo 2>/dev/null | grep -q "VERDICT: WORKING"; then
+      printf '  FAIL  a dead hop (%s) still reported WORKING\n' "$combo"; fail=1
+    fi
+  done
+  [ "$fail" = 0 ] && printf '  ok    WORKING is never reported with a dead hop\n'
+  # exit codes are part of the contract: a failing verdict must be non-zero, or a caller that tests
+  # $? (the installer does) treats a dead inbox as a success.
+  if verdict 1 1 0 >/dev/null 2>&1; then printf '  FAIL  a PARTIAL verdict exited 0\n'; fail=1
+  else printf '  ok    a failing verdict exits non-zero\n'; fi
+  [ "$fail" = 0 ] && { printf '%s\n' "CANARY CLEAN - each broken hop is named, and WORKING needs all three."; exit 0; }
+  printf '%s\n' "CANARY FAILED"; exit 2
+fi
+
+# ── LIVE PATH ────────────────────────────────────────────────────────────────────────────────────
+# Resolve the persona from the same marker the SessionStart hook uses, so the check and the hook can
+# never disagree about WHO this seat is.
+if [ -z "$PERSONA" ]; then
+  for d in "${CLAUDE_PROJECT_DIR:-}" "$PWD"; do
+    if [ -n "$d" ] && [ -f "$d/.kijito_persona" ]; then
+      PERSONA=$(head -n1 "$d/.kijito_persona" | tr -d '\r\n')
+      # trim the ENDS only — deleting interior spaces renames the user's persona (row M290).
+      PERSONA="${PERSONA#"${PERSONA%%[![:space:]]*}"}"
+      PERSONA="${PERSONA%"${PERSONA##*[![:space:]]}"}"
+      [ -n "$PERSONA" ] && break
+    fi
+  done
+fi
+[ -n "$PERSONA" ] || { echo "COULD NOT MEASURE: no persona (pass --persona, or add a .kijito_persona marker)."; exit 2; }
+
+# The producer publishes the persona->filename rule; asking it is the only way to be sure this check
+# looks where the producer writes (row M290 — three hand-written copies had already drifted).
+# Resolved through the SHARED helper (row M291 moved it into kijito-persona-lib.sh, so the heartbeat
+# watchdog and this check cannot disagree about where a persona's stream lives).
+_st_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/kijito-persona-lib.sh"
+[ -r "$_st_lib" ] || _st_lib="$HOME/.claude/kijito-persona-lib.sh"
+# shellcheck source=/dev/null
+. "$_st_lib" || { echo "COULD NOT MEASURE: cannot source kijito-persona-lib.sh"; exit 2; }
+EVENTS=$(kijito_stream_for_persona "$PERSONA" || true)
+
+printf '%s\n' "kijito inbox self-test [persona=$PERSONA]"
+
+# ── HOP 1: PRODUCER ──────────────────────────────────────────────────────────────────────────────
+# ⚠️ "A producer is running" is a HOST-GLOBAL fact; "a producer covers ME" is a per-persona one, and
+# on a multi-persona seat they come apart routinely. The second is the one that matters here.
+producer_ok=0
+if [ -n "$EVENTS" ] && [ -e "$EVENTS" ]; then
+  producer_ok=1
+  printf '  ok    producer: covers %s (stream: %s)\n' "$PERSONA" "$EVENTS"
+elif pgrep -f "kijito_inbox_monitor\.py|bin/kijito-inbox-monitor" >/dev/null 2>&1; then
+  printf '  FAIL  producer: a producer is running, but none of it is writing a stream for %s\n' "$PERSONA"
+else
+  printf '  FAIL  producer: no producer process is running on this host\n'
+fi
+
+# ── HOP 2: STREAM ────────────────────────────────────────────────────────────────────────────────
+stream_ok=0
+if [ "$producer_ok" = 1 ]; then
+  if [ "$DO_SEND" = 0 ]; then
+    stream_ok=1
+    printf '  --    stream: not exercised (--no-send); the verdict below is about the OTHER hops only\n'
+  else
+    TOKEN=""
+    for tf in "${KIJITOMON_TOKEN_FILE:-}" "$HOME/.claude/.kijito_api_token.$PERSONA" \
+              "$HOME/.claude/.kijito_api_token" "$HOME/.config/kijito-inbox-monitor/token"; do
+      [ -n "$tf" ] && [ -r "$tf" ] && { TOKEN=$(tr -d ' \t\r\n' < "$tf"); break; }
+    done
+    if [ -z "$TOKEN" ]; then
+      printf '  ????  stream: COULD NOT MEASURE - no API token found, so no test message can be sent\n'
+      printf '%s\n' "COULD NOT MEASURE: the wake path was not exercised. This is not a pass."
+      exit 2
+    fi
+    before=$(wc -c < "$EVENTS" 2>/dev/null || echo 0)
+    stamp="kijito-inbox-selftest $(date -u +%FT%TZ) $$"
+    # Send to SELF. A self-addressed message is the only test message that cannot bother anyone else,
+    # and it exercises exactly the path a real sender uses.
+    if ! curl -fsS -m 20 -A "$UA" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+         -X POST "$KIJITO_BASE/api/send" \
+         -d "{\"to\":\"$PERSONA\",\"persona\":\"$PERSONA\",\"content\":\"$stamp — automated install self-test; safe to ignore and to delete.\"}" \
+         >/dev/null 2>&1; then
+      printf '  ????  stream: COULD NOT MEASURE - the test message could not be SENT (API unreachable or token rejected)\n'
+      printf '%s\n' "COULD NOT MEASURE: the wake path was not exercised. This is not a pass."
+      exit 2
+    fi
+    printf '  ..    stream: test message sent; waiting up to %ss for it to appear in the stream\n' "$TIMEOUT"
+    waited=0
+    while [ "$waited" -lt "$TIMEOUT" ]; do
+      now=$(wc -c < "$EVENTS" 2>/dev/null || echo 0)
+      if [ "$now" -gt "$before" ] && tail -c $((now - before + 1)) "$EVENTS" 2>/dev/null \
+           | grep -q '"event": *"new"'; then
+        stream_ok=1; break
+      fi
+      sleep 3; waited=$((waited + 3))
+    done
+    if [ "$stream_ok" = 1 ]; then
+      printf '  ok    stream: the message reached %s after ~%ss\n' "$EVENTS" "$waited"
+    else
+      printf '  FAIL  stream: nothing new arrived in %s within %ss\n' "$EVENTS" "$TIMEOUT"
+    fi
+  fi
+fi
+
+# ── HOP 3: CONSUMER ──────────────────────────────────────────────────────────────────────────────
+# ⚠️ ANCHOR THE PATTERN. An unanchored pgrep on the events path SELF-MATCHES the producer (its own
+# argv contains that path) and reports a consumer where there is none — armed-looking and deaf.
+consumer_ok=0
+if [ -n "$EVENTS" ] && kijito_stream_consumed "$EVENTS"; then consumer_ok=1; fi
+if [ "$consumer_ok" = 1 ]; then
+  printf '  ok    consumer: a wake-capable consumer is attached to the stream\n'
+else
+  printf '  FAIL  consumer: nothing is reading the stream\n'
+fi
+
+printf '\n'
+verdict "$producer_ok" "$stream_ok" "$consumer_ok"

package/providers/claude/scripts/kijito-persona-lib.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# ONE place that turns a project directory into a persona NAME. Sourced, never executed.
+#
+# WHY THIS FILE EXISTS. Row M290 was two defects, and both were copies: the SessionStart hook and the
+# producer disagreed about how a persona name becomes a FILENAME, and separately the hook mangled the
+# NAME itself before any of that (`tr -d '[:space:]'` deletes interior spaces, so `name (purpose)`
+# became `name(purpose)`). The filename half is now owned by the producer and published as
+# `kijito-inbox-monitor --safe-persona`. This file owns the other half — reading the marker — so that
+# the status line, the hook, and anything added later cannot drift the way those did.
+#
+# ⛔ THE RULE, AND IT IS THE WHOLE FILE: A MARKER'S PAYLOAD IS ITS FIRST LINE WITH THE ENDS TRIMMED.
+# Anything stricter silently RENAMES the user's persona, and the rename is invisible — it surfaces
+# later as "your mail is not being collected", pointing at a file nobody writes.
+
+# kijito_persona_from_marker [dir ...] -> prints the persona, or nothing.
+# Searches the given directories in order; defaults to $CLAUDE_PROJECT_DIR then $PWD.
+kijito_persona_from_marker() {
+  local d p
+  if [ "$#" -eq 0 ]; then set -- "${CLAUDE_PROJECT_DIR:-}" "$PWD"; fi
+  for d in "$@"; do
+    [ -n "$d" ] || continue
+    [ -f "$d/.kijito_persona" ] || continue
+    # first line, CR/LF stripped — NOT all whitespace (see the rule above)
+    p=$(head -n1 "$d/.kijito_persona" 2>/dev/null | tr -d '\r\n')
+    p="${p#"${p%%[![:space:]]*}"}"   # leading blanks
+    p="${p%"${p##*[![:space:]]}"}"   # trailing blanks
+    if [ -n "$p" ]; then printf '%s' "$p"; return 0; fi
+  done
+  return 1
+}
+
+# kijito_truncate <string> <max> -> prints the string, ellipsised if longer than max.
+# A status line shares a terminal with everything else, so a long persona must not push the context
+# figure off the edge — the figure is the thing the user was watching before the persona existed.
+kijito_truncate() {
+  local s=$1 max=$2
+  if [ "${#s}" -le "$max" ]; then printf '%s' "$s"; return 0; fi
+  [ "$max" -le 1 ] && { printf '%s' "${s:0:$max}"; return 0; }
+  printf '%s…' "${s:0:$((max-1))}"
+}
+
+# kijito_stream_for_persona <persona> -> prints the producer's event-stream path for it, or nothing.
+# TWO NON-GUESSING ROUTES, in order (moved here from inbox-selftest.sh for row M291, so the heartbeat
+# watchdog and the self-test cannot drift — the M290 lesson):
+#   1. ask the producer: `kijito-inbox-monitor --safe-persona` publishes the persona->filename rule;
+#   2. read the streams: the producer stamps every event with the persona it was written for, so the
+#      file itself says whose mail it holds — works on a seat whose producer predates --safe-persona.
+kijito_stream_for_persona() {
+  local want=${1:-} km="" c safe="" cand
+  [ -n "$want" ] || return 1
+  for c in "${KIJITOMON_BIN:-}" "$(command -v kijito-inbox-monitor 2>/dev/null)" \
+           "$HOME/.local/bin/kijito-inbox-monitor" "/usr/local/bin/kijito-inbox-monitor"; do
+    if [ -n "$c" ] && [ -x "$c" ]; then km=$c; break; fi
+  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
+      [ -e "$cand" ] && { printf '%s' "$cand"; return 0; }
+    done
+  fi
+  command -v python3 >/dev/null 2>&1 || return 1
+  cand=$(KJ_WANT="$want" python3 - <<'PYSCAN' 2>/dev/null
+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")):
+    for path in glob.glob(pat):
+        try:
+            with open(path, "rb") as fh:
+                who = json.loads(fh.readline(65536)).get("persona")
+        except Exception:
+            continue
+        if isinstance(who, str) and who.casefold() == want:
+            hits.append(path)
+if len(hits) == 1:
+    sys.stdout.write(hits[0])
+PYSCAN
+)
+  [ -n "$cand" ] && { printf '%s' "$cand"; return 0; }
+  return 1
+}
+
+# kijito_stream_consumed <stream-path> -> 0 if a wake-capable consumer (`tail -n 0 -F …`) reads it.
+# ⚠️ ANCHOR ON WHAT THE PROCESS *IS*. An unanchored pgrep on the events path SELF-MATCHES the producer
+# (its own argv contains that path), and the harness's `bash -c … eval` wrappers carry the same argv —
+# armed-looking and deaf. Only a process whose comm is `tail` counts.
+kijito_stream_consumed() {
+  local s=${1:-} p
+  [ -n "$s" ] || return 1
+  for p in $(pgrep -f "tail -n 0 -F.*$(basename "$s")" 2>/dev/null); do
+    [ "$(ps -o comm= -p "$p" 2>/dev/null)" = tail ] && return 0
+  done
+  return 1
+}

package/providers/claude/scripts/kijito-qa-pass.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Record that /kijito-qa-memory Phase-4 cold-boot verification PASSED for THIS session.
+# self-clear.sh REQUIRES a fresh token from this before it will fire (gate C1) — i.e. you
+# cannot self-clear without a passing cold-boot verify. The token is consumed by one /clear.
+# 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"
+lc_now > "$(lc_qa_token)"
+lc_log QA_PASS "cold-boot verified"
+echo "Recorded kijito-qa-memory pass for session ${CLAUDE_CODE_SESSION_ID:-?}. self-clear unlocked for ONE clear."

package/providers/claude/scripts/lifecycle-lib.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# Shared helpers for Kijito session-lifecycle scripts. SOURCE this (`. lifecycle-lib.sh`), don't exec.
+KIJITO_LC_DIR="${KIJITO_LC_DIR:-$HOME/.claude/.lifecycle}"
+mkdir -p "$KIJITO_LC_DIR" 2>/dev/null
+KIJITO_LC_LOG="$KIJITO_LC_DIR/lifecycle.log"
+KIJITO_LC_STOP="$KIJITO_LC_DIR/STOP"
+
+lc_now() { date +%s; }                                   # epoch (portable BSD/GNU)
+
+lc_log() {                                               # M2 — audit log:  action [detail]
+  printf '%s sid=%s pane=%s %s %s\n' \
+    "$(date '+%Y-%m-%dT%H:%M:%S')" "${CLAUDE_CODE_SESSION_ID:-?}" "${TMUX_PANE:-?}" "$1" "${2:-}" \
+    >> "$KIJITO_LC_LOG" 2>/dev/null
+}
+
+lc_stopped() { [ -f "$KIJITO_LC_STOP" ]; }              # M1 — kill switch: `touch ~/.claude/.lifecycle/STOP` halts all
+
+# C3 — best-effort subagent guard. VERIFIED 2026-06-24: a subagent shares the parent's
+# CLAUDE_CODE_SESSION_ID / CLAUDE_CODE_CHILD_SESSION / ENTRYPOINT, so there is NO reliable env
+# discriminator today. This only trips on FUTURE markers and NEVER false-positives the main
+# session (both are unset now). Real C3 protection = consumable QA token + kill switch.
+# (The cycle cap was part of this list until 2026-07-29, when it was removed as non-discriminating —
+# see self-clear.sh "C2". Do not cite it as protection.)
+lc_is_child() { [ -n "${CLAUDE_AGENT_TYPE:-}" ] || [ -n "${CLAUDE_CODE_AGENT:-}" ]; }
+
+# ⛔ THIS GATE RETURNED TRUE FOR EVERY INPUT, INCLUDING GARBAGE — IT HAD NEVER ONCE REFUSED.
+# Found by argus 2026-08-01, measured on Linux tmux 3.4 AND macOS tmux 3.6a. The old body asked
+# `tmux display-message -p -t "$1" '#{session_name}'` and read its EXIT CODE — but display-message
+# EXITS 0 FOR A NONEXISTENT PANE, it simply prints empty fields:
+#     $ tmux display-message -p -t %999 'sess=#{session_name}'   ->  "sess="   rc=0
+# so `lc_pane_alive %999`, and even `lc_pane_alive nonsense`, were both TRUE.
+#
+# ★ WHY IT SURVIVED SO LONG: it was only ever exercised against a LIVE pane — the one input
+# incapable of exposing it. A control verified solely in the direction it was designed to move is
+# not verified at all. (Reproduced before fixing: %999 and "nonsense" TRUE on the old body, both
+# FALSE on this one, real pane still TRUE.)
+#
+# ⚠️ BOUNDED HONESTLY, per argus: `send-keys` itself refuses on a dead pane, and enumerating every
+# pane on the host confirmed a dead-pane /clear lands in NO pane — so this could not misfire into a
+# sibling's session on a shared seat. The gate was decorative, not dangerous.
+#
+# ENUMERATE, DON'T ASK. `list-panes -a` is the authoritative set; `grep -Fqx` matches a whole line
+# literally, so `%1` cannot match `%11` and a metacharacter in the argument cannot act as a pattern.
+# Portable across BSD and GNU userland.
+lc_pane_alive() {
+  command -v tmux >/dev/null 2>&1 || return 1
+  [ -n "${1:-}" ] || return 1
+  tmux list-panes -a -F '#{pane_id}' 2>/dev/null | grep -Fqx -- "$1"
+}
+
+# M4 (FIXED) — a running claude pane reports pane_current_command as its VERSION (e.g. "2.1.190"),
+# NOT "claude"/"node" (verified 2026-06-24). So check "not a bare shell" instead of whitelisting claude.
+lc_pane_usable() {
+  [ "${KIJITO_LC_TEST:-0}" = "1" ] && return 0          # test-harness escape hatch
+  local c; c=$(tmux display-message -p -t "$1" '#{pane_current_command}' 2>/dev/null)
+  case "$c" in ""|zsh|bash|sh|-zsh|-bash|-sh|fish|tcsh|dash) return 1 ;; *) return 0 ;; esac
+}
+
+# Arming has TWO INDEPENDENT INPUTS, and they are ORed. Keep them as separate named predicates:
+# anything that REPORTS on arming, or claims to change it, must be able to say WHICH one is in force.
+#   (1) per-pane marker — claude-armed.sh / arm-session.sh drop a file keyed to the pane; the hook
+#       (which reliably has TMUX_PANE) reads it. Session-scoped, removable by the agent.
+#   (2) KIJITO_AUTOCATCHUP=1 — a SEAT-WIDE env var, typically set in ~/.claude/settings.json, which
+#       reaches every session on the host. A running process CANNOT unset it for itself, so it is not
+#       revocable from inside a session at all.
+# ⛔ WHY THE SPLIT EXISTS: while (2) is in force, deleting the marker changes NOTHING. `arm-session.sh
+# off` did exactly that and printed "AUTONOMY OFF" — a control that reported success without acting,
+# which is worse than one that errors (measured by ladybug on the Ubuntu VM 2026-08-01: with
+# KIJITO_AUTOCATCHUP=1 live, `lc_is_armed %99999` — a pane that does not exist — returns ARMED).
+# The only brake that works against (2) is the kill switch: touch "$KIJITO_LC_DIR/STOP".
+# ⛔ A ZERO-BYTE MARKER FILE IS NOT EVIDENCE THAT *YOU* ARMED *THIS* SESSION — AND tmux PANE IDS
+# RESTART AT %0 WHEN THE SERVER RESTARTS, AND RECYCLE. ladybug found 13 stale `arm.*` markers on the
+# Mac (2026-08-01) with `arm.%2` matching a LIVE, UNRELATED pane. Markers are never garbage-collected
+# and carry no provenance, so a fresh session landing on a low-numbered pane silently INHERITS an
+# arming performed weeks ago by a different agent — and arming gates an IRREVERSIBLE `/clear`.
+# ★ THE FIX IS NOT A BETTER KEY, IT IS EVIDENCE IN THE CONTENT. Any key recycles eventually (pane
+# ids recycle; session NAMES recycle too — kill and recreate reuses the name). So the marker records
+# the SESSION FINGERPRINT it was written against, and `lc_marker_armed` re-derives that fingerprint
+# from the live tmux server on EVERY read. `#{session_created}` is immutable per session INSTANCE, so
+# a server restart or a recreated session yields a different value and the stale marker stops
+# validating — no GC required, and the check cannot be fooled by a coincidence of names.
+# ⛔ FAIL CLOSED, DELIBERATELY: no file, an EMPTY (legacy, pre-provenance) file, an unreadable
+# fingerprint, a dead pane, or any mismatch ⇒ NOT ARMED. Not-armed is the safe state — an agent that
+# wants autonomy re-arms in one second, whereas a falsely-inherited arming gates a one-way wipe.
+# ⚠️ UPGRADE NOTE: legacy zero-byte markers therefore stop counting. That is intended, it is the safe
+# direction, and `arm-session.sh status` says so explicitly rather than reporting a bare "not armed".
+# ⚠️ NOT part of the fingerprint: $CLAUDE_CODE_SESSION_ID. It ROTATES on every /clear, so validating
+# against it would disarm the pane at exactly the moment the self-clear loop needs it. It is recorded
+# for the audit trail only.
+_lc_sess_fp() {                                          # "<session_name> <session_created>"
+  command -v tmux >/dev/null 2>&1 || return 1
+  tmux display-message -p -t "$1" '#{session_name} #{session_created}' 2>/dev/null
+}
+
+lc_marker_write() {                                      # $1 = pane id (default $TMUX_PANE)
+  local pane="${1:-${TMUX_PANE:-}}" fp
+  [ -n "$pane" ] || return 1
+  lc_pane_alive "$pane" || return 1                      # enumerates; display-message alone exits 0 on a dead pane
+  fp=$(_lc_sess_fp "$pane") || return 1
+  case "$fp" in ''|' ') return 1 ;; esac
+  { echo "v=1"; echo "pane=$pane"
+    echo "session=${fp% *}"; echo "session_created=${fp##* }"
+    echo "claude_session=${CLAUDE_CODE_SESSION_ID:-}"; echo "armed_at=$(lc_now)"
+  } > "$KIJITO_LC_DIR/arm.$pane" 2>/dev/null
+}
+
+lc_marker_armed() {
+  local pane="${1:-${TMUX_PANE:-x}}" f fp want_s want_c
+  f="$KIJITO_LC_DIR/arm.$pane"
+  [ -s "$f" ] || return 1                                # missing OR legacy zero-byte → fail closed
+  want_s=$(awk -F= '$1=="session"{sub(/^[^=]*=/,"");print}' "$f" 2>/dev/null)
+  want_c=$(awk -F= '$1=="session_created"{print $2}' "$f" 2>/dev/null)
+  [ -n "$want_c" ] || return 1
+  lc_pane_alive "$pane" || return 1
+  fp=$(_lc_sess_fp "$pane") || return 1
+  [ -n "$fp" ] || return 1
+  [ "$want_c" = "${fp##* }" ] && [ "$want_s" = "${fp% *}" ]
+}
+
+lc_marker_legacy() {                                     # exists but carries no provenance
+  local f="$KIJITO_LC_DIR/arm.${1:-${TMUX_PANE:-x}}"
+  [ -f "$f" ] && [ ! -s "$f" ]
+}
+
+# ── M291: NEVER TYPE INTO A MENU ─────────────────────────────────────────────────────────────────
+# Anything that sends keys into a pane (the heartbeat nudge above all) must first ask whether the pane
+# is showing an interactive MENU rather than the chat input. The case that makes this a hard rule:
+# Claude Code's folder-trust dialog, whose second option is "No, exit" — a nudge's Enter there does
+# not deliver a prompt, it can QUIT the session, turning a stuck-but-recoverable pane into a dead one.
+# Any numbered selection menu has the same shape (Enter picks whatever is highlighted), so the rule is
+# stated for menus, with the trust dialog as the case pinned by a test.
+# Reads pane TEXT on stdin (pure, so a test can drive it with fixtures); 0 = a menu is showing.
+lc_text_is_menu() {
+  grep -Eq -- 'No, exit|Do you trust|trust (the files in )?this folder|Enter to confirm|❯ ?[0-9]+\.'
+}
+lc_pane_at_menu() {                                      # $1 = pane id; the last 20 NON-BLANK-ended lines
+  # ⚠️ capture-pane returns the WHOLE pane height, blank rows included, and a dialog drawn in a fresh
+  # pane sits at the TOP — so a bare `tail -20` of a 50-row pane reads twenty blank lines and misses the
+  # trust dialog entirely (measured by this row's own test). Trim trailing blank rows first.
+  tmux capture-pane -p -t "$1" 2>/dev/null \
+    | awk '{ l[NR] = $0 } NF { last = NR } END { s = (last > 20) ? last - 19 : 1; for (i = s; i <= last; i++) print l[i] }' \
+    | lc_text_is_menu
+}
+
+# ── M291: IS A BACKUP HEARTBEAT ALREADY WATCHING THIS PANE? ──────────────────────────────────────
+# A watchdog's argv ENDS with its pane id (hand-run, nohup, the systemd unit's `%%%i`, and a launchd
+# ProgramArguments all render `…/heartbeat-watchdog.sh %N`), so anchoring on the END is what stops
+# `%1` from matching `%11`.
+# ⚠️ KNOWN LIMIT: the argv names a pane, not a tmux SERVER. A seat running two tmux servers (a second
+# `-L` socket) can see a watchdog for ITS `%2` as one for yours; the result is a skipped start, never a
+# double one. One server per seat — the normal layout — is unaffected.
+lc_heartbeat_running() {                                 # $1 = pane id
+  [ -n "${1:-}" ] || return 1
+  pgrep -f "heartbeat-watchdog\.sh ${1}\$" >/dev/null 2>&1
+}
+
+lc_env_armed()    { [ "${KIJITO_AUTOCATCHUP:-0}" = "1" ]; }
+lc_is_armed()     { lc_marker_armed "${1:-}" || lc_env_armed; }
+
+# qa-token is SESSION-keyed (correct: each post-/clear session must earn its OWN fresh QA pass).
+lc_qa_token()   { echo "$KIJITO_LC_DIR/qa-pass.${CLAUDE_CODE_SESSION_ID:-nosession}"; }
+# The cycle counter is PANE-keyed: /clear ROTATES CLAUDE_CODE_SESSION_ID (verified live: 1c5947c1→
+# 6f305fa1 in the same pane %19), so a session-keyed counter would reset every clear and never
+# accumulate across the self-clear loop. The pane persists across clears → accumulates correctly.
+# ⚠️ Since 2026-07-29 this counter is TELEMETRY ONLY — nothing gates on it (see self-clear.sh "C2").
+# It stays because the cycle number is useful in the audit log; it is not a limit.
+lc_cycle_file() { echo "$KIJITO_LC_DIR/cycles.${TMUX_PANE:-${CLAUDE_CODE_SESSION_ID:-nosession}}"; }

package/providers/claude/scripts/myctx.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# "How full am I, really?" — hard data vs. gut. Run this when you FEEL full.
+# Bulletproof: finds THIS session's transcript via CLAUDE_CODE_SESSION_ID (no
+# "newest file" guessing), then reads the API's own token ledger (== /context).
+#
+# ⛔ THIS SCRIPT USED TO PRINT A CONFIDENT `0.0%` WHEN IT COULD NOT MEASURE, AND THAT IS WRONG IN
+# THE ONE DIRECTION THAT COSTS SOMETHING. Found by ladybug 2026-08-01, hit live at a session start.
+# On the FIRST tool call of a session the transcript carries no assistant row with `.message.usage`
+# yet; `last // {}` then yields `{}`, the arithmetic gives 0, and the output read:
+#     context: 0 tok = 0.0% of 1000k   (free: 100.0%, ~1000000 tok)
+# The ONE caller whose entire job is deciding whether to recycle was told it had a full window.
+#
+# ★ 0 IS NOT A POSSIBLE ANSWER IN A LIVE SESSION — the system prompt alone is thousands of tokens —
+# so a 0 here has only ever meant "I could not read the ledger". A meter that cannot distinguish
+# EMPTY from CANNOT-MEASURE is worse than no meter, because the felt-sense it exists to override is
+# at least known to be unreliable. ⇒ REFUSE, LOUDLY, ON STDERR, WITH A NON-ZERO EXIT. This is the
+# same rule the gate runner lives by: "I could not check" is BLOCKED, never a green number.
+set -u
+
+command -v jq >/dev/null 2>&1 || {
+  echo "myctx: UNMEASURABLE — jq is not on PATH, so the token ledger cannot be read." >&2; exit 1; }
+
+sid="${CLAUDE_CODE_SESSION_ID:?CLAUDE_CODE_SESSION_ID not set}"
+# Quote the search root: an unquoted ~/.claude/projects breaks on a HOME containing spaces, which
+# is not exotic on macOS.
+f=$(find "$HOME/.claude/projects" -name "$sid.jsonl" 2>/dev/null | head -1)
+[ -z "$f" ] && { echo "myctx: UNMEASURABLE — no transcript for session $sid" >&2; exit 1; }
+
+win="${CTX_WINDOW:-1000000}"
+used=$(jq -s 'map(select(.type=="assistant" and .message.usage!=null).message.usage)|last // {}
+              |(.input_tokens//0)+(.cache_read_input_tokens//0)+(.cache_creation_input_tokens//0)' "$f")
+
+# Refuse rather than report. `0` is folded in with empty/null deliberately — see the header.
+case "$used" in
+  ''|null|0)
+    echo "myctx: UNMEASURABLE — this session's token ledger is not populated yet (no assistant turn" >&2
+    echo "       has been flushed to the transcript). NORMAL on the first tool call of a session." >&2
+    echo "       Read the live <total_tokens> count instead. DO NOT read this as 0%." >&2
+    exit 1 ;;
+  *[!0-9]*)
+    echo "myctx: UNMEASURABLE — non-numeric ledger value ('$used')" >&2
+    exit 1 ;;
+esac
+
+awk -v u="$used" -v w="$win" 'BEGIN{
+  printf "context: %d tok = %.1f%% of %dk   (free: %.1f%%, ~%d tok)\n", u, u/w*100, w/1000, (1-u/w)*100, w-u }'