@aixle/insights 0.2.4-staging → 0.2.6-staging

package/README.md

@@ -102,7 +102,27 @@ After `init` succeeds:
 
 ## Multi-org
 
-If your account has several organization memberships, `init` mints ingest tokens for the **oldest** membership unless you scope to a different org:
+If your account belongs to a **single** organization, `init` binds that org automatically — no flag, zero friction.
+
+If your account belongs to **more than one** organization, `init` needs to know which org to bind. It resolves the target in this order:
+
+1. `--organization-id <uuid>` flag (or `DB90_ORGANIZATION_ID` env var), or
+2. your **Default Organization** preference from the web app.
+
+If neither is set, `init` **does not** guess. It prints the organizations you belong to and exits non-zero without saving credentials:
+
+```
+Multiple organizations found — choose one to bind this install:
+  - Acme Corp (b1e2...  ) — owner
+  - Contoso (c3d4...  ) — member
+Then either:
+  1. Re-run init with --organization-id <uuid> (completes device login again), or
+  2. Set a Default Organization in web Preferences, then re-run init.
+```
+
+Because credentials are only persisted on success, re-running `init` means completing the Keycloak device login again.
+
+To scope explicitly:
 
 ```bash
 npx -y @aixle/insights init \
@@ -113,6 +133,10 @@ npx -y @aixle/insights init \
 
 You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin it via `mcpServers.aixle-insights.env` in `~/.claude.json`. The CLI flag overrides the env var when both are set.
 
+Once `init` succeeds it reports the bound org (`Credentials saved (organization <uuid>).`), and `aixle-insights health` (or the `aixle_insights_status` MCP tool) shows the bound `organization_id`.
+
+> **Preferences caveat — this is non-obvious.** The web app's "current org" (the one you appear to be viewing) is normally the **last-used** org, remembered in your browser's `localStorage`. That is **not** the same as your **Default Organization** preference, which is what `init` reads. A multi-org user who has switched orgs in the UI but never explicitly set **Default Organization** in web Preferences has no server-side preference for `init` to use — so `init` will hit the org-selection error above until you either set the Default Organization preference or pass `--organization-id`.
+
 ## First run and backfill
 
 Before you run `init`, the MCP server is a deliberate no-op: it does not read, buffer, or send anything, and it does not create any state files. Nothing is lost during this window — Claude Code's transcripts and Cursor's local telemetry stores are unaffected by whether `@aixle/insights` is watching them.
@@ -162,6 +186,12 @@ Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per
 }
 ```
 
+The file is optional — an absent `config.json` is the normal case and is silent. A file that is
+present but unusable is ignored entirely (every override falls back to its default) and a
+`config_parse_failed` line is written to `mcp.log`. That covers malformed JSON and valid JSON that
+isn't an object, including a **top-level array** — a common mistake when writing per-model rates.
+Nothing is printed to the terminal, so check the log if an override appears to have no effect.
+
 ## 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.
@@ -188,6 +218,22 @@ The runtime gate exists because `init`'s two gates only run once, at login time.
 
 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.
 
+### Local store integrity
+
+Transport security covers data in flight. The other half of the threat model is what the package
+reads back off the local machine: credentials (keychain or file), `config.json`, and state files are
+all attacker-writable if the account is compromised, so none of them is trusted on read.
+
+Each is validated every time it is loaded. A payload that fails to parse, or that parses but does
+not match the expected shape, is **rejected** and the caller falls back to its documented default —
+no credentials, no config overrides, fresh state. Every rejection is recorded in `mcp.log`, so a
+corrupted or tampered store is distinguishable from one that was never created; before this, both
+were silent and looked identical to a fresh install. See
+[Diagnostics](#diagnostics) for the event names.
+
+Log fields carry only the file path (or the keychain service name) and a short machine-readable
+reason. File contents, keychain payloads, and tokens are never logged.
+
 ## 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.
@@ -225,6 +271,35 @@ 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 **`aixle_insights_status`** MCP tool returns the same diagnostic structure as `aixle-insights health`.
 
+### Local-store integrity events
+
+These four are the only signal that a local store was present but unusable — `health` and
+`aixle_insights_status` do **not** report them, so `mcp.log` is the sole surface:
+
+| Event | Fires when |
+|---|---|
+| `credentials_parse_failed` | `credentials.json` exists but was rejected |
+| `credentials_keytar_parse_failed` | the OS keychain entry exists but was rejected |
+| `config_parse_failed` | `config.json` exists but was rejected |
+| `state_parse_failed` | a state file exists but was rejected |
+
+Each carries a `reason` distinguishing the two failure modes:
+
+- `invalid_json` — the payload did not parse at all.
+- `invalid_shape` — it parsed, but validation rejected it: credentials with no usable token, a
+  `config.json` that is a JSON array, a state file missing `version` / `sessions`, and so on.
+
+Three properties are worth relying on:
+
+- An **absent** file never warns. That is the everyday case (most users never create a
+  `config.json`, and every machine starts with no state file), so a warning always means something
+  is actually there and wrong.
+- A **missing or disabled OS keychain** never warns either — falling back to the file is expected
+  on headless Linux, CI, and containers, not an error.
+- All four are written to the log **only**, never mirrored to stderr, because stray output on the
+  stdio transport corrupts the MCP protocol. Emitting a warning never changes the fallback the
+  caller returns.
+
 ## Troubleshooting
 
 | Symptom | Most likely cause | Fix |
@@ -236,6 +311,9 @@ aixle-insights verify-hooks  # JSON: hooks installed + queue depth
 | `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`). |
+| `health` reports `authenticated: false` right after a successful `init`, and `credentials_parse_failed` or `credentials_keytar_parse_failed` is in the log | The credential store exists but was rejected, so it is treated as absent. The `reason` field says whether it failed to parse (`invalid_json`) or parsed into the wrong shape (`invalid_shape`). | Re-run `init`. If you hand-edited `credentials.json` for local testing, remember the keychain is read **first** — see [State + credentials](#state--credentials). |
+| A `config.json` override has no effect, and `config_parse_failed` is in the log | The file is malformed, or is valid JSON that is not an object — a top-level array is the usual mistake. | Fix it to match the shape under [Environment](#environment); until it parses, every override is ignored. |
+| Sync re-sends history that was already delivered, and `state_parse_failed` is in the log | A state file was present but rejected, so sync fell back to fresh state and lost its dedup checkpoints. | This is recovery, not a loop — the next successful cycle writes valid state. Ingest upserts by session, so duplicates are absorbed. Worth investigating what wrote the bad file. |
 | `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. |
 

package/dist/auth/credentials.js

@@ -4,6 +4,7 @@ import { userInfo } from "node:os";
 import { join } from "node:path";
 import { getAppDir } from "../state.js";
 import { mcpLog } from "../log.js";
+import { describeReadFailure } from "../lib/parse-error.js";
 export const KEYTAR_SERVICE = "aixle-insights";
 const KEYTAR_ACCOUNT = "aixle-insights-ingest-credential";
 function credentialsPath(appDir) {
@@ -62,15 +63,23 @@ export function loadCredentialsFromFileOnly(appDir = getAppDir()) {
     const filePath = credentialsPath(appDir);
     if (!existsSync(filePath))
         return null;
+    let raw;
     try {
-        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
-        return normalizeLoadedCredentials(raw);
+        raw = JSON.parse(readFileSync(filePath, "utf-8"));
     }
     catch (err) {
-        // File exists (checked above) but failed to parse/normalize — distinguishes tampering from "never created".
-        mcpLog.warn("credentials_parse_failed", { path: filePath, error: err instanceof Error ? err.message : String(err) }, false);
+        // File exists (checked above) but is not readable/valid JSON — distinguishes tampering from "never created".
+        mcpLog.warn("credentials_parse_failed", { path: filePath, ...describeReadFailure(err) }, false);
         return null;
     }
+    const normalized = normalizeLoadedCredentials(raw);
+    if (normalized === null) {
+        // Valid JSON, but not a credential shape we accept. `normalizeLoadedCredentials` signals
+        // rejection by returning null and never throws, so this cannot surface in the catch
+        // above — without this branch a plausible-looking replacement file stays silent. (DB90DV-699)
+        mcpLog.warn("credentials_parse_failed", { path: filePath, reason: "invalid_shape" }, false);
+    }
+    return normalized;
 }
 async function tryKeytarGet() {
     if (keytarDisabled())
@@ -86,15 +95,22 @@ async function tryKeytarGet() {
     }
     if (!raw)
         return null;
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        return normalizeLoadedCredentials(parsed);
+        parsed = JSON.parse(raw);
     }
     catch (err) {
-        // Keychain entry exists (checked above) but failed to parse/normalize — distinguishes tampering from "no entry".
-        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, error: err instanceof Error ? err.message : String(err) }, false);
+        // Keychain entry exists (checked above) but is not valid JSON — distinguishes tampering from "no entry".
+        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, ...describeReadFailure(err) }, false);
         return null;
     }
+    const normalized = normalizeLoadedCredentials(parsed);
+    if (normalized === null) {
+        // Same shape-rejection hole as the file path above. Fields stay service-only — never the
+        // keychain payload. (DB90DV-699)
+        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, reason: "invalid_shape" }, false);
+    }
+    return normalized;
 }
 async function tryKeytarSet(payload) {
     if (keytarDisabled())

package/dist/auth/exchange.d.ts

@@ -1,3 +1,12 @@
+export interface OrgOption {
+    id: string;
+    name: string;
+    role: string;
+}
+export declare class OrganizationSelectionRequiredError extends Error {
+    readonly organizations: OrgOption[];
+    constructor(message: string, organizations: OrgOption[]);
+}
 export interface ExchangeAccount {
     ingestToken: string;
 }

package/dist/auth/exchange.js

@@ -1,3 +1,11 @@
+export class OrganizationSelectionRequiredError extends Error {
+    organizations;
+    constructor(message, organizations) {
+        super(message);
+        this.name = "OrganizationSelectionRequiredError";
+        this.organizations = organizations;
+    }
+}
 export async function exchangeIngestToken(params) {
     const fetchFn = params.fetchImpl ?? fetch;
     const requestedTools = params.tools?.length ? [...params.tools] : params.toolName ? [params.toolName] : [];
@@ -38,6 +46,21 @@ export async function exchangeIngestToken(params) {
         throw new Error(`DB90 exchange: invalid JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
     }
     if (!res.ok) {
+        const errBody = json;
+        if (errBody["error"] === "organization_selection_required") {
+            const rawOrgs = Array.isArray(errBody["organizations"]) ? errBody["organizations"] : [];
+            // Defensive: skip null/non-object elements so a malformed server body cannot crash init.
+            const orgs = rawOrgs
+                .filter((o) => typeof o === "object" && o !== null && !Array.isArray(o))
+                .filter((o) => typeof o["id"] === "string" && typeof o["name"] === "string")
+                .map((o) => ({
+                id: o["id"],
+                name: o["name"],
+                role: String(o["role"] ?? ""),
+            }));
+            const msg = typeof errBody["message"] === "string" ? errBody["message"] : "Organization selection required.";
+            throw new OrganizationSelectionRequiredError(msg, orgs);
+        }
         throw new Error(`DB90 exchange failed (HTTP ${res.status}): ${text.slice(0, 500)}`);
     }
     const root = json;

package/dist/auth/flow.d.ts

@@ -1,3 +1,4 @@
+import { type OrgOption } from "./exchange.js";
 import { defaultKeycloakClientId, defaultKeycloakIssuer } from "./keycloak.js";
 import type { TelemetryToolId } from "./credentials.js";
 export interface LoginAndPersistOptions {
@@ -29,5 +30,7 @@ export declare function loginAndPersistCredentials(opts: LoginAndPersistOptions)
 } | {
     ok: false;
     error: string;
+    code?: "organization_selection_required";
+    organizations?: OrgOption[];
 }>;
 export { defaultKeycloakIssuer, defaultKeycloakClientId };

package/dist/auth/flow.js

@@ -1,4 +1,4 @@
-import { exchangeIngestToken } from "./exchange.js";
+import { exchangeIngestToken, OrganizationSelectionRequiredError } from "./exchange.js";
 import { defaultKeycloakClientId, defaultKeycloakIssuer, obtainKeycloakAccessTokenViaDeviceFlow } from "./keycloak.js";
 import { loadCredentials, saveStoredCredentials } from "./credentials.js";
 import { getAppDir } from "../state.js";
@@ -78,10 +78,11 @@ export async function loginAndPersistCredentials(opts) {
             opts.onSecurityWarning?.(ingestHostSecurity.warning);
         }
         const existing = await loadCredentials(appDir);
+        const sameOrg = existing?.host === exchanged.ingestHost && existing.organizationId === exchanged.organizationId;
         const stored = {
             host: exchanged.ingestHost,
             organizationId: exchanged.organizationId,
-            accounts: existing?.host === exchanged.ingestHost ? { ...existing.accounts } : {},
+            accounts: sameOrg ? { ...existing.accounts } : {},
             ...(opts.allowInsecureHttp === true ? { insecureHttpAllowed: true } : {}),
         };
         for (const tid of ["claude_code", "cursor"]) {
@@ -92,6 +93,14 @@ export async function loginAndPersistCredentials(opts) {
         await saveStoredCredentials(stored, appDir);
     }
     catch (e) {
+        if (e instanceof OrganizationSelectionRequiredError) {
+            return {
+                ok: false,
+                code: "organization_selection_required",
+                organizations: e.organizations,
+                error: e.message,
+            };
+        }
         return { ok: false, error: e instanceof Error ? e.message : String(e) };
     }
     return { ok: true, organizationId: exchanged.organizationId };

package/dist/cli.js

@@ -185,7 +185,9 @@ init options:
   --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.
+  If you belong to more than one org, pass \`--organization-id <uuid>\` (or set \`DB90_ORGANIZATION_ID\`),
+  or set a Default Organization in web Preferences. Without either, \`init\` lists your orgs and exits.
+  Single-org users need no flag. Run \`aixle-insights health\` to see the bound organization_id.
 
 Credentials:
   Stored in the OS keychain via keytar when available; otherwise
@@ -270,6 +272,19 @@ export async function runInit(cliArgs, deps) {
         },
     });
     if (!result.ok) {
+        if (result.code === "organization_selection_required") {
+            runtime.error(result.error);
+            if (result.organizations?.length) {
+                runtime.error("Multiple organizations found — choose one to bind this install:");
+                for (const o of result.organizations) {
+                    runtime.error(`  - ${o.name} (${o.id})${o.role ? ` — ${o.role}` : ""}`);
+                }
+            }
+            runtime.error("Then either:");
+            runtime.error("  1. Re-run init with --organization-id <uuid> (completes device login again), or");
+            runtime.error("  2. Set a Default Organization in web Preferences, then re-run init.");
+            return 1;
+        }
         runtime.error(`Auth failed: ${result.error}`);
         return 1;
     }

package/dist/health.d.ts

@@ -5,6 +5,7 @@ export interface HealthSnapshot {
     authenticated: boolean;
     configured: boolean;
     host: string | null;
+    organization_id: string | null;
     ingest_tools: TelemetryToolId[];
     app_dir: string;
     log_path: string;

package/dist/health.js

@@ -70,6 +70,7 @@ export async function buildHealthSnapshot() {
                 authenticated: false,
                 configured: false,
                 host: null,
+                organization_id: null,
                 ingest_tools: [],
                 app_dir: appDir,
                 log_path: logPath,
@@ -94,6 +95,7 @@ export async function buildHealthSnapshot() {
             authenticated: true,
             configured: true,
             host: creds.host,
+            organization_id: creds.organizationId ?? null,
             ingest_tools,
             app_dir: appDir,
             log_path: logPath,
@@ -114,6 +116,7 @@ export async function buildHealthSnapshot() {
             authenticated: false,
             configured: false,
             host: null,
+            organization_id: null,
             ingest_tools: [],
             app_dir: appDir,
             log_path: logPath,
@@ -150,6 +153,7 @@ export function healthSnapshotToStatusPayload(snapshot) {
         authenticated: snapshot.authenticated,
         configured: snapshot.configured,
         host: snapshot.host,
+        organization_id: snapshot.organization_id,
         ingest_tools: snapshot.ingest_tools,
         needs_init: needsInit,
         onboarding_message: onboardingMessage,
@@ -172,6 +176,7 @@ export function formatHealthForCli(snapshot) {
     lines.push(`authenticated: ${snapshot.authenticated}`);
     lines.push(`configured: ${snapshot.configured}`);
     lines.push(`host: ${snapshot.host ?? "(none)"}`);
+    lines.push(`organization_id: ${snapshot.organization_id ?? "(none)"}`);
     lines.push(`ingest_tools: ${snapshot.ingest_tools.length ? snapshot.ingest_tools.join(", ") : "(none)"}`);
     lines.push(`state_file_paths:`);
     if (snapshot.state_file_paths.length === 0) {

package/dist/lib/config.d.ts

@@ -12,8 +12,8 @@ export interface BaseConfig {
  * Load a connector's `config.json` from disk. Returns `{}` on missing or
  * malformed files — callers fall back to env vars / CLI flags / defaults.
  *
- * @param configDir Directory containing `config.json`, typically the
- *                  connector's `APP_DIR` (`~/.db90-claude` / `~/.db90-cursor`).
+ * @param configDir Directory containing `config.json`, typically the app home directory
+ *                  (`~/.aixle-insights`, or `AIXLE_INSIGHTS_HOME` when set).
  * @param parsePricing Optional callback that extracts a connector-specific
  *                     pricing shape from the raw parsed JSON. Returns
  *                     `undefined` when the pricing block is missing or invalid.

package/dist/lib/config.js

@@ -1,12 +1,13 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { mcpLog } from "../log.js";
+import { describeReadFailure } from "./parse-error.js";
 /**
  * Load a connector's `config.json` from disk. Returns `{}` on missing or
  * malformed files — callers fall back to env vars / CLI flags / defaults.
  *
- * @param configDir Directory containing `config.json`, typically the
- *                  connector's `APP_DIR` (`~/.db90-claude` / `~/.db90-cursor`).
+ * @param configDir Directory containing `config.json`, typically the app home directory
+ *                  (`~/.aixle-insights`, or `AIXLE_INSIGHTS_HOME` when set).
  * @param parsePricing Optional callback that extracts a connector-specific
  *                     pricing shape from the raw parsed JSON. Returns
  *                     `undefined` when the pricing block is missing or invalid.
@@ -16,29 +17,36 @@ import { mcpLog } from "../log.js";
  */
 export function loadBaseConfig(configDir, parsePricing) {
     const configPath = join(configDir, "config.json");
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
-        if (typeof parsed === "object" && parsed !== null) {
-            const obj = parsed;
-            const result = {
-                token: typeof obj.token === "string" ? obj.token : undefined,
-                host: typeof obj.host === "string" ? obj.host : undefined,
-                project_id: typeof obj.project_id === "string" ? obj.project_id : undefined,
-            };
-            if (parsePricing) {
-                const pricing = parsePricing(obj);
-                if (pricing !== undefined)
-                    result.pricing = pricing;
-            }
-            return result;
-        }
+        parsed = JSON.parse(readFileSync(configPath, "utf-8"));
     }
     catch (err) {
         const code = err?.code;
         if (code !== "ENOENT") {
-            // Config file exists but failed to parse — distinguishes tampering from "never created".
-            mcpLog.warn("config_parse_failed", { path: configPath, error: err instanceof Error ? err.message : String(err) }, false);
+            // Config file exists but is not valid JSON — distinguishes tampering from "never created".
+            // ENOENT stays silent: this file is optional and most users never create it.
+            mcpLog.warn("config_parse_failed", { path: configPath, ...describeReadFailure(err) }, false);
         }
+        return {};
+    }
+    // Valid JSON, but not a config object. Arrays are rejected explicitly because
+    // `typeof [] === "object"` would otherwise let them reach the happy path and be handed
+    // to `parsePricing`. Previously every non-object fell through silently. (DB90DV-699)
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        mcpLog.warn("config_parse_failed", { path: configPath, reason: "invalid_shape" }, false);
+        return {};
+    }
+    const obj = parsed;
+    const result = {
+        token: typeof obj.token === "string" ? obj.token : undefined,
+        host: typeof obj.host === "string" ? obj.host : undefined,
+        project_id: typeof obj.project_id === "string" ? obj.project_id : undefined,
+    };
+    if (parsePricing) {
+        const pricing = parsePricing(obj);
+        if (pricing !== undefined)
+            result.pricing = pricing;
     }
-    return {};
+    return result;
 }

package/dist/lib/parse-error.d.ts

@@ -0,0 +1,21 @@
+export type ReadFailureReason = "invalid_json" | "unreadable";
+/**
+ * Classifies a caught error from `JSON.parse(readFileSync(...))` (or a parsed keychain
+ * payload) into a log-safe reason + error string.
+ *
+ * V8's `JSON.parse` throws a `SyntaxError` whose `.message` can embed a prefix (or, for a
+ * short enough input, the entirety) of the unparsed content — e.g.
+ * `JSON.parse("example_local_fixture_1234567890")` produces
+ * `Unexpected token 'e', "example_lo"... is not valid JSON`. Logging that message would
+ * leak exactly the secret content the parse-failure events exist to describe without
+ * exposing (see `credentials_parse_failed` / `credentials_keytar_parse_failed` /
+ * `config_parse_failed` / `state_parse_failed`). So for a `SyntaxError` this reports only
+ * the error name, never `.message`.
+ *
+ * Any other error (fs I/O — `EACCES`, `EISDIR`, etc.) is reported as `unreadable` using its
+ * errno `code`, which never contains file content and is more actionable than a bare name.
+ */
+export declare function describeReadFailure(err: unknown): {
+    reason: ReadFailureReason;
+    error: string;
+};

package/dist/lib/parse-error.js

@@ -0,0 +1,25 @@
+/**
+ * Classifies a caught error from `JSON.parse(readFileSync(...))` (or a parsed keychain
+ * payload) into a log-safe reason + error string.
+ *
+ * V8's `JSON.parse` throws a `SyntaxError` whose `.message` can embed a prefix (or, for a
+ * short enough input, the entirety) of the unparsed content — e.g.
+ * `JSON.parse("example_local_fixture_1234567890")` produces
+ * `Unexpected token 'e', "example_lo"... is not valid JSON`. Logging that message would
+ * leak exactly the secret content the parse-failure events exist to describe without
+ * exposing (see `credentials_parse_failed` / `credentials_keytar_parse_failed` /
+ * `config_parse_failed` / `state_parse_failed`). So for a `SyntaxError` this reports only
+ * the error name, never `.message`.
+ *
+ * Any other error (fs I/O — `EACCES`, `EISDIR`, etc.) is reported as `unreadable` using its
+ * errno `code`, which never contains file content and is more actionable than a bare name.
+ */
+export function describeReadFailure(err) {
+    if (err instanceof SyntaxError) {
+        return { reason: "invalid_json", error: "SyntaxError" };
+    }
+    const code = err?.code;
+    if (code)
+        return { reason: "unreadable", error: code };
+    return { reason: "unreadable", error: err instanceof Error ? err.name : "unknown_error" };
+}

package/dist/state.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { createHash, randomBytes } from "node:crypto";
 import { mcpLog } from "./log.js";
+import { describeReadFailure } from "./lib/parse-error.js";
 export function getAppDir() {
     const override = process.env["AIXLE_INSIGHTS_HOME"]?.trim();
     if (override && override.length > 0)
@@ -90,48 +91,50 @@ export function migrateLegacyState(dir, host, token) {
 }
 export function readState(dir, host, token) {
     const filePath = stateFilePath(dir ?? getAppDir(), host, token);
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
-        if (typeof parsed === "object" && parsed !== null) {
-            const p = parsed;
-            if (typeof p.version === "number" &&
-                typeof p.sessions === "object" &&
-                p.sessions !== null) {
-                const lastRecentCommitHashes = Array.isArray(p.lastRecentCommitHashes)
-                    ? p.lastRecentCommitHashes.filter((h) => typeof h === "string")
-                    : undefined;
-                const out = {
-                    version: p.version,
-                    sessions: p.sessions,
-                };
-                if (lastRecentCommitHashes !== undefined) {
-                    out.lastRecentCommitHashes = lastRecentCommitHashes;
-                }
-                if ("mcp_operator" in p) {
-                    const mcp = parseMcpOperator(p.mcp_operator);
-                    if (mcp)
-                        out.mcp_operator = mcp;
-                }
-                if ("rate_limited_until" in p) {
-                    if (typeof p.rate_limited_until === "string") {
-                        out.rate_limited_until = p.rate_limited_until;
-                    }
-                    else if (p.rate_limited_until === null) {
-                        out.rate_limited_until = null;
-                    }
-                }
-                return out;
-            }
-        }
+        parsed = JSON.parse(readFileSync(filePath, "utf-8"));
     }
     catch (err) {
         const code = err?.code;
         if (code !== "ENOENT") {
-            // State file exists but failed to parse — distinguishes tampering from "never created".
-            mcpLog.warn("state_parse_failed", { path: filePath, error: err instanceof Error ? err.message : String(err) }, false);
+            // State file exists but is not valid JSON — distinguishes tampering from "never created".
+            // ENOENT stays silent: that is the normal first-run case.
+            mcpLog.warn("state_parse_failed", { path: filePath, ...describeReadFailure(err) }, false);
+        }
+        return { version: 1, sessions: {} };
+    }
+    const p = typeof parsed === "object" && parsed !== null ? parsed : null;
+    if (p === null || typeof p.version !== "number" || typeof p.sessions !== "object" || p.sessions === null) {
+        // Valid JSON, wrong shape. This fallback discards every dedup checkpoint and causes a full
+        // re-send, so it is the most consequential of the four to have been silent. (DB90DV-699)
+        mcpLog.warn("state_parse_failed", { path: filePath, reason: "invalid_shape" }, false);
+        return { version: 1, sessions: {} };
+    }
+    const lastRecentCommitHashes = Array.isArray(p.lastRecentCommitHashes)
+        ? p.lastRecentCommitHashes.filter((h) => typeof h === "string")
+        : undefined;
+    const out = {
+        version: p.version,
+        sessions: p.sessions,
+    };
+    if (lastRecentCommitHashes !== undefined) {
+        out.lastRecentCommitHashes = lastRecentCommitHashes;
+    }
+    if ("mcp_operator" in p) {
+        const mcp = parseMcpOperator(p.mcp_operator);
+        if (mcp)
+            out.mcp_operator = mcp;
+    }
+    if ("rate_limited_until" in p) {
+        if (typeof p.rate_limited_until === "string") {
+            out.rate_limited_until = p.rate_limited_until;
+        }
+        else if (p.rate_limited_until === null) {
+            out.rate_limited_until = null;
         }
     }
-    return { version: 1, sessions: {} };
+    return out;
 }
 /** Atomic write: write to a temp file then rename over the target. */
 export function writeState(state, dir, host, token) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aixle/insights",
-  "version": "0.2.4-staging",
+  "version": "0.2.6-staging",
   "description": "stdio MCP server for AI coding-assistant telemetry — Claude transcript sync + Cursor SQLite ingest.",
   "type": "module",
   "bin": {