@aixle/insights 0.1.1 → 0.2.0

package/README.md

@@ -2,6 +2,83 @@
 
 stdio **MCP server** for AI coding-assistant telemetry. Ingests Claude Code JSONL transcripts and Cursor IDE SQLite telemetry into your organization's ingest API, exposes operator tools on the MCP bridge, and pairs with `aixle-insights init` so teammates can onboard without juggling cron jobs or brittle shell hooks.
 
+## Architecture reference
+
+For implementation architecture, design decisions, and package direction, see [`ARD.md`](./ARD.md).
+
+## Choosing a version
+
+Two channels are published. Pick one deliberately — they are **not** interchangeable.
+
+| | Production | Staging (QA) |
+|---|---|---|
+| Install | `npm i -g @aixle/insights` | `npm i -g @aixle/insights@staging` |
+| Version looks like | `0.2.0` | `0.2.1-staging` |
+| Points at | the production API | the staging API |
+| Who should use it | **everyone** | QA validating unreleased work |
+| Stability | released, supported | may change or break without notice |
+
+### Production — use this unless told otherwise
+
+```bash
+# One-shot via npx (recommended — always pulls the current release):
+npx -y @aixle/insights init \
+  --host https://insights.aixle.com \
+  --keycloak-url https://YOUR-KEYCLOAK/realms/YOUR_REALM
+
+# Or global install:
+npm i -g @aixle/insights
+aixle-insights --version    # e.g. 0.2.0  (no suffix)
+```
+
+### Staging — QA only
+
+Staging builds carry a `-staging` suffix and live on the `staging` dist-tag. You must ask for
+them explicitly; a plain `npm install` will never give you one.
+
+```bash
+# One-shot via npx:
+npx -y @aixle/insights@staging init \
+  --host https://staging.insights.aixle.com \
+  --keycloak-url https://YOUR-STAGING-KEYCLOAK/realms/YOUR_REALM
+
+# Or global install:
+npm i -g @aixle/insights@staging
+aixle-insights --version    # e.g. 0.2.1-staging  (note the suffix)
+```
+
+Point a staging build at the **staging** API host. Sending staging telemetry to production
+pollutes production analytics.
+
+### Which one do I have?
+
+```bash
+aixle-insights --version                 # a -staging suffix means a QA build
+npm view @aixle/insights dist-tags       # what each channel currently resolves to
+```
+
+Expected output — `latest` and `staging` move independently:
+
+```
+{ latest: '0.2.0', staging: '0.2.1-staging' }
+```
+
+### Switching back to production
+
+```bash
+npm i -g @aixle/insights@latest
+```
+
+Then re-run `init` against the production host, since credentials and the MCP entry are
+per-host.
+
+> **Why `npm install` never surprises you with a staging build:** `-staging` versions are semver
+> prereleases, and no ordinary version range resolves to a prerelease. `*`, `^0.2.0`, `~0.2.0`
+> and `>=0.1.0` all select `0.2.0` even when `0.2.1-staging` exists. Staging builds are
+> reachable only by exact version or the `staging` dist-tag.
+
+Maintainers: see [`../RELEASING.md`](../RELEASING.md) for how each channel is cut.
+
 ## Install
 
 ```bash
@@ -44,6 +121,8 @@ You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin
 | `aixle-insights run --once` | Perform one multi-tool sync, exit. Useful for cron / manual flushes. |
 | `aixle-insights run --once --full` | Backfill: ignore Cursor watermarks and commit-hash dedupe. |
 | `aixle-insights init` | Keycloak device login + persist credentials + merge `~/.claude.json` entry. |
+| `aixle-insights init --host <url>` | Use a DB90 API origin for token exchange. Remote hosts must use HTTPS; `http://localhost` and loopback addresses are allowed for local development. |
+| `aixle-insights init --insecure --host http://...` | Allow a remote plaintext HTTP host for a trusted non-production test endpoint. Prints a warning because tokens and telemetry can be exposed. |
 | `aixle-insights init --hooks --tool-name cursor` | Also install the Cursor-side hook forwarder (opt-in; requires Cursor restart). |
 | `aixle-insights uninstall-hooks` | Remove the hook forwarder + restore `~/.cursor/hooks.json` backup. |
 | `aixle-insights verify-hooks` | Print hooks install status + queue depth as JSON. |
@@ -59,6 +138,8 @@ You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin
 | `DB90_ORGANIZATION_ID` | Optional UUID scoping `init` to that org membership (header `X-Organization-ID`). |
 | `AIXLE_INSIGHTS_HOME` | Override the local state directory (defaults to `~/.aixle-insights/`). |
 
+Remote API and ingest hosts must use `https://`. Plaintext `http://` is local-dev-only for `localhost`, `127.0.0.0/8`, and `[::1]`; those loopback URLs work without warnings. A remote `http://` host is rejected during `init` unless you pass `--insecure`, which should only be used for trusted non-production test endpoints and will print a warning because ingest tokens and telemetry can cross the network unencrypted.
+
 Note: the `DB90_*` variables above are retained as compatibility names for the deployment-side Keycloak realm/client identifiers. Future versions may rename them with a deprecation window.
 
 Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per-model rates):
@@ -73,6 +154,29 @@ Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per
 }
 ```
 
+## Security
+
+`@aixle/insights` enforces HTTPS for any remote host. Plaintext `http://` is allowed only for loopback (`localhost`, `127.0.0.0/8`, `[::1]`) so that local-dev flows against `make up` continue to work without friction.
+
+### Two gates
+
+| Gate | Where it fires | What it checks |
+|---|---|---|
+| CLI `--host` gate | `runInit()` at the top of `aixle-insights init`, before any network call to Keycloak | The `--host` value the user typed |
+| Post-exchange `ingestHost` gate | `auth/flow.ts`, immediately after the OIDC-for-ingest-token exchange returns, before persisting credentials to the keychain | The `ingestHost` returned by the server, in case it differs from `--host` |
+
+Both gates use the same pure utility, `evaluateTransportSecurity()` in `src/lib/transport-security.ts`. Either gate rejecting aborts `init` with exit code 1 and a single-line error naming the offending host.
+
+### `--insecure` (init-only)
+
+`aixle-insights init --insecure --host http://<remote>` downgrades both gates from "reject" to "warn + continue." It is intended only for trusted non-production test endpoints (e.g. a self-hosted staging on a private network without a TLS cert).
+
+`--insecure` is rejected on the `run` subcommand by design — the long-running MCP server should never run insecurely. `run --insecure` routes to the help screen, the same as any unknown flag.
+
+### What is NOT gated
+
+The Keycloak issuer URL (`--keycloak-url` / `KEYCLOAK_ISSUER`) is **not** TLS-gated by this package. Same threat model, different ticket — tracked separately. For now, use HTTPS for any remote Keycloak issuer; the OIDC device-flow library will fail the request if the cert is invalid, but it will not refuse to attempt plaintext.
+
 ## Cursor hook forwarder (opt-in)
 
 `aixle-insights init --hooks --tool-name cursor` installs a Node script as a Cursor hook (`~/.cursor/hooks.json`). The script appends redacted hook payloads to `~/.aixle-insights/hooks-queue.ndjson`; the background sync drains the queue on its next cycle and POSTs the events with accurate per-turn model attribution. Requires a Cursor restart after install. To remove, run `aixle-insights uninstall-hooks` and restart Cursor again.
@@ -94,6 +198,19 @@ aixle-insights verify-hooks  # JSON: hooks installed + queue depth
 
 `mcp.log` (rotates at 5 MiB to `mcp.log.1`) under the app home directory captures operational events. Inside Claude Code, the **`db90_status`** MCP tool returns the same diagnostic structure as `aixle-insights health`.
 
+## Troubleshooting
+
+| Symptom | Most likely cause | Fix |
+|---|---|---|
+| `Error: DB90 API host <name> uses remote plaintext HTTP.` | You passed `--host http://<remote>` without `--insecure`. | Use `https://...`, or add `--insecure` if you know the endpoint is trusted and non-production. |
+| `Auth failed: fetch failed` during `init` | The `--keycloak-url` host doesn't resolve (NXDOMAIN), is behind a VPN, or the TLS cert is bad. | Verify with `curl -sS https://<host>/realms/<realm>/.well-known/openid-configuration`. For DB90 staging, the canonical Keycloak URL is embedded in the SPA — `curl https://<APP_HOST> \| grep keycloakUrl` extracts the current value. |
+| `Failed to post event: HTTP 401 Unauthorized` repeated for every turn | Your saved ingest token has been rotated, revoked, or invalidated by a server redeploy. The ingest token is distinct from the Keycloak access token that `health` reports as `authenticated: true`. | Reset the keychain entry and re-run `init`: `security delete-generic-password -s "aixle-insights" -a "aixle-insights-ingest-credential"` then `rm -f ~/.aixle-insights/credentials.json` then `aixle-insights init --host ... --keycloak-url ...`. State files are **not** deleted, so already-sent sessions stay deduped. |
+| `health` shows `authenticated: true` but `last_result` is `sent: 0, failed: N` cycle after cycle | Same as the 401 row above. `authenticated` only proves the OIDC token was acquired, not that the ingest token still validates server-side. | Re-init as above. |
+| `last_result` reports `sent: N` but the Events UI shows nothing | The Temporal worker is not running. The ingest endpoint returns HTTP 202 (queued) regardless of worker state. | `make worker` (or check `docker ps` for `db90-worker`). See [LOCAL-DEV.md](./LOCAL-DEV.md) §1. |
+| `sync_lock_skip {reason: "advisory_lock_held"}` in the log | Another sync cycle is still holding `~/.aixle-insights/state.lock`. | Wait for it to finish; only delete the lock file (`rm -f ~/.aixle-insights/state.lock`) after confirming no `aixle-insights run` process is alive (`pgrep -fa aixle-insights`). |
+| `aixle-insights --help` doesn't list `--insecure` | You're running an older published version of the package, not the local source. | `which aixle-insights` shows the path. To run local source: `cd packages/tools/aixle-insights && npm run build && npm link`. To return to the published version: `npm unlink -g @aixle/insights && npm install -g @aixle/insights@latest`. |
+| Not sure whether `aixle-insights` is a `npm link` or a real install | Real installs are regular files; `npm link` is a symlink chain into the repo. | `readlink "$(which aixle-insights)"` shows the link target if any. A linked install will trace back to a path under your monorepo checkout. |
+
 ## Local development — `/aixle-reset` skill
 
 > Audience: contributors editing this package. If you installed `@aixle/insights` from npm and aren't modifying the source, you can skip this section.
@@ -131,6 +248,12 @@ After the script reports success: **quit and reopen Claude Code / Cursor** so ea
 
 - Node.js ≥ 20.
 - macOS / Linux / Windows. On Windows, the package writes a `cmd /c npx …` wrapper in `~/.claude.json` so Claude Code can spawn the MCP server reliably.
+- `better-sqlite3` is a native module. After a Node upgrade, if SQLite reads start failing, rebuild it from the tools workspace:
+
+```bash
+cd packages/tools
+npm rebuild better-sqlite3
+```
 
 ## License
 

package/dist/auth/flow.d.ts

@@ -11,6 +11,8 @@ export interface LoginAndPersistOptions {
     exchangeOrganizationId?: string;
     clientId?: string;
     appDir?: string;
+    allowInsecureHttp?: boolean;
+    onSecurityWarning?: (message: string) => void;
     onVisitInstructions?: (verification_uri: string, user_code: string) => void;
     fetchImpl?: typeof fetch;
 }

package/dist/auth/flow.js

@@ -2,6 +2,7 @@ import { exchangeIngestToken } from "./exchange.js";
 import { defaultKeycloakClientId, defaultKeycloakIssuer, obtainKeycloakAccessTokenViaDeviceFlow } from "./keycloak.js";
 import { loadCredentials, saveStoredCredentials } from "./credentials.js";
 import { getAppDir } from "../state.js";
+import { evaluateTransportSecurity } from "../lib/transport-security.js";
 export async function loginAndPersistCredentials(opts) {
     const issuer = opts.keycloakIssuer.trim();
     if (!issuer) {
@@ -45,6 +46,16 @@ export async function loginAndPersistCredentials(opts) {
                 fetchImpl: opts.fetchImpl,
             });
         }
+        const ingestHostSecurity = evaluateTransportSecurity(exchanged.ingestHost, {
+            allowInsecureHttp: opts.allowInsecureHttp === true,
+            label: "DB90 ingest host",
+        });
+        if (!ingestHostSecurity.ok) {
+            return { ok: false, error: ingestHostSecurity.error };
+        }
+        if (ingestHostSecurity.warning) {
+            opts.onSecurityWarning?.(ingestHostSecurity.warning);
+        }
         const existing = await loadCredentials(appDir);
         const stored = {
             host: exchanged.ingestHost,

package/dist/cli.d.ts

@@ -21,6 +21,8 @@ export interface Args {
     force?: boolean;
     /** When set on init, install the Cursor hooks forwarder into ~/.cursor/hooks.json. */
     hooks?: boolean;
+    /** Allow remote plaintext HTTP hosts for trusted non-production test environments. */
+    insecure?: boolean;
 }
 interface RunOnceDeps {
     loadCredentials: typeof loadCredentials;

package/dist/cli.js

@@ -12,12 +12,13 @@ import { resolveCursorPricing } from "./cursor-config.js";
 import { buildHealthSnapshot, formatHealthForCli } from "./health.js";
 import { installClaudeUserMcp } from "./install/claude.js";
 import { installHooksConfig, uninstallHooksConfig, verifyHooksConfig, FORWARDER_FILENAME } from "./hooks/hooks-config.js";
+import { evaluateTransportSecurity } from "./lib/transport-security.js";
 import { join } from "node:path";
 import { fileURLToPath as nodeFileURLToPath } from "node:url";
 import { mcpLog } from "./log.js";
 const GLOBAL_FLAGS = new Set(["--help", "-h", "--once", "--full"]);
 const INIT_VALUE_FLAGS = new Set(["--host", "--keycloak-url", "--tool-name", "--organization-id"]);
-const INIT_BOOLEAN_FLAGS = new Set(["--force", "--hooks"]);
+const INIT_BOOLEAN_FLAGS = new Set(["--force", "--hooks", "--insecure"]);
 /** Matches DB90 Rails `McpController` UUID check for `X-Organization-ID` (RFC 4122 variant). */
 export const DB90_ORGANIZATION_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 export function isValidDb90OrganizationUuid(value) {
@@ -112,7 +113,8 @@ export function parseArgs(argv) {
         const organizationId = takeFlagValue(args, "--organization-id");
         const force = args.includes("--force");
         const hooks = args.includes("--hooks");
-        return { command: "init", help, once: false, host, keycloakUrl, toolName, organizationId, force, hooks };
+        const insecure = args.includes("--insecure");
+        return { command: "init", help, once: false, host, keycloakUrl, toolName, organizationId, force, hooks, insecure };
     }
     const nonInitBad = args.filter((a) => {
         if (!a.startsWith("--") && a !== "-h")
@@ -177,6 +179,7 @@ init options:
   --force                  Replace an existing user "aixle-insights" MCP entry in ~/.claude.json if it differs.
   --hooks                  (opt-in) Install Cursor hook forwarder for per-turn model attribution.
                            Requires Cursor restart. Run 'aixle-insights uninstall-hooks' to remove.
+  --insecure               Allow remote http:// hosts for trusted non-production test endpoints only.
 
 Multi-org:
   Set \`DB90_ORGANIZATION_ID\` to a UUID, or pass \`--organization-id\` on \`init\`, so ingest tokens are minted for that membership instead of the default (oldest) org.
@@ -213,6 +216,17 @@ export async function runInit(cliArgs, deps) {
         ...deps,
     };
     const db90Host = (cliArgs.host ?? defaultDb90Host()).replace(/\/$/, "");
+    const transportSecurity = evaluateTransportSecurity(db90Host, {
+        allowInsecureHttp: cliArgs.insecure === true,
+        label: "DB90 API host",
+    });
+    if (!transportSecurity.ok) {
+        runtime.error(`Error: ${transportSecurity.error}`);
+        return 1;
+    }
+    if (transportSecurity.warning) {
+        runtime.error(`Warning: ${transportSecurity.warning}`);
+    }
     const kcIssuer = (cliArgs.keycloakUrl ?? runtime.defaultKeycloakIssuer()).trim();
     if (!kcIssuer) {
         runtime.error("Error: Keycloak issuer is not configured. Pass --keycloak-url or set KEYCLOAK_ISSUER / DB90_KEYCLOAK_ISSUER.");
@@ -246,6 +260,10 @@ export async function runInit(cliArgs, deps) {
         deviceLabel: "aixle-insights CLI init",
         appDir: runtime.getAppDir(),
         exchangeOrganizationId: exchangeOrganizationId || undefined,
+        allowInsecureHttp: cliArgs.insecure === true,
+        onSecurityWarning: (message) => {
+            runtime.error(`Warning: ${message}`);
+        },
         onVisitInstructions: (uri, code) => {
             runtime.log(`Visit ${uri} and enter code ${code}`);
         },

package/dist/cursor-payload-contract.js

@@ -11,6 +11,7 @@ const TOP_LEVEL_KEYS = new Set([
     "metadata",
 ]);
 const METADATA_BASE_KEYS = new Set([
+    "session_id",
     "cursor_session_id",
     "workspace",
     "workspace_scope",

package/dist/cursor-store-audit.d.ts

@@ -39,8 +39,8 @@ export interface CursorStoreAuditReport {
     daily_stats_version_note: string;
 }
 export declare function redactCursorPath(p: string): string;
-export declare function auditStateVscdbFile(dbPath: string): StateVscdbAuditEntry;
-export declare function auditLegacyCursorDbFile(dbPath: string): LegacyDbAuditEntry;
+export declare function auditStateVscdbFile(dbPath: string, rootDir?: string): StateVscdbAuditEntry;
+export declare function auditLegacyCursorDbFile(dbPath: string, rootDir?: string): LegacyDbAuditEntry;
 /**
  * CUR-V07 — inventory local Cursor stores (state.vscdb vs legacy cursor.db).
  * Does not read disk outside Cursor's User directory unless `baseDir` is passed (tests).

package/dist/cursor-store-audit.js

@@ -1,9 +1,9 @@
 import { existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import Database from "better-sqlite3";
 import { discoverDailyStatsVersionsInDb, mergeDailyStatsVersionDiscoveries, } from "./daily-stats-versions.js";
 import { cursorUserDir, findCursorDbs, findStateVscDbs, isGlobalStateDbPath, probeCursorGlobalStateDb, } from "./readers/cursor.js";
+import { openCursorSqliteReadonly, resolveCursorSqlitePath } from "./readers/cursor-sqlite.js";
 const LEGACY_TABLE = "CursorRequestFeedback";
 const STATE_TABLE = "ItemTable";
 const RECENT_COMMIT_KEY = "aiCodeTracking.recentCommit";
@@ -16,7 +16,7 @@ function tableExists(db, tableName) {
         .get(tableName);
     return row !== undefined;
 }
-export function auditStateVscdbFile(dbPath) {
+export function auditStateVscdbFile(dbPath, rootDir) {
     const entry = {
         db_path_redacted: redactCursorPath(dbPath),
         exists: existsSync(dbPath),
@@ -27,7 +27,10 @@ export function auditStateVscdbFile(dbPath) {
         return entry;
     let db = null;
     try {
-        db = new Database(dbPath, { readonly: true });
+        const opened = openCursorSqliteReadonly(dbPath, { rootDir });
+        if (!opened.ok)
+            return entry;
+        db = opened.db;
         const ds = db
             .prepare(`SELECT count(*) AS c FROM ${STATE_TABLE} WHERE key LIKE 'aiCodeTracking.dailyStats%'`)
             .get();
@@ -45,18 +48,25 @@ export function auditStateVscdbFile(dbPath) {
     }
     return entry;
 }
-export function auditLegacyCursorDbFile(dbPath) {
+export function auditLegacyCursorDbFile(dbPath, rootDir) {
     const entry = {
         db_path_redacted: redactCursorPath(dbPath),
-        file_bytes: existsSync(dbPath) ? statSync(dbPath).size : 0,
+        file_bytes: 0,
         has_feedback_table: false,
         feedback_row_count: 0,
     };
     if (!existsSync(dbPath))
         return entry;
+    const resolved = resolveCursorSqlitePath(dbPath, { rootDir });
+    if (!resolved.ok)
+        return entry;
+    entry.file_bytes = statSync(resolved.path).size;
     let db = null;
     try {
-        db = new Database(dbPath, { readonly: true });
+        const opened = openCursorSqliteReadonly(resolved.path, { rootDir });
+        if (!opened.ok)
+            return entry;
+        db = opened.db;
         if (!tableExists(db, LEGACY_TABLE))
             return entry;
         entry.has_feedback_table = true;
@@ -105,19 +115,20 @@ function pathCIngestNote(verdict, legacyCount, totalRows) {
  * Does not read disk outside Cursor's User directory unless `baseDir` is passed (tests).
  */
 export function auditCursorLocalStores(baseDir) {
-    const sqlite_probe_ok = probeCursorGlobalStateDb(false);
+    const rootDir = baseDir ?? cursorUserDir();
+    const sqlite_probe_ok = probeCursorGlobalStateDb(false, baseDir);
     const statePaths = findStateVscDbs(baseDir);
     const globalPath = statePaths.find((p) => isGlobalStateDbPath(p)) ??
         join(baseDir ?? cursorUserDir(), "globalStorage", "state.vscdb");
-    const global = auditStateVscdbFile(globalPath);
+    const global = auditStateVscdbFile(globalPath, rootDir);
     const workspacePaths = statePaths.filter((p) => !isGlobalStateDbPath(p));
-    const workspaceAudits = workspacePaths.map(auditStateVscdbFile);
+    const workspaceAudits = workspacePaths.map((p) => auditStateVscdbFile(p, rootDir));
     const versionDiscoveries = statePaths
         .filter((p) => existsSync(p))
-        .map(discoverDailyStatsVersionsInDb);
+        .map((p) => discoverDailyStatsVersionsInDb(p, { rootDir }));
     const daily_stats_versions = mergeDailyStatsVersionDiscoveries(versionDiscoveries);
     const legacyPaths = findCursorDbs(baseDir);
-    const legacyEntries = legacyPaths.map(auditLegacyCursorDbFile);
+    const legacyEntries = legacyPaths.map((p) => auditLegacyCursorDbFile(p, rootDir));
     const withFeedbackTable = legacyEntries.filter((e) => e.has_feedback_table).length;
     const totalFeedbackRows = legacyEntries.reduce((sum, e) => sum + e.feedback_row_count, 0);
     let path_c_verdict;

package/dist/daily-stats-versions.d.ts

@@ -26,6 +26,8 @@ export declare function isVersionNewerThanV1_5(version: string): boolean;
 /**
  * Read all `aiCodeTracking.dailyStats%` keys from one `state.vscdb` file.
  */
-export declare function discoverDailyStatsVersionsInDb(dbPath: string): DailyStatsVersionDiscovery;
+export declare function discoverDailyStatsVersionsInDb(dbPath: string, options?: {
+    rootDir?: string;
+}): DailyStatsVersionDiscovery;
 /** Merge discoveries from global + workspace `state.vscdb` files (dedupe sample keys only). */
 export declare function mergeDailyStatsVersionDiscoveries(discoveries: DailyStatsVersionDiscovery[]): DailyStatsVersionDiscovery;

package/dist/daily-stats-versions.js

@@ -1,8 +1,4 @@
-/**
- * CUR-V11 — discover `aiCodeTracking.dailyStats` version prefixes on disk.
- * Keys look like: aiCodeTracking.dailyStats.v1.5.2026-05-20
- */
-import Database from "better-sqlite3";
+import { openCursorSqliteReadonly } from "./readers/cursor-sqlite.js";
 const STATE_TABLE = "ItemTable";
 const DAILY_STATS_LIKE = "aiCodeTracking.dailyStats%";
 /** Full key shape for a dated dailyStats row. */
@@ -70,12 +66,15 @@ function mergeBuckets(target, discovery) {
 /**
  * Read all `aiCodeTracking.dailyStats%` keys from one `state.vscdb` file.
  */
-export function discoverDailyStatsVersionsInDb(dbPath) {
+export function discoverDailyStatsVersionsInDb(dbPath, options = {}) {
     const byVersion = new Map();
     const unmatched = [];
     let db = null;
     try {
-        db = new Database(dbPath, { readonly: true });
+        const opened = openCursorSqliteReadonly(dbPath, { rootDir: options.rootDir });
+        if (!opened.ok)
+            return emptyDiscovery();
+        db = opened.db;
         const table = db
             .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
             .get(STATE_TABLE);

package/dist/lib/transport-security.d.ts

@@ -0,0 +1,12 @@
+export type TransportSecurityResult = {
+    ok: true;
+    warning?: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface TransportSecurityOptions {
+    allowInsecureHttp: boolean;
+    label: string;
+}
+export declare function evaluateTransportSecurity(rawUrl: string, options: TransportSecurityOptions): TransportSecurityResult;

package/dist/lib/transport-security.js

@@ -0,0 +1,47 @@
+function isIpv4Loopback(hostname) {
+    const parts = hostname.split(".");
+    if (parts.length !== 4)
+        return false;
+    const octets = parts.map((part) => Number(part));
+    return octets.every((octet, index) => Number.isInteger(octet) &&
+        octet >= 0 &&
+        octet <= 255 &&
+        String(octet) === parts[index]) && octets[0] === 127;
+}
+function isLoopbackHost(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "localhost" ||
+        normalized === "::1" ||
+        normalized === "[::1]" ||
+        isIpv4Loopback(normalized);
+}
+function plaintextMessage(label, host, action) {
+    const prefix = `${label} ${host} uses remote plaintext HTTP`;
+    const guidance = "Plaintext HTTP can expose ingest tokens and telemetry. Use HTTPS for remote hosts";
+    if (action === "warn") {
+        return `${prefix}. ${guidance}; --insecure should only be used for trusted non-production test endpoints.`;
+    }
+    return `${prefix}. ${guidance}, or pass --insecure only for a trusted non-production test endpoint.`;
+}
+export function evaluateTransportSecurity(rawUrl, options) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        return { ok: false, error: `${options.label} must be a valid URL.` };
+    }
+    if (parsed.protocol === "https:") {
+        return { ok: true };
+    }
+    if (parsed.protocol !== "http:") {
+        return { ok: false, error: `${options.label} must use HTTPS, or HTTP for localhost/loopback local development.` };
+    }
+    if (isLoopbackHost(parsed.hostname)) {
+        return { ok: true };
+    }
+    if (options.allowInsecureHttp) {
+        return { ok: true, warning: plaintextMessage(options.label, parsed.host, "warn") };
+    }
+    return { ok: false, error: plaintextMessage(options.label, parsed.host, "reject") };
+}

package/dist/pricing.d.ts

@@ -2,7 +2,7 @@
  * Model pricing table and cost calculation for @aixle/insights.
  *
  * Default rates source: https://platform.claude.com/docs/en/about-claude/pricing
- * Rates last verified: 2026-05-04
+ * Rates last verified: 2026-06-17
  */
 export interface ModelPricing {
     input_per_mtok: number;
@@ -32,6 +32,14 @@ export declare const DEFAULT_PRICING: PricingTable;
  * - Returns a new table object so mutations never affect DEFAULT_PRICING.
  */
 export declare function mergePricing(base: PricingTable, overrides: PricingTable): PricingTable;
+/**
+ * Strips a trailing -YYYYMMDD date suffix to produce the bare model key used
+ * in the pricing table. Returns the original ID when:
+ *  - it has no date suffix, OR
+ *  - the bare form is not in the table (i.e. the dated form IS the canonical key,
+ *    like legacy "claude-3-5-sonnet-20241022").
+ */
+export declare function normalizeModelId(model: string, pricing: PricingTable): string;
 export declare function calculateCost(model: string | null, baseInputTokens: number, outputTokens: number, cacheWriteTokens: number, cacheReadTokens: number, pricing: PricingTable): number | null;
 /**
  * Returns a human-readable warning string explaining why cost could not be

package/dist/pricing.js

@@ -2,7 +2,7 @@
  * Model pricing table and cost calculation for @aixle/insights.
  *
  * Default rates source: https://platform.claude.com/docs/en/about-claude/pricing
- * Rates last verified: 2026-05-04
+ * Rates last verified: 2026-06-17
  */
 /**
  * Default pricing table (USD per million tokens).
@@ -14,7 +14,20 @@
  * breakdown is a future improvement.
  */
 export const DEFAULT_PRICING = {
-    // Opus 4.7/4.6/4.5 — $5 input / $25 output
+    // Fable 5 — $10 input / $50 output
+    "claude-fable-5": {
+        input_per_mtok: 10.0,
+        output_per_mtok: 50.0,
+        cache_write_per_mtok: 12.5,
+        cache_read_per_mtok: 1.0,
+    },
+    // Opus 4.8/4.7/4.6/4.5 — $5 input / $25 output
+    "claude-opus-4-8": {
+        input_per_mtok: 5.0,
+        output_per_mtok: 25.0,
+        cache_write_per_mtok: 6.25,
+        cache_read_per_mtok: 0.5,
+    },
     "claude-opus-4-7": {
         input_per_mtok: 5.0,
         output_per_mtok: 25.0,
@@ -47,26 +60,26 @@ export const DEFAULT_PRICING = {
         cache_read_per_mtok: 1.5,
     },
     // Sonnet 4.x family — $3 input / $15 output
-    "claude-sonnet-4": {
+    "claude-sonnet-4-6": {
         input_per_mtok: 3.0,
         output_per_mtok: 15.0,
         cache_write_per_mtok: 3.75,
         cache_read_per_mtok: 0.3,
     },
-    "claude-sonnet-4-6": {
+    "claude-sonnet-4-5": {
         input_per_mtok: 3.0,
         output_per_mtok: 15.0,
         cache_write_per_mtok: 3.75,
         cache_read_per_mtok: 0.3,
     },
-    "claude-sonnet-4-5-20251001": {
+    "claude-sonnet-4": {
         input_per_mtok: 3.0,
         output_per_mtok: 15.0,
         cache_write_per_mtok: 3.75,
         cache_read_per_mtok: 0.3,
     },
     // Haiku 4.5 — $1 input / $5 output
-    "claude-haiku-4-5-20251001": {
+    "claude-haiku-4-5": {
         input_per_mtok: 1.0,
         output_per_mtok: 5.0,
         cache_write_per_mtok: 1.25,
@@ -110,6 +123,22 @@ export function mergePricing(base, overrides) {
     }
     return result;
 }
+/**
+ * Strips a trailing -YYYYMMDD date suffix to produce the bare model key used
+ * in the pricing table. Returns the original ID when:
+ *  - it has no date suffix, OR
+ *  - the bare form is not in the table (i.e. the dated form IS the canonical key,
+ *    like legacy "claude-3-5-sonnet-20241022").
+ */
+export function normalizeModelId(model, pricing) {
+    if (pricing[model])
+        return model;
+    const match = model.match(/^(.+)-(\d{8})$/);
+    if (!match)
+        return model;
+    const bare = match[1];
+    return pricing[bare] ? bare : model;
+}
 /** Returns true only when all four rate fields are finite numbers. */
 function hasValidRates(rates) {
     return (Number.isFinite(rates.input_per_mtok) &&
@@ -120,7 +149,8 @@ function hasValidRates(rates) {
 export function calculateCost(model, baseInputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, pricing) {
     if (!model)
         return null;
-    const rates = pricing[model];
+    const resolved = normalizeModelId(model, pricing);
+    const rates = pricing[resolved];
     if (!rates || !hasValidRates(rates))
         return null;
     const raw = (baseInputTokens * rates.input_per_mtok +
@@ -138,7 +168,8 @@ export function calculateCost(model, baseInputTokens, outputTokens, cacheWriteTo
 export function getCostWarning(model, pricing) {
     if (!model)
         return null;
-    const rates = pricing[model];
+    const resolved = normalizeModelId(model, pricing);
+    const rates = pricing[resolved];
     if (!rates) {
         return `Model "${model}" not in pricing table — cost_usd will be null. Extend DEFAULT_PRICING or add future pricing overrides when supported.`;
     }

package/dist/readers/claude.js

@@ -304,12 +304,12 @@ export function mapTranscriptTurn(turn, options) {
     };
     if (turn.model)
         payload.model = turn.model;
-    if (turn.tokensIn > 0)
-        payload.tokens_in = turn.tokensIn;
+    if (baseInputTokens > 0)
+        payload.tokens_in = baseInputTokens;
     if (turn.tokensOut > 0)
         payload.tokens_out = turn.tokensOut;
-    if (turn.tokensIn > 0 || turn.tokensOut > 0) {
-        payload.tokens_total = turn.tokensIn + turn.tokensOut;
+    if (baseInputTokens > 0 || turn.tokensOut > 0) {
+        payload.tokens_total = baseInputTokens + turn.tokensOut;
     }
     if (projectId)
         payload.project_id = projectId;

package/dist/readers/cursor-sqlite.d.ts

@@ -0,0 +1,23 @@
+import Database from "better-sqlite3";
+export type CursorSqliteOpenFailureReason = "missing" | "outside_root" | "native_binding" | "unknown";
+export type CursorSqliteOpenResult = {
+    ok: true;
+    db: Database.Database;
+} | {
+    ok: false;
+    reason: CursorSqliteOpenFailureReason;
+    message: string;
+};
+export type CursorSqlitePathResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: CursorSqliteOpenFailureReason;
+    message: string;
+};
+export interface CursorSqliteOpenOptions {
+    rootDir?: string;
+}
+export declare function openCursorSqliteReadonly(dbPath: string, options?: CursorSqliteOpenOptions): CursorSqliteOpenResult;
+export declare function resolveCursorSqlitePath(dbPath: string, options?: CursorSqliteOpenOptions): CursorSqlitePathResult;

package/dist/readers/cursor-sqlite.js

@@ -0,0 +1,68 @@
+import { existsSync, realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import Database from "better-sqlite3";
+function validatedRealPathWithinRoot(path, rootDir) {
+    const realPath = realpathSync(path);
+    const realRoot = realpathSync(rootDir);
+    if (realPath === realRoot)
+        return realPath;
+    const rootWithSep = realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`;
+    return realPath.startsWith(rootWithSep) ? realPath : null;
+}
+function isNativeBindingError(message) {
+    return (message.includes("Could not locate the bindings file") ||
+        message.includes("better_sqlite3.node") ||
+        message.includes("dlopen"));
+}
+export function openCursorSqliteReadonly(dbPath, options = {}) {
+    const resolved = resolveCursorSqlitePath(dbPath, options);
+    if (!resolved.ok)
+        return resolved;
+    try {
+        const db = new Database(resolved.path, { readonly: true, fileMustExist: true });
+        return { ok: true, db };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            reason: isNativeBindingError(message) ? "native_binding" : "unknown",
+            message,
+        };
+    }
+}
+export function resolveCursorSqlitePath(dbPath, options = {}) {
+    const normalizedPath = resolve(dbPath);
+    if (!existsSync(normalizedPath)) {
+        return {
+            ok: false,
+            reason: "missing",
+            message: `Database file does not exist: ${normalizedPath}`,
+        };
+    }
+    const { rootDir } = options;
+    let pathToOpen = normalizedPath;
+    if (rootDir) {
+        const normalizedRoot = resolve(rootDir);
+        try {
+            const realPath = validatedRealPathWithinRoot(normalizedPath, normalizedRoot);
+            if (realPath === null) {
+                return {
+                    ok: false,
+                    reason: "outside_root",
+                    message: `Database path escapes root: ${normalizedPath}`,
+                };
+            }
+            pathToOpen = realPath;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                reason: "unknown",
+                message,
+            };
+        }
+    }
+    return { ok: true, path: pathToOpen };
+}

package/dist/readers/cursor.d.ts

@@ -2,7 +2,7 @@ import type { IngestPayload } from "../lib/index.js";
 import { type RiskLevel } from "../risk-scanner.js";
 export declare function cursorUserDir(): string;
 /** Smoke-test better-sqlite3 against the global Cursor state DB (CUR-V02 / verify scripts). */
-export declare function probeCursorGlobalStateDb(verbose?: boolean): boolean;
+export declare function probeCursorGlobalStateDb(verbose?: boolean, baseDir?: string): boolean;
 export declare function findCursorDbs(baseDir?: string): string[];
 export interface CursorRow {
     requestId?: string | null;

package/dist/readers/cursor.js

@@ -10,8 +10,8 @@ import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { glob } from "glob";
-import Database from "better-sqlite3";
 import { scanText } from "../risk-scanner.js";
+import { openCursorSqliteReadonly } from "./cursor-sqlite.js";
 // ─── Reader: paths & SQLite ──────────────────────────────────────────────────
 export function cursorUserDir() {
     switch (process.platform) {
@@ -43,14 +43,19 @@ function logDbTables(db, dbPath, label) {
     console.log(`  tables: ${tables.join(", ") || "(none)"}`);
 }
 /** Smoke-test better-sqlite3 against the global Cursor state DB (CUR-V02 / verify scripts). */
-export function probeCursorGlobalStateDb(verbose = false) {
-    const dbPath = join(cursorUserDir(), "globalStorage", "state.vscdb");
+export function probeCursorGlobalStateDb(verbose = false, baseDir) {
+    const userDir = baseDir ?? cursorUserDir();
+    const dbPath = join(userDir, "globalStorage", "state.vscdb");
+    const opened = openCursorSqliteReadonly(dbPath, { rootDir: userDir });
+    if (!opened.ok) {
+        console.error(`  [probe] failed to read ${dbPath}: ${opened.message}`);
+        return false;
+    }
+    const db = opened.db;
     try {
-        const db = new Database(dbPath, { readonly: true });
         const row = db
             .prepare(`SELECT count(*) AS c FROM ${STATE_TABLE} WHERE key LIKE 'aiCodeTracking.dailyStats%'`)
             .get();
-        db.close();
         if (verbose) {
             console.log(`  [probe] global state.vscdb OK — ${row.c} dailyStats key(s)`);
         }
@@ -61,6 +66,9 @@ export function probeCursorGlobalStateDb(verbose = false) {
         console.error(`  [probe] failed to read ${dbPath}: ${msg}`);
         return false;
     }
+    finally {
+        db.close();
+    }
 }
 // ─── Legacy: cursor.db / CursorRequestFeedback ─────────────────────────────────
 export function findCursorDbs(baseDir) {
@@ -72,10 +80,13 @@ export function findCursorDbs(baseDir) {
         return [];
     }
 }
-function readLegacyFromDb(dbPath, since, workspacePath, verbose) {
+function readLegacyFromDb(dbPath, since, workspacePath, rootDir, verbose) {
     let db = null;
     try {
-        db = new Database(dbPath, { readonly: true });
+        const opened = openCursorSqliteReadonly(dbPath, { rootDir });
+        if (!opened.ok)
+            return [];
+        db = opened.db;
         if (verbose)
             logDbTables(db, dbPath, "cursor.db");
         if (!tableExists(db, LEGACY_TABLE))
@@ -105,13 +116,14 @@ function readLegacyFromDb(dbPath, since, workspacePath, verbose) {
     }
 }
 export function readLegacyEvents(since, baseDir, verbose = false) {
+    const rootDir = baseDir ?? cursorUserDir();
     const dbPaths = findCursorDbs(baseDir);
     if (verbose)
         console.log(`Found ${dbPaths.length} legacy cursor.db file(s)`);
     const results = [];
     for (const dbPath of dbPaths) {
         const workspacePath = dbPath.replace(/[\\/]cursor\.db$/, "");
-        for (const row of readLegacyFromDb(dbPath, since, workspacePath, verbose)) {
+        for (const row of readLegacyFromDb(dbPath, since, workspacePath, rootDir, verbose)) {
             results.push({ row, workspacePath });
         }
     }
@@ -239,10 +251,13 @@ export function findStateVscDbs(baseDir) {
     }
     return results;
 }
-function readDailyStatsFromDb(dbPath, since, verbose) {
+function readDailyStatsFromDb(dbPath, since, rootDir, verbose) {
     let db = null;
     try {
-        db = new Database(dbPath, { readonly: true });
+        const opened = openCursorSqliteReadonly(dbPath, { rootDir });
+        if (!opened.ok)
+            return [];
+        db = opened.db;
         if (verbose)
             logDbTables(db, dbPath, "state.vscdb");
         if (!tableExists(db, STATE_TABLE))
@@ -264,7 +279,7 @@ function readDailyStatsFromDb(dbPath, since, verbose) {
             if (!dateMatch)
                 continue;
             const date = dateMatch[1];
-            if (since && date <= since.toISOString().slice(0, 10))
+            if (since && date < since.toISOString().slice(0, 10))
                 continue;
             let parsed;
             try {
@@ -285,6 +300,7 @@ function readDailyStatsFromDb(dbPath, since, verbose) {
     }
 }
 function readDailyStatsRaw(since, baseDir, verbose) {
+    const rootDir = baseDir ?? cursorUserDir();
     const dbPaths = findStateVscDbs(baseDir);
     if (verbose) {
         console.log(`Searching: ${baseDir ?? cursorUserDir()}`);
@@ -292,7 +308,7 @@ function readDailyStatsRaw(since, baseDir, verbose) {
     }
     const raw = [];
     for (const dbPath of dbPaths) {
-        raw.push(...readDailyStatsFromDb(dbPath, since, verbose));
+        raw.push(...readDailyStatsFromDb(dbPath, since, rootDir, verbose));
     }
     return raw;
 }
@@ -339,10 +355,13 @@ function dedupeRecentCommitSnapshots(entries) {
     }
     return [...byKey.values()];
 }
-function readRecentCommitFromDb(dbPath, since, verbose) {
+function readRecentCommitFromDb(dbPath, since, rootDir, verbose) {
     let db = null;
     try {
-        db = new Database(dbPath, { readonly: true });
+        const opened = openCursorSqliteReadonly(dbPath, { rootDir });
+        if (!opened.ok)
+            return [];
+        db = opened.db;
         if (!tableExists(db, STATE_TABLE))
             return [];
         const row = db
@@ -384,13 +403,14 @@ function readRecentCommitFromDb(dbPath, since, verbose) {
     }
 }
 export function readRecentCommitSnapshots(since, baseDir, verbose = false) {
+    const rootDir = baseDir ?? cursorUserDir();
     const dbPaths = findStateVscDbs(baseDir);
     if (verbose) {
         console.log(`Searching recentCommit: ${baseDir ?? cursorUserDir()}`);
     }
     const found = [];
     for (const dbPath of dbPaths) {
-        found.push(...readRecentCommitFromDb(dbPath, since, verbose));
+        found.push(...readRecentCommitFromDb(dbPath, since, rootDir, verbose));
     }
     return dedupeRecentCommitSnapshots(found);
 }
@@ -432,7 +452,10 @@ function readComposerHeaders(baseDir) {
     const dbPath = join(userDir, "globalStorage", "state.vscdb");
     let db = null;
     try {
-        db = new Database(dbPath, { readonly: true });
+        const opened = openCursorSqliteReadonly(dbPath, { rootDir: userDir });
+        if (!opened.ok)
+            return new Map();
+        db = opened.db;
         if (!tableExists(db, STATE_TABLE))
             return new Map();
         const row = db
@@ -702,8 +725,12 @@ function pick(obj, ...keys) {
     }
     return typeof cur === "number" ? cur : null;
 }
+function dailyStatsSessionId(date, eventType, modelKey) {
+    const suffix = modelKey ? `${eventType}:${modelKey}` : eventType;
+    return `cursor:daily_stats:${date}:${suffix}`;
+}
 function buildPayload(opts) {
-    const { eventType, tokensIn, tokensOut, costUsd, occurredAt, dbPath, model = "unknown", projectId, costModel = LINE_COST_MODEL, } = opts;
+    const { eventType, tokensIn, tokensOut, costUsd, occurredAt, dbPath, date, model = "unknown", modelKey, projectId, costModel = LINE_COST_MODEL, } = opts;
     const payload = {
         tool_name: "cursor",
         event_type: eventType,
@@ -713,6 +740,7 @@ function buildPayload(opts) {
         cost_usd: costUsd,
         occurred_at: occurredAt,
         metadata: {
+            session_id: dailyStatsSessionId(date, eventType, modelKey),
             cursor_session_id: null,
             ...cursorWorkspaceMetadata(dbPath),
             cost_model: costModel,
@@ -740,9 +768,10 @@ export function mapDailyStats(entry, projectId, pricing = DEFAULT_CURSOR_PRICING
             eventType: "completion",
             tokensIn: tabSuggested,
             tokensOut: tabAccepted,
-            costUsd: computeLineCost("completion", tabSuggested, pricing),
+            costUsd: computeLineCost("completion", tabAccepted, pricing),
             occurredAt,
             dbPath,
+            date,
             model,
             projectId,
         }));
@@ -752,9 +781,10 @@ export function mapDailyStats(entry, projectId, pricing = DEFAULT_CURSOR_PRICING
             eventType: "chat",
             tokensIn: composerSuggested,
             tokensOut: composerAccepted,
-            costUsd: computeLineCost("chat", composerSuggested, pricing),
+            costUsd: computeLineCost("chat", composerAccepted, pricing),
             occurredAt,
             dbPath,
+            date,
             model,
             projectId,
         }));
@@ -776,7 +806,9 @@ export function mapDailyStats(entry, projectId, pricing = DEFAULT_CURSOR_PRICING
             costUsd: computeTokenCost("chat", tokensIn, tokensOut, pricing),
             occurredAt,
             dbPath,
+            date,
             model,
+            modelKey: model,
             projectId,
             costModel: TOKEN_COST_MODEL,
         }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aixle/insights",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "stdio MCP server for AI coding-assistant telemetry — Claude transcript sync + Cursor SQLite ingest.",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "provenance": false
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.19.0"
   },
   "license": "MIT",
   "repository": {
@@ -62,6 +62,6 @@
     "@types/node": "^24",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3",
-    "vitest": "^1.2.2"
+    "vitest": "^4.1.0"
   }
 }