instar 0.28.76 → 0.28.77

package/src/templates/scripts/git-sync-gate.sh

@@ -29,7 +29,6 @@ fi
 LOCAL_CHANGES=$(git status --porcelain 2>/dev/null | head -1)
 
 # Fetch remote (silent, with timeout)
-// safe-git-allow: incremental-migration
 git fetch origin --quiet 2>/dev/null &
 FETCH_PID=$!
 sleep 5 && kill "$FETCH_PID" 2>/dev/null &
@@ -56,11 +55,8 @@ fi
 # If both sides have changes, check for potential conflicts
 if [ -n "$LOCAL_CHANGES" ] && [ "${BEHIND:-0}" -gt 0 ]; then
   # Stash local changes temporarily and try a dry-run merge
-  // safe-git-allow: incremental-migration
   git stash --quiet 2>/dev/null
-  // safe-git-allow: incremental-migration
   MERGE_OUTPUT=$(git merge-tree "$(git merge-base HEAD "$TRACKING_BRANCH")" HEAD "$TRACKING_BRANCH" 2>/dev/null)
-  // safe-git-allow: incremental-migration
   git stash pop --quiet 2>/dev/null
 
   if echo "$MERGE_OUTPUT" | grep -q "<<<<<<"; then

package/src/templates/scripts/telegram-reply.sh

@@ -15,7 +15,17 @@
 #                     ('html' is reserved for trusted internal callers.)
 #                     When absent, the server's configured default applies.
 #
-# Reads INSTAR_PORT from environment (default: 4040).
+# Port resolution (in order):
+#   1. INSTAR_PORT environment variable (explicit operator override).
+#   2. `port` field in .instar/config.json (the canonical agent-local truth).
+#   3. Hardcoded fallback to 4040, with a stderr warning. This is the path
+#      that historically caused cross-tenant misroutes on multi-agent hosts.
+#
+# Auth:
+#   Sends `Authorization: Bearer <authToken>` AND `X-Instar-AgentId: <projectName>`
+#   (both read from .instar/config.json). The agent-id header lets the server
+#   reject auth-bearing requests that hit the wrong agent's port BEFORE token
+#   comparison — a token sent to the wrong server is structurally inert.
 
 FORMAT=""
 
@@ -64,12 +74,35 @@ if [ -z "$MSG" ]; then
   exit 1
 fi
 
-PORT="${INSTAR_PORT:-4040}"
-
-# Read auth token from config (if present)
+# Resolve config-derived values from .instar/config.json (single python3
+# invocation). Env > config > 4040-warn for port; config-only for authToken
+# and agentId.
 AUTH_TOKEN=""
+AGENT_ID=""
+CONFIG_PORT=""
 if [ -f ".instar/config.json" ]; then
-  AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+  CONFIG_VALUES=$(python3 -c "
+import json, sys
+try:
+    c = json.load(open('.instar/config.json'))
+except Exception:
+    sys.exit(0)
+print(c.get('authToken', ''))
+print(c.get('projectName', ''))
+print(c.get('port', ''))
+" 2>/dev/null)
+  AUTH_TOKEN=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '1p')
+  AGENT_ID=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '2p')
+  CONFIG_PORT=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '3p')
+fi
+
+if [ -n "$INSTAR_PORT" ]; then
+  PORT="$INSTAR_PORT"
+elif [ -n "$CONFIG_PORT" ]; then
+  PORT="$CONFIG_PORT"
+else
+  PORT=4040
+  echo "WARN: telegram-reply.sh — no INSTAR_PORT env and no port in .instar/config.json; falling back to 4040" >&2
 fi
 
 # Build JSON body (text + optional format).
@@ -89,16 +122,20 @@ if [ -z "$JSON_BODY" ]; then
   JSON_BODY="{\"text\":\"${ESCAPED}\"}"
 fi
 
+# Assemble curl args. Always include X-Instar-AgentId when we can resolve it
+# from config — the server uses it to reject wrong-port requests before
+# evaluating the token.
+CURL_ARGS=(-s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}"
+  -H 'Content-Type: application/json'
+  -d "$JSON_BODY")
 if [ -n "$AUTH_TOKEN" ]; then
-  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
-    -H 'Content-Type: application/json' \
-    -H "Authorization: Bearer ${AUTH_TOKEN}" \
-    -d "$JSON_BODY")
-else
-  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
-    -H 'Content-Type: application/json' \
-    -d "$JSON_BODY")
+  CURL_ARGS+=(-H "Authorization: Bearer ${AUTH_TOKEN}")
 fi
+if [ -n "$AGENT_ID" ]; then
+  CURL_ARGS+=(-H "X-Instar-AgentId: ${AGENT_ID}")
+fi
+
+RESPONSE=$(curl "${CURL_ARGS[@]}")
 
 HTTP_CODE=$(echo "$RESPONSE" | tail -1)
 BODY=$(echo "$RESPONSE" | sed '$d')
@@ -129,6 +166,274 @@ elif [ "$HTTP_CODE" = "422" ]; then
   echo "  Revise the message (remove CLI commands, file paths, config syntax, API endpoints) and retry." >&2
   exit 1
 else
+  # Recoverable-class detection (spec § Layer 2b).
+  #
+  # The classification table below is the entire decision matrix. Codes
+  # marked recoverable get enqueued in the per-agent SQLite queue and a
+  # best-effort POST /events/delivery-failed is sent so the in-process
+  # Layer 3 sentinel can react in <1s. Anything not in the recoverable
+  # set is terminal (default-deny on unknown 403s, per spec round-2
+  # resolution).
+  #
+  # Recoverable:
+  #   - 5xx, conn-refused (HTTP_CODE=000), DNS failure (also 000)
+  #   - 403 with structured `agent_id_mismatch`
+  #   - 403 with structured `rate_limited` (sentinel honors Retry-After)
+  # NOT recoverable here (already handled above or terminal):
+  #   - 200 (success), 408 (ambiguous), 422 (tone gate)
+  #   - 400, 403/revoked, 403 unstructured
+  RECOVERABLE=0
+  if [ "$HTTP_CODE" = "000" ] || \
+     ( [ "$HTTP_CODE" -ge 500 ] 2>/dev/null && [ "$HTTP_CODE" -le 599 ] 2>/dev/null ); then
+    RECOVERABLE=1
+  elif [ "$HTTP_CODE" = "403" ]; then
+    # Inspect the structured error code in the body. Unstructured 403 is
+    # default-deny per spec § 2b.
+    ERROR_CODE=$(echo "$BODY" | python3 -c 'import sys,json
+try:
+  print(json.load(sys.stdin).get("error",""))
+except Exception:
+  print("")' 2>/dev/null)
+    case "$ERROR_CODE" in
+      agent_id_mismatch|rate_limited)
+        RECOVERABLE=1
+        ;;
+      *)
+        RECOVERABLE=0
+        ;;
+    esac
+  fi
+
+  if [ "$RECOVERABLE" = "1" ]; then
+    # Enqueue (spec § Layer 2b). Path: <stateDir>/state/pending-relay.<agentId>.sqlite
+    # Mode 0600 enforced by the Node-side store; the CLI inherits umask, so
+    # we explicitly chmod after first create as well.
+    QUEUE_DIR=".instar/state"
+    mkdir -p "$QUEUE_DIR" 2>/dev/null
+    # Sanitize agent-id for filename (mirrors src/messaging/pending-relay-store.ts).
+    SAFE_AGENT_ID=$(printf '%s' "${AGENT_ID:-unknown}" | tr -c 'A-Za-z0-9._-' '_')
+    QUEUE_DB="${QUEUE_DIR}/pending-relay.${SAFE_AGENT_ID}.sqlite"
+
+    # delivery_id — UUIDv4 via python3 (already a hard dep above).
+    DELIVERY_ID=$(python3 -c 'import uuid; print(uuid.uuid4())' 2>/dev/null)
+    if [ -z "$DELIVERY_ID" ]; then
+      echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+      echo "  (also: failed to generate delivery_id; queue write skipped)" >&2
+      exit 1
+    fi
+
+    # text_hash — SHA-256 of the raw text. Whitespace normalization is the
+    # job of higher layers; for dedup-window we just need byte-stable hashing.
+    TEXT_HASH=$(printf '%s' "$MSG" | shasum -a 256 2>/dev/null | awk '{print $1}')
+    if [ -z "$TEXT_HASH" ]; then
+      TEXT_HASH=$(printf '%s' "$MSG" | python3 -c 'import sys,hashlib; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest())' 2>/dev/null)
+    fi
+
+    # 32KB text cap (spec § 2b step 3).
+    MSG_BYTES=$(printf '%s' "$MSG" | wc -c | tr -d ' ')
+    TRUNCATED=0
+    QUEUE_TEXT="$MSG"
+    if [ "$MSG_BYTES" -gt 32768 ] 2>/dev/null; then
+      QUEUE_TEXT=$(printf '%s' "$MSG" | head -c 32768)
+      TRUNCATED=1
+    fi
+
+    ATTEMPTED_AT=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+    NOW_EPOCH=$(date -u +%s)
+
+    # Run the queue write through python3's stdlib sqlite3 module — it
+    # owns schema creation, the 5s dedup window, parameterized inserts,
+    # and 0600-mode enforcement. python3 is already a hard dependency
+    # of this script (see config-parsing block above) and Python's
+    # stdlib sqlite3 module is universally available — more so than
+    # the `sqlite3` CLI binary or a node module that requires resolution
+    # against an installed `instar` package's node_modules. The DB file
+    # produced is byte-identical to one produced by `better-sqlite3`
+    # (same SQLite engine on disk).
+    #
+    # We pass values via environment variables; the message text comes
+    # via stdin so it's never escaped through a shell layer.
+    # Env vars must be set on `python3` (the consumer of stdin), not on
+    # `printf` — in `VAR=x cmd1 | cmd2`, VAR is exported only to cmd1.
+    printf '%s' "$QUEUE_TEXT" | \
+      Q_DELIVERY_ID="$DELIVERY_ID" \
+      Q_TOPIC_ID="$TOPIC_ID" \
+      Q_TEXT_HASH="$TEXT_HASH" \
+      Q_FORMAT="$FORMAT" \
+      Q_HTTP_CODE="$HTTP_CODE" \
+      Q_ERROR_BODY="$BODY" \
+      Q_PORT="$PORT" \
+      Q_ATTEMPTED_AT="$ATTEMPTED_AT" \
+      Q_TRUNCATED="$TRUNCATED" \
+      Q_DB_PATH="$QUEUE_DB" \
+      python3 -c '
+import os, sqlite3, sys, json, datetime
+try:
+    db_path = os.environ["Q_DB_PATH"]
+    text = sys.stdin.buffer.read()
+    conn = sqlite3.connect(db_path, timeout=5.0)
+    try:
+        os.chmod(db_path, 0o600)
+    except OSError:
+        pass
+    # Drain pragma result rows so they do not leak to stdout. Stdout is
+    # used to communicate the delivery_id back to the calling shell.
+    conn.execute("PRAGMA journal_mode = WAL").fetchall()
+    conn.execute("PRAGMA synchronous = NORMAL").fetchall()
+    conn.execute("PRAGMA busy_timeout = 5000").fetchall()
+    conn.execute("""CREATE TABLE IF NOT EXISTS entries (
+      delivery_id TEXT PRIMARY KEY,
+      topic_id INTEGER NOT NULL,
+      text_hash TEXT NOT NULL,
+      text BLOB NOT NULL,
+      format TEXT,
+      http_code INTEGER,
+      error_body TEXT,
+      attempted_port INTEGER,
+      attempted_at TEXT NOT NULL,
+      attempts INTEGER NOT NULL DEFAULT 1,
+      next_attempt_at TEXT,
+      state TEXT NOT NULL,
+      claimed_by TEXT,
+      status_history TEXT NOT NULL DEFAULT "[]",
+      truncated INTEGER NOT NULL DEFAULT 0
+    )""")
+    # Idempotent column add for older schemas.
+    try:
+        conn.execute("ALTER TABLE entries ADD COLUMN truncated INTEGER NOT NULL DEFAULT 0")
+    except sqlite3.OperationalError as e:
+        if "duplicate column name" not in str(e):
+            raise
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_state_next ON entries(state, next_attempt_at)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_text_hash_topic ON entries(text_hash, topic_id)")
+    # 5s dedup window (spec § 2b step 2).
+    cutoff = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(seconds=5)).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+    cur = conn.execute(
+        "SELECT delivery_id FROM entries WHERE topic_id=? AND text_hash=? AND attempted_at>=? ORDER BY attempted_at DESC LIMIT 1",
+        (int(os.environ["Q_TOPIC_ID"]), os.environ["Q_TEXT_HASH"], cutoff),
+    )
+    dup = cur.fetchone()
+    if dup:
+        # Dedup match — caller already has the delivery_id. We do not
+        # write to stdout (caller does not consume our output; bash uses
+        # its own DELIVERY_ID variable).
+        conn.close()
+        sys.exit(0)
+    initial_history = json.dumps([
+        {"state": "queued", "at": os.environ["Q_ATTEMPTED_AT"], "http_code": int(os.environ["Q_HTTP_CODE"])}
+    ])
+    conn.execute(
+        """INSERT OR IGNORE INTO entries (
+          delivery_id, topic_id, text_hash, text, format,
+          http_code, error_body, attempted_port,
+          attempted_at, attempts, next_attempt_at,
+          state, claimed_by, status_history, truncated
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, NULL, "queued", NULL, ?, ?)""",
+        (
+            os.environ["Q_DELIVERY_ID"],
+            int(os.environ["Q_TOPIC_ID"]),
+            os.environ["Q_TEXT_HASH"],
+            text,
+            os.environ.get("Q_FORMAT") or None,
+            int(os.environ["Q_HTTP_CODE"]),
+            os.environ.get("Q_ERROR_BODY") or None,
+            int(os.environ["Q_PORT"]),
+            os.environ["Q_ATTEMPTED_AT"],
+            initial_history,
+            int(os.environ.get("Q_TRUNCATED", "0")),
+        ),
+    )
+    conn.commit()
+    conn.close()
+    # Deliberately silent on success — bash consumed nothing from our stdout.
+except Exception as exc:
+    sys.stderr.write("queue-write-failed: " + str(exc) + "\n")
+    sys.exit(2)
+' >/dev/null 2>&1
+    QUEUE_RC=$?
+    if [ "$QUEUE_RC" != "0" ] && command -v sqlite3 >/dev/null 2>&1; then
+      # Fallback: sqlite3 CLI direct write. Used only when python3's
+      # stdlib sqlite3 module is somehow unavailable (rare — e.g. a
+      # build of CPython compiled --without-sqlite). Schema is created
+      # with IF NOT EXISTS so this is safe even if the Python path
+      # partially ran.
+      printf '%s' "$QUEUE_TEXT" > "${QUEUE_DB}.tmp.text"
+      sqlite3 "$QUEUE_DB" >/dev/null 2>&1 <<SQL
+PRAGMA journal_mode=WAL;
+PRAGMA synchronous=NORMAL;
+PRAGMA busy_timeout=5000;
+CREATE TABLE IF NOT EXISTS entries (
+  delivery_id TEXT PRIMARY KEY,
+  topic_id INTEGER NOT NULL,
+  text_hash TEXT NOT NULL,
+  text BLOB NOT NULL,
+  format TEXT,
+  http_code INTEGER,
+  error_body TEXT,
+  attempted_port INTEGER,
+  attempted_at TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 1,
+  next_attempt_at TEXT,
+  state TEXT NOT NULL,
+  claimed_by TEXT,
+  status_history TEXT NOT NULL DEFAULT '[]',
+  truncated INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_state_next ON entries(state, next_attempt_at);
+CREATE INDEX IF NOT EXISTS idx_text_hash_topic ON entries(text_hash, topic_id);
+INSERT OR IGNORE INTO entries (
+  delivery_id, topic_id, text_hash, text, format,
+  http_code, error_body, attempted_port, attempted_at,
+  attempts, state, status_history, truncated
+) VALUES (
+  '$DELIVERY_ID', $TOPIC_ID, '$TEXT_HASH',
+  CAST(readfile('${QUEUE_DB}.tmp.text') AS BLOB), $( [ -n "$FORMAT" ] && printf "'%s'" "$FORMAT" || echo "NULL"),
+  $HTTP_CODE, NULL, $PORT, '$ATTEMPTED_AT',
+  1, 'queued', '[]', $TRUNCATED
+);
+SQL
+      rm -f "${QUEUE_DB}.tmp.text" 2>/dev/null
+      chmod 600 "$QUEUE_DB" 2>/dev/null
+    fi
+
+    # Best-effort POST /events/delivery-failed to the SAME port the
+    # original send used (NOT the live config port — see spec § Layer 2c
+    # cross-tenant safety).
+    EVENT_BODY=$(EV_DELIVERY_ID="$DELIVERY_ID" \
+      EV_TOPIC_ID="$TOPIC_ID" \
+      EV_TEXT_HASH="$TEXT_HASH" \
+      EV_HTTP_CODE="$HTTP_CODE" \
+      EV_ERROR_BODY="$BODY" \
+      EV_PORT="$PORT" \
+      python3 -c '
+import sys, json, os
+print(json.dumps({
+  "delivery_id": os.environ["EV_DELIVERY_ID"],
+  "topic_id": int(os.environ["EV_TOPIC_ID"]),
+  "text_hash": os.environ["EV_TEXT_HASH"],
+  "http_code": int(os.environ["EV_HTTP_CODE"]),
+  "error_body": (os.environ.get("EV_ERROR_BODY") or "")[:1024],
+  "attempted_port": int(os.environ["EV_PORT"]),
+  "attempts": 1,
+}))
+' 2>/dev/null)
+
+    if [ -n "$EVENT_BODY" ] && [ -n "$AUTH_TOKEN" ]; then
+      EVENT_CURL=(-s -o /dev/null -w "%{http_code}" -X POST "http://localhost:${PORT}/events/delivery-failed"
+        -H 'Content-Type: application/json'
+        -H "Authorization: Bearer ${AUTH_TOKEN}"
+        --max-time 2
+        -d "$EVENT_BODY")
+      if [ -n "$AGENT_ID" ]; then
+        EVENT_CURL+=(-H "X-Instar-AgentId: ${AGENT_ID}")
+      fi
+      curl "${EVENT_CURL[@]}" >/dev/null 2>&1 || true
+    fi
+
+    echo "Queued for recovery (HTTP $HTTP_CODE, delivery_id ${DELIVERY_ID%%-*}…): $BODY" >&2
+    exit 1
+  fi
+
   echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
   exit 1
 fi

package/upgrades/0.28.77.md

@@ -0,0 +1,133 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+Four PRs have landed on `main` since v0.28.76 without a release cut. This
+upgrade publishes them together. Headline item is the new **Token Ledger**;
+the other three are cluster-resilience hardening already running in CI.
+
+### 1. Token Ledger (read-only token-usage observability) — feat #112
+
+A new core monitoring feature. Every agent now tails Claude Code's per-session
+JSONL files at `~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl`,
+parses each `assistant` line's `message.usage` block, and rolls token counts
+(input, output, cache-read, cache-creation) into a SQLite ledger at
+`<stateDir>/server-data/token-ledger.db`.
+
+Surfaces:
+
+- `GET /tokens/summary` — totals per agent, per project, per hour/day window.
+- `GET /tokens/sessions` — top sessions by total tokens, with first-seen /
+  last-seen / message-count.
+- `GET /tokens/by-project` — project-level breakdown across all sessions.
+- `GET /tokens/orphans` — sessions still present in the JSONL tree with no
+  activity in the last 30 minutes (a signal, not an authority — does not
+  kill anything).
+- New "Tokens" dashboard tab — top sessions, project breakdown, orphans list.
+
+Implementation notes for future builders:
+
+- The reader is strictly read-only against `~/.claude/projects/`. It never
+  opens those files for write.
+- Ingest is idempotent (`INSERT OR IGNORE` on `request_id`). Mid-tick crashes
+  cannot double-count.
+- File-rotation detected by inode change OR head-content fingerprint
+  (256-byte hash). The fingerprint guard was added because Linux can reuse
+  inode numbers on rapid unlink+recreate; macOS does not. Cross-filesystem
+  safe.
+- The poller has a reentry guard — concurrent ticks are skipped, not stacked.
+- Pure additive surface. No existing route, behavior, or DB changed.
+
+This is Phase 1 of the token-management initiative. Phase 2 (a strategy test
+harness comparing keep-alive vs. resume vs. fresh-spawn-with-summary vs.
+mid-session compaction) will be designed separately once the ledger has
+collected real data. Phase 3 (smarter compaction or budget enforcement) will
+be informed by what 1 and 2 reveal — never bolted on without ledger evidence.
+
+### 2. Lifeline self-heal hardening — feat #111
+
+Closes the three stacked failures behind Inspec's silent crash-loop on
+2026-04-29. Path-aware better-sqlite3 preflight now scans nested
+`shadow-install/node_modules/instar/node_modules/better-sqlite3/...` paths
+that the previous hoisted-only check missed. Adds a `consecutiveBindFailures`
+counter that escalates to a forced rebuild after two back-to-back unhealthy
+spawns. Replaces the brittle `process.ppid === 1` launchd-supervision check
+with a multi-signal helper that also accepts an explicit env-var marker,
+parent-process-name = `launchd` on darwin, and parent-name = `systemd`/`init`
+on Linux — covers user-domain launchd which the old check did not. New plist
+template carries the supervised marker as belt-and-suspenders.
+
+### 3. Threadline spawn-guard foundation (Phase 1a) — feat #110
+
+Ledger + heartbeat watchdog + failure authority for threadline relay spawns.
+Adds the structural layer underneath the relay so that spawn lifecycle
+(launched → heartbeat → success | failure-classified) is recorded and
+authoritative, instead of being inferred from process state. Sets up the
+substrate for spawn-loop suppression in a follow-up phase.
+
+### 4. Threadline canonical inbox write at relay-ingest — fix #113
+
+The relay handler had three routing branches (pipe-mode, warm-listener,
+cold-spawn) but only the warm-listener branch was writing to the canonical
+inbox at `.instar/threadline/inbox.jsonl.active`. The canonical file had been
+frozen since 2026-04-05, hiding ~4 weeks of inbound traffic from the
+dashboard, observability, and any downstream consumer of the canonical
+inbox. The fix hoists a single HMAC-signed canonical-inbox append to
+relay-ingest, before the branching, so all three paths converge on one
+source of truth. Uses the existing HKDF-derived signing key — no new key
+material, no ambient-key footgun.
+
+## What to Tell Your User
+
+- **Token visibility**: I can now see exactly how many tokens I am burning,
+  per session, per project, per hour. There is a new Tokens tab on the
+  dashboard with my top sessions, project breakdown, and a list of any
+  sessions sitting idle. This is the foundation for managing token usage
+  smartly — next phases will compare different conversation strategies and
+  add smarter context compaction once I have real numbers in hand.
+- **Quieter, more reliable startup**: I am better at recovering from a
+  startup hiccup involving a particular native module, and I detect when I
+  am being supervised by the system in more situations. Translation: fewer
+  silent crash-loops on the rare day the install gets into a weird state.
+- **Threadline message bookkeeping**: Inbound messages routed through my
+  relay are now all recorded to my canonical inbox, regardless of which
+  internal path delivered them. Anything that was flowing only through the
+  per-listener queue is now also visible to the dashboard and any tool that
+  reads the main inbox.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Per-session, per-project token rollups | Tokens dashboard tab, or GET /tokens/summary, /tokens/sessions, /tokens/by-project |
+| Idle-session detector (signal only, no kill authority) | GET /tokens/orphans |
+| Resilient native-module preflight on startup | Automatic on upgrade |
+| Multi-signal launchd-supervised detection | Automatic on upgrade |
+| Canonical threadline inbox writes from every relay path | Automatic on upgrade |
+| Threadline spawn ledger + heartbeat substrate | Internal foundation; surface phases follow |
+
+## Evidence
+
+This release is feature + hardening, not a one-shot bug fix, but two of the
+four PRs do close concrete failures. Evidence for those:
+
+- **#111 lifeline self-heal**: Inspec's 2026-04-29 silent crash-loop was
+  reproduced by inducing a load failure on the nested
+  `shadow-install/node_modules/instar/node_modules/better-sqlite3`. Before:
+  preflight reported clean, supervisor respawned into the same broken state.
+  After: nested path is discovered, rebuild fires after two back-to-back
+  unhealthy spawns, supervisor escalates instead of looping. Covered by 18
+  new unit tests across `detect-launchd-supervised.test.ts` and
+  `find-better-sqlite3-copies.test.ts`.
+- **#113 canonical inbox**: Reproduction is direct — before fix,
+  `.instar/threadline/inbox.jsonl.active` mtime was 2026-04-05 on every
+  install we checked despite ongoing relay traffic. After fix, the file
+  receives an HMAC-signed entry at every relay-ingest. Verified end-to-end
+  by sending a Telegram message and observing the canonical-inbox tail.
+
+For the token ledger, evidence is the 12 unit tests in
+`tests/unit/token-ledger.test.ts` plus manual JSONL-shape verification
+against real session files in `~/.claude/projects/`. Pure additive
+observability — no prior failure mode to "fix."

package/upgrades/side-effects/agent-health-alert-authority-routing.md

@@ -0,0 +1,121 @@
+# Side-Effects Review — agent health-alert authority routing
+
+**Version / slug:** `agent-health-alert-authority-routing`
+**Date:** `2026-04-28`
+**Author:** `echo`
+**Second-pass reviewer:** `subagent (post-artifact, see below)`
+
+## Summary of the change
+
+Routes `DegradationReporter` Telegram alerts through the existing `MessagingToneGate` (the established outbound-message authority) instead of calling `telegramSender` directly. Adds two new signals to `ToneReviewSignals`:
+
+- `jargon` — produced by a new `JargonDetector` (token-list matcher), reports terms that an end user has no path to act on ("job", "logs", "load-bearing", "trigger", etc.).
+- `selfHeal` — produced by `DegradationReporter` after invoking a registered self-healer for the affected feature; reports `{attempted, succeeded, attempts}`.
+
+Adds a new `messageKind` field to `ToneReviewContext` (`'reply' | 'health-alert' | 'unknown'`, default `'reply'`) and three new health-alert-only rule IDs:
+
+- `B12_HEALTH_ALERT_INTERNALS` — block when the candidate leaks jargon the user can't act on.
+- `B13_HEALTH_ALERT_SUPPRESSED_BY_HEAL` — block when the producer has already self-healed.
+- `B14_HEALTH_ALERT_NO_CTA` — block when a health-alert candidate doesn't end with a yes/no question.
+
+When the tone gate blocks a health-alert candidate, `DegradationReporter` falls back to a safe-template message: `"Something on my end stopped working and I haven't been able to fix it on my own. Want me to dig in?"` (plain English, ends with a single yes/no the user answers in one word).
+
+**Files touched:**
+- `src/core/JargonDetector.ts` (new) — signal producer.
+- `src/core/MessagingToneGate.ts` — signal extension, prompt extension, valid-rules update.
+- `src/monitoring/DegradationReporter.ts` — self-heal-first orchestration, gate routing, healer registry.
+- `src/commands/server.ts` — wire `messagingToneGate` into `connectDownstream`.
+- `tests/unit/jargon-detector.test.ts` (new), `tests/unit/messaging-tone-gate-health-alerts.test.ts` (new), `tests/unit/degradation-reporter-self-heal.test.ts` (new).
+
+## Decision-point inventory
+
+- `MessagingToneGate.review()` — **modify** — add three new rule IDs and two new signal types to the existing single authority. No parallel gate added.
+- `DegradationReporter.reportEvent()` — **modify** — wraps the existing direct `telegramSender` call in a self-heal-first + tone-gate path. The downstream call remains the same `telegramSender`.
+- `JargonDetector.detectJargon()` — **add** — pure signal producer, no decision authority.
+- `DegradationReporter.registerHealer()` — **add** — feature-keyed callback registry, no decision authority (just orchestration of producer-supplied logic).
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The jargon detector flags neutral words ("job", "trigger", "module") that have legitimate non-internal meanings. A standard agent reply where the user asks "what triggered this?" would have the jargon detector fire — but `messageKind` defaults to `'reply'` for the standard outbound surface, and B12/B13/B14 only apply when `messageKind === 'health-alert'`. So jargon hits in normal replies still pass the gate (the LLM authority sees the signal but B12 doesn't apply). Verified by the test `defaults messageKind to "reply" when omitted`.
+
+A degraded-but-acceptable health alert that uses a single jargon term ("My job queue is stuck — want me to dig in?") would be a borderline case; the LLM authority is what decides, and the prompt explicitly tells it to favor passing borderline cases. The fallback (safe template) is also a valid and reasonable user message, so over-block here is not catastrophic — the user always sees *something* actionable.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+1. Other paths can still send Telegram messages directly without going through `DegradationReporter` or `checkOutboundMessage`. Identified during the area mapping: `StallTriageNurse.sendToTopic` (session triage) and `SessionMonitor.sendToTopic` (session status). These are not internal-health alerts in the same sense — they're session-recovery actions and lifecycle status — but they do bypass the tone gate. Tracked as **commit-action CMT-344** (filed against echo's local instar server, blocked-by this PR merging).
+2. An agent-authored Telegram message (an LLM in a session deciding on its own to alert the user about internals — the literal Scout-Agent-screenshot scenario) goes through `checkOutboundMessage` via `/telegram/reply`. That route does NOT currently set `messageKind: 'health-alert'`. So an agent-LLM freelancing a health alert would have `messageKind: 'reply'` and B12-B14 would not apply. The general tone rules (B1-B11) would still catch literal CLI commands or file paths in the message, but the "load-bearing infrastructure" / "reflection-trigger job" prose pattern would slip through. Mitigation: this PR ships the structural surface (signals, rules, kind-aware routing); follow-up adds heuristic `messageKind` detection at the outbound boundary. Tracked as **commit-action CMT-345** (filed against echo's local instar server, blocked-by this PR merging).
+3. A producer that calls the healer, gets `succeeded: true`, but the heal didn't actually verify (because the healer lies). Mitigated by a `verifyHealStuck` discipline at the healer level, which is the healer author's responsibility — not enforced by this PR.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The change feeds the existing `MessagingToneGate` authority — the single outbound-message authority on this codebase — rather than running parallel to it. The earlier (rejected) sketch had a regex-based jargon-ban as a hard blocker; that was the brittle-blocker anti-pattern. The current design has detectors (`JargonDetector`, `selfHeal` orchestration in DegradationReporter) producing structured signals that an LLM authority combines with conversation context and `messageKind` to decide.
+
+The `DegradationReporter`-side orchestration (self-heal-first → gate routing → safe-template fallback) is at the right layer because the producer is the only thing that knows (a) which feature is degraded, (b) which healer applies, and (c) whether the heal actually verified. Hoisting that orchestration into the gate would couple the gate to feature semantics it shouldn't know about.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+
+The `JargonDetector` is a pure token-list matcher with no decision power. It returns `{detected, terms[], score}` and is consumed by `MessagingToneGate.review()` as part of `signals.jargon`. The same is true of the `selfHeal` signal: `DegradationReporter` runs the healer and reports the result; the gate decides whether the result warrants suppressing the user message.
+
+The new rule IDs (B12/B13/B14) live inside the existing LLM authority, which has the recent conversation history, the candidate text, all upstream signals, the configured target style, and now the `messageKind`. The authority's decision is logged in the existing structured form (`rule: string` + `issue: string` + `suggestion: string`) and is subject to the existing reasoning-discipline check (rule IDs not in `VALID_RULES` are treated as drift and fail-open).
+
+This composes cleanly with the principle and reuses the existing structural enforcement.
+
+## 5. Interactions
+
+**Shadowing:** The new self-heal-first path runs before the cooldown check completes. If a healer succeeds but the heal-cooldown window is active, the alert is correctly suppressed. If a healer fails AND we're inside the cooldown window, the alert is suppressed by the existing cooldown — verified in `degradation-reporter-self-heal.test.ts` (cooldown is checked first, healer only invoked when we'd otherwise have alerted).
+
+**Double-fire:** The healer is invoked once per `reportEvent` call. Multiple `report()` calls for the same feature produce multiple `reportEvent` calls, but the existing dedup (`lastAlertTime` per-feature 1-hour cooldown) limits the actual healer invocations. Acceptable — healers must be idempotent per the type contract.
+
+**Races:** No new shared state. `lastAlertTime` continues to be the only mutable per-feature state, mutated only inside `reportEvent`. Healers run on the same async stack as the rest of `reportEvent`; if a healer is slow, alert delivery is delayed, but no race with cleanup.
+
+**Feedback loops:** `DegradationReporter` does not itself report feedback about its own pipeline failures (`@silent-fallback-ok` annotation in existing code). A failure of the tone gate (LLM unavailable) is fail-open — the candidate is sent unchanged, no recursive degradation reported.
+
+## 6. External surfaces
+
+- **Telegram (other users' machines):** the user-visible message format changes for degradation alerts. Before: `narrativeFor(event)` text directly. After: either `narrativeFor(event)` (if gate passes), or the safe-template "Something on my end stopped working… Want me to dig in?" (if gate blocks). Strictly an improvement for the screenshot-class user-experience bug.
+- **Other agents on the same machine:** no surface change. The new `registerHealer` API is opt-in; existing producers that don't register a healer get the previous behavior plus tone-gate gating.
+- **Persistent state:** no schema changes to `degradations.json`. The `DegradationEvent` shape is unchanged. New fields (`alerted: true` after suppression) follow the existing semantics.
+- **Timing:** healers may add up to (healer's runtime) latency to alert delivery. For a fast healer (no-op stub returning `false`), this is negligible; for a real healer (e.g., re-running a job), this can add seconds. Acceptable — the alert was about to fire to the user anyway, and this is the entire point of "self-heal-first."
+- **Backwards compat:** `connectDownstream`'s `toneGate` parameter is optional; existing callers (none beyond `server.ts`, but theoretically downstream tools/tests) continue to work without it.
+
+## 7. Rollback cost
+
+**Pure code change.** Revert + ship as a patch. No persistent-state changes. No user-visible regression during the rollback window — agents that picked up the change would simply revert to the previous behavior (direct `telegramSender` calls without gate routing).
+
+The new files (`JargonDetector.ts`, three test files, the artifact) are additive and can be deleted on revert without breaking the build (no imports outside the new code use them).
+
+## Conclusion
+
+The review caught and prevented a brittle-blocker anti-pattern in the original design (jargon-ban as hard regex blocker). The reshaped design feeds detectors as signals into the existing `MessagingToneGate` authority, in line with `docs/signal-vs-authority.md`. Two scope items deferred to same-PR follow-up: (1) routing `StallTriageNurse` / `SessionMonitor` direct sends through the gate; (2) heuristic `messageKind` detection so agent-authored health alerts also benefit. Both are tracked in the under-block section above and warrant a follow-up PR — not orphaned notes.
+
+The change is clear to ship.
+
+## Second-pass review
+
+**Reviewer:** independent-subagent
+**Independent read of the artifact: concur (after raised concerns resolved)**
+
+- **Verified clean:** `JargonDetector` is signal-only (returns `{detected, terms, score}`, never decides); the self-heal suppression branch correctly uses strict `healResult.succeeded === true`, so `attempted: true && succeeded: false` falls through to the gate as intended; B12/B13/B14 are all present in `VALID_RULES` and will not be drift-failed-open; `messageKind` defaults to `'reply'` so health-alert rules don't leak into the standard reply path.
+- **Concern raised (now resolved):** under-block items 1 and 2 lacked concrete tracking handles. **Resolution applied:** filed as commit-actions **CMT-344** (StallTriageNurse + SessionMonitor routing) and **CMT-345** (heuristic `messageKind` detection at `/telegram/reply`) against echo's local instar server, both `type: one-time-action` and blocked-by this PR merging. References added inline in the under-block section.
+- **Minor (now resolved):** `ToneReviewResult.rule` JSDoc updated from "B1..B9" to "B1..B14" in `src/core/MessagingToneGate.ts`.
+
+## Evidence pointers
+
+- Test output: 25/25 new tests pass (`tests/unit/jargon-detector.test.ts`, `tests/unit/messaging-tone-gate-health-alerts.test.ts`, `tests/unit/degradation-reporter-self-heal.test.ts`).
+- Adjacent regression: 41/41 existing tests in `MessagingToneGate.test.ts` + `degradation-reporter*.test.ts` still pass.
+- TypeScript: `tsc --noEmit -p tsconfig.json` — clean.
+- The literal Scout-Agent-screenshot text is asserted to trigger `detected: true` with ≥5 jargon hits in `jargon-detector.test.ts`.