@cleocode/core 2026.4.48 → 2026.4.49

package/dist/telemetry/sqlite.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SQLite store for telemetry.db via drizzle-orm/node-sqlite + node:sqlite.
+ *
+ * Stores opt-in command telemetry in ~/.local/share/cleo/telemetry.db.
+ * Follows the same singleton + WAL + migration pattern as brain-sqlite.ts.
+ * Telemetry is disabled by default — check isTelemetryEnabled() before writing.
+ *
+ * @task T624
+ */
+import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
+import * as telemetrySchema from './schema.js';
+/** Schema version. Single source of truth. */
+export declare const TELEMETRY_SCHEMA_VERSION = "1.0.0";
+/**
+ * Get the absolute path to telemetry.db in the global CLEO home directory.
+ * Linux: ~/.local/share/cleo/telemetry.db
+ */
+export declare function getTelemetryDbPath(): string;
+/**
+ * Resolve the drizzle-telemetry migrations folder.
+ * Handles both src/ (dev via tsx) and dist/ (bundled) layouts.
+ */
+export declare function resolveTelemetryMigrationsFolder(): string;
+/**
+ * Reset the singleton (used in tests).
+ */
+export declare function resetTelemetryDbState(): void;
+/**
+ * Initialize telemetry.db (lazy singleton).
+ * Creates the file and runs migrations on first call.
+ */
+export declare function getTelemetryDb(): Promise<NodeSQLiteDatabase<typeof telemetrySchema>>;
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/telemetry/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/telemetry/sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAKlE,OAAO,KAAK,eAAe,MAAM,aAAa,CAAC;AAK/C,8CAA8C;AAC9C,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAQhD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,IAAI,MAAM,CAQzD;AAgCD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAU5C;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,kBAAkB,CAAC,OAAO,eAAe,CAAC,CAAC,CAmC1F"}

package/migrations/drizzle-telemetry/20260415000001_t624-initial/migration.sql

@@ -0,0 +1,23 @@
+CREATE TABLE IF NOT EXISTS `telemetry_events` (
+	`id` text PRIMARY KEY,
+	`anonymous_id` text NOT NULL,
+	`domain` text NOT NULL,
+	`gateway` text NOT NULL,
+	`operation` text NOT NULL,
+	`command` text NOT NULL,
+	`exit_code` integer NOT NULL DEFAULT 0,
+	`duration_ms` integer NOT NULL,
+	`error_code` text,
+	`timestamp` text NOT NULL DEFAULT (datetime('now'))
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS `telemetry_schema_meta` (
+	`key` text PRIMARY KEY,
+	`value` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_telemetry_command` ON `telemetry_events` (`command`);--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_telemetry_domain` ON `telemetry_events` (`domain`);--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_telemetry_exit_code` ON `telemetry_events` (`exit_code`);--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_telemetry_timestamp` ON `telemetry_events` (`timestamp`);--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_telemetry_duration` ON `telemetry_events` (`duration_ms`);

package/migrations/drizzle-telemetry/20260415000001_t624-initial/snapshot.json

@@ -0,0 +1,35 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "id": "a1b2c3d4-0000-0000-0000-t624telemetry",
+  "prevIds": [
+    "00000000-0000-0000-0000-000000000000"
+  ],
+  "ddl": [
+    {
+      "name": "telemetry_events",
+      "columns": {
+        "id": { "name": "id", "type": "text", "notNull": true, "primaryKey": true },
+        "anonymous_id": { "name": "anonymous_id", "type": "text", "notNull": true },
+        "domain": { "name": "domain", "type": "text", "notNull": true },
+        "gateway": { "name": "gateway", "type": "text", "notNull": true },
+        "operation": { "name": "operation", "type": "text", "notNull": true },
+        "command": { "name": "command", "type": "text", "notNull": true },
+        "exit_code": { "name": "exit_code", "type": "integer", "notNull": true, "default": 0 },
+        "duration_ms": { "name": "duration_ms", "type": "integer", "notNull": true },
+        "error_code": { "name": "error_code", "type": "text", "notNull": false },
+        "timestamp": { "name": "timestamp", "type": "text", "notNull": true }
+      }
+    },
+    {
+      "name": "telemetry_schema_meta",
+      "columns": {
+        "key": { "name": "key", "type": "text", "notNull": true, "primaryKey": true },
+        "value": { "name": "value", "type": "text", "notNull": true }
+      }
+    }
+  ],
+  "indexes": {},
+  "foreignKeys": {},
+  "tables": {}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.4.48",
+  "version": "2026.4.49",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -63,13 +63,13 @@
     "write-file-atomic": "^7.0.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@cleocode/adapters": "2026.4.48",
-    "@cleocode/agents": "2026.4.48",
-    "@cleocode/caamp": "2026.4.48",
-    "@cleocode/contracts": "2026.4.48",
-    "@cleocode/lafs": "2026.4.48",
-    "@cleocode/nexus": "2026.4.48",
-    "@cleocode/skills": "2026.4.48"
+    "@cleocode/adapters": "2026.4.49",
+    "@cleocode/agents": "2026.4.49",
+    "@cleocode/caamp": "2026.4.49",
+    "@cleocode/contracts": "2026.4.49",
+    "@cleocode/lafs": "2026.4.49",
+    "@cleocode/nexus": "2026.4.49",
+    "@cleocode/skills": "2026.4.49"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/__tests__/telemetry.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Tests for the telemetry module (T624 — diagnostic feedback loop).
+ *
+ * Covers:
+ *   - Opt-in / opt-out config management
+ *   - Anonymous ID generation (stable across calls, new on first enable)
+ *   - recordTelemetryEvent is a no-op when disabled
+ *   - buildDiagnosticsReport returns null when disabled
+ *   - buildDiagnosticsReport returns correct aggregates when enabled
+ *
+ * @task T624
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  buildDiagnosticsReport,
+  disableTelemetry,
+  enableTelemetry,
+  isTelemetryEnabled,
+  loadTelemetryConfig,
+  recordTelemetryEvent,
+} from '../telemetry/index.js';
+import { resetTelemetryDbState } from '../telemetry/sqlite.js';
+
+// ---------------------------------------------------------------------------
+// Test setup: redirect CLEO_HOME to a temp directory for isolation
+// ---------------------------------------------------------------------------
+
+let tempDir: string;
+const origCleoHome = process.env['CLEO_HOME'];
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'cleo-telemetry-test-'));
+  process.env['CLEO_HOME'] = tempDir;
+  // Reset the DB singleton so each test starts clean
+  resetTelemetryDbState();
+});
+
+afterEach(async () => {
+  resetTelemetryDbState();
+  await rm(tempDir, { recursive: true, force: true });
+  if (origCleoHome !== undefined) {
+    process.env['CLEO_HOME'] = origCleoHome;
+  } else {
+    delete process.env['CLEO_HOME'];
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Config management
+// ---------------------------------------------------------------------------
+
+describe('loadTelemetryConfig', () => {
+  it('returns disabled config when file does not exist', () => {
+    const config = loadTelemetryConfig();
+    expect(config.enabled).toBe(false);
+    expect(config.anonymousId).toBe('');
+  });
+});
+
+describe('enableTelemetry', () => {
+  it('sets enabled=true and generates a non-empty anonymousId', () => {
+    const config = enableTelemetry();
+    expect(config.enabled).toBe(true);
+    expect(config.anonymousId).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+  });
+
+  it('preserves existing anonymousId on subsequent calls', () => {
+    const first = enableTelemetry();
+    const second = enableTelemetry();
+    expect(second.anonymousId).toBe(first.anonymousId);
+  });
+});
+
+describe('disableTelemetry', () => {
+  it('sets enabled=false', () => {
+    enableTelemetry();
+    const config = disableTelemetry();
+    expect(config.enabled).toBe(false);
+  });
+
+  it('preserves anonymousId after disable', () => {
+    const { anonymousId } = enableTelemetry();
+    const after = disableTelemetry();
+    expect(after.anonymousId).toBe(anonymousId);
+  });
+});
+
+describe('isTelemetryEnabled', () => {
+  it('returns false by default', () => {
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+
+  it('returns true after enable', () => {
+    enableTelemetry();
+    expect(isTelemetryEnabled()).toBe(true);
+  });
+
+  it('returns false after disable', () => {
+    enableTelemetry();
+    disableTelemetry();
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Event recording
+// ---------------------------------------------------------------------------
+
+describe('recordTelemetryEvent', () => {
+  it('is a no-op when telemetry is disabled (no error thrown)', async () => {
+    // Ensure disabled
+    disableTelemetry();
+    await expect(
+      recordTelemetryEvent({
+        domain: 'tasks',
+        gateway: 'query',
+        operation: 'show',
+        durationMs: 42,
+        exitCode: 0,
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('writes an event to the DB when enabled', async () => {
+    enableTelemetry();
+    await recordTelemetryEvent({
+      domain: 'tasks',
+      gateway: 'mutate',
+      operation: 'add',
+      durationMs: 100,
+      exitCode: 0,
+    });
+    // Verify by building a report
+    const report = await buildDiagnosticsReport(1);
+    expect(report).not.toBeNull();
+    expect(report!.totalEvents).toBeGreaterThanOrEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Diagnostics report
+// ---------------------------------------------------------------------------
+
+describe('buildDiagnosticsReport', () => {
+  it('returns null when telemetry is disabled', async () => {
+    disableTelemetry();
+    const report = await buildDiagnosticsReport(30);
+    expect(report).toBeNull();
+  });
+
+  it('returns a report with zero events when DB is empty', async () => {
+    enableTelemetry();
+    const report = await buildDiagnosticsReport(30);
+    expect(report).not.toBeNull();
+    expect(report!.totalEvents).toBe(0);
+    expect(report!.topFailing).toHaveLength(0);
+    expect(report!.topSlow).toHaveLength(0);
+  });
+
+  it('surfaces high-failure-rate commands in topFailing', async () => {
+    enableTelemetry();
+
+    // Record 10 failures and 2 successes for tasks.add
+    for (let i = 0; i < 10; i++) {
+      await recordTelemetryEvent({
+        domain: 'tasks',
+        gateway: 'mutate',
+        operation: 'add',
+        durationMs: 50,
+        exitCode: 6,
+        errorCode: 'E_VALIDATION',
+      });
+    }
+    for (let i = 0; i < 2; i++) {
+      await recordTelemetryEvent({
+        domain: 'tasks',
+        gateway: 'mutate',
+        operation: 'add',
+        durationMs: 50,
+        exitCode: 0,
+      });
+    }
+
+    const report = await buildDiagnosticsReport(1);
+    expect(report).not.toBeNull();
+    const failing = report!.topFailing.find((c) => c.command === 'tasks.add');
+    expect(failing).toBeDefined();
+    expect(failing!.failureCount).toBe(10);
+    expect(failing!.failureRate).toBeCloseTo(10 / 12);
+    expect(failing!.topErrorCode).toBe('E_VALIDATION');
+  });
+
+  it('generates BRAIN observation text for failing commands', async () => {
+    enableTelemetry();
+
+    // Need at least 5 invocations to appear in topFailing
+    for (let i = 0; i < 8; i++) {
+      await recordTelemetryEvent({
+        domain: 'session',
+        gateway: 'mutate',
+        operation: 'start',
+        durationMs: 200,
+        exitCode: i < 7 ? 1 : 0,
+        errorCode: i < 7 ? 'E_GENERAL' : null,
+      });
+    }
+
+    const report = await buildDiagnosticsReport(1);
+    expect(report).not.toBeNull();
+    expect(report!.observations.length).toBeGreaterThan(0);
+    const obs = report!.observations[0]!;
+    expect(obs).toContain('session.start');
+    expect(obs).toContain('%');
+  });
+});

package/src/index.ts

@@ -72,6 +72,7 @@ export * as sticky from './sticky/index.js';
 export * as system from './system/index.js';
 export * as taskWork from './task-work/index.js';
 export * as tasks from './tasks/index.js';
+export * as telemetry from './telemetry/index.js';
 export * as templates from './templates/index.js';
 export * as ui from './ui/index.js';
 export * as validation from './validation/index.js';

package/src/internal.ts

@@ -291,7 +291,7 @@ export {
 export { searchAcrossProjects } from './nexus/discover.js';
 export { setPermission } from './nexus/permissions.js';
 export { resolveTask, validateSyntax } from './nexus/query.js';
-export type { NexusPermissionLevel } from './nexus/registry.js';
+export type { NexusPermissionLevel, NexusProject, NexusProjectStats } from './nexus/registry.js';
 export {
   nexusGetProject,
   nexusInit,
@@ -301,6 +301,7 @@ export {
   nexusSync,
   nexusSyncAll,
   nexusUnregister,
+  nexusUpdateIndexStats,
 } from './nexus/registry.js';
 export { getSharingStatus } from './nexus/sharing/index.js';
 // Context
@@ -625,6 +626,24 @@ export {
   coreTaskTree,
   coreTaskUnarchive,
 } from './tasks/task-ops.js';
+// Self-improvement telemetry (T624)
+export type {
+  CommandStats as TelemetryCommandStats,
+  DiagnosticsReport as TelemetryDiagnosticsReport,
+  TelemetryConfig,
+  TelemetryEvent,
+} from './telemetry/index.js';
+export {
+  buildDiagnosticsReport,
+  disableTelemetry,
+  enableTelemetry,
+  exportTelemetryEvents,
+  getTelemetryConfigPath,
+  getTelemetryDbPath,
+  isTelemetryEnabled,
+  loadTelemetryConfig,
+  recordTelemetryEvent,
+} from './telemetry/index.js';
 export type { IssueTemplate, TemplateConfig, TemplateSection } from './templates/parser.js';
 // Templates
 export {

package/src/nexus/index.ts

@@ -74,6 +74,7 @@ export {
   type NexusPermissionLevel,
   // Types
   type NexusProject,
+  type NexusProjectStats,
   type NexusRegistryFile,
   nexusGetProject,
   nexusInit,
@@ -85,6 +86,7 @@ export {
   nexusSync,
   nexusSyncAll,
   nexusUnregister,
+  nexusUpdateIndexStats,
   // Operations
   readRegistry,
   readRegistryRequired,

package/src/nexus/registry.ts

@@ -13,7 +13,7 @@
 
 import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
 import { getLogger } from '../logger.js';
@@ -36,6 +36,13 @@ export type NexusPermissionLevel = 'read' | 'write' | 'execute';
 
 export type NexusHealthStatus = 'unknown' | 'healthy' | 'degraded' | 'unreachable';
 
+/** Per-project code intelligence statistics stored in stats_json. */
+export interface NexusProjectStats {
+  nodeCount: number;
+  relationCount: number;
+  fileCount: number;
+}
+
 /** Domain representation of a registered Nexus project. */
 export interface NexusProject {
   hash: string;
@@ -50,6 +57,14 @@ export interface NexusProject {
   lastSync: string;
   taskCount: number;
   labels: string[];
+  /** Absolute path to the project's brain.db. Null if not yet populated. */
+  brainDbPath: string | null;
+  /** Absolute path to the project's tasks.db. Null if not yet populated. */
+  tasksDbPath: string | null;
+  /** ISO 8601 timestamp of the last code intelligence index run. Null if never indexed. */
+  lastIndexed: string | null;
+  /** Code intelligence stats from the last index run. */
+  stats: NexusProjectStats;
 }
 
 /** Legacy registry file shape (pre-SQLite). Retained for migration compatibility. */
@@ -90,6 +105,17 @@ function rowToProject(row: ProjectRegistryRow): NexusProject {
   } catch {
     labels = [];
   }
+  let stats: NexusProjectStats = { nodeCount: 0, relationCount: 0, fileCount: 0 };
+  try {
+    const parsed = JSON.parse(row.statsJson ?? '{}') as Partial<NexusProjectStats>;
+    stats = {
+      nodeCount: parsed.nodeCount ?? 0,
+      relationCount: parsed.relationCount ?? 0,
+      fileCount: parsed.fileCount ?? 0,
+    };
+  } catch {
+    stats = { nodeCount: 0, relationCount: 0, fileCount: 0 };
+  }
   return {
     hash: row.projectHash,
     projectId: row.projectId,
@@ -103,6 +129,10 @@ function rowToProject(row: ProjectRegistryRow): NexusProject {
     lastSync: row.lastSync,
     taskCount: row.taskCount,
     labels,
+    brainDbPath: row.brainDbPath ?? null,
+    tasksDbPath: row.tasksDbPath ?? null,
+    lastIndexed: row.lastIndexed ?? null,
+    stats,
   };
 }
 
@@ -328,6 +358,9 @@ export async function nexusRegister(
   const meta = await readProjectMeta(projectPath);
   const now = new Date().toISOString();
   let projectId = await readProjectId(projectPath);
+  const resolvedPath = resolve(projectPath);
+  const brainDbPath = join(resolvedPath, '.cleo', 'brain.db');
+  const tasksDbPath = join(resolvedPath, '.cleo', 'tasks.db');
 
   if (existing) {
     // Merge nexus fields into existing entry
@@ -339,6 +372,8 @@ export async function nexusRegister(
         taskCount: meta.taskCount,
         labelsJson: JSON.stringify(meta.labels),
         lastSeen: now,
+        brainDbPath,
+        tasksDbPath,
       })
       .where(eq(projectRegistry.projectHash, projectHash));
   } else {
@@ -361,6 +396,9 @@ export async function nexusRegister(
       lastSync: now,
       taskCount: meta.taskCount,
       labelsJson: JSON.stringify(meta.labels),
+      brainDbPath,
+      tasksDbPath,
+      statsJson: '{}',
     });
   }
 
@@ -527,6 +565,70 @@ export async function nexusSyncAll(): Promise<{ synced: number; failed: number }
   return { synced, failed };
 }
 
+/**
+ * Update code intelligence index stats for a registered project.
+ *
+ * Called after a successful `cleo nexus analyze` run to record the
+ * latest node/relation/file counts and the indexed timestamp.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param stats       - Results from the pipeline run.
+ * @task T622
+ */
+export async function nexusUpdateIndexStats(
+  projectPath: string,
+  stats: NexusProjectStats,
+): Promise<void> {
+  if (!projectPath) return;
+
+  const projectHash = generateProjectHash(projectPath);
+  const now = new Date().toISOString();
+
+  try {
+    const { getNexusDb } = await import('../store/nexus-sqlite.js');
+    const { eq } = await import('drizzle-orm');
+    const db = await getNexusDb();
+
+    const rows = await db
+      .select()
+      .from(projectRegistry)
+      .where(eq(projectRegistry.projectHash, projectHash));
+
+    if (rows.length === 0) {
+      // Not yet registered — auto-register first (best effort)
+      try {
+        await nexusRegister(projectPath);
+      } catch {
+        // Already registered or cannot register — ignore
+      }
+    }
+
+    await db
+      .update(projectRegistry)
+      .set({
+        lastIndexed: now,
+        statsJson: JSON.stringify(stats),
+        lastSeen: now,
+      })
+      .where(eq(projectRegistry.projectHash, projectHash));
+
+    await writeNexusAudit({
+      action: 'update-index-stats',
+      projectHash,
+      operation: 'update-index-stats',
+      success: true,
+      details: {
+        nodeCount: stats.nodeCount,
+        relationCount: stats.relationCount,
+        fileCount: stats.fileCount,
+      },
+    });
+  } catch (err) {
+    // Non-fatal — index stats update must never break the analyze pipeline
+    getLogger('nexus').warn({ err }, 'nexus: failed to update index stats');
+  }
+}
+
 /**
  * Update a project's permission level in the registry.
  * Used by permissions.ts to avoid direct JSON file writes.

package/src/store/nexus-schema.ts

@@ -31,11 +31,20 @@ export const projectRegistry = sqliteTable(
     lastSync: text('last_sync').notNull().default(sql`(datetime('now'))`),
     taskCount: integer('task_count').notNull().default(0),
     labelsJson: text('labels_json').notNull().default('[]'),
+    /** Absolute path to the project's brain.db file. */
+    brainDbPath: text('brain_db_path'),
+    /** Absolute path to the project's tasks.db file. */
+    tasksDbPath: text('tasks_db_path'),
+    /** ISO 8601 timestamp of the last successful code intelligence index run. */
+    lastIndexed: text('last_indexed'),
+    /** JSON object with per-project code intelligence stats (node_count, relation_count, file_count). */
+    statsJson: text('stats_json').notNull().default('{}'),
   },
   (table) => [
     index('idx_project_registry_hash').on(table.projectHash),
     index('idx_project_registry_health').on(table.healthStatus),
     index('idx_project_registry_name').on(table.name),
+    index('idx_project_registry_last_indexed').on(table.lastIndexed),
   ],
 );