instar 0.28.76 → 0.28.78

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

@@ -0,0 +1,90 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+The Token Ledger (shipped in v0.28.77 as Phase 1 read-only token-usage
+observability) had an unbounded synchronous first scan. On agents with
+deep Claude Code history this blocked the Node event loop for minutes —
+one local agent had 119,130 JSONL transcripts totaling 12 GB, and on
+boot the server stopped responding to its own `/health` endpoint, which
+caused the lifeline supervisor to declare the agent dead and restart it
+in a loop.
+
+This release bounds the scan in three independent ways:
+
+1. **Per-tick file cap** (default 500) with a persistent in-memory
+   cursor across ticks. The first poll backfills 500 files; the next
+   poll picks up where the previous one stopped; once the tree is fully
+   walked the cursor wraps back to the start so newly-written sessions
+   are still picked up.
+2. **Intra-tick yielding** (default every 25 files) via `setImmediate`.
+   Even within a single tick the event loop gets to drain HTTP and
+   health-check traffic — the server stays responsive while the ledger
+   is doing its work.
+3. **Optional max file age** (default 30 days at the wiring layer). The
+   ledger ignores transcripts whose mtime is older than the backfill
+   window. Active sessions are never blackholed: appending a new turn
+   updates the file's mtime, which brings it back into the window. The
+   source JSONLs in `~/.claude/projects/` remain the ground truth, so an
+   operator can widen the window later by passing a larger
+   `maxFileAgeMs` and the ledger will pick up the older data on the
+   next scan.
+
+A new `scanAllAsync()` method is the path the poller now uses; the
+original `scanAll()` sync entry point is preserved for tests and any
+caller that doesn't need yielding (and now honors the per-tick cap and
+age cutoff too).
+
+No schema migration. No new routes. No new external surfaces. Pure
+containment fix for the v0.28.77 regression.
+
+## What to Tell Your User
+
+- **Quieter, more reliable startup with the new Tokens tab**: I no
+  longer get stuck staring at years of old session transcripts on boot.
+  When I start up, I look at the most recent month of activity first,
+  in small batches, and I keep answering you in between batches. The
+  Tokens tab will fill in over the first few minutes instead of being
+  empty until everything has been read at once.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Bounded first-boot scan of the token ledger | Automatic on upgrade |
+| Configurable backfill window for the token ledger | Pass `maxFileAgeMs` to TokenLedger constructor (defaults to 30 days at the wiring layer) |
+| Per-tick scan cap and event-loop yielding | Automatic on upgrade |
+
+## Evidence
+
+Reproduction (before fix):
+
+1. Start v0.28.77 on a host with deep Claude Code history (the local
+   reproduction host had 119,130 JSONL files / 12 GB under
+   `~/.claude/projects/`).
+2. `curl -m 5 http://localhost:4042/health` hangs — connection accepted
+   but no response within timeout.
+3. `sample <pid> 1` shows the main thread spending 100% of its time in
+   `uv_fs_stat` callbacks under
+   `Builtins_InterpreterEntryTrampoline` — a JS loop hammering the
+   filesystem with no event-loop yields.
+4. The lifeline supervisor's health probe times out, declares the
+   server unhealthy, and restarts it. The next boot starts the same
+   scan over again.
+
+After fix:
+
+1. Same host, same `~/.claude/projects/` tree. Server boots and
+   `curl http://localhost:4042/health` returns a normal JSON response
+   within a few hundred ms.
+2. `curl http://localhost:4042/tokens/summary` returns valid JSON
+   immediately (initially with a small subset of recent sessions).
+   Subsequent ticks fill in the rest of the 30-day window.
+3. The lifeline supervisor sees a healthy server and stops restarting.
+
+Unit tests: `tests/unit/token-ledger.test.ts` — 15/15 passing locally
+on the `fix/token-ledger-bounded-scan` branch. Three new tests cover
+the cursor resume, age cutoff, and async yielding behavior. Typecheck
+clean (`npx tsc --noEmit`).