patchwork-os 0.2.0-alpha.3 → 0.2.0-alpha.31

package/README.bridge.md

@@ -40,6 +40,12 @@ claude --ide
 
 > **Updating?** Use `npm install -g claude-ide-bridge@latest` — `npm update -g` may lag the registry cache after a new release.
 
+> **macOS LaunchAgent users:** always install from the registry (`npm install -g patchwork-os`) or
+> from a tarball (`npm pack && npm install -g patchwork-os-*.tgz`).
+> Running `npm install -g .` from a repo checkout creates a symlink — the macOS sandbox
+> cannot follow it, causing EPERM when launchctl starts the bridge.
+> `patchwork-os launchd install` will refuse to proceed and print fix instructions.
+
 After `init`, type `/mcp` in Claude Code to confirm the bridge is connected. Type `/ide` to see open files, diagnostics, and editor state.
 
 > **One bridge per workspace.** Each project runs its own bridge instance on its own port. Start a separate `claude-ide-bridge --watch` in each directory.

package/README.md

@@ -25,14 +25,16 @@ Patchwork OS watches for things that matter, acts, and asks before anything risk
 ## After init
 
 ```bash
-patchwork-os recipe list            # see installed recipes
-patchwork-os recipe run daily-status  # run one now
-patchwork-os                        # open terminal dashboard
+patchwork-os recipe list                    # see installed recipes
+patchwork-os recipe run daily-status      # run one now
+patchwork-os recipe run morning-brief --local  # run with local LLM
+patchwork-os tools list                   # browse all 140+ tools
+patchwork-os                              # open terminal dashboard
 ```
 
-The oversight web UI runs at `http://localhost:3100` when the bridge is active.
+The oversight web UI runs at `http://localhost:3100` when the bridge is active. The dashboard shows live sessions, pending approvals, recent recipe runs, and analytics.
 
-## 5 starter recipes (no API key needed)
+## Starter recipes (no external API keys needed)
 
 | Recipe | Trigger | What it does |
 |---|---|---|
@@ -41,25 +43,48 @@ The oversight web UI runs at `http://localhost:3100` when the bridge is active.
 | `watch-failing-tests` | test run | drops triage note to inbox on failure |
 | `lint-on-save` | file save | surfaces new TS/JS diagnostics to inbox |
 | `stale-branches` | cron weekly | lists branches older than 30 days |
+| `morning-brief` | cron 08:00 | commits + Linear issues + Calendar events |
+| `sentry-to-linear` | manual | Sentry issue → Linear ticket (one-shot) |
 
-All 5 write to `~/.patchwork/inbox/` only. Nothing is sent anywhere without your approval.
+Local recipes write to `~/.patchwork/inbox/` only. Connectors (Linear, Sentry, etc.) require API keys and approval-gated writes.
 
-## Roadmap
+## What's working today
 
-| Phase | Status |
+| Feature | Status |
 |---|---|
-| Foundation — init, recipes, terminal dashboard | **shipped (W1)** |
-| Connectors — Gmail, calendar, Slack | W2 |
-| Mobile oversight — approve from phone | W3 |
-| Community recipes + ecosystem | Q3 |
-
-## From source
+| `patchwork-init` — one-command setup | **shipped** |
+| Terminal dashboard (`patchwork-os`) | **shipped** |
+| Web oversight UI (approvals, sessions, recipes) | **shipped** |
+| Recipe runner (YAML, cron, manual, webhook) | **shipped** |
+| Multi-provider LLM (Claude, Gemini, OpenAI, Grok, Ollama) | **shipped** |
+| Linear connector (read + approval-gated write) | **shipped** |
+| Sentry connector (fetch issues, stack traces) | **shipped** |
+| Google Calendar connector (read-only) | **shipped** |
+| Slack connector (post messages, list channels) | **shipped** |
+| 140+ MCP tools (LSP, git, tests, diagnostics) | **shipped** |
+| Cross-session memory (traces, handoff notes) | **shipped** |
+| Gmail connector | W2 |
+| Mobile oversight PWA | W3 |
+| Community recipe marketplace | Q3 |
+
+## Install
+
+**From the registry (recommended):**
+```bash
+npm install -g patchwork-os
+patchwork-os patchwork-init
+```
 
+**From a local build (development / CI):**
 ```bash
 git clone https://github.com/Oolab-labs/patchwork-os
 cd patchwork-os
 npm install && npm run build
-node dist/index.js patchwork-init
+# Use npm pack to create a real copy — do NOT use `npm install -g .`
+# That creates a symlink which breaks the macOS LaunchAgent (EPERM at startup).
+npm pack
+npm install -g patchwork-os-*.tgz
+patchwork-os patchwork-init
 ```
 
 ## License

package/deploy/bootstrap-vps.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# deploy/bootstrap-vps.sh
+# Full VPS bootstrap for patchworkos.com
+# Run as root on a fresh Ubuntu 24.04 VPS
+# Usage: bash bootstrap-vps.sh
+
+set -euo pipefail
+
+DOMAIN="patchworkos.com"
+EMAIL="support@gigsecure.co.ke"
+BRIDGE_PORT=3284
+BRIDGE_USER="patchwork"
+BRIDGE_HOME="/opt/patchwork"
+NODE_VERSION="22"
+
+# ── Colours ──────────────────────────────────────────────────────────────────
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+info()  { echo -e "${GREEN}[bootstrap]${NC} $*"; }
+warn()  { echo -e "${YELLOW}[bootstrap]${NC} $*"; }
+error() { echo -e "${RED}[bootstrap]${NC} $*"; exit 1; }
+
+# ── 1. System updates ─────────────────────────────────────────────────────────
+info "Updating system packages..."
+apt-get update -qq
+apt-get upgrade -y -qq
+apt-get install -y -qq curl wget gnupg2 ca-certificates lsb-release \
+  nginx certbot python3-certbot-nginx ufw git jq unzip
+
+# ── 2. Node.js ────────────────────────────────────────────────────────────────
+info "Installing Node.js ${NODE_VERSION}..."
+curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - >/dev/null
+apt-get install -y -qq nodejs
+node --version
+npm --version
+
+# ── 3. Service user ───────────────────────────────────────────────────────────
+info "Creating service user '${BRIDGE_USER}'..."
+id "${BRIDGE_USER}" &>/dev/null || useradd -r -m -d "${BRIDGE_HOME}" -s /bin/bash "${BRIDGE_USER}"
+mkdir -p "${BRIDGE_HOME}"
+chown "${BRIDGE_USER}:${BRIDGE_USER}" "${BRIDGE_HOME}"
+
+# ── 4. Install bridge globally ────────────────────────────────────────────────
+info "Installing claude-ide-bridge from npm..."
+npm install -g claude-ide-bridge 2>&1 | tail -5
+BRIDGE_BIN="$(which claude-ide-bridge)"
+info "Bridge binary: ${BRIDGE_BIN}"
+
+# ── 5. Generate fixed token ───────────────────────────────────────────────────
+FIXED_TOKEN="$(uuidgen | tr '[:upper:]' '[:lower:]')"
+info "Generated bridge token (save this!): ${FIXED_TOKEN}"
+
+# Persist token to a file readable only by root + patchwork user
+TOKEN_FILE="/etc/patchwork/bridge-token"
+mkdir -p /etc/patchwork
+echo "${FIXED_TOKEN}" > "${TOKEN_FILE}"
+chown root:"${BRIDGE_USER}" "${TOKEN_FILE}"
+chmod 640 "${TOKEN_FILE}"
+
+# ── 6. Systemd service ────────────────────────────────────────────────────────
+info "Writing systemd service..."
+cat > /etc/systemd/system/patchwork-bridge.service <<EOF
+[Unit]
+Description=Patchwork OS — Claude IDE Bridge
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${BRIDGE_USER}
+Group=${BRIDGE_USER}
+WorkingDirectory=${BRIDGE_HOME}
+Environment=NODE_ENV=production
+Environment=HOME=${BRIDGE_HOME}
+
+ExecStart=${BRIDGE_BIN} \\
+  --bind 0.0.0.0 \\
+  --port ${BRIDGE_PORT} \\
+  --vps \\
+  --issuer-url https://${DOMAIN} \\
+  --cors-origin https://claude.ai \\
+  --cors-origin https://app.patchworkos.com \\
+  --fixed-token ${FIXED_TOKEN}
+
+Restart=always
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=patchwork-bridge
+
+# Hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=${BRIDGE_HOME}
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable patchwork-bridge
+
+# ── 7. UFW firewall ───────────────────────────────────────────────────────────
+info "Configuring firewall..."
+ufw --force reset >/dev/null
+ufw default deny incoming >/dev/null
+ufw default allow outgoing >/dev/null
+ufw allow ssh >/dev/null
+ufw allow http >/dev/null
+ufw allow https >/dev/null
+ufw --force enable >/dev/null
+ufw status
+
+# ── 8. Nginx config — HTTP only first (certbot needs nginx up to issue cert) ──
+info "Writing nginx config (HTTP only)..."
+cat > /etc/nginx/sites-available/patchworkos <<'NGINX'
+server {
+    listen 80;
+    listen [::]:80;
+    server_name patchworkos.com www.patchworkos.com;
+
+    location /.well-known/acme-challenge/ { root /var/www/html; }
+
+    location / {
+        proxy_pass         http://127.0.0.1:3284;
+        proxy_http_version 1.1;
+        proxy_set_header   Upgrade $http_upgrade;
+        proxy_set_header   Connection "upgrade";
+        proxy_set_header   Host $host;
+        proxy_set_header   X-Real-IP $remote_addr;
+        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+}
+NGINX
+
+ln -sf /etc/nginx/sites-available/patchworkos /etc/nginx/sites-enabled/patchworkos
+rm -f /etc/nginx/sites-enabled/default
+
+nginx -t
+systemctl reload nginx
+
+# ── 9. TLS certificate ────────────────────────────────────────────────────────
+info "Issuing Let's Encrypt certificate for ${DOMAIN}..."
+certbot --nginx \
+  -d "${DOMAIN}" \
+  -d "www.${DOMAIN}" \
+  --non-interactive \
+  --agree-tos \
+  --email "${EMAIL}" \
+  --redirect
+
+# Certbot rewrites the nginx config with SSL — reload to apply
+systemctl reload nginx
+
+# ── 10. Start bridge ──────────────────────────────────────────────────────────
+info "Starting bridge service..."
+systemctl start patchwork-bridge
+sleep 3
+systemctl is-active patchwork-bridge && info "Bridge is running." || warn "Bridge may have failed — check: journalctl -u patchwork-bridge -n 50"
+
+# ── 11. Print summary ─────────────────────────────────────────────────────────
+echo ""
+echo -e "${GREEN}═══════════════════════════════════════════════════${NC}"
+echo -e "${GREEN}  Patchwork OS — VPS bootstrap complete${NC}"
+echo -e "${GREEN}═══════════════════════════════════════════════════${NC}"
+echo ""
+echo "  Domain:       https://${DOMAIN}"
+echo "  Bridge port:  ${BRIDGE_PORT} (internal, nginx proxied)"
+echo "  Token file:   ${TOKEN_FILE}"
+echo "  Token:        ${FIXED_TOKEN}"
+echo ""
+echo "  Service:      systemctl status patchwork-bridge"
+echo "  Logs:         journalctl -u patchwork-bridge -f"
+echo "  Nginx logs:   tail -f /var/log/nginx/access.log"
+echo ""
+echo -e "${YELLOW}  Save the token above — you'll need it to connect Claude Code.${NC}"
+echo ""
+echo "  To connect Claude Code remotely:"
+echo "    claude mcp add patchwork https://${DOMAIN}/mcp --token ${FIXED_TOKEN}"
+echo ""

package/deploy/deploy-dashboard.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# deploy-dashboard.sh — Build dashboard locally and deploy to VPS
+# Run from Mac: bash deploy/deploy-dashboard.sh
+set -euo pipefail
+
+VPS="root@185.167.97.141"
+REMOTE_DIR="/opt/patchwork-dashboard"
+PM2_NAME="patchwork-dashboard"
+PORT=3200
+NGINX_CONF="/etc/nginx/sites-available/patchworkos"
+DASHBOARD_URL="https://patchworkos.com/dashboard"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DASHBOARD_DIR="$REPO_ROOT/dashboard"
+
+echo "==> Building dashboard..."
+cd "$DASHBOARD_DIR"
+npm run build
+
+echo "==> Packaging standalone build..."
+TARBALL="/tmp/patchwork-dashboard.tar.gz"
+STAGE="/tmp/patchwork-dashboard-stage"
+rm -rf "$STAGE" && mkdir -p "$STAGE"
+
+# Copy standalone output
+cp -r "$DASHBOARD_DIR/.next/standalone/." "$STAGE/"
+# Standalone needs static assets in .next/static
+mkdir -p "$STAGE/.next/static"
+cp -r "$DASHBOARD_DIR/.next/static/." "$STAGE/.next/static/"
+# Copy public dir if it exists
+if [ -d "$DASHBOARD_DIR/public" ]; then
+  cp -r "$DASHBOARD_DIR/public/." "$STAGE/public/"
+fi
+
+tar -czf "$TARBALL" --no-xattrs -C "$STAGE" .
+
+echo "==> Copying tarball to VPS..."
+scp "$TARBALL" "$VPS:/tmp/patchwork-dashboard.tar.gz"
+
+echo "==> Deploying on VPS..."
+# shellcheck disable=SC2087
+ssh "$VPS" bash <<'REMOTE'
+set -euo pipefail
+REMOTE_DIR="/opt/patchwork-dashboard"
+PM2_NAME="patchwork-dashboard"
+PORT=3200
+
+# Stop existing PM2 process if running
+if pm2 list | grep -q "$PM2_NAME"; then
+  pm2 stop "$PM2_NAME" || true
+  pm2 delete "$PM2_NAME" || true
+fi
+
+# Wipe and recreate deploy dir
+rm -rf "$REMOTE_DIR"
+mkdir -p "$REMOTE_DIR"
+
+# Extract
+tar -xzf /tmp/patchwork-dashboard.tar.gz -C "$REMOTE_DIR"
+rm /tmp/patchwork-dashboard.tar.gz
+
+# Copy static assets into standalone's expected location
+mkdir -p "$REMOTE_DIR/.next"
+if [ -d "$REMOTE_DIR/.next/static" ]; then
+  echo "static dir already in place"
+else
+  # tar may have extracted flat; handle both layouts
+  if [ -d /tmp/dashboard-static ]; then
+    cp -r /tmp/dashboard-static "$REMOTE_DIR/.next/static"
+  fi
+fi
+
+# Also copy public dir if present
+if [ -d "$REMOTE_DIR/public" ]; then
+  echo "public dir in place"
+fi
+
+# Write .env.local — secrets must be set via environment before running this script:
+#   PATCHWORK_BRIDGE_TOKEN, DASHBOARD_PASSWORD
+# PATCHWORK_BRIDGE_TOKEN is the bridge auth token (from: patchwork print-token)
+# DASHBOARD_PASSWORD protects the dashboard UI (leave blank to disable auth)
+if [ -f "$REMOTE_DIR/.env.local" ]; then
+  echo ".env.local already exists on VPS — preserving (delete manually to reset)"
+else
+  cat > "$REMOTE_DIR/.env.local" <<ENV
+NEXT_PUBLIC_BASE_PATH=/dashboard
+PATCHWORK_BRIDGE_URL=https://patchworkos.com
+PATCHWORK_BRIDGE_TOKEN=${PATCHWORK_BRIDGE_TOKEN:-REPLACE_ME}
+VAPID_SUBJECT=mailto:support@gigsecure.co.ke
+DASHBOARD_PASSWORD=${DASHBOARD_PASSWORD:-}
+ENV
+  chmod 600 "$REMOTE_DIR/.env.local"
+  echo "Wrote .env.local — review and update secrets if placeholders remain"
+fi
+
+# Install PM2 if missing
+which pm2 || npm install -g pm2
+
+# Start with PM2
+cd "$REMOTE_DIR"
+PORT=3200 pm2 start server.js --name "$PM2_NAME"
+
+pm2 save
+echo "PM2 started: $PM2_NAME on port $PORT"
+REMOTE
+
+echo "==> Configuring nginx..."
+ssh "$VPS" bash <<'NGINX'
+set -euo pipefail
+NGINX_CONF="/etc/nginx/sites-available/patchworkos"
+
+# Add SSE location block if missing
+if ! grep -q "location /dashboard/api/bridge/stream" "$NGINX_CONF"; then
+  # Insert before the closing brace of the SSL server block
+  # We insert just before the last `}` that closes the server block listening on 443
+  python3 - "$NGINX_CONF" <<'PYEOF'
+import sys, re
+
+path = sys.argv[1]
+with open(path) as f:
+    content = f.read()
+
+sse_block = """
+    # SSE passthrough — no buffering
+    location /dashboard/api/bridge/stream {
+        proxy_pass http://127.0.0.1:3200;
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        add_header X-Accel-Buffering no;
+    }
+
+    # Dashboard app
+    location /dashboard {
+        proxy_pass http://127.0.0.1:3200;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 60s;
+    }
+"""
+
+# Find the ssl/443 server block and insert before its closing brace
+# Strategy: find last `}` in file and insert before it
+idx = content.rfind('\n}')
+if idx == -1:
+    print("ERROR: could not find closing brace in nginx config", file=sys.stderr)
+    sys.exit(1)
+
+new_content = content[:idx] + sse_block + content[idx:]
+with open(path, 'w') as f:
+    f.write(new_content)
+print("nginx: location blocks inserted")
+PYEOF
+else
+  echo "nginx: location blocks already present, skipping"
+fi
+
+nginx -t && systemctl reload nginx
+echo "nginx reloaded"
+NGINX
+
+echo ""
+echo "==> Deploy complete!"
+echo "    Dashboard: https://patchworkos.com/dashboard"

package/deploy/deploy-landing.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# deploy-landing.sh — Deploy static landing page to VPS
+# Run from Mac: bash deploy/deploy-landing.sh
+set -euo pipefail
+
+VPS="root@185.167.97.141"
+LANDING_DIR="/var/www/patchwork-landing"
+NGINX_CONF="/etc/nginx/sites-available/patchworkos"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+echo "==> Copying landing page to VPS..."
+ssh "$VPS" "mkdir -p $LANDING_DIR"
+scp "$REPO_ROOT/landing/index.html" "$VPS:$LANDING_DIR/index.html"
+
+echo "==> Updating nginx to serve landing page at root..."
+ssh "$VPS" bash <<'REMOTE'
+set -euo pipefail
+NGINX_CONF="/etc/nginx/sites-available/patchworkos"
+
+# Insert landing page root location if not already present
+if ! grep -q "location = /" "$NGINX_CONF"; then
+  python3 - "$NGINX_CONF" <<'PYEOF'
+import sys, re
+
+path = sys.argv[1]
+with open(path) as f:
+    content = f.read()
+
+landing_blocks = """
+    # Static landing page at root
+    location = / {
+        root /var/www/patchwork-landing;
+        try_files /index.html =404;
+    }
+
+    # Bridge API paths — proxy to bridge
+    location ~ ^/(mcp|oauth|notify|\.well-known|metrics|health|approvals|activity|sessions|traces|recipes|connectors|settings|schemas|push) {
+        proxy_pass http://127.0.0.1:3284;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+"""
+
+# Insert before the SSE/dashboard blocks (before first "location /dashboard")
+# or before the last closing brace if those don't exist
+if 'location /dashboard' in content:
+    idx = content.find('    # SSE passthrough')
+    if idx == -1:
+        idx = content.find('    location /dashboard')
+else:
+    idx = content.rfind('\n}')
+
+if idx == -1:
+    idx = content.rfind('\n}')
+
+new_content = content[:idx] + landing_blocks + content[idx:]
+with open(path, 'w') as f:
+    f.write(new_content)
+print("nginx: landing + bridge location blocks inserted")
+PYEOF
+else
+  echo "nginx: landing location already present, skipping"
+fi
+
+nginx -t && systemctl reload nginx
+echo "nginx reloaded"
+REMOTE
+
+echo ""
+echo "==> Deploy complete!"
+echo "    Landing page: https://patchworkos.com"

package/dist/activationMetrics.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Activation metrics — a small, local-only counter file that tracks how far
+ * along the user is in the "first success" journey. Nothing here is ever
+ * transmitted off-machine. The outbound usage analytics pipeline lives in
+ * `analyticsAggregator.ts` / `analyticsSend.ts` and is a separate concern.
+ *
+ * Intended counters:
+ *   - installedAt            first time any metric was recorded
+ *   - firstRecipeRunAt       timestamp of the first successful recipe run
+ *   - recipeRunsTotal        running count of successful recipe runs
+ *   - recipeRunsByDay        map of YYYY-MM-DD -> count, trimmed to 14 days
+ *   - approvalsPrompted      count of approval requests created
+ *   - approvalsCompleted     count of approvals approved or rejected (not timed out)
+ *
+ * These feed a single "first success in N days" KPI card on the dashboard.
+ *
+ * Opt-out: if the existing outbound analytics preference is explicitly `false`
+ * via `getAnalyticsPref()`, all record operations become no-ops. The user does
+ * not need to re-opt-out; the existing opt-out is sufficient. Reads are
+ * always allowed (they never leave the machine).
+ *
+ * Storage: `~/.patchwork/telemetry.json` (respects PATCHWORK_HOME override).
+ * File is written atomically via tmp+rename with 0o600 permissions.
+ */
+export interface ActivationMetrics {
+    installedAt: number;
+    firstRecipeRunAt: number | null;
+    recipeRunsTotal: number;
+    recipeRunsByDay: Record<string, number>;
+    approvalsPrompted: number;
+    approvalsCompleted: number;
+}
+export interface ActivationSummary {
+    installedAt: number;
+    firstRecipeRunAt: number | null;
+    /** Milliseconds between install and first successful recipe run. Null until first success. */
+    timeToFirstRecipeRunMs: number | null;
+    /** Total successful recipe runs across all time. */
+    recipeRunsTotal: number;
+    /** Recipe runs in the last 7 days (inclusive of today). */
+    recipeRunsLast7Days: number;
+    /** Distinct calendar days with at least one recipe run in the last 7 days. */
+    activeDaysLast7: number;
+    /** Fraction of prompted approvals that were completed (approved or rejected). 0..1 or null. */
+    approvalCompletionRate: number | null;
+    approvalsPrompted: number;
+    approvalsCompleted: number;
+}
+/**
+ * Load metrics from disk. Returns a fresh empty record if the file is missing
+ * or malformed. Never throws on I/O errors.
+ */
+export declare function loadMetrics(configDir?: string, now?: number): ActivationMetrics;
+/**
+ * Record one successful recipe run. Sets `firstRecipeRunAt` on the first call
+ * and increments total + per-day counters. Trims the per-day map so the file
+ * stays O(14 entries).
+ *
+ * No-op if the user has explicitly opted out of analytics.
+ */
+export declare function recordRecipeRun(configDir?: string, now?: number): void;
+/** Record an approval prompt being surfaced to the user. */
+export declare function recordApprovalPrompted(configDir?: string, now?: number): void;
+/** Record an approval being acted on (approved or rejected — not a timeout). */
+export declare function recordApprovalCompleted(configDir?: string, now?: number): void;
+/** Derive a dashboard-friendly summary from a metrics record. Pure function. */
+export declare function computeSummary(metrics: ActivationMetrics, now?: number): ActivationSummary;