instar 0.28.75 → 0.28.77

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.76.md

@@ -0,0 +1,67 @@
+# Upgrade Guide — v0.28.76
+
+<!-- bump: patch -->
+
+## What Changed
+
+`POST /internal/telegram-forward` no longer reports the backward-compat
+`TelegramLifeline.versionMissing` event into the feedback pipeline as a
+`[DEGRADATION]` signal. The condition (an upgraded but un-restarted lifeline
+forwarding a Telegram message without the Stage-B `lifelineVersion` field) is
+expected, accepted, and documented behaviour — emitting it as a critical
+degradation was producing noisy regressions in cluster
+`cmo7wswhj0000mgmdbw4j7dyd` every time any pre-Stage-B lifeline forwarded a
+message.
+
+The forward itself still succeeds via the documented backward-compat path;
+the response, the inbound-message log, and the version-handshake logic for
+lifelines that *do* send `lifelineVersion` are all unchanged. On the first
+occurrence per server process, a one-shot `console.info` is emitted so the
+operator-side observability signal is preserved without per-request log
+spam.
+
+The systemic work to give `DegradationReporter` a typed severity / category
+field (so callers can mark events as ERROR vs COMPAT_SIGNAL at the reporter
+layer rather than the call site) remains tracked under PROP-543 and is
+deliberately out of scope for this release.
+
+## What to Tell Your User
+
+- **Quieter feedback signal**: I won't keep logging a critical-looking
+  message every time my lifeline forwards a Telegram note before I've had a
+  chance to restart it. The forward still works the same way; only the
+  noisy critical report goes away.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Quieter pre-Stage-B lifeline forwards | Automatic on upgrade |
+
+## Evidence
+
+Reproduction (before fix):
+
+1. Run a lifeline at v0.28.67 or later, then upgrade the server-side package
+   without restarting the lifeline daemon.
+2. Send a Telegram message that the lifeline forwards via
+   `POST /internal/telegram-forward`.
+3. The handler accepts the forward and emits a
+   `[DEGRADATION] TelegramLifeline.versionMissing: …` feedback event,
+   classified as critical by the Portal cluster intake.
+
+After fix:
+
+1. Same setup; same forward; same successful response.
+2. On the first forward per server process, a single
+   `[telegram-forward] Accepted pre-Stage-B lifeline forward …`
+   `console.info` is emitted; subsequent forwards on the same process emit
+   nothing.
+3. No `TelegramLifeline.versionMissing` feedback events are submitted, so
+   cluster `cmo7wswhj0000mgmdbw4j7dyd` does not auto-reopen on every
+   forward.
+
+`grep -rn versionMissing src/ tests/ test/ __tests__/` shows the symbol
+appears only in `routes.ts` (the one-shot guard and the comment explaining
+it). No test changed because the call site has no existing test coverage of
+the reporter side-effect.

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/0.28.76.md

@@ -0,0 +1,76 @@
+# Side-Effects Review — TelegramLifeline.versionMissing → info-only log
+
+**Slug:** `telegram-lifeline-version-missing-info`
+**Date:** `2026-04-27`
+**Author:** Dawn (instar-bug-fix autonomous job)
+**Cluster:** `cmo7wswhj0000mgmdbw4j7dyd` (severity: critical → resolved by reclassification)
+
+## Summary of the change
+
+In `src/server/routes.ts`, the backward-compat branch of the `POST /internal/telegram-forward` handler stops emitting `TelegramLifeline.versionMissing` as a `[DEGRADATION]` feedback event. The forward itself is still accepted via the documented backward-compat path; only the *classification* of the observed transition changes.
+
+Concretely:
+
+- The call to `DegradationReporter.getInstance().report({ feature: 'TelegramLifeline.versionMissing', … })` is removed from `routes.ts:6367-6376`.
+- A one-shot `console.info` is emitted on first occurrence per process, gated by a new module-scoped `_versionMissingLogged` flag declared next to the existing `_serverVersionParsed` cache.
+- No other lines of code change. No new files. No test files added or modified — the call site has no existing test coverage and the change is observability-only.
+
+Files touched:
+- `src/server/routes.ts` — two small edits described above.
+- `docs/specs/telegram-lifeline-version-missing-info.md` — new spec (LOW-risk autonomous-approved).
+- `upgrades/side-effects/telegram-lifeline-version-missing-info.md` — this file.
+- `upgrades/NEXT.md` — release notes appended.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None. The handler still accepts the forward; nothing is rejected. Pre-Stage-B lifelines continue to work exactly as they did, including the response body and logged inbound message. The only thing that changes is whether the acceptance is also reported as a `[DEGRADATION]` event into the feedback pipeline.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+A genuine class of "lifeline running with wrong assumptions about server" issues that *also* manifest as a missing version field would no longer raise a degradation event. In practice, `lifelineVersion === undefined` only happens in the pre-Stage-B compatibility scenario — newer lifelines always send the field. Any *new* incompatibility class would also need to hit a different branch of this handler to surface, which is the correct layer.
+
+The console.info preserves the signal in server logs (the operator-side observability surface). What we lose is the per-incident feedback-pipeline submission — which was the entire point of this change, since those submissions were being mis-classified as critical.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The right long-term fix — adding a typed severity / category field to `DegradationReporter` so callers can distinguish ERROR from COMPAT_SIGNAL — is a broader API change tracked under PROP-543. This spec deliberately stays at the call site. The call site already has the contextual knowledge that *this particular* condition is observability-only (per the existing comment "emit informational signal once per cooldown" and the original commit's "Missing field accepted for backward compat."). Encoding "this is observability, not a degradation" at the call site is correct until the typed-severity refactor lands.
+
+The chosen mechanism (module-scoped boolean + console.info) matches existing patterns in `routes.ts` (e.g. `console.log('[telegram-forward] …')` at lines 6452, 6515, 6604).
+
+## 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?**
+
+No. This change has no block/allow surface. It is purely a presentation/classification change about how an *already-accepted* request is reported back into the feedback pipeline. The handler still makes the same admission decision (accept the forward) it did before.
+
+## 5. Interactions
+
+- **Shadowing:** No — there is no alternative reporting path that this could shadow. The DegradationReporter call was the only emission site for `TelegramLifeline.versionMissing`. Removing it removes the signal from the feedback pipeline and only from there.
+- **Cooldown coupling:** The previous code relied implicitly on `DegradationReporter`'s per-feature alert cooldown to avoid Telegram spam. Replacing the call with a one-shot `console.info` on the same condition removes that coupling: even without cooldown, the new path emits at most once per process. Per-process log noise is bounded; restart frequency dominates.
+- **Build manifest:** `routes.ts` is a route-group source, so `scripts/generate-builtin-manifest.cjs` re-emits its inventory. No symbol added or removed (the new boolean is local), so the manifest delta is zero entries.
+
+## 6. Test coverage
+
+**What tests changed and why.**
+
+No test file is added or modified.
+
+- The pre-fix call site had no direct test referencing `TelegramLifeline.versionMissing` (`grep` confirms). The only test surface for `/internal/telegram-forward` exercises the version-handshake decision tree, not the feedback emission side-effect.
+- A "no degradation feedback emitted" assertion on this branch would require reaching into `DegradationReporter` internals, which is brittle and out of step with the existing test harness.
+- The signal-preserving `console.info` is a logging-only side-effect; in line with existing `console.log` patterns in `routes.ts`, it is intentionally untested.
+
+If a future test ever wants to assert "backward-compat path is informational only," the natural seam is the `DegradationReporter` mock in `tests/integration/server-route-degradation.test.ts` (if/when written) — verifying the reporter is *not* called for this branch.
+
+## 7. Reviewer notes
+
+The cluster research notes cite this exact fix and acknowledge the broader systemic work as PROP-543. This change is the minimal, lowest-risk realisation of the cited fix and explicitly does not anticipate the systemic refactor.
+
+A second-pass review is not required: no signal/authority change, no contract surface, no API change, single-file edit at a documented call site with no existing tests.