create-egregore 0.19.32 → 0.20.0

package/runtime/prime/bin/settings.sh

@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# settings.sh — deterministic config verbs for an Egregore instance.
+#
+# Edits egregore.json atomically. No agent, no network, no session. Idempotent:
+# re-adding an existing item is a no-op success; removing a missing one is too.
+# This is the deterministic core the launcher settings screen (and slash
+# commands) call — the reliability lives here, the surfaces are thin callers.
+#
+# Usage:
+#   settings.sh hosting status|on|off
+#   settings.sh relay status|on|off
+#   settings.sh repo list | add <name> [description] | remove <name>
+#   settings.sh admin list | add <github-handle> | remove <github-handle>
+#   settings.sh dump                 # full settings snapshot as JSON (for the launcher)
+#
+# Add --json to a read verb (status/list) for machine-readable output.
+#
+# Exit codes: 0 ok · 1 usage/validation error · 2 config not found.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
+
+# ── helpers ──────────────────────────────────────────────────────────────
+
+_die() { echo "$1" >&2; exit "${2:-1}"; }
+
+_valid_token() {
+  # non-empty, GitHub-handle / repo-name safe charset
+  [ -n "${1:-}" ] && printf '%s' "$1" | grep -qE '^[A-Za-z0-9._-]+$'
+}
+
+_save() {
+  # _save '<jq-filter>' [jq-args...] — apply filter to CONFIG, write atomically.
+  local filter="$1"; shift
+  local tmp
+  tmp="$(mktemp "$CONFIG.XXXXXX")" || _die "cannot create temp file" 1
+  if jq "$@" "$filter" "$CONFIG" > "$tmp" 2>/dev/null && [ -s "$tmp" ]; then
+    mv "$tmp" "$CONFIG"
+  else
+    rm -f "$tmp"
+    _die "failed to update $CONFIG (invalid jq filter or unwritable file)" 1
+  fi
+}
+
+_has_repo() { jq -e --arg n "$1" 'any(.repos[]?; (if type=="object" then .name else . end) == $n)' "$CONFIG" >/dev/null; }
+_has_admin() { jq -e --arg h "$1" 'any(.admins[]?; . == $h)' "$CONFIG" >/dev/null; }
+
+usage() {
+  cat >&2 <<'EOF'
+settings.sh — Egregore instance settings
+
+  settings.sh hosting status|on|off
+  settings.sh relay  status|on|off
+  settings.sh repo   list | add <name> [description] | remove <name>
+  settings.sh admin  list | add <github-handle> | remove <github-handle>
+  settings.sh people list | add <github-handle> | remove <github-handle>
+  settings.sh dump                         full snapshot (JSON)
+
+  --json    machine-readable output for status/list
+EOF
+  exit "${1:-1}"
+}
+
+# ── verbs ────────────────────────────────────────────────────────────────
+
+cmd_hosting() {
+  local action="${1:-status}"
+  # NEVER use jq's `// "true"` here: `//` treats an explicit `false` as empty and
+  # would return the default, silently defeating the off-switch. Test `!= false`
+  # so absent/true => enabled, explicit false => disabled. `enabled` is the
+  # resolved boolean string ("true"/"false").
+  local enabled; enabled="$(jq -r '.features.publishing != false' "$CONFIG" 2>/dev/null || echo "true")"
+  case "$action" in
+    status)
+      if [ "$JSON" = 1 ]; then
+        jq -n --argjson on "$enabled" '{domain:"hosting", publishing:$on}'
+      elif [ "$enabled" = "false" ]; then echo "Hosting (egregore.xyz): OFF"
+      else echo "Hosting (egregore.xyz): ON"; fi ;;
+    on)
+      _save '.features.publishing = true'
+      echo "Hosting (egregore.xyz): ON" ;;
+    off)
+      _save '.features.publishing = false'
+      echo "Hosting (egregore.xyz): OFF — artifacts will no longer upload to egregore.xyz" ;;
+    *) _die "usage: settings.sh hosting status|on|off" 1 ;;
+  esac
+}
+
+# The public share relay is the only upload route when there is no org API
+# key. It is unauthenticated, readable by anyone with the URL, and expires
+# after 7 days, so it is OFF unless explicitly enabled.
+cmd_relay() {
+  local action="${1:-status}"
+  local enabled; enabled="$(jq -r 'if .features.public_relay == true then "true" else "false" end' "$CONFIG" 2>/dev/null || echo "false")"
+  case "$action" in
+    status)
+      if [ "$JSON" = 1 ]; then
+        jq -n --argjson on "$enabled" '{domain:"relay", public_relay:$on}'
+      elif [ "$enabled" = "true" ]; then
+        echo "Public share relay: ON — artifacts published without an org API key upload to a public, unauthenticated URL (expires after 7 days)"
+      else
+        echo "Public share relay: OFF — without an org API key, nothing uploads anywhere"
+      fi ;;
+    on)
+      _save '.features.public_relay = true'
+      echo "Public share relay: ON"
+      echo "  Artifacts published without an org API key now upload to a public, unauthenticated URL that anyone with the link can read for 7 days." ;;
+    off)
+      _save '.features.public_relay = false'
+      echo "Public share relay: OFF — without an org API key, nothing uploads anywhere" ;;
+    *) _die "usage: settings.sh relay status|on|off" 1 ;;
+  esac
+}
+
+cmd_repo() {
+  local action="${1:-list}"; shift || true
+  case "$action" in
+    list)
+      if [ "$JSON" = 1 ]; then
+        jq '[.repos[]? | if type=="object" then . else {name:.} end]' "$CONFIG"
+      else
+        jq -r '.repos[]? | if type=="object" then "  " + .name + (if .description then " — " + .description else "" end) else "  " + . end' "$CONFIG"
+      fi ;;
+    add)
+      local name="${1:-}"; shift || true
+      local desc="${*:-}"
+      _valid_token "$name" || _die "usage: settings.sh repo add <name> [description]" 1
+      if _has_repo "$name"; then echo "repo '$name' already managed"; return 0; fi
+      if [ -n "$desc" ]; then
+        _save '.repos = ((.repos // []) + [{name:$n, description:$d}])' --arg n "$name" --arg d "$desc"
+      else
+        _save '.repos = ((.repos // []) + [{name:$n}])' --arg n "$name"
+      fi
+      echo "added repo '$name'"
+      echo "  clone it with: /sync-repos  (or reopen the egregore)" ;;
+    remove)
+      local name="${1:-}"
+      _valid_token "$name" || _die "usage: settings.sh repo remove <name>" 1
+      if ! _has_repo "$name"; then echo "repo '$name' is not managed"; return 0; fi
+      _save '.repos = [.repos[]? | select((if type=="object" then .name else . end) != $n)]' --arg n "$name"
+      echo "removed repo '$name' from config"
+      echo "  note: the local ../$name checkout is left untouched" ;;
+    *) _die "usage: settings.sh repo list|add|remove" 1 ;;
+  esac
+}
+
+cmd_admin() {
+  local action="${1:-list}"; shift || true
+  case "$action" in
+    list)
+      if [ "$JSON" = 1 ]; then jq '{admins:(.admins // [])}' "$CONFIG"
+      else jq -r '.admins[]? | "  " + .' "$CONFIG"; fi ;;
+    add)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh admin add <github-handle>" 1
+      if _has_admin "$h"; then echo "'$h' is already an admin"; return 0; fi
+      _save '.admins = ((.admins // []) + [$h])' --arg h "$h"
+      echo "added admin '$h'" ;;
+    remove)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh admin remove <github-handle>" 1
+      if ! _has_admin "$h"; then echo "'$h' is not an admin"; return 0; fi
+      local count; count="$(jq '(.admins // []) | length' "$CONFIG")"
+      [ "$count" -le 1 ] && _die "refusing to remove the last admin ('$h') — add another admin first" 1
+      _save '.admins = [.admins[]? | select(. != $h)]' --arg h "$h"
+      echo "removed admin '$h'" ;;
+    *) _die "usage: settings.sh admin list|add|remove" 1 ;;
+  esac
+}
+
+# ── people ───────────────────────────────────────────────────────────────
+# People live as files in memory/people/. add/remove manage that directory AND
+# GitHub repo access (the meaningful local grant). Connected-mode extras — the
+# invite link + Telegram (/invite) and Supabase/Neo4j teardown (/delete-user) —
+# are pointed to, not duplicated here.
+
+_people_dir() { echo "$SCRIPT_DIR/memory/people"; }
+
+_people_names() {
+  local pdir; pdir="$(_people_dir)"
+  [ -d "$pdir" ] || return 0
+  ls "$pdir"/*.md 2>/dev/null | while IFS= read -r f; do basename "$f" .md; done \
+    | grep -viE '^(index|readme)$' || true
+}
+
+_people_json() {
+  local names; names="$(_people_names)"
+  if [ -z "$names" ]; then echo '[]'; return; fi
+  printf '%s\n' "$names" | jq -R . | jq -sc 'map(select(length>0))'
+}
+
+_has_person() { [ -f "$(_people_dir)/$1.md" ]; }
+
+# add|remove a GitHub push-collaborator across the instance's repos. Best-effort:
+# no token/org => skip with a note; per-repo failures never abort.
+_people_github() {
+  local user="$1" op="$2" token org repos r
+  token="$(grep '^GITHUB_TOKEN=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d= -f2- || true)"
+  org="$(jq -r '.github_org // empty' "$CONFIG" 2>/dev/null)"
+  if [ -z "$token" ] || [ -z "$org" ]; then
+    echo "  (no GitHub token/org — skipped repo access; run bin/github-auth.sh)" >&2
+    return 0
+  fi
+  repos="$(jq -r '[.repo_name, (.memory_repo // "" | split("/") | last | sub("\\.git$";"")), (.repos[]? | if type=="object" then .name else . end)] | map(select(. != null and . != "")) | unique | .[]' "$CONFIG" 2>/dev/null)"
+  for r in $repos; do
+    if [ "$op" = "add" ]; then
+      curl -s -o /dev/null -X PUT -H "Authorization: Bearer $token" -H "Accept: application/vnd.github+json" \
+        "https://api.github.com/repos/$org/$r/collaborators/$user" -d '{"permission":"push"}' 2>/dev/null || true
+    else
+      curl -s -o /dev/null -X DELETE -H "Authorization: Bearer $token" -H "Accept: application/vnd.github+json" \
+        "https://api.github.com/repos/$org/$r/collaborators/$user" 2>/dev/null || true
+    fi
+  done
+}
+
+# create|remove memory/people/<user>.md, committing ONLY the people dir.
+_people_file() {
+  local user="$1" op="$2" pdir f inviter today
+  pdir="$(_people_dir)"
+  [ -d "$SCRIPT_DIR/memory" ] || { echo "  (no memory dir — skipped person file)" >&2; return 0; }
+  mkdir -p "$pdir"
+  f="$pdir/$user.md"
+  if [ "$op" = "add" ]; then
+    if [ ! -f "$f" ]; then
+      inviter="$(jq -r '.display_name // .github_username // "admin"' "$SCRIPT_DIR/.egregore-state.json" 2>/dev/null || echo admin)"
+      today="$(date -u +%Y-%m-%d)"
+      printf -- '---\nname: %s\nperson_id: github-login:%s\ngithub: %s\ninvited_by: %s\njoined: %s\n---\n' "$user" "$(printf '%s' "$user" | tr '[:upper:]' '[:lower:]')" "$user" "$inviter" "$today" > "$f"
+    fi
+  else
+    rm -f "$f"
+  fi
+  ( cd "$SCRIPT_DIR/memory" 2>/dev/null && git add -A people/ 2>/dev/null \
+      && git commit -q -m "settings: people $op $user" 2>/dev/null \
+      && git push -q 2>/dev/null ) || true
+}
+
+cmd_people() {
+  local action="${1:-list}"; shift || true
+  case "$action" in
+    list)
+      if [ "$JSON" = 1 ]; then _people_json
+      else
+        local names; names="$(_people_names)"
+        if [ -n "$names" ]; then printf '  %s\n' $names; else echo "    (none)"; fi
+      fi ;;
+    add)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh people add <github-handle>" 1
+      if _has_person "$h"; then echo "'$h' is already in people"; return 0; fi
+      _people_github "$h" "add"
+      _people_file "$h" "add"
+      echo "added '$h' (repo access + person file)"
+      [ -n "$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)" ] && echo "  connected org: for the invite link + Telegram, run /invite $h" ;;
+    remove)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh people remove <github-handle>" 1
+      if ! _has_person "$h"; then echo "'$h' is not in people"; return 0; fi
+      _people_github "$h" "remove"
+      _people_file "$h" "remove"
+      echo "removed '$h' (repo access + person file)"
+      [ -n "$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)" ] && echo "  connected org: for full deprovision (Supabase/Neo4j), run /delete-user $h" ;;
+    *) _die "usage: settings.sh people list|add|remove" 1 ;;
+  esac
+}
+
+cmd_dump() {
+  # Always JSON — the launcher calls this once to render the whole settings screen.
+  local people; people="$(_people_json)"
+  jq --argjson people "$people" '{
+    org: .org_name,
+    slug: .slug,
+    hosting: (.features.publishing != false),
+    public_relay: (.features.public_relay == true),
+    repos: [.repos[]? | if type=="object" then . else {name:.} end],
+    admins: (.admins // []),
+    people: $people
+  }' "$CONFIG"
+}
+
+# ── dispatch ─────────────────────────────────────────────────────────────
+
+[ -f "$CONFIG" ] || _die "egregore.json not found at $CONFIG" 2
+
+# Pull out --json (bash 3.2-safe array handling), leave the rest as positionals.
+JSON=0
+_args=()
+for _a in "$@"; do
+  if [ "$_a" = "--json" ]; then JSON=1; else _args+=("$_a"); fi
+done
+set -- "${_args[@]+"${_args[@]}"}"
+
+DOMAIN="${1:-}"; shift || true
+case "$DOMAIN" in
+  hosting) cmd_hosting "$@" ;;
+  relay)   cmd_relay "$@" ;;
+  repo)    cmd_repo "$@" ;;
+  admin)   cmd_admin "$@" ;;
+  people)  cmd_people "$@" ;;
+  dump)    cmd_dump ;;
+  ""|-h|--help|help) usage 0 ;;
+  *) _die "unknown settings domain: '$DOMAIN' (try: hosting, relay, repo, admin, people, dump)" 1 ;;
+esac

package/runtime/prime/bin/telemetry.sh

@@ -0,0 +1,391 @@
+#!/usr/bin/env bash
+# Egregore telemetry — privacy-respecting product analytics.
+# Mirrors bin/graph.sh and bin/notify.sh patterns.
+#
+# Subcommands:
+#   emit <type> <json>   Append event to local JSONL buffer (no network)
+#   flush                Send buffered events to API and clear buffer
+#   status               Show telemetry status (enabled/disabled, buffer size)
+#   enable               Enable telemetry
+#   disable              Disable telemetry
+#   clear                Clear local buffer
+#   show [n]             Show last N events from buffer (default 10)
+#
+# Consent: opt-out via EGREGORE_NO_TELEMETRY=1, DO_NOT_TRACK=1,
+#          or .egregore-state.json → "telemetry": false
+#
+# Never collected: file paths, file contents, code, env var values,
+#                  conversation content, command arguments with user content.
+# Only collected: command names, timestamps, durations, error codes, branch names.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+BUFFER_DIR="$HOME/.egregore"
+BUFFER_FILE="$BUFFER_DIR/telemetry.jsonl"
+STATE_FILE="$SCRIPT_DIR/.egregore-state.json"
+CONFIG="$SCRIPT_DIR/egregore.json"
+ENV_FILE="$SCRIPT_DIR/.env"
+MAX_BUFFER_BYTES=1048576  # 1MB
+MAX_EVENTS_AFTER_TRUNCATE=500
+LOCK_DIR="$BUFFER_DIR/telemetry.lock"
+# Public relay for local/OSS egregores without API keys
+TELEMETRY_RELAY_URL="https://egregore-production-55f2.up.railway.app"
+
+# --- Cross-platform file locking via mkdir (atomic on all POSIX systems) ---
+_lock() {
+  local attempts=0
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    attempts=$((attempts + 1))
+    if [ "$attempts" -gt 50 ]; then
+      local holder_pid
+      holder_pid=$(cat "$LOCK_DIR/pid" 2>/dev/null || echo "")
+      if [ -n "$holder_pid" ] && ! kill -0 "$holder_pid" 2>/dev/null; then
+        rm -rf "$LOCK_DIR" 2>/dev/null
+        continue
+      fi
+      return 1
+    fi
+    sleep 0.1
+  done
+  echo $$ > "$LOCK_DIR/pid" 2>/dev/null
+}
+
+_unlock() {
+  rm -rf "$LOCK_DIR" 2>/dev/null
+}
+
+trap '_unlock' EXIT
+
+# --- Consent check (fast path) ---
+_check_consent() {
+  # Environment variable opt-outs (fastest check)
+  [ "${EGREGORE_NO_TELEMETRY:-}" = "1" ] && return 1
+  [ "${DO_NOT_TRACK:-}" = "1" ] && return 1
+
+  # State file opt-out
+  if [ -f "$STATE_FILE" ]; then
+    local val
+    val=$(jq -r '.telemetry // "true"' "$STATE_FILE" 2>/dev/null || echo "true")
+    [ "$val" = "false" ] && return 1
+  fi
+
+  return 0
+}
+
+# --- Debug mode ---
+_is_debug() {
+  [ "${EGREGORE_TELEMETRY_DEBUG:-}" = "1" ]
+}
+
+# --- Resolve identity (from env vars first, fallback to config files) ---
+_resolve_user() {
+  if [ -n "${EGREGORE_USER:-}" ]; then
+    echo "$EGREGORE_USER"
+  elif [ -f "$STATE_FILE" ]; then
+    jq -r '.github_username // .name // "unknown"' "$STATE_FILE" 2>/dev/null || echo "unknown"
+  else
+    echo "unknown"
+  fi
+}
+
+_resolve_org() {
+  if [ -n "${EGREGORE_ORG:-}" ]; then
+    echo "$EGREGORE_ORG"
+  elif [ -f "$CONFIG" ]; then
+    jq -r '.slug // .github_org // "unknown"' "$CONFIG" 2>/dev/null || echo "unknown"
+  else
+    echo "unknown"
+  fi
+}
+
+_resolve_proj_hash() {
+  # Use git common dir so worktrees hash to the same path as the main checkout
+  local repo_root
+  repo_root=$(git -C "$SCRIPT_DIR" rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's|/\.git$||') || repo_root="$SCRIPT_DIR"
+  echo -n "$repo_root" | md5 2>/dev/null || echo -n "$repo_root" | md5sum 2>/dev/null | cut -d' ' -f1
+}
+
+_resolve_session_id() {
+  if [ -n "${EGREGORE_SESSION_ID:-}" ]; then
+    echo "$EGREGORE_SESSION_ID"
+    return
+  fi
+
+  # Fallback: read from file written by session-start.sh
+  # (env vars from hooks don't propagate into the Claude Code agent)
+  local proj_hash
+  proj_hash=$(_resolve_proj_hash)
+  local sid_file="$HOME/.egregore/session-${proj_hash}.id"
+  if [ -f "$sid_file" ]; then
+    cat "$sid_file" 2>/dev/null || echo "unknown"
+  else
+    echo "unknown"
+  fi
+}
+
+_resolve_model() {
+  local proj_hash
+  proj_hash=$(_resolve_proj_hash)
+  local model_file="$HOME/.egregore/session-model-${proj_hash}"
+  if [ ! -s "$model_file" ]; then
+    return 0
+  fi
+
+  local model=""
+  IFS= read -r model < "$model_file" || true
+  if [ -n "$model" ]; then
+    printf '%s\n' "$model"
+  fi
+}
+
+_stamp_model_if_absent() {
+  local compact_data="$1"
+  local has_model=""
+  has_model=$(printf '%s' "$compact_data" | jq -e 'has("model")' 2>/dev/null || true)
+  if [ "$has_model" != "false" ]; then
+    printf '%s' "$compact_data"
+    return 0
+  fi
+
+  local model=""
+  model=$(_resolve_model 2>/dev/null || true)
+  if [ -z "$model" ]; then
+    printf '%s' "$compact_data"
+    return 0
+  fi
+
+  local stamped_data=""
+  if stamped_data=$(printf '%s' "$compact_data" | jq -c --arg m "$model" 'if has("model") then . else . + {model:$m} end' 2>/dev/null); then
+    printf '%s' "$stamped_data"
+  else
+    printf '%s' "$compact_data"
+  fi
+}
+
+# --- emit: append event to local JSONL buffer ---
+cmd_emit() {
+  local event_type="${1:?Usage: telemetry.sh emit <type> <json>}"
+  local data="${2:-"{}"}"
+
+  # Consent gate
+  if ! _check_consent; then
+    return 0
+  fi
+
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  # Compact data to single line — callers may pass pretty-printed JSON
+  local compact_data
+  compact_data=$(printf '%s' "$data" | tr -d '\n' | tr -s ' ')
+  compact_data=$(_stamp_model_if_absent "$compact_data")
+
+  # Debug mode: print to stderr instead of writing
+  if _is_debug; then
+    printf '{"ts":"%s","type":"%s","sid":"%s","org":"%s","user":"%s","data":%s}\n' \
+      "$ts" "$event_type" "$(_resolve_session_id)" "$(_resolve_org)" "$(_resolve_user)" "$compact_data" >&2
+    return 0
+  fi
+
+  # Ensure buffer directory exists
+  mkdir -p "$BUFFER_DIR"
+
+  # Build event line (outside lock for minimal hold time)
+  local line
+  line=$(printf '{"ts":"%s","type":"%s","sid":"%s","org":"%s","user":"%s","data":%s}' \
+    "$ts" "$event_type" "$(_resolve_session_id)" "$(_resolve_org)" "$(_resolve_user)" "$compact_data")
+
+  # Append under lock
+  _lock || { echo "$line" >> "$BUFFER_FILE" 2>/dev/null; return 0; }
+  echo "$line" >> "$BUFFER_FILE"
+
+  # Buffer guard: if file exceeds max size, truncate to last N events
+  if [ -f "$BUFFER_FILE" ]; then
+    local size
+    size=$(wc -c < "$BUFFER_FILE" 2>/dev/null | tr -d ' ')
+    if [ "$size" -gt "$MAX_BUFFER_BYTES" ] 2>/dev/null; then
+      local tmp="$BUFFER_FILE.truncate.$$"
+      tail -n "$MAX_EVENTS_AFTER_TRUNCATE" "$BUFFER_FILE" > "$tmp" 2>/dev/null \
+        && mv "$tmp" "$BUFFER_FILE" \
+        || rm -f "$tmp"
+    fi
+  fi
+  _unlock
+}
+
+# --- flush: send buffered events to API ---
+cmd_flush() {
+  if [ ! -f "$BUFFER_FILE" ] || [ ! -s "$BUFFER_FILE" ]; then
+    return 0
+  fi
+
+  # Read API config
+  local api_url=""
+  local api_key=""
+  local endpoint=""
+  local auth_header=""
+  if [ -f "$CONFIG" ]; then
+    api_url=$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null || true)
+  fi
+  if [ -f "$ENV_FILE" ]; then
+    api_key=$(grep '^EGREGORE_API_KEY=' "$ENV_FILE" 2>/dev/null | cut -d'=' -f2- || true)
+  fi
+
+  if [ -n "$api_url" ] && [ -n "$api_key" ]; then
+    # Connected mode: authenticated ingest
+    endpoint="${api_url}/api/telemetry/ingest"
+    auth_header="Authorization: Bearer $api_key"
+  else
+    # Local/OSS mode: public relay (no auth needed)
+    endpoint="${TELEMETRY_RELAY_URL}/api/telemetry/relay"
+    auth_header=""
+  fi
+
+  # Atomic rotate under lock: move buffer so new events can keep writing
+  _lock || return 0
+  local flush_file="$BUFFER_FILE.flush.$$"
+  mv "$BUFFER_FILE" "$flush_file" 2>/dev/null || { _unlock; return 0; }
+  _unlock
+
+  # POST to API
+  local response
+  local http_code
+  local curl_args=(-s -o /dev/null -w '%{http_code}' -X POST "$endpoint"
+    -H "Content-Type: application/x-ndjson"
+    --data-binary "@$flush_file"
+    --max-time 15)
+  if [ -n "$auth_header" ]; then
+    curl_args+=(-H "$auth_header")
+  fi
+  http_code=$(curl "${curl_args[@]}" 2>/dev/null || echo "000")
+
+  if [ "$http_code" -ge 200 ] 2>/dev/null && [ "$http_code" -lt 300 ] 2>/dev/null; then
+    # Success — remove flush file
+    rm -f "$flush_file"
+  else
+    # Failure — move events back so they aren't lost (under lock to prevent races)
+    _lock || { mv "$flush_file" "$BUFFER_FILE" 2>/dev/null || true; return 1; }
+    if [ -f "$BUFFER_FILE" ]; then
+      # New events were written while we were flushing; prepend old events
+      cat "$flush_file" "$BUFFER_FILE" > "$BUFFER_FILE.merge.$$" 2>/dev/null \
+        && mv "$BUFFER_FILE.merge.$$" "$BUFFER_FILE" \
+        && rm -f "$flush_file" \
+        || rm -f "$BUFFER_FILE.merge.$$"
+    else
+      mv "$flush_file" "$BUFFER_FILE" 2>/dev/null || true
+    fi
+    _unlock
+  fi
+}
+
+# --- status: show telemetry status ---
+cmd_status() {
+  echo "Telemetry status:"
+  echo ""
+
+  # Consent
+  if _check_consent; then
+    echo "  Enabled: yes"
+  else
+    echo "  Enabled: no"
+    if [ "${EGREGORE_NO_TELEMETRY:-}" = "1" ]; then
+      echo "  Reason: EGREGORE_NO_TELEMETRY=1"
+    elif [ "${DO_NOT_TRACK:-}" = "1" ]; then
+      echo "  Reason: DO_NOT_TRACK=1"
+    else
+      echo "  Reason: telemetry=false in .egregore-state.json"
+    fi
+  fi
+
+  # Buffer
+  if [ -f "$BUFFER_FILE" ]; then
+    local count size
+    count=$(grep -c '^{' "$BUFFER_FILE" 2>/dev/null || echo 0)
+    size=$(wc -c < "$BUFFER_FILE" 2>/dev/null | tr -d ' ')
+    echo "  Buffer: $count events ($size bytes)"
+    echo "  Path: $BUFFER_FILE"
+  else
+    echo "  Buffer: empty"
+  fi
+
+  echo ""
+  echo "  Opt-out: set EGREGORE_NO_TELEMETRY=1 in .env, or run /telemetry off"
+}
+
+# --- enable: turn telemetry on ---
+cmd_enable() {
+  if [ -f "$STATE_FILE" ]; then
+    jq '.telemetry = true' "$STATE_FILE" > "$STATE_FILE.tmp" \
+      && mv "$STATE_FILE.tmp" "$STATE_FILE"
+  fi
+  echo "Telemetry enabled."
+}
+
+# --- disable: turn telemetry off ---
+cmd_disable() {
+  if [ -f "$STATE_FILE" ]; then
+    jq '.telemetry = false' "$STATE_FILE" > "$STATE_FILE.tmp" \
+      && mv "$STATE_FILE.tmp" "$STATE_FILE"
+  else
+    echo '{"telemetry": false}' > "$STATE_FILE"
+  fi
+  echo "Telemetry disabled."
+}
+
+# --- clear: delete local buffer ---
+cmd_clear() {
+  rm -f "$BUFFER_FILE"
+  echo "Telemetry buffer cleared."
+}
+
+# --- show: display last N events ---
+cmd_show() {
+  local n="${1:-10}"
+  if [ ! -f "$BUFFER_FILE" ] || [ ! -s "$BUFFER_FILE" ]; then
+    echo "No buffered events."
+    return 0
+  fi
+  echo "Last $n events:"
+  echo ""
+  # Extract JSON objects (handles both single-line and legacy multi-line format)
+  grep '^{' "$BUFFER_FILE" | tail -n "$n" | jq -c . 2>/dev/null \
+    || grep '^{' "$BUFFER_FILE" | tail -n "$n"
+}
+
+# --- Main dispatch ---
+case "${1:-status}" in
+  emit)
+    shift
+    cmd_emit "$@"
+    ;;
+  flush)
+    cmd_flush
+    ;;
+  status)
+    cmd_status
+    ;;
+  enable)
+    cmd_enable
+    ;;
+  disable)
+    cmd_disable
+    ;;
+  clear)
+    cmd_clear
+    ;;
+  show)
+    shift
+    cmd_show "${1:-10}"
+    ;;
+  help|*)
+    echo "Usage: telemetry.sh <command>"
+    echo ""
+    echo "Commands:"
+    echo "  emit <type> <json>  Append event to local buffer (no network)"
+    echo "  flush               Send buffered events to API"
+    echo "  status              Show telemetry status"
+    echo "  enable              Enable telemetry"
+    echo "  disable             Disable telemetry"
+    echo "  clear               Clear local buffer"
+    echo "  show [n]            Show last N events (default 10)"
+    ;;
+esac