create-egregore 0.20.2 → 0.21.0-runtime-mvp.1

package/runtime/claude/.claude/context/telemetry.md

@@ -0,0 +1,133 @@
+# Telemetry Spec
+
+Telemetry makes runtime behavior inspectable without turning organizational
+content into an analytics feed. Rich events are local-first, content-free,
+user-controlled, and excluded from canonical memory and Git.
+
+## How it works
+
+`bin/telemetry.sh` handles all telemetry — mirrors `bin/graph.sh` and `bin/notify.sh` patterns:
+
+```bash
+# Emit an event (O(1) local append, no network)
+bash bin/telemetry.sh emit "command" '{"command":"save"}'
+
+# Check status
+bash bin/telemetry.sh status
+
+# Inspect or export locally
+bash bin/telemetry.sh inspect 10
+bash bin/telemetry.sh export ~/.egregore/exports/telemetry.jsonl
+
+# Prepare an explicit share proposal (does not send)
+bash bin/telemetry.sh share
+```
+
+Events buffer on-device at `~/.egregore/telemetry.jsonl`, outside the project,
+canonical memory, and Git. `flush` remains a compatibility no-op for old
+lifecycle callers and never uploads. Sharing is a separate two-step operation:
+the CLI discloses the exact target, event count, bytes, dataset hash, and fields,
+then requires a fresh short-lived token against the unchanged dataset.
+
+## Consent (opt-out)
+
+Telemetry is on by default. Users can opt out via:
+- `/telemetry off` — persistent opt-out in `.egregore-state.json`
+- `EGREGORE_NO_TELEMETRY=1` in `.env`
+- `DO_NOT_TRACK=1` — standard environment variable
+
+## What is collected
+
+Structured identifiers and scalar metrics: event/task/actor/org/session IDs,
+timestamps, command enums, retrieval type, privacy-safe lexical/vector
+fingerprints when configured, returned/opened artifact IDs (ordered for rank),
+tool-call counts, latency, token counts, writeback/action outcome,
+success/failure codes, and index-spec/version. Metric names are allowlisted and
+string values must be bounded identifiers/enums rather than prose.
+
+## What is NEVER collected
+
+Raw prompts/queries, passages, file paths, file contents, code, env var values,
+secrets, conversation content, prose error messages, or command arguments that
+might contain user content.
+
+## Command instrumentation
+
+**After executing any slash command**, emit a `command` event (fire-and-forget, must not delay response):
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"save"}' 2>/dev/null &
+```
+
+Optional extended payload example: `{"command":"save","model":"haiku-4-5","tier":"haiku","routed":true,"escalated":false,"override":false,"duration_ms":1240}`
+
+All extended fields are optional, and `duration_ms` is measured by the emitting
+wrapper (executor spawn wall-time or script time). Harness adapters may include
+content-free aggregate token counts when they are available.
+
+Replace `"save"` with the actual command name. Do this for every slash command execution.
+
+## Onboarding instrumentation
+
+When completing an onboarding step, emit:
+
+```bash
+bash bin/telemetry.sh emit "onboarding_step" '{"step":"workspace_setup","duration_ms":1200}' 2>/dev/null &
+```
+
+## First-session telemetry notice
+
+On the first session where telemetry events are emitted, if `telemetry_noticed` is not set in `.egregore-state.json`, mention once:
+
+> Egregore records content-free runtime telemetry locally (structured identifiers and metrics — never prompts, code, or content). Nothing is shared automatically. Run `/telemetry` to inspect it or `/telemetry off` to disable collection.
+
+Then set `telemetry_noticed: true` in the state file. Never repeat this notice.
+
+## Session Reports
+
+Separate from telemetry. Users can optionally share session reports during `/wrap` or via `/issue egregore:`. Reports are **opt-in per session** — the user is asked each time and must explicitly agree.
+
+### How it works
+
+`bin/session-report.sh` handles report submission. It POSTs directly to Supabase via the anon key (no API server needed). The agent generates a structured report from the session context inline — no separate LLM call.
+
+```bash
+# Submit a report (reads JSON from stdin)
+echo '{"topic":"...","summary":"..."}' | bash bin/session-report.sh submit
+
+# Check reporting status
+bash bin/session-report.sh status
+```
+
+### What is sent
+
+- AI-analyzed topic + summary (same as what's written to memory)
+- Gap analysis: `{type, detail}` where type is `missing_skill`, `missing_tool`, `repeated_failure`, `wrong_info`, or `confusing_ux`
+- User's own description (if provided)
+- System info: mode, platform, shell, framework version
+- Session duration and message count
+
+### What is NEVER sent
+
+- Code, file contents, or file paths
+- Conversation transcript or user prompts
+- Environment variables or secrets
+- Org-specific data (sanitized before sending — org names, person names, tokens replaced)
+
+### Opt-out
+
+- `EGREGORE_NO_REPORTS=1` in `.env`
+- `.egregore-state.json` → `"session_reports": false`
+- Simply answer "No thanks" when prompted during `/wrap`
+- `DO_NOT_TRACK=1` also disables reports
+
+### Transport
+
+- Direct to Supabase via anon key (INSERT-only RLS policy)
+- If network fails: saved locally to `~/.egregore/reports/` as fallback
+- Telegram notification to maintainers fires server-side via Supabase DB webhook
+- Optional: GitHub issue creation on `egregore-labs/egregore` (user chooses each time)
+
+### Configuration
+
+Reports require `report_url` and `report_key` in `egregore.json`. New OSS installations get these automatically via `create-egregore`. If missing, the report prompt is skipped entirely.

package/runtime/claude/.claude/hooks/boundary-check.sh

@@ -0,0 +1,333 @@
+#!/usr/bin/env bash
+# boundary-check.sh — PreToolUse hook for environment isolation
+# Receives tool input JSON on stdin from Claude Code.
+# Exit 0 = allow, exit 2 = block (reason on stderr).
+# Must be fast (<50ms) — no network calls, just path checks.
+#
+# Two-tier model (decided 2026-07-08, harvest-2026-07-08-boundary-hook-refinement):
+#   HARD tier — paths of other Egregore instances (denied_paths): denied for
+#               every tool, always. No consent path exists.
+#   SOFT tier — everything else outside the boundary: consent-gated for every
+#               tool. Grants live in .egregore-boundary-consent (session-scoped,
+#               cleared by session-start) or in config read roots.
+# Posture (strict|standard|open), lock, and read roots are merged at session
+# start from egregore.json .boundary + .egregore-boundary.local.json into the
+# cached boundary JSON. Sessions running with permission_mode=bypassPermissions
+# skip the soft tier (never the hard tier) unless the org boundary is locked.
+
+# No set -e — hook must never accidentally block by crashing
+# If anything fails unexpectedly, fall through to exit 0 (allow)
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "$0")/../.." && pwd)}"
+
+# --- Guard: if project dir no longer exists (worktree deleted), allow gracefully ---
+if [ ! -d "$PROJECT_DIR" ]; then
+  exit 0
+fi
+
+# --- Load boundary file (cached at session start) ---
+HASH=$(echo -n "$PROJECT_DIR" | md5 2>/dev/null || echo -n "$PROJECT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)
+BOUNDARY_FILE="/tmp/egregore-boundary-${HASH}.json"
+
+if [ ! -f "$BOUNDARY_FILE" ]; then
+  # No boundary computed yet (session-start hasn't run) — allow everything
+  exit 0
+fi
+
+# Read boundary once. Empty fields carry a "-" sentinel: tab counts as IFS
+# whitespace, so a genuinely empty @tsv field would collapse and shift every
+# following field left.
+BOUNDARY_JSON=$(cat "$BOUNDARY_FILE" 2>/dev/null) || exit 0
+IFS=$'\t' read -r B_PROJECT_DIR B_MEMORY_DIR POSTURE LOCKED HAS_READ_ROOTS < <(
+  echo "$BOUNDARY_JSON" | jq -r \
+    '[(.project_dir // "" | if . == "" then "-" else . end), (.memory_dir // "" | if . == "" then "-" else . end), (.posture // "standard"), ((.locked // false) | tostring), (has("read_roots") | tostring)] | @tsv' 2>/dev/null
+) || true
+[ "$B_PROJECT_DIR" = "-" ] && B_PROJECT_DIR=""
+[ "$B_MEMORY_DIR" = "-" ] && B_MEMORY_DIR=""
+case "$POSTURE" in strict|standard|open) ;; *) POSTURE="standard" ;; esac
+[ "$LOCKED" = "true" ] || LOCKED="false"
+
+# Read roots: from boundary JSON when present; legacy boundary files (no key)
+# get the inbox defaults, matching the default posture.
+if [ "$HAS_READ_ROOTS" = "true" ]; then
+  READ_ROOTS=$(echo "$BOUNDARY_JSON" | jq -r '.read_roots[]?' 2>/dev/null) || true
+elif [ "$POSTURE" != "strict" ]; then
+  READ_ROOTS="$HOME/Downloads
+$HOME/Desktop"
+else
+  READ_ROOTS=""
+fi
+
+DENIED_PATHS=$(echo "$BOUNDARY_JSON" | jq -r '.denied_paths[]?' 2>/dev/null) || true
+
+CONSENT_FILE="$PROJECT_DIR/.egregore-boundary-consent"
+
+# --- Read tool input from stdin ---
+INPUT=$(cat)
+IFS=$'\t' read -r TOOL_NAME PERM_MODE < <(
+  echo "$INPUT" | jq -r '[(.tool_name // "" | if . == "" then "-" else . end), (.permission_mode // "")] | @tsv' 2>/dev/null
+) || true
+[ "$TOOL_NAME" = "-" ] && TOOL_NAME=""
+
+if [ -z "$TOOL_NAME" ]; then
+  exit 0
+fi
+
+# Yolo inheritance: a session the user runs in bypassPermissions has already
+# declared maximal trust — Egregore doesn't re-ask (soft tier off). The hard
+# tier stays on. An org lock disables this relaxation.
+RELAXED="false"
+if [ "$LOCKED" != "true" ] && [ "$PERM_MODE" = "bypassPermissions" ]; then
+  RELAXED="true"
+fi
+
+# --- Helper: collapse /./ and component/../ sequences lexically ---
+# Used when the target does not exist on disk, so ../ escapes still normalize.
+normalize_lexical() {
+  local p="$1" prev=""
+  while [ "$p" != "$prev" ]; do
+    prev="$p"
+    p=$(printf '%s' "$p" | sed -E 's|/\./|/|g; s|/[^/]+/\.\./|/|; s|/[^/]+/\.\.$||' 2>/dev/null) || p="$prev"
+  done
+  while [[ "$p" == /../* ]]; do p="/${p#/../}"; done
+  [ -z "$p" ] && p="/"
+  printf '%s\n' "$p"
+}
+
+# --- Helper: resolve path ---
+resolve_path() {
+  local path="$1"
+  path="${path/#\~/$HOME}"
+  path="${path/#\$HOME/$HOME}"
+  if [[ "$path" != /* ]]; then
+    path="$PROJECT_DIR/$path"
+  fi
+  local resolved
+  resolved=$(realpath "$path" 2>/dev/null) && { echo "$resolved"; return; }
+  # Target may not exist yet (e.g. a write destination): resolve the nearest
+  # existing ancestor, then fall back to pure lexical normalization.
+  local dir base
+  dir=$(dirname "$path")
+  base=$(basename "$path")
+  resolved=$(realpath "$dir" 2>/dev/null) && { echo "$resolved/$base"; return; }
+  normalize_lexical "$path"
+}
+
+# --- Helper: HARD tier — another instance's path? ---
+# Self-scope carve-out, per entry: an ENCLOSING denied checkout (different or
+# unproven organization identity) never covers the project's own files — the
+# enclosing tree stays denied while the project stays usable. A denied entry
+# nested INSIDE the project is still enforced: residence under the project
+# proves nothing about identity.
+is_denied() {
+  local resolved="$1" denied in_project=1
+  if [ -n "${B_PROJECT_DIR:-}" ] && [[ "$resolved" == "$B_PROJECT_DIR" || "$resolved" == "$B_PROJECT_DIR/"* ]]; then
+    in_project=0
+  fi
+  for denied in $DENIED_PATHS; do
+    if [[ "$resolved" == "$denied" || "$resolved" == "$denied/"* ]]; then
+      if [ "$in_project" = "0" ] && [[ "$B_PROJECT_DIR" == "$denied" || "$B_PROJECT_DIR" == "$denied/"* ]]; then
+        continue
+      fi
+      return 0
+    fi
+  done
+  return 1
+}
+
+# --- Helper: core boundary (no consent needed, all tiers) ---
+in_core_boundary() {
+  local resolved="$1"
+
+  # Always-allowed system paths
+  case "$resolved" in
+    /tmp/*|/tmp|/private/*|/private) return 0 ;;
+    "$HOME/.claude"/*|"$HOME/.claude") return 0 ;;
+    /usr/*|/etc/*|/var/*|/bin/*|/sbin/*|/opt/*) return 0 ;;
+    /dev/*|/dev|/proc/*|/sys/*) return 0 ;;
+    /System/*|/Applications/*|/Library/*) return 0 ;;
+  esac
+
+  # Allow reading instance registry (needed for multi-instance features)
+  if [[ "$resolved" == "$HOME/.egregore"/* ]]; then
+    return 0
+  fi
+
+  # Project directory
+  if [ -n "${B_PROJECT_DIR:-}" ]; then
+    if [[ "$resolved" == "$B_PROJECT_DIR" || "$resolved" == "$B_PROJECT_DIR/"* ]]; then
+      return 0
+    fi
+  fi
+
+  # Memory directory
+  if [ -n "${B_MEMORY_DIR:-}" ]; then
+    if [[ "$resolved" == "$B_MEMORY_DIR" || "$resolved" == "$B_MEMORY_DIR/"* ]]; then
+      return 0
+    fi
+  fi
+
+  # Managed repos
+  local repo_paths repo_path
+  repo_paths=$(echo "$BOUNDARY_JSON" | jq -r '.managed_repos[]?' 2>/dev/null) || true
+  for repo_path in $repo_paths; do
+    if [[ "$resolved" == "$repo_path" || "$resolved" == "$repo_path/"* ]]; then
+      return 0
+    fi
+  done
+
+  # Parent directory (for sibling repo operations). Denied paths are checked
+  # before this helper is ever consulted, so no denied check needed here.
+  local parent_dir
+  parent_dir="$(dirname "${B_PROJECT_DIR:-$PROJECT_DIR}")"
+  if [[ "$resolved" == "$parent_dir" || "$resolved" == "$parent_dir/"* ]]; then
+    return 0
+  fi
+
+  return 1
+}
+
+# --- Helper: SOFT tier grants ---
+in_read_roots() {
+  local resolved="$1" root
+  for root in $READ_ROOTS; do
+    if [[ "$resolved" == "$root" || "$resolved" == "$root/"* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+is_consented() {
+  local resolved="$1" line
+  # A locked org boundary has no consent path — stale grant files are void.
+  [ "$LOCKED" = "true" ] && return 1
+  [ -f "$CONSENT_FILE" ] || return 1
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    line="${line/#\~/$HOME}"
+    if [[ "$resolved" == "$line" || "$resolved" == "$line/"* ]]; then
+      return 0
+    fi
+  done < "$CONSENT_FILE"
+  return 1
+}
+
+# --- Block messages ---
+block_hard() {
+  local resolved="$1"
+  echo "Environment isolation: $resolved belongs to another Egregore instance. Access is denied for every tool and cannot be consented — do not retry and do not attempt via other tools. If the user needs something from it, they must fetch it themselves in that instance." >&2
+  exit 2
+}
+
+block_soft() {
+  local resolved="$1" action="$2" dir
+  dir=$(dirname "$resolved")
+  if [ "$LOCKED" = "true" ]; then
+    echo "Environment isolation: $resolved is outside this instance's boundary and the org boundary is locked (egregore.json boundary.locked) — no consent path exists. Do not retry. Use AskUserQuestion with options: 'Paste contents inline' / 'Move the file into the repo and point me at the new path' / 'Cancel'." >&2
+  else
+    echo "Boundary consent needed: $resolved is outside this instance's $action surface (posture: $POSTURE). Do not retry yet and do not route around via other tools. Ask via AskUserQuestion with exactly these options: 'Allow $dir for this session' (on approval: append $dir as one line to $PROJECT_DIR/.egregore-boundary-consent, then retry) / 'Always allow on this instance' (on approval: add \"$dir\" to the read[] array in $PROJECT_DIR/.egregore-boundary.local.json, then retry) / 'Paste contents inline' / 'Cancel'. Never write a consent grant without the user's explicit approval in this exchange." >&2
+  fi
+  exit 2
+}
+
+# --- Check based on tool type ---
+case "$TOOL_NAME" in
+  Read|Glob|Grep)
+    if [ "$TOOL_NAME" = "Read" ]; then
+      FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || true
+    else
+      FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.path // empty' 2>/dev/null) || true
+    fi
+    if [ -z "${FILE_PATH:-}" ]; then
+      exit 0  # No path = CWD = project dir, allowed
+    fi
+
+    RESOLVED=$(resolve_path "$FILE_PATH")
+    is_denied "$RESOLVED" && block_hard "$RESOLVED"
+    in_core_boundary "$RESOLVED" && exit 0
+    [ "$POSTURE" = "open" ] && exit 0
+    [ "$RELAXED" = "true" ] && exit 0
+    in_read_roots "$RESOLVED" && exit 0
+    is_consented "$RESOLVED" && exit 0
+    block_soft "$RESOLVED" "read"
+    ;;
+
+  Edit|Write)
+    FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || true
+    if [ -z "${FILE_PATH:-}" ]; then
+      exit 0
+    fi
+
+    RESOLVED=$(resolve_path "$FILE_PATH")
+    is_denied "$RESOLVED" && block_hard "$RESOLVED"
+    in_core_boundary "$RESOLVED" && exit 0
+    # Read roots and posture=open grant reads only — writes always need
+    # consent (or a bypassPermissions session, unless locked).
+    [ "$RELAXED" = "true" ] && exit 0
+    is_consented "$RESOLVED" && exit 0
+    block_soft "$RESOLVED" "write"
+    ;;
+
+  Bash)
+    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) || true
+    if [ -z "${COMMAND:-}" ]; then
+      exit 0
+    fi
+
+    # HARD tier — never relaxed by posture or bypassPermissions.
+    # Pass 1: denied instance paths as literals, matched on a path boundary so
+    # a denied path never matches a longer sibling name sharing its prefix.
+    for denied in ${DENIED_PATHS:-}; do
+      # When the project itself sits inside this denied checkout, a literal
+      # match cannot tell the enclosing tree's files from the project's own
+      # (the project path continues the denied prefix). Pass 2 resolves every
+      # path token and enforces these entries with the self-scope carve-out.
+      if [ -n "${B_PROJECT_DIR:-}" ] && [[ "$B_PROJECT_DIR" == "$denied" || "$B_PROJECT_DIR" == "$denied/"* ]]; then
+        continue
+      fi
+      if echo "$COMMAND" | grep -qF "$denied" 2>/dev/null; then
+        DENIED_ESC=$(printf '%s' "$denied" | sed -E 's|[^A-Za-z0-9/_-]|\\&|g' 2>/dev/null) || DENIED_ESC=""
+        if [ -n "$DENIED_ESC" ] && echo "$COMMAND" | grep -qE "${DENIED_ESC}(\$|[^A-Za-z0-9._-])" 2>/dev/null; then
+          block_hard "$denied"
+        fi
+      fi
+    done
+
+    # Pass 2: resolve path-like tokens — absolute, ~, $HOME, ../ traversal,
+    # and plain relative tokens containing a slash (a denied entry can sit
+    # inside the project, so "relative stays inside the project" is not a
+    # safety argument) — and deny any that resolve into a foreign instance.
+    # Relative tokens resolve against the project dir (the tool's working
+    # directory), best effort.
+    HARD_CANDIDATES=$(echo "$COMMAND" | grep -oE '(~|\$HOME)?/[A-Za-z0-9._/-]+|[A-Za-z0-9._/-]*\.\./[A-Za-z0-9._/-]+|[A-Za-z0-9._-]+/[A-Za-z0-9._/-]+' 2>/dev/null | sort -u | head -40) || true
+    for c in $HARD_CANDIDATES; do
+      RESOLVED=$(resolve_path "$c")
+      is_denied "$RESOLVED" && block_hard "$RESOLVED"
+    done
+
+    # SOFT tier: best-effort. Only user-home-area path literals are checked —
+    # system paths are core-allowed and relative paths stay inside the project.
+    # A missed path degrades to "no prompt", never to a hard-tier breach.
+    [ "$POSTURE" = "open" ] && exit 0
+    [ "$RELAXED" = "true" ] && exit 0
+
+    CANDIDATES=$(echo "$COMMAND" | grep -oE '(~|\$HOME|/Users/[A-Za-z0-9._-]+)/[A-Za-z0-9._/-]+' 2>/dev/null | sort -u | head -20) || true
+    for c in $CANDIDATES; do
+      RESOLVED=$(resolve_path "$c")
+      is_denied "$RESOLVED" && block_hard "$RESOLVED"
+      in_core_boundary "$RESOLVED" && continue
+      in_read_roots "$RESOLVED" && continue
+      is_consented "$RESOLVED" && continue
+      block_soft "$RESOLVED" "shell"
+    done
+    ;;
+
+  *)
+    # Other tools (WebFetch, etc.) — allow
+    exit 0
+    ;;
+esac
+
+# Default: allow
+exit 0