@bahulam/code 2.6.15 → 2.6.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "2.6.15",
+  "version": "2.6.17",
   "description": "Bahulam Code \u2014 abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   ],
   "scripts": {
     "start": "node src/terminal/main.mjs",
-    "test": "BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-backend-url.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-agent-history.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-sse-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-tool-executor.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-project-artifacts.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-work-scope.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-skills.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-callback.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-rate-limit-display.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-preflight.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-formatter.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-terminal-rendering.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-input-dock.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-live-steering-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-slash-commands.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval-log.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-kepler-contract.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-session-manager.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-safety.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-jsonl-writer.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-analytics.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-stagnation.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-attachments.mjs"
+    "test": "BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-backend-url.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-agent-history.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-sse-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-tool-executor.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-project-artifacts.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-work-scope.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-skills.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-callback.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-rate-limit-display.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-preflight.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-formatter.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-terminal-rendering.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-render-queue.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-input-dock.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-live-steering-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-slash-commands.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval-log.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-kepler-contract.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-session-manager.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-safety.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-jsonl-writer.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-analytics.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-stagnation.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-attachments.mjs"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -49,8 +49,8 @@
     "web-tree-sitter": "^0.26.9"
   },
   "optionalDependencies": {
-    "@bahulam/runtime-darwin-arm64": "2.6.15",
-    "@bahulam/runtime-linux-x64": "2.6.15",
-    "@bahulam/runtime-win32-x64": "2.6.15"
+    "@bahulam/runtime-darwin-arm64": "2.6.17",
+    "@bahulam/runtime-linux-x64": "2.6.17",
+    "@bahulam/runtime-win32-x64": "2.6.17"
   }
 }

package/src/auth/tarang-auth.mjs

@@ -76,6 +76,12 @@ export class TarangAuth {
             models: this._config.models || {},
             configuredProviders: this._config.configured_providers || [],
             gatewayConfig: this._config.gateway_config || {},
+            // PRD-076 W7: persisted /model picks. `modelConfig` mirrors the
+            // Python-side key read_local_model_config() looks for; keep the
+            // snake_case JSON key so the runtime picks it up unchanged.
+            modelConfig: this._config.model_config || {},
+            modelMode: this._config.model_mode || null,
+            routePreference: this._config.route_preference || null,
         };
     }
 

package/src/config/cli-args.mjs

@@ -29,6 +29,7 @@ export function parseArgs(args) {
         timeout: null,
         allowedTools: null,
         disallowedTools: null,
+        route: null,
         resume: false,
         resumeSessionId: null,
         headless: false,
@@ -49,6 +50,10 @@ export function parseArgs(args) {
                 result.model = args[++i];
                 break;
 
+            case '--route':
+                result.route = args[++i];
+                break;
+
             case '--permission-mode':
                 result.permissionMode = args[++i];
                 break;
@@ -169,7 +174,8 @@ export function getUsageText() {
 Usage: occ [options] [prompt]
 
 Options:
-  --model, -m <model>        Model to use (default: claude-sonnet-4-6)
+  --model, -m <id|role=id>   Session model override (also named modes: fast|thinking|extra|max)
+  --route <platform|byok>    Model route; platform validates against the curated catalog
   --permission-mode <mode>   Permission mode (bypassPermissions, acceptEdits, plan, auto, dontAsk)
   --print, -p <prompt>       Non-interactive mode: run prompt and exit
   --output-format <fmt>      Output format: text, json, stream-json

package/src/config/model-catalog.mjs

@@ -0,0 +1,57 @@
+/**
+ * Shipped model catalog snapshot — Node side of PRD-076 W7.
+ *
+ * The canonical source is `codekepler-backend/app/services/
+ * model_catalog_snapshot.json` (admin dashboard edits it and publishes to
+ * Supabase). `stage-runtime-app.sh` copies that file into every runtime
+ * wheel at `runtime/app/services/model_catalog_snapshot.json`, so when
+ * `@bahulam/runtime-<platform>-<arch>` is installed as a sibling optional
+ * dep of `@bahulam/code`, the file is already on disk — we read from
+ * there instead of maintaining a third copy in the CLI package.
+ */
+
+import * as fs from 'node:fs';
+import { runtimeSnapshotPath } from '../core/bundled-runtime.mjs';
+
+let _cache = null;
+
+// Snapshot rows are camelCase (matches how the backend delivers the
+// static file); the /api/models response is snake_case. Normalize once
+// here so downstream consumers can treat both sources identically.
+function normalizeSnapshotRow(row) {
+  const id = row.value || row.id;
+  if (!id) return null;
+  return {
+    id,
+    provider: row.provider || (id.includes('/') ? id.split('/', 1)[0] : 'unknown'),
+    label: row.label || id,
+    input_cost_usd_per_m: row.inputCost ?? row.input_cost_usd_per_m ?? null,
+    output_cost_usd_per_m: row.outputCost ?? row.output_cost_usd_per_m ?? null,
+    context_length: row.context ?? row.context_length ?? null,
+    max_output: row.maxOutput ?? row.max_output ?? null,
+    supports_tools: row.supportsTools ?? row.supports_tools ?? false,
+    supports_reasoning: row.supportsReasoning ?? row.supports_reasoning ?? false,
+    harness_validated: row.harnessValidated ?? row.harness_validated ?? false,
+    cache_profile: row.cacheProfile ?? row.cache_profile ?? null,
+    platform_access_tier: row.platformAccessTier ?? row.platform_access_tier ?? [],
+  };
+}
+
+/**
+ * Read the shipped catalog snapshot from the installed runtime bundle.
+ * Returns an array of normalized rows (API-shape) or null if the runtime
+ * isn't installed / the file is unreadable. Cached after first success.
+ */
+export function readShippedCatalog() {
+  if (_cache !== null) return _cache;
+  try {
+    const raw = fs.readFileSync(runtimeSnapshotPath(), 'utf-8');
+    const data = JSON.parse(raw);
+    const rows = Array.isArray(data?.models) ? data.models : [];
+    _cache = rows.map(normalizeSnapshotRow).filter(Boolean);
+    return _cache;
+  } catch {
+    _cache = null;
+    return null;
+  }
+}

package/src/core/bundled-runtime.mjs

@@ -364,6 +364,18 @@ export function isRuntimeInstalled() {
   return fs.existsSync(_runtimeBin());
 }
 
+/**
+ * Absolute path to the shipped model catalog snapshot inside the runtime
+ * bundle. Backend edits `app/services/model_catalog_snapshot.json` as the
+ * canonical source (admin dashboard publishes it to Supabase);
+ * stage-runtime-app.sh copies that same file into every runtime wheel at
+ * `runtime/app/services/model_catalog_snapshot.json`. The CLI reads from
+ * there so there is no third copy to keep in sync.
+ */
+export function runtimeSnapshotPath() {
+  return path.join(_runtimeRoot(), 'runtime', 'app', 'services', 'model_catalog_snapshot.json');
+}
+
 /** Diagnostic snapshot for `bahulam doctor`. */
 export function runtimeInfo() {
   return {

package/src/core/error-guidance.mjs

@@ -251,12 +251,16 @@ export function formatAgentErrorGuidance(data = {}) {
     lines.push('Upgrade your plan for a larger 5-hour message window, or switch to BYOK if available.');
     if (pricingUrl) lines.push(`Open ${pricingUrl} to upgrade.`);
   } else if (phase === 'gateway' || code.includes('gateway')) {
-    const label = providerGuidance?.label || 'provider';
-    lines.push(`The ${label} gateway failed before the agent could respond.`);
-    if (providerGuidance) {
+    // Generic first: on the platform route the user has NO provider key —
+    // telling them to "check your DeepSeek API key" is wrong and alarming.
+    // Provider-key guidance only applies when we know the route is BYOK.
+    const label = providerGuidance?.label || compact(data.provider) || 'model provider';
+    lines.push(`The upstream ${label} request failed before the agent could respond — usually a transient provider-side error.`);
+    lines.push('Retry the turn. If it persists, switch models with /model and try again.');
+    if (compact(data.route) === 'byok' && providerGuidance) {
       lines.push(...providerGuidance.lines);
     } else {
-      lines.push('Check the selected provider, model, and BYOK credentials in settings, then retry.');
+      lines.push('Using your own key (BYOK)? Verify it is saved and active in settings, then run /login so provider settings sync.');
     }
   } else if (/authentication|token/i.test(message)) {
     lines.push('Run /login to re-authenticate.');

package/src/core/local-agent.mjs

@@ -21,11 +21,11 @@ const MAX_ITERATIONS = 50;
 const TOOL_SCHEMAS = [
     {
         name: 'shell',
-        description: 'Run one non-interactive shell command and return stdout/stderr. Do not use command substitution, backticks, or $(); run separate simple shell calls instead.',
+        description: 'Run one non-interactive shell command and return stdout/stderr. Command substitution (backticks, $()) is allowed but triggers a user-approval prompt; prefer plain commands when equivalent.',
         input_schema: {
             type: 'object',
             properties: {
-                command: { type: 'string', description: 'The command to execute. Avoid backticks and $(); split dependent checks into separate commands.' },
+                command: { type: 'string', description: 'The command to execute. Backticks/$() are allowed (user approval required); use them when splitting would be awkward.' },
                 timeout: { type: 'number', description: 'Timeout in milliseconds (default: 120000)' },
             },
             required: ['command'],
@@ -478,7 +478,7 @@ export class LocalAgent {
             'You are Bahulam Code, Bahulam\'s AI coding agent running in local mode.',
             'You have access to tools for reading, writing, and executing code.',
             'Use tools to accomplish the user\'s request. Be concise and direct.',
-            'For shell tools, never use command substitution, backticks, or $(). Run separate simple commands and carry values forward in text.',
+            'Shell command substitution (backticks, $()) is allowed but requires user approval — use it when it is the natural expression; otherwise prefer plain commands.',
         ];
         if (context.cwd) parts.push(`Working directory: ${context.cwd}`);
         if (context.gitBranch) parts.push(`Git branch: ${context.gitBranch}`);

package/src/index.mjs

@@ -35,7 +35,7 @@ import { printBanner, printProjectInfo, printHints, printAuthStatus, printStyled
 import { ContextRetriever } from './context/retriever.mjs';
 import { loadSettings } from './config/settings.mjs';
 
-const VERSION = '2.6.15';
+const VERSION = '2.6.17';
 
 // ── Arg Parsing (consolidated from index.mjs + cli-args.mjs) ──
 
@@ -50,6 +50,7 @@ function parseArgs(argv) {
         // Config subcommand flags
         showConfig: false, openRouterKey: null, anthropicKey: null,
         backendUrl: null, mode: null,
+        model: null, route: null,
         // Extended flags (from cli-args.mjs)
         permissionMode: null,
         outputFormat: null,
@@ -96,7 +97,8 @@ function parseArgs(argv) {
             case '--google-key': args.googleKey = argv[++i]; break;
             case '--gateway': args.gateway = argv[++i]; break;
             // --backend-url removed: use TARANG_ENV
-            // --model removed: use tarang configure (web settings)
+            case '--model': case '-m': args.model = argv[++i]; break;
+            case '--route': args.route = argv[++i]; break;
             // Extended flags
             case '--permission-mode': args.permissionMode = argv[++i]; break;
             case '--print': case '-p': case '--instruction': case '--input': args.instruction = argv[++i]; break;
@@ -175,9 +177,11 @@ function printUsage() {
     process.stderr.write(`  ${D}(default: auto-select based on task complexity)${R}\n`);
     process.stderr.write('\n');
     process.stderr.write(`${B}MODEL FLAGS${R}\n`);
+    process.stderr.write(`  ${G}--model, -m <id|role=id>${R}     Session model override ${D}(also: fast|thinking|extra|max)${R}\n`);
+    process.stderr.write(`  ${G}--route <platform|byok>${R}      Model route ${D}(platform validates against curated catalog)${R}\n`);
     process.stderr.write(`  ${G}--system-prompt <text>${R}       Override system prompt\n`);
     process.stderr.write(`  ${G}--max-turns <n>${R}              Maximum conversation turns\n`);
-    process.stderr.write(`  ${D}Models are configured via: bahulam configure${R}\n`);
+    process.stderr.write(`  ${D}Persistent defaults are configured via: bahulam configure${R}\n`);
     process.stderr.write('\n');
     process.stderr.write(`${B}PERMISSION FLAGS${R}\n`);
     process.stderr.write(`  ${G}--yes, -y${R}                    Auto-approve all operations\n`);

package/src/permissions/command-classifier.mjs

@@ -132,6 +132,32 @@ function containsUnquotedExpansion(command) {
 /**
  * Detect command substitution patterns.
  */
+/**
+ * Extract the inner text of every `$( … )` (nesting-aware) and
+ * `` ` … ` `` region so each body can be classified on its own.
+ */
+function extractSubstitutionBodies(command) {
+    const bodies = [];
+    const s = String(command || '');
+    for (const m of s.match(/`([^`]*)`/g) || []) {
+        bodies.push(m.slice(1, -1));
+    }
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '$' && s[i + 1] === '(') {
+            let depth = 1;
+            let j = i + 2;
+            while (j < s.length && depth > 0) {
+                if (s[j] === '(') depth++;
+                else if (s[j] === ')') depth--;
+                j++;
+            }
+            bodies.push(s.slice(i + 2, depth === 0 ? j - 1 : j));
+            i = j - 1;
+        }
+    }
+    return bodies.map(b => b.trim()).filter(Boolean);
+}
+
 function containsCommandSubstitution(command) {
     // Backticks
     if (/`/.test(command)) return true;
@@ -505,9 +531,31 @@ export function classifyCommand(command) {
         }
     }
 
-    // ── Step 2: Check for command substitution / injection ──
+    // ── Step 2: Command substitution → approval-gated, not hard-blocked ──
+    // Backticks / $() are legitimate shell (lsof -ti:8000 | xargs kill,
+    // $(git rev-parse HEAD), etc). Hard-blocking them forced the model
+    // into awkward multi-step workarounds even after the user approved.
+    // The substitution BODY is classified recursively — `echo $(rm -rf /)`
+    // stays hard-blocked because the inner command is; a benign body
+    // surfaces as an explicit HITL approval (contained + highRisk), same
+    // as process cleanup above. (Step 1's whole-string regexes alone are
+    // not enough: `rm -rf /` inside $() terminates with `)` which the
+    // \s|$ terminators never match.)
     if (containsCommandSubstitution(trimmed)) {
-        return { classification: 'blocked', reason: 'Contains command substitution (backticks or $())' };
+        for (const inner of extractSubstitutionBodies(trimmed)) {
+            const innerResult = classifyCommand(inner);
+            if (innerResult.classification === 'blocked') {
+                return {
+                    classification: 'blocked',
+                    reason: `Substitution body is blocked: ${inner.slice(0, 50)}`,
+                };
+            }
+        }
+        return {
+            classification: 'contained',
+            reason: 'Uses command substitution (backticks or $()); requires approval',
+            highRisk: true,
+        };
     }
 
     if (containsUnsafeOutputRedirection(trimmed)) {

package/src/telemetry/index.mjs

@@ -1,96 +1,122 @@
 /**
- * Telemetry Stub — basic telemetry interface (no actual reporting).
+ * Telemetry — Funnel event emitter (PRD-076 W3).
  *
- * Logs events to debug output when CLAUDE_CODE_DEBUG is set.
- * Designed to be a drop-in interface for the full telemetry system.
+ * Buffers funnel events and flushes to {backend}/api/telemetry/funnel
+ * on a timer and on process exit. Device ID is generated once per install
+ * for anon-to-logged-in correlation.
+ *
+ * Opt-out: BAHULAM_DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_TELEMETRY=1
  */
 
-const events = [];
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { bahulamHome } from '../core/paths.mjs';
+
+const BUF_LIMIT = 500;
+const FLUSH_INTERVAL_MS = 30_000;
+
+let events = [];
 let enabled = true;
+let flushTimer = null;
+let _backendUrl = null;
+let _token = null;
+let _deviceId = null;
 
-/**
- * Track a telemetry event.
- * @param {string} event - event name
- * @param {object} [properties] - event properties
- */
-export function track(event, properties = {}) {
-    if (!enabled) return;
-    if (process.env.CLAUDE_CODE_DISABLE_TELEMETRY === '1') return;
+/* ── Configuration ── */
 
-    const entry = {
-        event,
-        properties,
-        timestamp: Date.now(),
-    };
+export function disable() {
+  enabled = false;
+  if (flushTimer) { clearInterval(flushTimer); flushTimer = null; }
+}
 
-    events.push(entry);
+export function configure(backendUrl, token) {
+  _backendUrl = backendUrl;
+  _token = token;
+}
 
-    // Keep max 1000 events in memory
-    if (events.length > 1000) {
-        events.splice(0, events.length - 1000);
-    }
+/* ── Device ID ── */
 
-    if (process.env.CLAUDE_CODE_DEBUG) {
-        console.error(`[telemetry] ${event}`, JSON.stringify(properties).slice(0, 200));
+function readOrCreateDeviceId() {
+  const dir = bahulamHome();
+  const idPath = path.join(dir, 'device_id');
+  try {
+    if (fs.existsSync(idPath)) {
+      return fs.readFileSync(idPath, 'utf-8').trim();
     }
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const id = crypto.randomUUID();
+    fs.writeFileSync(idPath, id, { mode: 0o600 });
+    return id;
+  } catch { return 'unknown'; }
+}
+
+export function getDeviceId() {
+  if (!_deviceId) _deviceId = readOrCreateDeviceId();
+  return _deviceId;
+}
+
+/* ── Tracking ── */
+
+export function track(event, properties = {}) {
+  if (!enabled) return;
+  if (process.env.BAHULAM_DISABLE_TELEMETRY === '1') return;
+  if (process.env.CLAUDE_CODE_DISABLE_TELEMETRY === '1') return;
+
+  const entry = { event, properties: { ...properties }, device_id: getDeviceId(), timestamp: Date.now() };
+  events.push(entry);
+  if (events.length > BUF_LIMIT) events.splice(0, events.length - BUF_LIMIT);
+
+  if (process.env.BAHULAM_DEBUG_TELEMETRY) {
+    process.stderr.write(`[telemetry] ${event} ${JSON.stringify(properties).slice(0, 200)}\n`);
+  }
+
+  if (!flushTimer) {
+    flushTimer = setInterval(flush, FLUSH_INTERVAL_MS);
+    flushTimer.unref();
+  }
 }
 
-/**
- * Track a timing event.
- * @param {string} event - event name
- * @param {number} durationMs - duration in milliseconds
- * @param {object} [properties] - additional properties
- */
 export function trackTiming(event, durationMs, properties = {}) {
-    track(event, { ...properties, durationMs });
+  track(event, { ...properties, durationMs });
 }
 
-/**
- * Track an error.
- * @param {string} event - error context
- * @param {Error} error - the error
- */
 export function trackError(event, error) {
-    track(`error.${event}`, {
-        message: error.message,
-        stack: error.stack?.split('\n').slice(0, 3).join('\n'),
-    });
+  track(`error.${event}`, { message: error.message, stack: error.stack?.split('\n').slice(0, 3).join('\n') });
 }
 
-/**
- * Get collected events (for debugging).
- * @returns {Array}
- */
-export function getEvents() {
-    return [...events];
-}
+/* ── Transport ── */
 
-/**
- * Clear collected events.
- */
-export function clear() {
-    events.length = 0;
+export async function flush() {
+  if (!enabled || events.length === 0 || !_backendUrl) return;
+  const batch = events.splice(0);
+  const headers = { 'Content-Type': 'application/json' };
+  if (_token) headers['Authorization'] = `Bearer ${_token}`;
+  try {
+    const resp = await fetch(`${_backendUrl}/api/telemetry/funnel`, {
+      method: 'POST', headers,
+      body: JSON.stringify({
+        events: batch,
+        user_id: _token ? undefined : undefined, // backend derives from token if present
+        source: 'cli',
+      }),
+    });
+    if (!resp.ok && resp.status >= 500) events.unshift(...batch);
+  } catch { events.unshift(...batch); if (events.length > BUF_LIMIT * 2) events.splice(0, events.length - BUF_LIMIT); }
 }
 
-/**
- * Enable or disable telemetry.
- * @param {boolean} value
- */
-export function setEnabled(value) {
-    enabled = value;
+export async function shutdown() {
+  if (flushTimer) { clearInterval(flushTimer); flushTimer = null; }
+  await flush();
 }
 
-/**
- * Get telemetry stats.
- */
+/* ── Debug ── */
+
+export function getEvents() { return [...events]; }
+export function clear() { events.length = 0; }
+export function setEnabled(value) { enabled = value; }
 export function getStats() {
-    const counts = {};
-    for (const e of events) {
-        counts[e.event] = (counts[e.event] || 0) + 1;
-    }
-    return {
-        totalEvents: events.length,
-        enabled,
-        eventCounts: counts,
-    };
-}
+  const counts = {};
+  for (const e of events) counts[e.event] = (counts[e.event] || 0) + 1;
+  return { totalEvents: events.length, enabled, eventCounts: counts };
+}

package/src/terminal/main.mjs

@@ -4,6 +4,8 @@
  * Zero React. Zero Ink. Zero flickering.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { startTerminalRepl } from './repl.mjs';
 import {
   runSessionsCommand,
@@ -11,6 +13,9 @@ import {
   runHistoryCommand,
 } from './analytics.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
+import * as telemetry from '../telemetry/index.mjs';
+import { bahulamHome } from '../core/paths.mjs';
+import { TarangAuth as Auth } from '../auth/tarang-auth.mjs';
 
 // ── Subcommands ──
 
@@ -83,7 +88,40 @@ function parseKeplerSubcommandArgs(command, argv) {
   return parsed;
 }
 
+function detectInstallFirstRun() {
+  const markerPath = path.join(bahulamHome(), '.install_marker');
+  try {
+    if (fs.existsSync(markerPath)) return false;
+    fs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });
+    return true;
+  } catch { return false; }
+}
+
 async function main() {
+  // ── Telemetry bootstrap ──
+  const _auth = new Auth();
+  const _creds = _auth.loadCredentials();
+  telemetry.configure(_creds.backendUrl, _creds.token);
+
+  // Fire install_first_run on first ever CLI invocation
+  if (detectInstallFirstRun()) {
+    telemetry.track('install_first_run', { version: process.env.npm_package_version || '' });
+  }
+
+  // Check day7_return — fire once per install
+  const configDir_ = bahulamHome();
+  const installMarker_ = path.join(configDir_, '.install_marker');
+  const returnFiredPath_ = path.join(configDir_, '.return_fired');
+  try {
+    if (fs.existsSync(installMarker_) && !fs.existsSync(returnFiredPath_)) {
+      const installTime = parseInt(fs.readFileSync(installMarker_, 'utf-8').trim(), 10);
+      if (!isNaN(installTime) && Date.now() - installTime >= 7 * 24 * 60 * 60 * 1000) {
+        telemetry.track('day7_return', {});
+        fs.writeFileSync(returnFiredPath_, '1', { mode: 0o600 });
+      }
+    }
+  } catch {}
+
   if (subcommand === 'dashboard') {
     // Launch Bahulam Pulse Next.js dashboard
     const { spawn } = await import('node:child_process');
@@ -134,7 +172,9 @@ async function main() {
     const { TarangAuth } = await import('../auth/tarang-auth.mjs');
     const auth = new TarangAuth();
     try {
+      telemetry.track('login_shown', { method: 'cli_subcommand' });
       await auth.login();
+      telemetry.track('login_completed', { method: 'cli_subcommand' });
       process.stderr.write('\x1b[32m✓ Login successful!\x1b[0m\n');
       return;
     } catch (err) {