@kontourai/flow-agents 3.2.0 → 3.4.0

package/scripts/telemetry/lib/config.sh

@@ -2,14 +2,78 @@
 # config.sh — Load telemetry configuration with defaults
 
 TELEMETRY_DIR="${TELEMETRY_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
-TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}"
+# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
+# two levels up.
+TELEMETRY_WORKSPACE_ROOT="${TELEMETRY_WORKSPACE_ROOT:-$(cd "${TELEMETRY_DIR}/../.." && pwd)}"
+
+# A workspace/global conf only counts as operator-created (and thus trusted
+# with credentials) if it is mode 600 and owned by the current user.
+# install-console-config.sh always chmod 600s the conf it writes; git can
+# only store 644/755 (never 600), so this gate rejects a conf smuggled in via
+# clone/tarball/PR/supply-chain even if it happens to land at the expected
+# path. Portable across macOS/BSD stat (-f) and GNU/Linux stat (-c).
+telemetry_conf_trusted() {
+  local file="$1" mode owner
+  # Reject symlinks outright: stat below reports the link's own mode/owner
+  # (lstat semantics, no -L), but the config file is later read by following
+  # the link, so a symlink lets `chmod -h 600 <link>` pass this gate while
+  # the read lands on a different, untrusted target. Never trust a link.
+  [[ -L "$file" ]] && return 1
+  [[ -f "$file" ]] || return 1
+  mode=$(stat -f '%Lp' "$file" 2>/dev/null) || mode=$(stat -c '%a' "$file" 2>/dev/null)
+  owner=$(stat -f '%u' "$file" 2>/dev/null) || owner=$(stat -c '%u' "$file" 2>/dev/null)
+  [[ "$mode" == "600" && -n "$owner" && "$owner" == "$(id -u)" ]]
+}
+
+# A candidate that exists on disk but fails telemetry_conf_trusted would
+# otherwise be silently ignored (telemetry stays fail-open with no signal to
+# the operator). Print a one-time, visible warning naming the path and the
+# fix whenever this happens. Never warn when the file is simply absent, and
+# never change which file TELEMETRY_CONFIG_FILE resolves to below -- this is
+# purely additive/observational.
+telemetry_conf_warn_untrusted() {
+  local file="$1"
+  # `-e` catches a regular file; `-L` additionally catches a symlink that
+  # `-e` would miss (a symlink to a directory, or a dangling symlink) --
+  # both of those are rejected by telemetry_conf_trusted's `-L` check above
+  # but must still surface this warning, not silently emit none.
+  [[ -e "$file" || -L "$file" ]] || return 0
+  printf 'warning: config.sh: %s exists but is not trusted (must be mode 600, owned by the current user, and not a symlink); telemetry will ignore it and stay fail-open. Fix with: chmod 600 "%s"\n' "$file" "$file" >&2
+}
+
+# Config file resolution order: (1) explicit TELEMETRY_CONFIG_FILE env always
+# wins; (2) a gitignored per-workspace conf at .kontourai/telemetry-console.conf
+# if present and operator-trusted (project-specific override); (3) a
+# gitignored user-global conf at ~/.flow-agents/telemetry-console.conf if
+# present and operator-trusted, matching the existing ~/.flow-agents
+# install-home convention (see scripts/discover-agents.sh,
+# scripts/context-budget/budget-scan.sh) so one machine-wide install can carry owner
+# credentials without per-workspace wiring; (4) the shipped telemetry.conf
+# default. The shipped scripts/telemetry/telemetry.conf is tracked and ships
+# into every packaged dist bundle, so it must never carry owner credentials.
+# A candidate that exists but fails the trust gate falls through silently
+# (telemetry stays fail-open).
+TELEMETRY_LOCAL_CONFIG_FILE="${TELEMETRY_WORKSPACE_ROOT}/.kontourai/telemetry-console.conf"
+TELEMETRY_GLOBAL_CONFIG_FILE="${HOME:-}/.flow-agents/telemetry-console.conf"
+if [[ -n "${TELEMETRY_CONFIG_FILE:-}" ]]; then
+  :
+elif telemetry_conf_trusted "$TELEMETRY_LOCAL_CONFIG_FILE"; then
+  TELEMETRY_CONFIG_FILE="$TELEMETRY_LOCAL_CONFIG_FILE"
+else
+  telemetry_conf_warn_untrusted "$TELEMETRY_LOCAL_CONFIG_FILE"
+  if [[ -n "${HOME:-}" ]] && telemetry_conf_trusted "$TELEMETRY_GLOBAL_CONFIG_FILE"; then
+    TELEMETRY_CONFIG_FILE="$TELEMETRY_GLOBAL_CONFIG_FILE"
+  else
+    [[ -n "${HOME:-}" ]] && telemetry_conf_warn_untrusted "$TELEMETRY_GLOBAL_CONFIG_FILE"
+    TELEMETRY_CONFIG_FILE="${TELEMETRY_DIR}/telemetry.conf"
+  fi
+fi
 
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
-# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
-# two levels up. Local runtime telemetry defaults under .kontourai/telemetry;
-# explicit TELEMETRY_DATA_DIR still wins.
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.kontourai/telemetry}"
+# Local runtime telemetry defaults under .kontourai/telemetry; explicit
+# TELEMETRY_DATA_DIR still wins.
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-${TELEMETRY_WORKSPACE_ROOT}/.kontourai/telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"
@@ -37,9 +101,16 @@ CONSOLE_TELEMETRY_URL="${CONSOLE_TELEMETRY_URL:-${CONSOLE_URL:-}}"
 CONSOLE_TELEMETRY_ENDPOINT_URL="${CONSOLE_TELEMETRY_ENDPOINT_URL:-}"
 CONSOLE_TELEMETRY_TOKEN="${CONSOLE_TELEMETRY_TOKEN:-${CONSOLE_AUTH_TOKEN:-}}"
 CONSOLE_TENANT_ID="${CONSOLE_TENANT_ID:-}"
+# Economics relay (#469): a caller-pre-set env var is preserved as the starting point; the
+# config-file key (parsed below) can override it, and if no key is present at all the
+# default-on rule below turns it on once a console telemetry sink resolves.
+FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY="${FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY:-}"
+FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL:-}"
+# Set (non-empty) only when the config file carries an explicit console_economics_relay key —
+# distinguishes "operator said 0/1" from "key absent" for the default-on rule below.
+console_economics_relay_raw=""
 # Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
-# otherwise the URL is derived from the console below so all runtimes read one
-# live pricing source. Falls back to the bundled pricing.json offline.
+# otherwise lib/pricing.sh uses the bundled pricing.json offline.
 TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
 TELEMETRY_PRICING_URL="${TELEMETRY_PRICING_URL:-${FLOW_AGENTS_PRICING_URL:-}}"
 
@@ -82,6 +153,17 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
         console_telemetry_token) CONSOLE_TELEMETRY_TOKEN="$value" ;;
         console_tenant_id) CONSOLE_TENANT_ID="$value" ;;
         console_telemetry_redact) CONSOLE_TELEMETRY_REDACT="$value" ;;
+        console_economics_relay)
+          case "$(echo "$value" | tr '[:upper:]' '[:lower:]')" in
+            1|true|yes|on) console_economics_relay_raw="1" ;;
+            0|false|no|off) console_economics_relay_raw="0" ;;
+            *)
+              printf 'warning: config.sh: unrecognized console_economics_relay value %q; treating as off\n' "$value" >&2
+              console_economics_relay_raw="$value"
+              ;;
+          esac
+          ;;
+        console_economics_endpoint_url) FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="$value" ;;
         console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
@@ -92,12 +174,20 @@ fi
 
 CONSOLE_TELEMETRY_REDACT="${CONSOLE_TELEMETRY_REDACT:-${TELEMETRY_CHANNEL_ANALYTICS_REDACT}}"
 
-# Derive the live pricing source from the console when not set explicitly, the
-# same way the transport derives /api/telemetry/records. One live source for
-# bash/Python/TS runtimes; lib/pricing.sh caches it and falls back to bundled.
-if [[ -z "${TELEMETRY_PRICING_URL:-}" && -n "${CONSOLE_TELEMETRY_URL:-}" ]]; then
-  TELEMETRY_PRICING_URL="${CONSOLE_TELEMETRY_URL%/}/api/telemetry/pricing"
+# Economics relay default-on rule (#469, opt-out not silent-off): an explicit
+# console_economics_relay config key always wins. Otherwise, once a console telemetry sink is
+# resolved (console_telemetry_url/console_telemetry_endpoint_url non-empty) the relay defaults ON —
+# unless a caller already pre-set FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY in the environment, which is
+# left untouched. economics-record.sh's own opt-in gate (unchanged) reads this exact variable.
+if [[ -n "$console_economics_relay_raw" ]]; then
+  FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY="$console_economics_relay_raw"
+elif [[ -z "$FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY" \
+      && ( -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ) ]]; then
+  FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY=1
 fi
 
+# Pricing URL is explicit-only (env or config). Do not derive the console
+# pricing endpoint by default; the bundled registry is the reliable offline floor.
+
 # Ensure directories exist
 mkdir -p "$TELEMETRY_DATA_DIR" "$TELEMETRY_SESSION_DIR" 2>/dev/null

package/scripts/telemetry/lib/pricing.sh

@@ -10,6 +10,11 @@
 
 PRICING_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
+pricing_registry_valid_json() {
+  command -v jq >/dev/null 2>&1 || return 1
+  jq -e '.current_version and .versions' >/dev/null 2>&1
+}
+
 # Echo the raw registry JSON. Returns non-zero if nothing resolvable.
 pricing_registry() {
   local f="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
@@ -21,18 +26,21 @@ pricing_registry() {
     local ttl="${TELEMETRY_PRICING_TTL_SEC:-3600}"
     if [[ -f "$cache" ]]; then
       local mtime now age
-      mtime=$(stat -f %m "$cache" 2>/dev/null || stat -c %Y "$cache" 2>/dev/null || echo 0)
+      mtime=$(stat -c %Y "$cache" 2>/dev/null || stat -f %m "$cache" 2>/dev/null || echo 0)
+      [[ "$mtime" =~ ^[0-9]+$ ]] || mtime=0
       now=$(date +%s)
       age=$(( now - mtime ))
-      if [[ "$age" -lt "$ttl" ]]; then cat "$cache"; return 0; fi
+      if [[ "$age" -lt "$ttl" ]] && pricing_registry_valid_json < "$cache"; then cat "$cache"; return 0; fi
     fi
     if curl -fsS --max-time 5 "$url" -o "${cache}.tmp" 2>/dev/null && [[ -s "${cache}.tmp" ]]; then
-      mv "${cache}.tmp" "$cache"
-      cat "$cache"
-      return 0
+      if pricing_registry_valid_json < "${cache}.tmp"; then
+        mv "${cache}.tmp" "$cache"
+        cat "$cache"
+        return 0
+      fi
     fi
     rm -f "${cache}.tmp" 2>/dev/null
-    [[ -f "$cache" ]] && { cat "$cache"; return 0; }  # stale cache beats nothing
+    [[ -f "$cache" ]] && pricing_registry_valid_json < "$cache" && { cat "$cache"; return 0; }
   fi
 
   local bundled

package/scripts/telemetry/lib/session.sh

@@ -60,4 +60,7 @@ session_end() {
 
 session_cleanup() {
   find "${TELEMETRY_SESSION_DIR}" -name "*.session" -mtime +1 -delete 2>/dev/null || true
+  # Bound the per-cwd project-label cache (see console_project_label) so a project rename
+  # (package.json name / git remote) self-heals within the same window instead of caching forever.
+  find "${TELEMETRY_SESSION_DIR}" -name "project-label.*" -mtime +1 -delete 2>/dev/null || true
 }

package/scripts/telemetry/lib/transport.sh

@@ -46,26 +46,38 @@ console_telemetry_timeout_seconds() {
   fi
 }
 
-console_telemetry_emit() {
-  local event="$1"
-  local endpoint_url
-  endpoint_url=$(console_telemetry_endpoint_url)
+# console_post_json <endpoint_url> <body> [connect_timeout] [max_time] [tmp_dir]
+# Shared best-effort JSON POST to a Console records endpoint. BOTH the telemetry mirror
+# (console_telemetry_emit) and the liveness relay (#295, scripts/liveness/relay.sh) go through this
+# ONE core so endpoint-allow, auth (Bearer + tenant), timeouts, temp-file handling, and the detached
+# fire can never drift between the two paths (the #356 shared-not-forked discipline). Reads
+# CONSOLE_TELEMETRY_TOKEN / CONSOLE_TENANT_ID from the environment. Never blocks or fails the caller.
+console_post_json() {
+  local endpoint_url="$1"
+  local body="$2"
+  local connect_timeout max_time tmp_dir curl_config curl_body
   [[ -z "$endpoint_url" ]] && return
-  console_telemetry_endpoint_allowed "$endpoint_url" || return
-
-  local processed_event
-  processed_event=$(redact_event "$event" "${CONSOLE_TELEMETRY_REDACT:-${TELEMETRY_CHANNEL_ANALYTICS_REDACT:-}}")
-
-  local curl_config curl_body connect_timeout max_time
-  connect_timeout=$(console_telemetry_timeout_seconds "${CONSOLE_TELEMETRY_CONNECT_TIMEOUT_SECONDS:-2}" 2 30)
-  max_time=$(console_telemetry_timeout_seconds "${CONSOLE_TELEMETRY_MAX_TIME_SECONDS:-5}" 5 60)
-  curl_config=$(mktemp "${TELEMETRY_SESSION_DIR}/console-curl.XXXXXX") || return
-  curl_body=$(mktemp "${TELEMETRY_SESSION_DIR}/console-body.XXXXXX") || {
+  if ! console_telemetry_endpoint_allowed "$endpoint_url"; then
+    # Dropped silently before today's change (no signal that the event never
+    # left the machine). Warn once per shell process (guarded by a plain,
+    # non-local var so it survives across repeated console_post_json calls
+    # within the same sourced shell) without changing the drop itself.
+    if [[ -z "${_CONSOLE_TELEMETRY_ENDPOINT_WARNED:-}" ]]; then
+      printf 'warning: transport.sh: console endpoint dropped by the allowlist (must be https://, or http://localhost|127.0.0.1): %s\n' "$endpoint_url" >&2
+      _CONSOLE_TELEMETRY_ENDPOINT_WARNED=1
+    fi
+    return
+  fi
+  connect_timeout=$(console_telemetry_timeout_seconds "${3:-2}" 2 30)
+  max_time=$(console_telemetry_timeout_seconds "${4:-5}" 5 60)
+  tmp_dir="${5:-${TELEMETRY_SESSION_DIR:-${TMPDIR:-/tmp}}}"
+  curl_config=$(mktemp "${tmp_dir%/}/console-curl.XXXXXX") || return
+  curl_body=$(mktemp "${tmp_dir%/}/console-body.XXXXXX") || {
     rm -f "$curl_config"
     return
   }
   chmod 600 "$curl_config" "$curl_body" 2>/dev/null
-  printf '%s' "$processed_event" > "$curl_body" || {
+  printf '%s' "$body" > "$curl_body" || {
     rm -f "$curl_config" "$curl_body"
     return
   }
@@ -94,6 +106,112 @@ console_telemetry_emit() {
   ) &
 }
 
+# Derive a coarse, path-free project label for console attribution, most-stable-first so the SAME
+# project resolves to the SAME label across developers and machines (folder names differ between
+# clones and worktrees; the project manifest and git remote do not). Precedence:
+#   1. FLOW_AGENTS_PROJECT       — explicit operator override, always wins
+#   2. nearest package.json name — walking up from cwd (monorepo-granular, committed => consistent)
+#   3. git remote origin org/repo — repo-level identity, stable across clones
+#   4. git toplevel dir basename  — repo dir even from a worktree/subdir
+#   5. cwd basename               — last resort
+# Path-free by construction (never the full local path). Cached per cwd under the telemetry data
+# dir so the git/manifest reads run once per project, not per event; session_cleanup bounds the
+# cache lifetime so a project rename (package.json name / git remote) self-heals within a day.
+# Failure signals via empty output; the sole caller wraps the call as `$(...) || proj=""` so even if
+# an internal command fails under `set -e`, telemetry is relayed unchanged (see
+# console_telemetry_emit). Do not call this unwrapped from a `set -e` context.
+console_project_label() {
+  local cwd="$1"
+  [[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+  [[ -n "${FLOW_AGENTS_PROJECT:-}" ]] && { printf '%s' "$FLOW_AGENTS_PROJECT"; return 0; }
+
+  local cache="" key
+  if [[ -n "${TELEMETRY_SESSION_DIR:-}" && -d "${TELEMETRY_SESSION_DIR:-}" ]]; then
+    key=$(printf '%s' "$cwd" | cksum | cut -d' ' -f1)
+    cache="${TELEMETRY_SESSION_DIR%/}/project-label.${key}"
+    [[ -s "$cache" ]] && { cat "$cache"; return 0; }
+  fi
+
+  local label="" dir name url top after path repo rest org
+  dir="$cwd"
+  while [[ -n "$dir" && "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]]; then
+      name=$(jq -r '.name // empty' "$dir/package.json" 2>/dev/null) || name=""
+      [[ -n "$name" ]] && { label="$name"; break; }
+    fi
+    dir=$(dirname "$dir")
+  done
+  if [[ -z "$label" ]]; then
+    url=$(git -C "$cwd" config --get remote.origin.url 2>/dev/null) || url=""
+    if [[ -n "$url" ]]; then
+      # Reduce a git remote to a coarse, host-free org/repo. Strip scheme+host STRUCTURALLY (not by
+      # a dot-in-host heuristic) so a self-hosted or dot-less host, a port, or a user@ prefix can
+      # never leak into the label; a remote with no org tier (single path segment) falls through.
+      url="${url%/}"; url="${url%.git}"
+      path=""
+      if [[ "$url" == *"://"* ]]; then
+        # Only network VCS schemes carry an org/repo path; file:// and other local schemes fall through.
+        if [[ "$url" =~ ^(https?|ssh|git|ftps?):// ]]; then
+          after="${url#*://}"                       # [user@]host[:port]/org/repo
+          [[ "$after" == */* ]] && path="${after#*/}" # drop host[:port] (and any user@), keep path
+        fi
+      elif [[ "$url" == *:* && "${url%%:*}" != */* ]]; then
+        path="${url#*:}"                            # scp form [user@]host:org/repo
+      elif [[ "$url" != /* ]]; then
+        path="$url"                                 # bare relative org/repo shorthand (not a local abs path)
+      fi
+      if [[ "$path" == */* ]]; then
+        repo="${path##*/}"; rest="${path%/*}"; org="${rest##*/}"  # last two path segments
+        [[ -n "$org" && -n "$repo" ]] && label="$org/$repo"
+      fi
+    fi
+  fi
+  if [[ -z "$label" ]]; then
+    top=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null) || top=""
+    [[ -n "$top" ]] && label=$(basename "$top")
+  fi
+  [[ -z "$label" ]] && label=$(basename "$cwd")
+
+  if [[ -n "$cache" ]]; then
+    printf '%s' "$label" > "${cache}.tmp.$$" 2>/dev/null && mv "${cache}.tmp.$$" "$cache" 2>/dev/null
+  fi
+  printf '%s' "$label"
+}
+
+console_telemetry_emit() {
+  local event="$1"
+  local endpoint_url
+  endpoint_url=$(console_telemetry_endpoint_url)
+  [[ -z "$endpoint_url" ]] && return
+
+  # Attribution: stamp a coarse, path-free project label (see console_project_label) before redaction
+  # so the console buckets by project consistently across developers. The full context.cwd is still
+  # redacted below — only the label leaves the machine. Every substitution is `|| var=""`-guarded so
+  # that even under `set -e` any failure (bad JSON, missing cwd, no git) relays the event unchanged.
+  local ev_cwd proj labeled_event
+  ev_cwd=$(printf '%s' "$event" | jq -r '.context.cwd // empty' 2>/dev/null) || ev_cwd=""
+  if [[ -n "$ev_cwd" ]]; then
+    proj=$(console_project_label "$ev_cwd" 2>/dev/null) || proj=""
+    if [[ -n "$proj" ]]; then
+      labeled_event=$(printf '%s' "$event" | jq -c --arg p "$proj" '
+        if ((.context.project // "") | length) == 0 then .context.project = $p else . end' 2>/dev/null) || labeled_event=""
+      [[ -n "$labeled_event" ]] && event="$labeled_event"
+    fi
+  fi
+
+  local processed_event
+  processed_event=$(redact_event "$event" "${CONSOLE_TELEMETRY_REDACT:-${TELEMETRY_CHANNEL_ANALYTICS_REDACT:-}}")
+
+  # Delegate the endpoint-allow gate, auth, timeouts, temp files, and detached POST to the shared
+  # core. Timeouts/tmp-dir are passed explicitly so telemetry behavior is byte-for-byte unchanged.
+  console_post_json \
+    "$endpoint_url" \
+    "$processed_event" \
+    "${CONSOLE_TELEMETRY_CONNECT_TIMEOUT_SECONDS:-2}" \
+    "${CONSOLE_TELEMETRY_MAX_TIME_SECONDS:-5}" \
+    "${TELEMETRY_SESSION_DIR:-}"
+}
+
 transport_emit() {
   local event="$1"
   [[ -z "$event" ]] && return

package/scripts/telemetry/lib/usage.sh

@@ -20,18 +20,49 @@ usage_get_model() {
   echo "unknown"
 }
 
+# Given the JSON object produced by usage_parse_transcript (has a top-level
+# `by_model[]` array), return the runtime-agnostic session model: the model
+# with the most total tokens (input+output+cache_creation+cache_read). This
+# lets any runtime that exposes a transcript (Claude Code, Codex, ...) resolve
+# a real model name instead of the kiro-only ~/.kiro/agents lookup, which
+# never matches non-kiro agent names (e.g. Claude Code's fixed "dev" hook
+# arg) and falls through to "unknown". Returns empty string when $1 is
+# null/empty or has no by_model entries, so the caller falls back to
+# usage_get_model().
+usage_model_from_transcript_usage() {
+  local transcript_usage="$1"
+  [[ -z "$transcript_usage" || "$transcript_usage" == "null" ]] && { echo ""; return; }
+  echo "$transcript_usage" | jq -r '
+    (.by_model // [])
+    | map({model, total: ((.input_tokens // 0) + (.output_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0))})
+    | sort_by([-.total, .model])
+    | .[0].model // empty
+  ' 2>/dev/null
+}
+
 # Count tool invocations for a session
 usage_count_tool_calls() {
   local session_id="$1" jsonl_path="$2"
-  [[ ! -f "$jsonl_path" ]] && echo 0 && return
-  grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"tool.invoke\"" "$jsonl_path" 2>/dev/null || echo 0
+  [[ ! -f "$jsonl_path" ]] && { echo 0; return; }
+  # grep -c prints "0" (not empty) on zero matches but still exits non-zero,
+  # so `grep -c ... || echo 0` double-emits "0\n0" here — that malformed
+  # value then breaks the caller's `jq --argjson tc "$tool_count"`, silently
+  # discarding the *entire* session.usage event whenever a session has no
+  # prior tool.invoke lines yet (a common, not-rare case). Capture the count
+  # first and only fall back when it's genuinely empty.
+  local count
+  count=$(grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"tool.invoke\"" "$jsonl_path" 2>/dev/null)
+  echo "${count:-0}"
 }
 
 # Count subagent delegations for a session
 usage_count_delegations() {
   local session_id="$1" jsonl_path="$2"
-  [[ ! -f "$jsonl_path" ]] && echo 0 && return
-  grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"agent.delegate\"" "$jsonl_path" 2>/dev/null || echo 0
+  [[ ! -f "$jsonl_path" ]] && { echo 0; return; }
+  # See usage_count_tool_calls above for why this can't be `grep -c ... || echo 0`.
+  local count
+  count=$(grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"agent.delegate\"" "$jsonl_path" 2>/dev/null)
+  echo "${count:-0}"
 }
 
 # Parse a runtime transcript (JSONL) into real per-model token + cost usage.
@@ -47,8 +78,13 @@ usage_count_delegations() {
 #                  estimated_cost_usd} ],
 #     input_tokens, output_tokens, cache_creation_input_tokens,
 #     cache_read_input_tokens, estimated_cost_usd, pricing_version }
-# Prints nothing (non-zero) when the transcript is missing/unparseable so the
-# caller can fall back to null usage. Never blocks agent work.
+# Tokens are source-of-truth and survive independently of pricing: if the
+# pricing registry is unavailable (or an explicit version arg doesn't exist in
+# it), by_model[]/input_tokens/output_tokens/etc. are still emitted — only
+# estimated_cost_usd and pricing_version degrade to null (the console
+# recomputes cost authoritatively from tokens). Prints nothing (non-zero) only
+# when the transcript itself is missing/empty/unreadable or truly carries zero
+# usage, so the caller can fall back to null usage. Never blocks agent work.
 # Expected transcript usage path (Claude Code / Anthropic usage object). Bumped
 # if the on-disk schema changes so drift is logged rather than silently zeroed.
 USAGE_TRANSCRIPT_SCHEMA="message.usage.input_tokens"
@@ -65,21 +101,68 @@ usage_log_drift() {
   fi
 }
 
+# Opt-in persistent diagnostics for usage_parse_transcript's no-usage/degraded
+# outcomes (gated by TELEMETRY_USAGE_DEBUG=1 so it never fires by default).
+# Goes to TELEMETRY_DRIFT_LOG if set, else stderr. Never fatal, never blocks —
+# purely so intermittent live "session.usage has null tokens" reports can be
+# distinguished (empty transcript_path vs missing file vs no pricing registry
+# vs a real zero-token parse) instead of being an unexplained black box.
+usage_log_debug() {
+  [[ "${TELEMETRY_USAGE_DEBUG:-}" == "1" ]] || return 0
+  local reason="$1"
+  local msg="[telemetry] usage_parse_transcript: ${reason}"
+  if [[ -n "${TELEMETRY_DRIFT_LOG:-}" ]]; then
+    echo "$msg" >> "${TELEMETRY_DRIFT_LOG}" 2>/dev/null || echo "$msg" >&2
+  else
+    echo "$msg" >&2
+  fi
+}
+
 usage_parse_transcript() {
   local transcript="$1" version="${2:-}"
-  [[ -z "$transcript" || ! -f "$transcript" ]] && return 1
-  command -v jq >/dev/null 2>&1 || return 1
-  local registry
-  registry="$(pricing_registry)" || return 1
-  [[ -z "$registry" ]] && return 1
+  if [[ -z "$transcript" ]]; then
+    usage_log_debug "no usage — reason: empty transcript_path"
+    return 1
+  fi
+  if [[ ! -f "$transcript" ]]; then
+    usage_log_debug "no usage — reason: transcript file missing (${transcript})"
+    return 1
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    usage_log_debug "no usage — reason: jq unavailable"
+    return 1
+  fi
+
+  # Pricing registry is best-effort: when unavailable, tokens are still
+  # extracted below and only the cost fields degrade to null (defect #2 fix —
+  # previously this hard-returned 1 here, discarding token extraction
+  # entirely whenever pricing_registry() failed).
+  local registry has_registry
+  registry="$(pricing_registry 2>/dev/null)"
+  if [[ $? -eq 0 && -n "$registry" ]]; then
+    has_registry=true
+  else
+    has_registry=false
+    registry='null'
+    usage_log_debug "pricing registry unavailable (${transcript}) — extracting tokens without cost"
+  fi
+  # A non-empty registry can still be malformed (corrupt/truncated pricing.json,
+  # or a bad remote 200) — validate it parses before handing it to `jq -n
+  # --argjson`, which would otherwise abort the whole parse and discard tokens
+  # (the exact intermittent-null-tokens defect this function exists to fix).
+  if [[ "$has_registry" == true ]] && ! jq -e . >/dev/null 2>&1 <<<"$registry"; then
+    has_registry=false
+    registry='null'
+    usage_log_debug "pricing registry unparseable (${transcript}) — extracting tokens without cost"
+  fi
 
   local out
-  out="$(jq -n --argjson registry "$registry" --arg version "$version" '
-    $registry as $reg
-    | (if $version == "" then ($reg.current_version) else $version end) as $ver
-    | ($reg.versions[$ver]) as $p
-    | if $p == null then empty else . end
-    | ($p.cache_multipliers) as $cm
+  out="$(jq -n --argjson registry "$registry" --argjson has_registry "$has_registry" --arg version "$version" '
+    ($has_registry and ($registry != null)) as $has_reg
+    | (if $has_reg then (if $version == "" then $registry.current_version else $version end) else null end) as $ver
+    | (if $has_reg and ($ver != null) then ($registry.versions[$ver]) else null end) as $p
+    | ($p != null) as $priced
+    | (if $priced then $p.cache_multipliers else null end) as $cm
     | (reduce inputs as $l ({};
         ($l.message.usage) as $u
         | if $u then
@@ -92,8 +175,8 @@ usage_parse_transcript() {
     | ($agg | to_entries
         | map(
             .key as $m | .value as $u
-            | (($p.models[$m]) // $p.default) as $rate
-            | (if ([$m] | inside($p.zero_cost_models)) then 0 else 1 end) as $billable
+            | (if $priced then (($p.models[$m]) // $p.default) else null end) as $rate
+            | (if $priced then (if ([$m] | inside($p.zero_cost_models)) then 0 else 1 end) else null end) as $billable
             | {
                 model: $m,
                 input_tokens: ($u.input // 0),
@@ -101,12 +184,14 @@ usage_parse_transcript() {
                 cache_creation_input_tokens: ($u.cache_creation // 0),
                 cache_read_input_tokens: ($u.cache_read // 0),
                 estimated_cost_usd: (
-                  $billable * (
-                    ($u.input // 0)          * $rate.input
-                    + ($u.output // 0)         * $rate.output
-                    + ($u.cache_creation // 0) * $rate.input * $cm.write_5m
-                    + ($u.cache_read // 0)     * $rate.input * $cm.read
-                  ) / 1000000
+                  if $priced then
+                    $billable * (
+                      ($u.input // 0)          * $rate.input
+                      + ($u.output // 0)         * $rate.output
+                      + ($u.cache_creation // 0) * $rate.input * $cm.write_5m
+                      + ($u.cache_read // 0)     * $rate.input * $cm.read
+                    ) / 1000000
+                  else null end
                 )
               })) as $by_model
     | {
@@ -115,20 +200,28 @@ usage_parse_transcript() {
         output_tokens: ([$by_model[].output_tokens] | add // 0),
         cache_creation_input_tokens: ([$by_model[].cache_creation_input_tokens] | add // 0),
         cache_read_input_tokens: ([$by_model[].cache_read_input_tokens] | add // 0),
-        estimated_cost_usd: (([$by_model[].estimated_cost_usd] | add // 0) * 1000000 | round / 1000000),
-        pricing_version: $ver
+        estimated_cost_usd: (if $priced then (([$by_model[].estimated_cost_usd] | add // 0) * 1000000 | round / 1000000) else null end),
+        pricing_version: (if $priced then $ver else null end)
       }
   ' < "$transcript" 2>/dev/null)"
 
-  [[ -z "$out" ]] && return 1
+  if [[ -z "$out" ]]; then
+    usage_log_debug "no usage — reason: jq parse failed (${transcript})"
+    return 1
+  fi
 
   # Drift / emptiness check: if we parsed zero tokens but the transcript clearly
   # contains usage data, the schema drifted — warn and fall back to null usage.
+  # This only discards tokens when there truly are none (total == 0); it never
+  # discards a non-zero token extraction, including the pricing-unavailable
+  # case above.
   local total
   total="$(printf '%s' "$out" | jq -r '((.input_tokens // 0) + (.output_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0))' 2>/dev/null)"
   if [[ -z "$total" || "$total" == "0" ]]; then
     if grep -q '"input_tokens"' "$transcript" 2>/dev/null; then
       usage_log_drift "$transcript"
+    else
+      usage_log_debug "no usage — reason: parsed 0 tokens (no usage entries found in ${transcript})"
     fi
     return 1
   fi

package/scripts/telemetry/telemetry.conf

@@ -8,6 +8,12 @@ channel.analytics.redact=tool.input,tool.output,turn.prompt_text,delegation.targ
 # The transport derives /api/telemetry/records from console_telemetry_url.
 # console_telemetry_token=
 # console_tenant_id=
+# Kit-economics relay (#469): once console_telemetry_url/console_telemetry_endpoint_url
+# resolves, the per-run kit-economics record relay defaults ON (opt-out, not silent-off).
+# Set console_economics_relay=0 to opt out while keeping the telemetry mirror; or run
+# install-console-config.sh --no-economics-relay to write this at install time.
+# console_economics_relay=0
+# console_economics_endpoint_url=
 # Live pricing registry source. If unset, derived from console_telemetry_url as
 # <console>/api/telemetry/pricing so bash/Python/TS runtimes read one live
 # source; lib/pricing.sh caches it and falls back to bundled pricing.json.