@aixle/insights 0.2.3-staging → 0.2.5-staging

package/README.md

@@ -162,6 +162,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 +194,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 +247,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 +287,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/cli.js

@@ -377,10 +377,12 @@ export async function runOnce(deps, options) {
     const lookupToken = pickProjectLookupToken(creds);
     let projectId = null;
     let projectIdSource = "none";
+    let repositoryId = null;
     if (lookupToken) {
         const resolution = await runtime.resolveProjectId(undefined, undefined, creds.host, lookupToken, false, creds.insecureHttpAllowed === true);
         projectId = resolution.projectId;
         projectIdSource = resolution.source;
+        repositoryId = resolution.repositoryId;
         mcpLog.info("project_attribution_resolved", { project_id: resolution.projectId, source: resolution.source }, false);
     }
     const result = await runtime.syncTelemetryTools({
@@ -389,6 +391,7 @@ export async function runOnce(deps, options) {
         verbose: false,
         projectId,
         projectIdSource,
+        repositoryId,
         projectLookupToken: lookupToken,
         pricing: runtime.pricing,
         cursorPricing: resolveCursorPricing(undefined, appDirRuntime),

package/dist/hooks/cursor-hooks-mapper.d.ts

@@ -19,4 +19,4 @@ export declare function warnOnCursorVersion(event: HookLogEvent, verbose: boolea
  * Map a validated hook event to the CursorPayload contract.
  * Call shouldIngestHookEvent() before this — it does not re-validate.
  */
-export declare function mapHookEventToPayload(event: HookLogEvent, projectId?: string | null): CursorPayload;
+export declare function mapHookEventToPayload(event: HookLogEvent, projectId?: string | null, repositoryId?: string | null): CursorPayload;

package/dist/hooks/cursor-hooks-mapper.js

@@ -50,7 +50,7 @@ export function warnOnCursorVersion(event, verbose) {
  * Map a validated hook event to the CursorPayload contract.
  * Call shouldIngestHookEvent() before this — it does not re-validate.
  */
-export function mapHookEventToPayload(event, projectId) {
+export function mapHookEventToPayload(event, projectId, repositoryId) {
     const workspace = Array.isArray(event.workspace_roots) && typeof event.workspace_roots[0] === "string"
         ? event.workspace_roots[0]
         : "unknown";
@@ -80,5 +80,7 @@ export function mapHookEventToPayload(event, projectId) {
     };
     if (projectId)
         payload.project_id = projectId;
+    if (repositoryId)
+        payload.repository_id = repositoryId;
     return payload;
 }

package/dist/hooks/cursor-hooks-reader.d.ts

@@ -14,7 +14,16 @@ export interface ProcessHooksQueueParams {
     on429: (retryAfter: number, quotaExceeded: boolean) => void;
     /** If true, skip events already in state.sessions. */
     skipSeen?: boolean;
-    resolveProjectId?: (workspace: string) => Promise<string | null>;
+    /**
+     * Resolve project + repository attribution for a workspace path. Returning a
+     * repositoryId lets hook events carry the same repository_id the sync path
+     * stamps. A null repositoryId (or an older resolver returning only a string)
+     * simply omits it.
+     */
+    resolveProjectId?: (workspace: string) => Promise<{
+        projectId: string | null;
+        repositoryId: string | null;
+    } | string | null>;
     verbose?: boolean;
 }
 export interface ProcessHooksResult {

package/dist/hooks/cursor-hooks-reader.js

@@ -100,10 +100,18 @@ export async function processHooksQueue(params) {
             continue;
         }
         let projectId;
+        let repositoryId;
         if (resolveProjectId && workspace) {
-            projectId = await resolveProjectId(workspace);
+            const resolved = await resolveProjectId(workspace);
+            if (typeof resolved === "string" || resolved === null) {
+                projectId = resolved;
+            }
+            else {
+                projectId = resolved.projectId;
+                repositoryId = resolved.repositoryId;
+            }
         }
-        const payload = mapHookEventToPayload(event, projectId);
+        const payload = mapHookEventToPayload(event, projectId, repositoryId);
         const ok = await postEvent(payload, host, token, { on429, allowInsecureHttp });
         if (ok) {
             totalSent++;

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/lib/project-resolver.d.ts

@@ -1,9 +1,17 @@
 export interface ProjectResolution {
     projectId: string | null;
+    /**
+     * Repository that owns the resolved project's attribution, when the API
+     * resolved one from the git remote. Only populated on auto-detect (the API
+     * only knows the repository via the remote lookup). Null for flag/config
+     * attribution — an explicit project id carries no repository context.
+     */
+    repositoryId: string | null;
     source: "flag" | "config" | "auto-detect" | "auto-detect-not-found" | "none";
 }
 export interface LookupResult {
     project_id: string;
+    repository_id?: string | null;
     name: string;
 }
 export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<ProjectResolution>;

package/dist/lib/project-resolver.js

@@ -10,29 +10,31 @@ export async function resolveProjectId(flagValue, configValue, host, token, verb
     const flag = coerce(flagValue);
     const config = coerce(configValue);
     if (flag !== undefined)
-        return { projectId: flag, source: "flag" };
+        return { projectId: flag, repositoryId: null, source: "flag" };
     if (config !== undefined)
-        return { projectId: config, source: "config" };
+        return { projectId: config, repositoryId: null, source: "config" };
     const gitRemote = getGitRemote(verbose);
     if (gitRemote === null)
-        return { projectId: null, source: "none" };
+        return { projectId: null, repositoryId: null, source: "none" };
     const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
-        return { projectId: null, source: "auto-detect-not-found" };
-    if (result !== null)
-        return { projectId: result.project_id, source: "auto-detect" };
-    return { projectId: null, source: "none" };
+        return { projectId: null, repositoryId: null, source: "auto-detect-not-found" };
+    if (result !== null) {
+        return { projectId: result.project_id, repositoryId: result.repository_id ?? null, source: "auto-detect" };
+    }
+    return { projectId: null, repositoryId: null, source: "none" };
 }
 export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose, allowInsecureHttp = false) {
     const gitRemote = getGitRemoteForPath(repoPath, verbose);
     if (gitRemote === null)
-        return { projectId: null, source: "none" };
+        return { projectId: null, repositoryId: null, source: "none" };
     const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
-        return { projectId: null, source: "auto-detect-not-found" };
-    if (result !== null)
-        return { projectId: result.project_id, source: "auto-detect" };
-    return { projectId: null, source: "none" };
+        return { projectId: null, repositoryId: null, source: "auto-detect-not-found" };
+    if (result !== null) {
+        return { projectId: result.project_id, repositoryId: result.repository_id ?? null, source: "auto-detect" };
+    }
+    return { projectId: null, repositoryId: null, source: "none" };
 }
 export function getGitRemote(verbose) {
     try {
@@ -145,7 +147,10 @@ function isLookupResponse(body) {
     if (typeof d !== "object" || d === null)
         return false;
     const data = d;
-    return typeof data.project_id === "string" && typeof data.name === "string";
+    if (typeof data.project_id !== "string" || typeof data.name !== "string")
+        return false;
+    // repository_id is optional (older servers omit it) but must be a string when present.
+    return data.repository_id == null || typeof data.repository_id === "string";
 }
 /**
  * Cursor `recentCommit.repoName` is typically `owner/repo` (GitHub-style slug), not a full

package/dist/readers/claude.d.ts

@@ -72,6 +72,7 @@ export interface ClaudePayload extends IngestPayload {
     cost_usd: number | null;
     occurred_at: string;
     project_id?: string;
+    repository_id?: string;
     metadata: {
         session_id: string;
         claude_session_id: string;
@@ -121,6 +122,7 @@ export type ClaudeMappedPayload = ClaudePayload | ClaudeDerivativePayload;
 /** Options for mapTranscriptTurn. */
 export interface ToClaudePayloadOptions {
     projectId?: string | null;
+    repositoryId?: string | null;
     pricing?: PricingTable;
 }
 /** Finds all *.jsonl transcript files across both Claude project directory roots. */

package/dist/readers/claude.js

@@ -395,7 +395,7 @@ export async function parseTranscriptFile(filePath, verbose = false) {
 }
 /** Converts a Claude transcript turn to parent chat and derivative tool-use payloads. */
 export function mapTranscriptTurn(turn, options) {
-    const { projectId, pricing } = options ?? {};
+    const { projectId, repositoryId, pricing } = options ?? {};
     const baseInputTokens = Math.max(0, turn.tokensIn - turn.cacheWriteTokens - turn.cacheReadTokens);
     const cost = pricing
         ? calculateCost(turn.model, baseInputTokens, turn.tokensOut, turn.cacheWriteTokens, turn.cacheReadTokens, pricing)
@@ -438,6 +438,8 @@ export function mapTranscriptTurn(turn, options) {
     }
     if (projectId)
         payload.project_id = projectId;
+    if (repositoryId)
+        payload.repository_id = repositoryId;
     const derivatives = turn.toolUses.map((toolUse) => {
         const derivative = {
             tool_name: "claude_code",

package/dist/readers/cursor.d.ts

@@ -122,6 +122,7 @@ export interface CursorPayload extends IngestPayload {
     cost_usd: number;
     occurred_at: string;
     project_id?: string;
+    repository_id?: string;
     metadata: CursorPayloadMetadata;
 }
 export declare function toEpochMs(timestamp: number | string | null | undefined): number | null;

package/dist/server.js

@@ -80,7 +80,7 @@ let cachedProjectResolution = null;
 async function getProjectResolutionForSync(creds) {
     const token = pickProjectLookupToken(creds);
     if (!token)
-        return { projectId: null, source: "none" };
+        return { projectId: null, repositoryId: null, source: "none" };
     const gitRemote = getGitRemote(false) ?? "no-remote";
     const cacheKey = `${creds.host}|${token}|${gitRemote}`;
     if (cachedProjectResolution?.key === cacheKey) {
@@ -112,6 +112,7 @@ async function executeSync(parsed) {
         verbose: false,
         projectId: projectResolution.projectId,
         projectIdSource: projectResolution.source,
+        repositoryId: projectResolution.repositoryId,
         projectLookupToken: pickProjectLookupToken(creds),
         pricing: defaultPricing(),
         cursorPricing: cursorPricingForSync(),
@@ -246,6 +247,7 @@ export async function startServer() {
                 verbose: false,
                 projectId: projectResolution.projectId,
                 projectIdSource: projectResolution.source,
+                repositoryId: projectResolution.repositoryId,
                 projectLookupToken: pickProjectLookupToken(creds),
                 pricing: defaultPricing(),
                 scopeDir: process.cwd(),

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/dist/sync.d.ts

@@ -26,6 +26,12 @@ export interface SyncOptions {
     projectIdSource?: ProjectResolution["source"];
     /** Mirrors StoredCredentials.insecureHttpAllowed — set when `init --insecure` was used for this host. */
     allowInsecureHttp?: boolean;
+    /**
+     * Repository resolved from the same remote lookup as the scoped `projectId`.
+     * Only meaningful alongside a pre-resolved scoped `projectId` — carries the
+     * repository attribution the lookup returned so scoped turns don't lose it.
+     */
+    repositoryId?: string | null;
     pricing: PricingTable;
     appDir?: string;
     transcriptBaseDirs?: string[];
@@ -44,6 +50,8 @@ export interface MultiSyncOptions {
     verbose: boolean;
     projectId: string | null;
     projectIdSource?: ProjectResolution["source"];
+    /** See SyncOptions.repositoryId. */
+    repositoryId?: string | null;
     /** Token for GET /projects/lookup (defaults to cursor ingest token in cursor slice). */
     projectLookupToken?: string | null;
     pricing: PricingTable;

package/dist/sync.js

@@ -103,21 +103,24 @@ function explicitProjectId(projectId, projectIdSource) {
         ? projectId
         : undefined;
 }
-async function resolveProjectIdForRepoPathCached(repoPath, host, token, verbose, cache, allowInsecureHttp = false) {
+async function resolveAttributionForRepoPathCached(repoPath, host, token, verbose, cache, allowInsecureHttp = false) {
+    const empty = { projectId: null, repositoryId: null };
     const normalized = normalizeRepoPathCandidate(repoPath);
     if (normalized === null)
-        return null;
+        return empty;
     if (cache.has(normalized))
-        return cache.get(normalized) ?? null;
+        return cache.get(normalized) ?? empty;
     const canonicalRemote = getGitRemoteForPath(normalized, verbose);
     if (!canonicalRemote) {
-        cache.set(normalized, null);
-        return null;
+        cache.set(normalized, empty);
+        return empty;
     }
     const result = await lookupProjectByRemote(canonicalRemote, host, token, verbose, allowInsecureHttp);
-    const projectId = result && typeof result === "object" && "project_id" in result ? result.project_id : null;
-    cache.set(normalized, projectId);
-    return projectId;
+    const resolved = result && typeof result === "object" && "project_id" in result
+        ? { projectId: result.project_id, repositoryId: result.repository_id ?? null }
+        : empty;
+    cache.set(normalized, resolved);
+    return resolved;
 }
 /**
  * The repo path for a Cursor payload, normalized and safe to hand to project
@@ -143,6 +146,7 @@ export function cursorRepoPathFromPayload(payload) {
 }
 async function runClaudeSlice(options) {
     const { token, host, dryRun, verbose, projectId, pricing, allowInsecureHttp = false } = options;
+    const preResolvedRepositoryId = options.repositoryId ?? undefined;
     const appDir = options.appDir ?? getAppDir();
     const backoffKey = credentialStateKey(host, token);
     const errors = [];
@@ -233,14 +237,22 @@ async function runClaudeSlice(options) {
         // (e.g. MCP server launched from a non-git cwd, or stuck null in module cache),
         // fall back to per-turn cwd lookup. The lookup cache dedupes by path so this is
         // effectively one network call per unique cwd per sync.
-        const resolvedProjectId = scopeDir
-            ? (projectId ??
-                (await resolveProjectIdForRepoPathCached(turn.cwd, host, token, verbose, projectLookupCache, allowInsecureHttp)) ??
-                undefined)
-            : (explicitProject ??
-                (await resolveProjectIdForRepoPathCached(turn.cwd, host, token, verbose, projectLookupCache, allowInsecureHttp)) ??
-                undefined);
-        const payloads = mapClaudeTranscriptTurn(turn, { projectId: resolvedProjectId, pricing });
+        // The scoped pre-resolve comes from the same remote lookup as projectId, so it
+        // carries repository_id too. An explicit flag/config projectId carries no
+        // repository context, so repository stays undefined there.
+        const preResolved = scopeDir ? projectId : explicitProject;
+        let resolvedProjectId = preResolved ?? undefined;
+        let resolvedRepositoryId = scopeDir && preResolved != null ? preResolvedRepositoryId : undefined;
+        if (resolvedProjectId === undefined) {
+            const attribution = await resolveAttributionForRepoPathCached(turn.cwd, host, token, verbose, projectLookupCache, allowInsecureHttp);
+            resolvedProjectId = attribution.projectId ?? undefined;
+            resolvedRepositoryId = attribution.repositoryId ?? undefined;
+        }
+        const payloads = mapClaudeTranscriptTurn(turn, {
+            projectId: resolvedProjectId,
+            repositoryId: resolvedRepositoryId,
+            pricing,
+        });
         if (!payloads?.length)
             continue;
         const parentPayload = payloads[0];
@@ -315,6 +327,7 @@ async function runClaudeSlice(options) {
 }
 async function runCursorSlice(params) {
     const { token, host, dryRun, verbose, projectId, projectIdSource, projectLookupToken, allowInsecureHttp = false, appDir, cursorBaseDir, cursorTranscriptProjectDirs, scopeDir, fullScan = false, cursorPricing = resolveCursorPricing(undefined, appDir), } = params;
+    const preResolvedRepositoryId = params.repositoryId ?? undefined;
     const backoffKey = credentialStateKey(host, token);
     // Read state first so we can restore a persisted rate-limit backoff from a prior process.
     const stateBefore = readState(appDir, host, token);
@@ -369,12 +382,26 @@ async function runCursorSlice(params) {
                 if (ws && isRepoPathWithinRoot(ws, scopeDir)) {
                     // Same fallback as Claude: when the pre-resolved projectId is null, do a
                     // per-payload lookup from the payload's workspace. Cache dedupes by path.
-                    const resolved = projectId ??
-                        (await resolveProjectIdForRepoPathCached(ws, host, lookupToken, verbose, projectLookupCache, allowInsecureHttp));
-                    if (resolved)
-                        payload.project_id = resolved;
-                    else
-                        delete payload.project_id;
+                    // The scoped pre-resolve comes from the same remote lookup as projectId,
+                    // so it carries repository_id too; a fresh lookup sets it otherwise.
+                    if (projectId) {
+                        payload.project_id = projectId;
+                        if (preResolvedRepositoryId)
+                            payload.repository_id = preResolvedRepositoryId;
+                        else
+                            delete payload.repository_id;
+                    }
+                    else {
+                        const attribution = await resolveAttributionForRepoPathCached(ws, host, lookupToken, verbose, projectLookupCache, allowInsecureHttp);
+                        if (attribution.projectId)
+                            payload.project_id = attribution.projectId;
+                        else
+                            delete payload.project_id;
+                        if (attribution.repositoryId)
+                            payload.repository_id = attribution.repositoryId;
+                        else
+                            delete payload.repository_id;
+                    }
                     inScope.push(payload);
                 }
                 else if (verbose) {
@@ -390,11 +417,15 @@ async function runCursorSlice(params) {
                 continue;
             for (const payload of group.payloads) {
                 const repoPath = cursorRepoPathFromPayload(payload);
-                const resolvedProjectId = await resolveProjectIdForRepoPathCached(repoPath, host, lookupToken, verbose, projectLookupCache, allowInsecureHttp);
-                if (resolvedProjectId)
-                    payload.project_id = resolvedProjectId;
+                const attribution = await resolveAttributionForRepoPathCached(repoPath, host, lookupToken, verbose, projectLookupCache, allowInsecureHttp);
+                if (attribution.projectId)
+                    payload.project_id = attribution.projectId;
                 else
                     delete payload.project_id;
+                if (attribution.repositoryId)
+                    payload.repository_id = attribution.repositoryId;
+                else
+                    delete payload.repository_id;
             }
         }
     }
@@ -530,7 +561,7 @@ async function runCursorSlice(params) {
                 on429,
                 resolveProjectId: explicitProject
                     ? undefined
-                    : (workspace) => resolveProjectIdForRepoPathCached(workspace, host, lookupToken, verbose, projectLookupCache, allowInsecureHttp),
+                    : (workspace) => resolveAttributionForRepoPathCached(workspace, host, lookupToken, verbose, projectLookupCache, allowInsecureHttp),
                 verbose,
             });
             totalSent += hooksResult.sent;
@@ -578,6 +609,7 @@ export async function syncTelemetryTools(options) {
     }
     try {
         const { credentials, dryRun, verbose, projectId, projectIdSource, projectLookupToken, pricing, scopeDir } = options;
+        const repositoryId = options.repositoryId ?? null;
         const host = credentials.host;
         const appDirResolved = options.appDir ?? getAppDir();
         const cursorPricing = options.cursorPricing ?? resolveCursorPricing(undefined, appDirResolved);
@@ -617,6 +649,7 @@ export async function syncTelemetryTools(options) {
                 verbose,
                 projectId,
                 allowInsecureHttp: credentials.insecureHttpAllowed === true,
+                repositoryId,
                 pricing,
                 appDir,
                 transcriptBaseDirs: options.transcriptBaseDirs,
@@ -632,6 +665,7 @@ export async function syncTelemetryTools(options) {
                 verbose,
                 projectId,
                 projectIdSource,
+                repositoryId,
                 projectLookupToken,
                 allowInsecureHttp: credentials.insecureHttpAllowed === true,
                 appDir,
@@ -699,9 +733,12 @@ export async function syncOnce(options) {
         dryRun: options.dryRun,
         verbose: options.verbose,
         projectId: options.projectId,
+        projectIdSource: options.projectIdSource,
+        repositoryId: options.repositoryId,
         pricing: options.pricing,
         appDir: options.appDir,
         transcriptBaseDirs: options.transcriptBaseDirs,
+        scopeDir: options.scopeDir,
         tools: ["claude_code"],
     });
 }

package/package.json

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