lynkr 9.9.0 → 9.10.0

package/README.md

@@ -68,7 +68,7 @@ The fastest path is the interactive wizard:
 lynkr init
 ```
 
-It asks four questions — usage mode (Claude Pro/Max via wrap, or direct API keys), tier picks for SIMPLE/MEDIUM/COMPLEX/REASONING across the 12 supported providers, credentials for what you chose, and a few routing-intelligence knobs — then writes a fully-populated `.env` with sensible production defaults for everything else (caching, compression, policy budgets, MCP sandbox, agents, rate limiting).
+It asks four questions — usage mode (Claude Pro/Max via wrap, or direct API keys), tier picks for SIMPLE/MEDIUM/COMPLEX/REASONING across the 12 supported providers, credentials for what you chose, and a few routing-intelligence knobs — then writes a fully-populated `.env` with sensible production defaults for everything else (caching, compression, policy budgets, MCP sandbox, rate limiting).
 
 Useful flags:
 
@@ -246,9 +246,9 @@ POLICY_MAX_STEPS=50
 POLICY_MAX_TOOL_CALLS=100
 ```
 
-Lynkr analyzes each request and routes it to the appropriate tier. Simple questions use fast models. Complex refactoring uses powerful models.
+Lynkr analyzes each request and routes it to the appropriate tier. Simple questions use fast models. Complex refactoring uses powerful models. The scorer combines anchor-embedding classification (WS7, payload-invariant) with an LLM difficulty classifier (Phase 6, added 2026-07-19) that catches topic-vs-difficulty confounding — `list the exports from this file` correctly routes to MEDIUM instead of getting boosted to REASONING by "technical vocabulary" alone.
 
-**Result:** 70-90% of requests use cheaper/faster models. Only hard problems hit expensive models.
+**Result:** 70-90% of requests use cheaper/faster models. Only hard problems hit expensive models. **15× reduction in expensive-tier over-routing** vs the anchor-only baseline on the 381-prompt eval set (0.6% vs ~15%).
 
 Tier configuration is strictly authoritative — bandit exploration is constrained to the models you've listed in `TIER_*`, and multi-turn conversations score with a recency-weighted sliding window so context isn't lost on short follow-ups. Conversations get a content-fingerprint session id (clients like Claude Code send none), the decision pins for the session, and a guarded escape ladder (risk keywords, force phrases, score drift, context overflow) re-escalates the moment a task outgrows its model. Full pipeline: [`docs/routing-intelligence.md`](docs/routing-intelligence.md) · intent scorer: [`docs/intent-window-routing.md`](docs/intent-window-routing.md) · verify any change: [`docs/benchmarking.md`](docs/benchmarking.md).
 
@@ -271,17 +271,39 @@ Tier configuration is strictly authoritative — bandit exploration is constrain
 
 ## Advanced Features
 
+### Real-time SSE streaming (all tiers)
+
+Responses stream token-by-token instead of arriving all at once — including
+through the tier router. Two mechanisms, both on by default:
+
+- **Native passthrough**: when the upstream already speaks Anthropic SSE
+  (Anthropic endpoints, Z.AI, Ollama v0.14+), Lynkr pipes the bytes straight
+  through with backpressure. Kill switch: `LYNKR_NATIVE_PASSTHROUGH=false`.
+- **Cross-format transform**: OpenAI-format upstreams (OpenAI, Azure OpenAI,
+  OpenRouter, Databricks, llama.cpp, LM Studio) are reshaped into Anthropic
+  events in flight — including reassembling tool-call argument fragments into
+  clean `tool_use` blocks. Kill switch: `LYNKR_STREAM_TRANSFORM=false`.
+
+The `LYNKR_VISIBLE_ROUTING` badge streams too (injected as the first content
+block), and telemetry is recorded on stream close with real token counts.
+Fallback safety: if an upstream fails before the first byte, the request
+falls back to the buffered path automatically.
+
+```bash
+# Ollama thinking models (MiniMax): streaming skips the <think>-leak repair.
+# If you see raw <think> text in responses, buffer that provider instead:
+LYNKR_OLLAMA_BUFFER_RESPONSES=true   # default true; false = stream Ollama
+```
+
 ### Token Optimization (60-80% savings)
 ```bash
 # Enable all optimizations
 PROMPT_CACHE_ENABLED=true
 SEMANTIC_CACHE_ENABLED=true
-TOOL_INJECTION_ENABLED=false
-CODE_MODE_ENABLED=true
 ```
 
-Always-on (no config): **smart tool selection** (server mode), **RTK tool-result
-compression** (test/git/grep/lint/build/JSON output), **MCP tool dedup** (drops
+Always-on (no config): **RTK tool-result compression**
+(test/git/grep/lint/build/JSON output), **MCP tool dedup** (drops
 built-in WebSearch/WebFetch when an Exa/Tavily MCP tool is present), and
 **request bypass** (Claude CLI Warmup / title-extraction calls are answered
 locally, never hitting a provider).
@@ -292,6 +314,25 @@ CAVEMAN_ENABLED=true        # off by default — nudges the model to be concise
 CAVEMAN_LEVEL=lite          # lite | full | ultra
 ```
 
+### Built-in dashboard
+
+Open `http://localhost:8081/dashboard` while Lynkr is running. No setup, reads
+the local telemetry store:
+
+- **Spend & savings** — actual cost vs what the same traffic would have cost
+  on the flagship model (the counterfactual no pass-through gateway can show,
+  since they neither pick your model nor see local-model traffic)
+- **Tier mix** — daily request breakdown across SIMPLE/MEDIUM/COMPLEX/REASONING
+- **Routing accuracy** — over-/under-provisioned request counts, a self-audit
+  of the tier router's decisions
+- **Request logs** — filterable by provider, tier, and errors, with latency,
+  tokens, and cost per request
+- **Provider health** — configured providers, credential warnings, circuit
+  breaker states
+
+JSON APIs behind it (`/dashboard/api/overview|usage|routing|logs`) if you want
+the raw numbers.
+
 ### Cost tracking & model pricing
 Per-request cost is computed from a model-pricing registry (LiteLLM → models.dev,
 cached 24h) and recorded in telemetry. Models the registry doesn't know record
@@ -413,16 +454,15 @@ npm start
 
 Head-to-head against **LiteLLM** on the **same backends** (Ollama `minimax-m2.5`, Moonshot, Azure OpenAI), 9 scenarios across 4 feature categories. Apples-to-apples comparison is Lynkr vs LiteLLM **billed tokens on the same scenario**. Run with `node benchmark-tier-routing.js`.
 
-> _Run: June 5, 2026 · Lynkr v9.3.2 · LiteLLM v1.87.1 · macOS, Apple Silicon._
+> _Runs: token benchmarks — June 5, 2026 (Lynkr v9.3.2 · LiteLLM v1.87.1). Tier routing head-to-head — **re-run July 19, 2026** (Lynkr working tree w/ Phase-6 classifier + config B · LiteLLM v1.94.0.dev1 Auto Router v2). macOS, Apple Silicon._
 
 ### Token reduction (vs LiteLLM, same model & prompt)
 
 | Mechanism | Lynkr | LiteLLM | Result |
 |---|---|---|---|
-| Smart tool selection (14 tools) | **959** tokens · $0.0044 | 2,085 tokens · $0.0091 | **53% fewer tokens, 52% cheaper** |
 | TOON compression (60-item grep JSON) | **427** tokens · $0.009 | 3,458 tokens · $0.018 | **87.6% fewer tokens, 50% cheaper** |
 
-Lynkr strips irrelevant tool schemas (smart tool selection) and binary-compresses large JSON tool results (TOON) — both in-process, no added latency.
+Lynkr binary-compresses large JSON tool results (TOON) in-process, with no added latency.
 
 ### Semantic cache
 
@@ -433,28 +473,56 @@ Lynkr strips irrelevant tool schemas (smart tool selection) and binary-compresse
 
 Near-identical prompts return cached responses in 171ms. Zero model tokens billed on a cache hit.
 
-### Tier routing — vs LiteLLM Auto Router v2 (July 15, 2026)
+### Tier routing — vs LiteLLM Auto Router v2 (re-run July 19, 2026)
 
-LiteLLM v1.94 shipped a native complexity router (`auto_router/complexity_router`) with the same four tier names Lynkr uses. Head-to-head on the **same backends** with identical prompts, both proxies judged against the same acceptable-tier sets (11 routing scenarios, `MODE=routing node benchmark-tier-routing.js`, LiteLLM config in `litellm-autorouter-v2.yaml`):
+LiteLLM v1.94 shipped a native complexity router (`auto_router/complexity_router`) with the same four tier names Lynkr uses. Head-to-head on the **same backends** with identical prompts, both proxies live, both judged against the same acceptable-tier sets (11 routing scenarios, `MODE=routing node benchmark-tier-routing.js`, LiteLLM config in `litellm-autorouter-v2.yaml`):
 
-| Router | Routing-correct | Routing overhead |
+| Router | Routing-correct | Notes |
 |---|---|---|
-| **Lynkr** | **11/11** | local embedding, ~0 marginal cost/latency after cache |
-| LiteLLM v2 — heuristic (default) | 4/11 | <1ms, free — but every miss under-routed hard work (banking security analysis, autonomous agentic loop) to the free local model |
-| LiteLLM v2 — LLM classifier | 6–8/11 (non-deterministic across runs) | a paid GPT-5.2 call + ~2–3s on **every** request; fails outright with local classifier models (structured-output errors → silent heuristic fallback) |
+| **Lynkr (Phase-6 classifier + config B)** | **11/11 ✅** | anchor embedding + local LLM classifier reconcile + FORCE_REASONING patterns + risk-remap; ~500ms warm classifier call, cached |
+| LiteLLM v2 — heuristic (default) | **4/11** | every miss *under-routed* — banking security analysis, whole-pipeline refactor, prod auth-file fix, autonomous agentic loop all sent to a 7B local model |
+| LiteLLM v2 — LLM classifier | 6–8/11 (non-deterministic) | paid GPT-5.2 call + ~2–3s on **every** request; fails outright with local classifier models |
+
+**The 7 requests LiteLLM v2 misroutes to a 7B ollama model (should be COMPLEX or REASONING):**
+
+| What you typed | Lynkr sends to | LiteLLM sends to |
+|---|---|---|
+| "Analyse security trade-offs of JWT vs httpOnly cookies for a banking app" | Claude Opus (top) | **ollama 7B** ❌ |
+| "Refactor the entire ingestion pipeline and give me the plan" | z.ai GLM-5.2 (mid) | **ollama 7B** ❌ |
+| "Fix the null-check bug in `src/auth/middleware.ts`" | Claude Opus (risk-remap) | **ollama 7B** ❌ |
+| "Figure out why this test is flaky. You have full autonomy — iterate until 10 runs pass" | Claude Opus (autonomous) | **ollama 7B** ❌ |
+| "please summarize the exports of this file quickly" | ollama minimax (correct — MEDIUM) | ollama minimax — but for the wrong reason (LiteLLM under-routed to SIMPLE) |
+
+Lynkr layers the following, in decreasing priority, to catch every miss LiteLLM leaks:
 
-Lynkr scores cleaned user-authored text against embedding anchors plus 13 weighted heuristic dimensions, detects agentic workflows, and strips harness-injected noise before scoring. LiteLLM's router reads the raw last message and has no verify-then-escalate cascade — its fallbacks trigger only on HTTP errors, never on a bad answer.
+- FORCE_REASONING regex (`ultrathink`, `prove`, `security audit`, `from first principles`) → deterministic top-tier
+- Risk classifier (auth/middleware/credentials paths) → REASONING under config B
+- Agentic detector (`AUTONOMOUS` workflows) → REASONING minimum
+- Anchor-embedding classifier over 4 difficulty classes + FRONTIER_MIN_SIM floor
+- Local LLM classifier (qwen2.5:3b) reconciles borderline anchor calls
+- Envelope invariance — scores cleaned user text only, ignoring tool schemas / history / system-reminders
 
-_Fairness notes: the 11 scenarios derive from Lynkr's own regression suite, so Lynkr has home-field advantage — the transferable finding is the direction of LiteLLM's failures (systematic under-routing on defaults; per-request cost and instability with the LLM classifier), not the exact scores. Lynkr's top tiers used Azure gpt-5.2-chat / Z.ai GLM-5.2; LiteLLM was given the identical tier targets._
+LiteLLM's router reads the raw last message with no envelope-stripping, no verify-then-escalate cascade, no risk classifier, no agentic detection — its fallbacks trigger only on HTTP errors, never on a bad answer.
+
+_Fairness notes: the 11 scenarios derive from Lynkr's own regression suite, so Lynkr has home-field advantage — the transferable finding is the **direction** of LiteLLM's failures (systematic under-routing to cheap on hard prompts), not the exact scores. Lynkr's top tiers used Claude Opus 4.8 / z.ai GLM-5.2; LiteLLM was given the identical tier targets._
 
 ### Cost projection (100,000 requests/month, same backend)
 
+**Direct cost (raw meter):**
+
 | | Monthly cost | vs LiteLLM |
 |---|---|---|
-| LiteLLM | ~$818 | baseline |
-| **Lynkr** | **~$409** | **~50% cheaper** |
+| LiteLLM (TOON tool-heavy scenario) | ~$818 | baseline |
+| **Lynkr (TOON tool-heavy)** | **~$409** | **~50% cheaper** via token optimization |
+
+**Effective cost per correct-tier answer** (July 19 head-to-head, all 11 routing scenarios):
+
+| | Direct $/mo | Effective $/mo if you re-issue misroutes at correct tier |
+|---|---|---|
+| **Lynkr** | ~$5.50 (spends where it should, doesn't where it shouldn't) | ~$5.50 |
+| LiteLLM v2 heuristic | $0 (under-routes everything to ollama) | ~$89 (7 misroutes need re-issue on Moonshot/COMPLEX) |
 
-_Based on a tool-heavy agentic session (TOON scenario). On equal footing — same provider, same model — Lynkr is cheaper due to token optimization._
+The story isn't "Lynkr always spends less." It's **Lynkr spends where it should and doesn't where it shouldn't**. LiteLLM's zero-dollar cost on complex prompts is bought with wrong-tier answers to hard work — a 7B model answering "prove this rate limiter is fair under concurrent refill" is silent quality collapse, not a savings.
 
 → [Full benchmark report with methodology](BENCHMARK_REPORT.md)
 
@@ -481,10 +549,11 @@ With tier routing + token optimization: **additional 50-87% savings** on cloud p
 | **Local models** | Ollama, llama.cpp, LM Studio | Ollama only | ❌ | ❌ |
 | **Automatic tier routing** | ✅ embedding intent + 13-dimension scorer, verified cascade | ⚠️ Auto Router v2 (v1.94): heuristic under-routes, LLM classifier billed per request | ❌ | ❌ Manual metadata |
 | **TOON JSON compression** | ✅ up to 87.6% | ❌ | ❌ | ❌ |
-| **Smart tool selection** | ✅ up to 60% token reduction | ❌ | ❌ | ❌ |
+| **Upstream SSE streaming** | ✅ native passthrough + cross-format transform | ⚠️ passthrough only | ✅ | ⚠️ |
 | **Semantic cache** | ✅ 171ms hits, 0 tokens | ❌ | ❌ | ✅ Prompt cache only |
+| **Savings & routing dashboard** | ✅ spend, savings vs flagship, tier mix, routing accuracy, request logs | ⚠️ spend UI only | ⚠️ usage page | ✅ observability suite (no routing accuracy) |
 | **Long-term memory** | ✅ SQLite, per-session | ❌ | ❌ | ❌ |
-| **MCP integration** | ✅ + Code Mode (96% reduction) | ❌ | ❌ | ❌ |
+| **MCP integration** | ✅ | ❌ | ❌ | ❌ |
 | **Self-hosted** | ✅ Node.js only | ✅ Python stack | ❌ SaaS | ✅ Docker |
 | **Dependencies** | Node.js 20+ | Python, Prisma, PostgreSQL | None | Docker, Python |
 

package/bin/cli.js

@@ -11,24 +11,27 @@ const SUBCOMMANDS = {
   trajectory: path.join(__dirname, "lynkr-trajectory.js"),
   wrap:       path.join(__dirname, "wrap.js"),
   init:       path.join(__dirname, "lynkr-init.js"),
+  reset:      path.join(__dirname, "lynkr-reset.js"),
 };
 
 const sub = process.argv[2];
-if (sub && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, sub)) {
+// `lynkr start` is an alias for `lynkr` (start the proxy). Drop the token
+// and fall through so users can use whichever spelling they prefer.
+if (sub === 'start') {
+  process.argv.splice(2, 1);
+} else if (sub && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, sub)) {
   process.argv.splice(2, 1); // drop the subcommand token so the script's own arg parser is happy
   // Subcommand scripts check this to decide whether to invoke their main()
   // when they're require()'d (vs being loaded by a test for unit-checking).
   process.env._LYNKR_SUBCMD = sub;
   require(SUBCOMMANDS[sub]);
   return;
-}
-
-// Unknown positional commands must error loudly, not silently boot the
-// server (`lynkr codex` used to start a bare gateway and never say why).
-if (sub && !sub.startsWith('-')) {
+} else if (sub && !sub.startsWith('-')) {
+  // Unknown positional commands must error loudly, not silently boot the
+  // server (`lynkr codex` used to start a bare gateway and never say why).
   console.error(`Error: unknown command '${sub}'.`);
   console.error(`Did you mean: lynkr wrap ${sub}`);
-  console.error(`Known commands: ${Object.keys(SUBCOMMANDS).join(', ')} (or no command to start the server)`);
+  console.error(`Known commands: ${Object.keys(SUBCOMMANDS).join(', ')}, start (or no command to start the server)`);
   process.exit(1);
 }
 
@@ -45,10 +48,13 @@ ${pkg.description}
 
 Usage:
   lynkr [options]                  Start the proxy server (default)
+  lynkr start [options]            Alias for the above
+  lynkr init [options]             Interactive setup wizard (writes .env, pulls classifier model)
   lynkr wrap <target> [options]    Wrap CLI tools through Lynkr proxy
   lynkr usage [options]            Show AI spend report and tier-routing savings
   lynkr stats [options]            Shareable savings-receipt card (also: lynkr usage --card)
   lynkr trajectory [options]       Export agent trajectories as JSONL training data
+  lynkr reset <resource>           Clear a stored resource (e.g. session_pins, all)
 
 Options:
   -h, --help      Show this help message

package/bin/lynkr-init.js

@@ -197,12 +197,9 @@ const BASELINE_ENV = {
   LYNKR_KNN_CONFIDENCE_HIGH: '0.55',
   LYNKR_KNN_CONFIDENCE_LOW: '0.30',
 
-  // ── Tool execution ────────────────────────────────────────────────────
-  TOOL_EXECUTION_MODE: 'client',
-  TOOL_INJECTION_ENABLED: 'false',
+  // ── Tool selection (routing signals) ──────────────────────────────────
   SMART_TOOL_SELECTION_MODE: 'disabled',
   SMART_TOOL_SELECTION_TOKEN_BUDGET: '2500',
-  CODE_MODE_ENABLED: 'true',
 
   // ── Caching ───────────────────────────────────────────────────────────
   PROMPT_CACHE_ENABLED: 'true',
@@ -253,7 +250,6 @@ const BASELINE_ENV = {
   MEMORY_DEDUP_LOOKBACK: '5',
   MEMORY_TTL: '3600000',
   TOKEN_TRACKING_ENABLED: 'true',
-  TOOL_TRUNCATION_ENABLED: 'true',
 
   // ── Prompt/output shaping ─────────────────────────────────────────────
   SYSTEM_PROMPT_MODE: 'dynamic',
@@ -280,12 +276,8 @@ const BASELINE_ENV = {
   POLICY_FILE_BLOCKED_PATHS: '/.env,.env,/etc/passwd,/etc/shadow',
   POLICY_SAFE_COMMANDS_ENABLED: 'true',
 
-  // ── Agents ────────────────────────────────────────────────────────────
+  // ── Agents (delegation prompt injection; execution is client-side) ────
   AGENTS_ENABLED: 'true',
-  AGENTS_MAX_CONCURRENT: '10',
-  AGENTS_DEFAULT_MODEL: 'haiku',
-  AGENTS_MAX_STEPS: '15',
-  AGENTS_TIMEOUT: '300000',
 
   // ── Rate limiting ─────────────────────────────────────────────────────
   RATE_LIMIT_ENABLED: 'true',
@@ -550,6 +542,36 @@ async function runInteractive(opts) {
     close();
     console.log('');
     writeEnvFile(buildEnvContent(env, isWrap, tierConfig), opts);
+
+    // ── Classifier bootstrap: detect ollama, pull model, warm-up ──
+    // Runs AFTER .env is written so the classifier can read tier config
+    // (currently uses hardcoded qwen2.5:3b, but leaves room for the future
+    // fine-tuned model to plug in via SIMPLE tier or an env override).
+    if (!opts.dryRun) {
+      console.log('');
+      console.log('Setting up the difficulty classifier…');
+      try {
+        const { ensureClassifierReady } = require('../src/routing/classifier-setup');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const prompt = (q) => new Promise((res) => rl.question(q, (a) => res(a)));
+        const result = await ensureClassifierReady({
+          mode: 'interactive',
+          log: (m) => console.log(m),
+          warn: (m) => console.warn(m),
+          prompt,
+        });
+        rl.close();
+        if (result.ready) {
+          console.log('✓ Classifier ready.');
+        } else if (result.reason === 'ollama_missing') {
+          console.log('(Install Ollama and re-run `lynkr init` to enable the classifier — Lynkr will still start without it, using anchor-only scoring.)');
+        } else {
+          console.log(`(Classifier disabled: ${result.reason}. Lynkr will fall back to anchor-only scoring.)`);
+        }
+      } catch (err) {
+        console.warn(`⚠ Classifier setup skipped: ${err.message}`);
+      }
+    }
   } catch (err) {
     close();
     throw err;
@@ -576,12 +598,12 @@ function buildEnvContent(env, isWrap, tierConfig) {
   // Group output by section in the order it appears in the generated file.
   // Mirrors the layout of the .env.example reference doc.
   const SERVER_KEYS = new Set(['PORT', 'NODE_ENV', 'REQUEST_JSON_LIMIT', 'SESSION_DB_PATH', 'WORKSPACE_ROOT', 'ENABLE_TOOL_SEARCH']);
-  const TOOL_EXEC_KEYS = new Set(['TOOL_EXECUTION_MODE', 'TOOL_INJECTION_ENABLED', 'SMART_TOOL_SELECTION_MODE', 'SMART_TOOL_SELECTION_TOKEN_BUDGET', 'CODE_MODE_ENABLED']);
+  const TOOL_EXEC_KEYS = new Set(['SMART_TOOL_SELECTION_MODE', 'SMART_TOOL_SELECTION_TOKEN_BUDGET']);
   const CACHE_KEYS = new Set([
     'PROMPT_CACHE_ENABLED', 'PROMPT_CACHE_MAX_ENTRIES', 'PROMPT_CACHE_TTL_MS',
     'SEMANTIC_CACHE_ENABLED', 'SEMANTIC_CACHE_THRESHOLD', 'SEMANTIC_CACHE_MAX_ENTRIES', 'SEMANTIC_CACHE_TTL_MS',
   ]);
-  const MEMORY_KEYS = new Set(Object.keys(merged).filter((k) => k.startsWith('MEMORY_') || k === 'TOKEN_TRACKING_ENABLED' || k === 'TOOL_TRUNCATION_ENABLED'));
+  const MEMORY_KEYS = new Set(Object.keys(merged).filter((k) => k.startsWith('MEMORY_') || k === 'TOKEN_TRACKING_ENABLED'));
   const SHAPING_KEYS = new Set([
     'SYSTEM_PROMPT_MODE', 'TOOL_DESCRIPTIONS',
     'HISTORY_COMPRESSION_ENABLED', 'HISTORY_KEEP_RECENT_TURNS', 'HISTORY_SUMMARIZE_OLDER',

package/bin/lynkr-reset.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const fs = require("fs");
+
+const DB_PATH =
+  process.env.LYNKR_TELEMETRY_DB ||
+  path.join(__dirname, "..", ".lynkr", "telemetry.db");
+
+const RESOURCES = {
+  session_pins: {
+    describe: "Session → provider affinity pins",
+    table: "session_pins",
+  },
+};
+
+function usage(code = 0) {
+  const lines = Object.entries(RESOURCES).map(
+    ([k, v]) => `  ${k.padEnd(16)} ${v.describe}`
+  );
+  console.log(
+`Usage: lynkr reset <resource>
+
+Resources:
+${lines.join("\n")}
+  all              Clear every resource above
+
+DB: ${DB_PATH}
+`
+  );
+  process.exit(code);
+}
+
+const target = process.argv[2];
+if (!target || target === "-h" || target === "--help") usage(0);
+
+if (target !== "all" && !RESOURCES[target]) {
+  console.error(`Error: unknown resource '${target}'.`);
+  usage(1);
+}
+
+if (!fs.existsSync(DB_PATH)) {
+  console.error(`Error: telemetry DB not found at ${DB_PATH}`);
+  process.exit(1);
+}
+
+let Database;
+try {
+  Database = require("better-sqlite3");
+} catch (err) {
+  console.error("Error: better-sqlite3 not installed. Run `npm install` in ~/claude-code.");
+  process.exit(1);
+}
+
+const db = new Database(DB_PATH);
+const targets = target === "all" ? Object.keys(RESOURCES) : [target];
+
+let hadError = false;
+for (const t of targets) {
+  const { table } = RESOURCES[t];
+  try {
+    const before = db.prepare(`SELECT COUNT(*) as n FROM ${table}`).get().n;
+    db.prepare(`DELETE FROM ${table}`).run();
+    console.log(`✓ cleared ${t} (${before} rows)`);
+  } catch (err) {
+    hadError = true;
+    console.error(`✗ ${t}: ${err.message}`);
+  }
+}
+db.close();
+process.exit(hadError ? 1 : 0);