@geraldmaron/construct 1.0.3 → 1.0.4

package/lib/read-tracker-store.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/hooks/read-tracker-store.mjs — batched persistence for read-efficiency tracking.
+ *
+ * The Read hook runs in a fresh process for every file read. Persisting the
+ * full session-efficiency store on every invocation is correct but noisy and
+ * expensive. This module appends compact JSONL deltas per read, then folds
+ * them into the durable session summary when the delta log is flushed.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
+const REPEATED_READ_WARNING_THRESHOLD = 5;
+const REPEATED_READ_TIER2_THRESHOLD = 8;
+const LARGE_READ_WARNING_THRESHOLD = 3;
+const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
+const FILES_LRU_CAP = 200;
+const EFFICIENCY_LARGE_READ_LIMIT = 400;
+
+export function readTrackerPaths(env = process.env) {
+  const home = env.CX_HOME_OVERRIDE || env.HOME || homedir();
+  const cxDir = join(home, '.cx');
+  return {
+    cxDir,
+    efficiencyStore: join(cxDir, 'session-efficiency.json'),
+    deltaLog: join(cxDir, 'session-efficiency.reads.jsonl'),
+    warnFlags: join(cxDir, 'warn-flags.txt'),
+  };
+}
+
+export function freshEfficiencyStats(nowIso) {
+  return {
+    sessionStartedAt: nowIso,
+    lastUpdatedAt: nowIso,
+    readCount: 0,
+    uniqueFileCount: 0,
+    repeatedReadCount: 0,
+    largeReadCount: 0,
+    totalBytesRead: 0,
+    warnings: {},
+    files: {},
+  };
+}
+
+export function loadEfficiencyStats(nowIso, env = process.env) {
+  const { efficiencyStore } = readTrackerPaths(env);
+  const fresh = freshEfficiencyStats(nowIso);
+  try {
+    const existing = JSON.parse(readFileSync(efficiencyStore, 'utf8'));
+    const lastUpdated = new Date(existing.lastUpdatedAt || 0).getTime();
+    if (!lastUpdated || Date.now() - lastUpdated > SESSION_IDLE_RESET_MS) return fresh;
+    return { ...fresh, ...existing, warnings: existing.warnings || {}, files: existing.files || {} };
+  } catch {
+    return fresh;
+  }
+}
+
+function appendWarning(message, env = process.env) {
+  try {
+    const { warnFlags } = readTrackerPaths(env);
+    appendFileSync(warnFlags, `${message}\n`);
+  } catch { /* best effort */ }
+}
+
+function topRepeatedPath(files) {
+  return Object.entries(files || {})
+    .map(([filePath, value]) => ({ filePath, count: Number(value?.count || 0) }))
+    .filter((entry) => entry.count > 1)
+    .sort((a, b) => b.count - a.count || a.filePath.localeCompare(b.filePath))[0];
+}
+
+export function applyReadDelta(stats, delta, env = process.env) {
+  const existingFile = stats.files[delta.path];
+  const isLargeRead = Number(delta.limit || 0) > EFFICIENCY_LARGE_READ_LIMIT;
+
+  stats.readCount += 1;
+  stats.totalBytesRead += Number(delta.size || 0);
+  if (isLargeRead) stats.largeReadCount += 1;
+  if (existingFile) stats.repeatedReadCount += 1;
+  else stats.uniqueFileCount += 1;
+
+  stats.files[delta.path] = {
+    count: Number(existingFile?.count || 0) + 1,
+    size: Number(delta.size || 0),
+    lastReadAt: delta.ts,
+    lastRequestedLimit: Number(delta.limit || 0),
+  };
+
+  const fileEntries = Object.entries(stats.files);
+  if (fileEntries.length > FILES_LRU_CAP) {
+    fileEntries.sort((a, b) => (a[1]?.lastReadAt || '').localeCompare(b[1]?.lastReadAt || ''));
+    const drop = fileEntries.length - FILES_LRU_CAP;
+    for (let i = 0; i < drop; i++) delete stats.files[fileEntries[i][0]];
+  }
+
+  if (stats.repeatedReadCount >= REPEATED_READ_WARNING_THRESHOLD && !stats.warnings.repeatedReads) {
+    const top = topRepeatedPath(stats.files);
+    const topNote = top ? ` Top repeat: ${top.filePath} (${top.count}x).` : '';
+    appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session.${topNote} Use rg or construct distill before re-reading more files.`, env);
+    stats.warnings.repeatedReads = delta.ts;
+    if (stats.repeatedReadCount >= REPEATED_READ_TIER2_THRESHOLD && !stats.warnings.repeatedReadsTier2) {
+      appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session — consider using construct distill or rg before re-reading entire files.`, env);
+      stats.warnings.repeatedReadsTier2 = delta.ts;
+    }
+  }
+
+  if (stats.largeReadCount >= LARGE_READ_WARNING_THRESHOLD && !stats.warnings.largeReads) {
+    appendWarning(`Efficiency: ${stats.largeReadCount} large reads this session — prefer rg/glob plus targeted reads under 400 lines.`, env);
+    stats.warnings.largeReads = delta.ts;
+  }
+
+  if (stats.totalBytesRead >= TOTAL_BYTES_WARNING_THRESHOLD && !stats.warnings.totalBytes) {
+    appendWarning(`Efficiency: ${Math.round(stats.totalBytesRead / 1024)} KB read this session — consider distill/query-focused retrieval or compact context before continuing.`, env);
+    stats.warnings.totalBytes = delta.ts;
+  }
+
+  stats.lastUpdatedAt = delta.ts;
+  return stats;
+}
+
+export function recordReadDelta(delta, env = process.env) {
+  const { cxDir, deltaLog } = readTrackerPaths(env);
+  mkdirSync(cxDir, { recursive: true });
+  appendFileSync(deltaLog, `${JSON.stringify(delta)}\n`, 'utf8');
+}
+
+export function flushReadTrackerDeltas({ nowIso = new Date().toISOString(), env = process.env } = {}) {
+  const { cxDir, deltaLog, efficiencyStore } = readTrackerPaths(env);
+  mkdirSync(cxDir, { recursive: true });
+  const stats = loadEfficiencyStats(nowIso, env);
+  if (!existsSync(deltaLog)) return stats;
+
+  const lines = readFileSync(deltaLog, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (const line of lines) {
+    try {
+      const delta = JSON.parse(line);
+      applyReadDelta(stats, delta, env);
+    } catch { /* best effort */ }
+  }
+
+  writeFileSync(efficiencyStore, `${JSON.stringify(stats, null, 2)}\n`);
+  rmSync(deltaLog, { force: true });
+  return stats;
+}

package/lib/server/index.mjs

@@ -1500,6 +1500,82 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  // ── Recommendations API ────────────────────────────────────────────────────
+  if (url.pathname === '/api/recommendations') {
+    if (req.method === 'GET') {
+      const { listActiveRecommendations, recommendationStats } = await import('../embed/recommendation-store.mjs');
+      const priority = url.searchParams.get('priority') || undefined;
+      const type = url.searchParams.get('type') || undefined;
+      const limit = Number(url.searchParams.get('limit') || 50);
+      const items = listActiveRecommendations({ priority, type, limit });
+      const stats = recommendationStats();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ items, stats }));
+      return;
+    }
+    if (req.method === 'PATCH' || req.method === 'POST') {
+      const chunks = [];
+      await new Promise((resolve, reject) => { req.on('data', c => chunks.push(c)); req.on('end', resolve); req.on('error', reject); });
+      let body;
+      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { body = {}; }
+      const action = body.action || url.searchParams.get('action');
+      const dedupKey = body.dedupKey || url.searchParams.get('dedupKey');
+      if (!action || !dedupKey) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'action and dedupKey are required' }));
+        return;
+      }
+      const { dismissRecommendation, reviveRecommendation } = await import('../embed/recommendation-store.mjs');
+      try {
+        if (action === 'dismiss') {
+          const result = dismissRecommendation(dedupKey, { reason: body.reason, suppressDays: body.suppressDays });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+        } else if (action === 'revive') {
+          const result = reviveRecommendation(dedupKey, { signalCount: body.signalCount, sourceSignalIds: body.sourceSignalIds });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+        } else {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: `unknown action: ${action}` }));
+        }
+      } catch (err) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err?.message || 'not found' }));
+      }
+      return;
+    }
+  }
+
+  // ── Strategy API ───────────────────────────────────────────────────────────
+  if (url.pathname === '/api/strategy') {
+    if (req.method === 'GET') {
+      const { readAllStrategies } = await import('../strategy-store.mjs');
+      const result = await readAllStrategies(process.env);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ scopes: Object.fromEntries(result) }));
+      return;
+    }
+    if (req.method === 'PUT' || req.method === 'POST') {
+      const chunks = [];
+      await new Promise((resolve, reject) => { req.on('data', c => chunks.push(c)); req.on('end', resolve); req.on('error', reject); });
+      let body;
+      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { body = {}; }
+      const content = (body.content || '').trim();
+      const scope = (body.scope || 'product').trim();
+      if (!content) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'content is required' }));
+        return;
+      }
+      const { writeStrategy } = await import('../strategy-store.mjs');
+      await writeStrategy(content, scope, { updatedBy: 'dashboard', env: process.env });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+  }
+
   if (url.pathname === '/api/snapshots') {
     handleSnapshots(req, res);
     return;

package/lib/server/telemetry-login.mjs

@@ -1,21 +1,15 @@
 /**
- * lib/server/telemetry-login.mjs — magic-link bridge for a local telemetry backend.
+ * lib/server/telemetry-login.mjs — magic-link bridge for a configured telemetry UI.
  *
- * When a self-hosted telemetry backend (e.g. a self-hosted or cloud telemetry backend)
- * is running locally, this bridge turns the "Open Telemetry" link in the
- * dashboard into a one-click sign-in. The server fetches a CSRF token from
- * the backend, then returns an HTML auto-submit form that POSTs the seeded
- * credentials to NextAuth's callback.
- *
- * The seeded creds are NOT secret — they are deterministic local defaults
- * for zero-touch local development. Not used when CONSTRUCT_TELEMETRY_URL
- * points at a remote backend.
+ * CONSTRUCT_TELEMETRY_URL may point at a Langfuse-compatible deployment.
+ * The dashboard link can use this bridge for one-click sign-in by fetching a
+ * CSRF token and returning an HTML auto-submit form for NextAuth's callback.
  */
 
 const HTML_HEADERS = { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' };
 
 /**
- * Resolve the telemetry backend URL from env with backward compat.
+ * Resolve the configured telemetry UI URL from env.
  */
 function resolveTelemetryUrl(env = process.env) {
   return (
@@ -45,10 +39,10 @@ function escapeHtml(value) {
  */
 export function renderAutoSubmitForm({ csrfToken, callbackUrl, redirectAfter, email, password }) {
   return `<!doctype html>
-<html><head><meta charset="utf-8"><title>Signing in to telemetry backend…</title>
+<html><head><meta charset="utf-8"><title>Signing in to telemetry UI…</title>
 <style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;color:#666;background:#fff}</style>
 </head><body>
-<p>Signing you in to telemetry backend…</p>
+<p>Signing you in to telemetry UI…</p>
 <form id="tf" method="POST" action="${escapeHtml(callbackUrl)}">
 <input type="hidden" name="csrfToken" value="${escapeHtml(csrfToken)}">
 <input type="hidden" name="email" value="${escapeHtml(email)}">
@@ -63,8 +57,8 @@ export function renderAutoSubmitForm({ csrfToken, callbackUrl, redirectAfter, em
 /**
  * HTTP handler: GET /api/services/telemetry/login
  *
- * Returns an HTML page that immediately POSTs credentials to the backend's
- * NextAuth callback. Returns 502 when the backend is unreachable.
+ * Returns an HTML page that immediately POSTs credentials to the configured
+ * NextAuth callback. Returns 502 when the endpoint is unreachable.
  */
 export async function handleTelemetryLogin(req, res, {
   baseUrl,
@@ -76,8 +70,8 @@ export async function handleTelemetryLogin(req, res, {
 
   if (!resolvedBaseUrl) {
     res.writeHead(503, HTML_HEADERS);
-    res.end(`<!doctype html><meta charset="utf-8"><title>Telemetry backend not configured</title>` +
-      `<pre>CONSTRUCT_TELEMETRY_URL is not set. Configure a telemetry backend to use this feature.</pre>`);
+    res.end(`<!doctype html><meta charset="utf-8"><title>Telemetry UI not configured</title>` +
+      `<pre>CONSTRUCT_TELEMETRY_URL is not set. Configure a Langfuse-compatible telemetry UI to use this feature.</pre>`);
     return;
   }
 
@@ -87,9 +81,9 @@ export async function handleTelemetryLogin(req, res, {
     });
     if (!csrfResponse.ok) {
       res.writeHead(502, HTML_HEADERS);
-      res.end(`<!doctype html><meta charset="utf-8"><title>Telemetry backend unreachable</title>` +
-        `<pre>Could not reach telemetry backend at ${escapeHtml(resolvedBaseUrl)}. Status: ${csrfResponse.status}. ` +
-        `Try \`construct up\` first.</pre>`);
+      res.end(`<!doctype html><meta charset="utf-8"><title>Telemetry UI unreachable</title>` +
+        `<pre>Could not reach telemetry UI at ${escapeHtml(resolvedBaseUrl)}. Status: ${csrfResponse.status}. ` +
+        `Check CONSTRUCT_TELEMETRY_URL and the configured service.</pre>`);
       return;
     }
     const { csrfToken } = await csrfResponse.json();
@@ -99,10 +93,8 @@ export async function handleTelemetryLogin(req, res, {
     res.end(renderAutoSubmitForm({ csrfToken, callbackUrl, redirectAfter, email, password }));
   } catch (err) {
     res.writeHead(502, HTML_HEADERS);
-    res.end(`<!doctype html><meta charset="utf-8"><title>Telemetry backend unreachable</title>` +
-      `<pre>Could not reach telemetry backend: ${escapeHtml(err?.message || 'unknown error')}. ` +
-      `Try \`construct up\` first.</pre>`);
+    res.end(`<!doctype html><meta charset="utf-8"><title>Telemetry UI unreachable</title>` +
+      `<pre>Could not reach telemetry UI: ${escapeHtml(err?.message || 'unknown error')}. ` +
+      `Check CONSTRUCT_TELEMETRY_URL and the configured service.</pre>`);
   }
 }
-
-

package/lib/service-manager.mjs

@@ -20,8 +20,8 @@ import {
   pruneStashDir,
   verifyTelemetryKeys,
   isRemoteTelemetry,
-  startManagedServices,
-} from './services/telemetry-backend.mjs';
+} from './services/local-postgres.mjs';
+import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
 
 const CONSTRUCT_PG_COMPOSE_DIR = 'services/postgres';
 const CONSTRUCT_PG_CONTAINER = 'construct-postgres';
@@ -464,7 +464,7 @@ export async function startServices({
   // On macOS, auto-launch Docker Desktop when the CLI is present but the
   // daemon is down. Polls up to 60s so downstream Postgres startup sees a working
   // compose runner instead of "Docker not available".
-  await tryStartDockerDaemonFn({ env: process.env });
+  await tryStartDockerDaemonFn({ env: { ...process.env, HOME: homeDir }, timeoutMs: 5000 });
 
   writeEnvValues(envPath, {
     DASHBOARD_PORT: String(ports.dashboard),
@@ -475,7 +475,7 @@ export async function startServices({
   // Construct Postgres — start if DATABASE_URL points to managed container
   const liveEnv = loadConstructEnvFn({ rootDir, homeDir });
   const results = [];
-  const pressureReport = runPressureReleaseFn({ env: liveEnv });
+  const pressureReport = runPressureReleaseFn({ env: { ...liveEnv, HOME: homeDir } });
   if (pressureReport?.killed?.length) {
     results.push({
       name: 'Pressure Guard',
@@ -527,31 +527,39 @@ export async function startServices({
     status: dashboard.reused ? 'reused' : 'started',
   });
 
-  // Telemetry backend — delegated to lib/services/telemetry-backend.mjs.
-  // Remote URLs short-circuit inside startManagedServices and return `configured`.
-
   const telemetryUrl = liveEnv.CONSTRUCT_TELEMETRY_URL ?? '';
-  if (telemetryUrl && isRemoteTelemetry(telemetryUrl)) {
+  const traceBackend = resolveTraceBackend(liveEnv);
+  if (traceBackend === 'local') {
+    results.push({
+      name: 'Telemetry',
+      url: path.join(rootDir, '.cx', 'traces'),
+      status: 'configured',
+      note: 'local JSONL traces; remote export not configured',
+    });
+  } else if (traceBackend === 'none') {
+    results.push({
+      name: 'Telemetry',
+      url: path.join(rootDir, '.cx', 'traces'),
+      status: 'configured',
+      note: 'remote export disabled; local JSONL traces preserved',
+    });
+  } else if (traceBackend === 'otel') {
+    const endpoint = liveEnv.CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT || '';
+    results.push({
+      name: 'Telemetry',
+      url: endpoint || undefined,
+      status: endpoint ? 'configured' : 'unavailable',
+      note: endpoint ? `OTLP export (${telemetryProviderLabel(liveEnv)})` : 'CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT not set',
+    });
+  } else if (telemetryUrl && (isRemoteTelemetry(telemetryUrl) || traceBackend === 'langfuse' || traceBackend === 'http')) {
     results.push({
       name: 'Telemetry',
       url: telemetryUrl,
       status: 'configured',
-      note: `remote — ${telemetryUrl}`,
+      note: `${telemetryProviderLabel(liveEnv)} export — ${telemetryUrl}`,
     });
   } else {
-    const composeRunner = detectDockerComposeFn();
-    if (composeRunner) {
-      const svc = await startManagedServices({
-        rootDir,
-        homeDir,
-        env: liveEnv,
-        composeRunner,
-        spawnDetached: spawnDetachedFn,
-      });
-      results.push({ name: 'Telemetry', url: svc.url, status: svc.status, note: svc.note });
-    } else {
-      results.push({ name: 'Telemetry', status: 'unavailable', note: 'Docker not available' });
-    }
+    results.push({ name: 'Telemetry', status: 'unavailable', note: 'remote export requested but endpoint is not configured' });
   }
 
   // Memory (cm)

package/lib/services/local-postgres.mjs

@@ -0,0 +1,15 @@
+/**
+ * lib/services/local-postgres.mjs — local Postgres helper exports.
+ *
+ * Compatibility wrappers live in telemetry-backend.mjs until downstream imports
+ * move, but new service-management code should use this name.
+ */
+export {
+  POSTGRES_LOCAL_PORT,
+  isRemoteTelemetry,
+  servicesComposePath,
+  pruneStashDir,
+  verifyPostgresHealth,
+  verifyTelemetryKeys,
+  startManagedServices,
+} from './telemetry-backend.mjs';

package/lib/services/telemetry-backend.mjs

@@ -18,7 +18,7 @@ import path from 'node:path';
 import { getUserEnvPath, writeEnvValues } from '../env-config.mjs';
 
 /** Local Postgres port (within Construct's 54329-54339 reserved block). */
-export const POSTGRES_LOCAL_PORT = 54332;
+export const POSTGRES_LOCAL_PORT = 54329;
 
 export function isRemoteTelemetry(url = '') {
   if (!url) return false;
@@ -175,4 +175,3 @@ export async function startManagedServices({
   };
 }
 
-

package/lib/setup.mjs

@@ -25,10 +25,6 @@ import { createSqlClient, closeSqlClient } from './storage/backend.mjs';
 import { getEmbeddingModelInfo, warmupEmbeddingModel } from './storage/embeddings-engine.mjs';
 import { restoreConstructDb } from './storage/postgres-backup.mjs';
 import { buildPressureGuardValues, installPressureGuardLaunchAgent, loadPressureGuardLaunchAgent } from './runtime-pressure.mjs';
-import {
-  isRemoteTelemetry,
-  startManagedServices,
-} from './services/telemetry-backend.mjs';
 import { consentToInstall } from './setup-prompts.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
@@ -86,9 +82,8 @@ export function defaultVectorIndexPath(homeDir = HOME) {
 export async function buildManagedSetupValues({ homeDir = HOME, env = process.env, databaseUrl = '' } = {}) {
   const modelInfo = await getEmbeddingModelInfo({ env });
 
-  // Local telemetry backend
   const values = {
-    CONSTRUCT_TRACE_BACKEND: env.CONSTRUCT_TRACE_BACKEND || 'remote',
+    CONSTRUCT_TRACE_BACKEND: env.CONSTRUCT_TRACE_BACKEND || 'local',
     CONSTRUCT_VECTOR_INDEX_PATH: env.CONSTRUCT_VECTOR_INDEX_PATH || defaultVectorIndexPath(homeDir),
     CONSTRUCT_VECTOR_MODEL: env.CONSTRUCT_VECTOR_MODEL || modelInfo.model,
     ...buildPressureGuardValues({ env }),
@@ -533,37 +528,10 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     console.log(`  ${dockerInstallHint()}`);
   }
 
-  // Local telemetry backend — starts Postgres via services/docker-compose.yml.
-  // Skipped automatically when CONSTRUCT_TELEMETRY_URL points to a remote instance.
-
-  let telemetryResult = { status: 'skipped', note: 'Docker not available' };
-  if (dockerAvailable) {
-    const svcConsent = await consentToInstall({
-      name: 'telemetry',
-      isYes,
-      alreadyConfigured: isRemoteTelemetry(process.env.CONSTRUCT_TELEMETRY_URL || ''),
-      alreadyConfiguredNote: 'CONSTRUCT_TELEMETRY_URL points to a remote instance — local stack not started.',
-      envPath,
-    });
-    if (svcConsent.decision) {
-      try {
-        telemetryResult = await startManagedServices({
-          rootDir,
-          homeDir,
-          env: process.env,
-          composeRunner: dockerRunner,
-          spawnDetached: spawnDetachedForSetup,
-        });
-        console.log(`Telemetry: ${telemetryResult.status} — ${telemetryResult.note || ''}`);
-      } catch (err) {
-        telemetryResult = { status: 'error', note: err?.message || 'spin-up failed' };
-        console.log(`Telemetry: error — ${telemetryResult.note}`);
-      }
-    } else {
-      telemetryResult = { status: 'skipped', note: svcConsent.note };
-      console.log(`Telemetry: skipped (${svcConsent.note})`);
-    }
-  }
+  const telemetryResult = process.env.CONSTRUCT_TELEMETRY_URL
+    ? { status: 'configured', note: `remote export configured (${process.env.CONSTRUCT_TELEMETRY_URL})` }
+    : { status: 'local', note: 'local JSONL traces in .cx/traces; remote export optional' };
+  console.log(`Telemetry: ${telemetryResult.note}`);
 
   fs.mkdirSync(path.dirname(defaultVectorIndexPath(homeDir)), { recursive: true });
 
@@ -790,18 +758,15 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   // Local-service summary — surfaces running local services. Same pattern
   // as `supabase start`, which prints all local URLs + keys after spin-up.
 
-  const hasLocalTelemetry = telemetryResult?.status === 'started' || telemetryResult?.status === 'degraded';
   const hasLocalPostgres = serviceResult?.status === 'ok' && serviceResult?.databaseUrl?.includes('127.0.0.1');
   const vectorBackend = hasLocalPostgres
     ? { label: 'Postgres + pgvector', detail: `${serviceResult.databaseUrl} (384d embeddings, ${managedValues.CONSTRUCT_VECTOR_MODEL})` }
     : { label: 'JSON fallback', detail: `${managedValues.CONSTRUCT_VECTOR_INDEX_PATH} (${managedValues.CONSTRUCT_VECTOR_MODEL})` };
 
   console.log('\nLocal services:');
-  if (hasLocalTelemetry) {
-    console.log(`  Telemetry:   ${telemetryResult.note || 'started'}`);
-  } else {
-    console.log(`  Telemetry:   not started`);
-  }
+  console.log('  Traces:      local JSONL (.cx/traces)');
+  if (process.env.CONSTRUCT_TELEMETRY_URL) console.log(`  Telemetry:   remote export (${process.env.CONSTRUCT_TELEMETRY_URL})`);
+  else console.log('  Telemetry:   remote export not configured');
   if (hasLocalPostgres) {
     console.log(`  Postgres:    ${serviceResult.databaseUrl}`);
   } else if (process.env.DATABASE_URL) {

package/lib/status.mjs

@@ -24,6 +24,7 @@ import { describeSqlStore, sqlStoreHealth } from './storage/sql-store.mjs';
 import { describeVectorStore } from './storage/vector-store.mjs';
 import { describeSqlStoreHealth } from './storage/sql-store.mjs';
 import { triggerAutoBackfillIfSparse } from './telemetry/backfill.mjs';
+import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
 const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
 
 function readJSON(path) {
@@ -317,18 +318,27 @@ async function defaultProbeService(service) {
 }
 
 async function fetchTelemetryStatus(env, { timeout = 2500 } = {}) {
+  const backend = resolveTraceBackend(env);
+  if (backend === 'local') return { status: 'healthy', summary: 'Local JSONL tracing enabled · remote export not configured', backend, provider: telemetryProviderLabel(env) };
+  if (backend === 'none') return { status: 'disabled', summary: 'Remote telemetry disabled · local JSONL tracing preserved', backend, provider: telemetryProviderLabel(env) };
+  if (backend === 'otel') {
+    const endpoint = (env.CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT ?? '').replace(/\/$/, '');
+    if (!endpoint) return { status: 'unavailable', summary: 'OTLP endpoint not configured', backend, provider: telemetryProviderLabel(env) };
+    return { status: 'configured', summary: `OTLP export configured · ${endpoint}`, backend, provider: telemetryProviderLabel(env) };
+  }
   const baseUrl = (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, '');
   const key = env.CONSTRUCT_TELEMETRY_PUBLIC_KEY;
   const secret = env.CONSTRUCT_TELEMETRY_SECRET_KEY;
-  if (!key || !secret) return { status: 'unavailable', summary: 'Telemetry credentials not configured' };
+  if (backend === 'langfuse' && (!key || !secret)) return { status: 'unavailable', summary: 'Langfuse credentials not configured', backend, provider: telemetryProviderLabel(env) };
   if (!baseUrl) return { status: 'unavailable', summary: 'CONSTRUCT_TELEMETRY_URL not set' };
   const headers = {
-    Authorization: `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`,
+    ...(key && secret ? { Authorization: `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}` } : {}),
   };
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   try {
-    const res = await fetch(`${baseUrl}/api/public/traces?limit=25`, { headers, signal: controller.signal });
+    const tracesPath = backend === 'http' ? '/traces?limit=25' : '/api/public/traces?limit=25';
+    const res = await fetch(`${baseUrl}${tracesPath}`, { headers, signal: controller.signal });
     if (res.status === 401 || res.status === 403) {
       return { status: 'credentials-invalid', summary: `Telemetry credentials rejected (HTTP ${res.status}) — run: construct init` };
     }
@@ -359,6 +369,8 @@ async function fetchTelemetryStatus(env, { timeout = 2500 } = {}) {
 
     return {
       status,
+      backend,
+      provider: telemetryProviderLabel(env),
       total,
       rich: counts.rich,
       partial: counts.partial,
@@ -478,6 +490,40 @@ export function buildPublicHealthSurface({
 }
 
 function traceBackendDefinition(env) {
+  const backend = resolveTraceBackend(env);
+  const provider = telemetryProviderLabel(env);
+  if (backend === 'local' || backend === 'none') {
+    return {
+      id: 'telemetry',
+      name: 'Telemetry',
+      url: 'local://.cx/traces',
+      runtime: 'local',
+      note: backend === 'none' ? 'Remote disabled; local JSONL preserved' : 'Local JSONL traces',
+      healthyMessage: 'Local trace capture enabled',
+      impactsOverall: false,
+      selfCheck: {
+        status: backend === 'none' ? 'disabled' : 'healthy',
+        message: backend === 'none' ? 'Remote telemetry disabled' : 'Writing .cx/traces/*.jsonl',
+      },
+    };
+  }
+  if (backend === 'otel') {
+    const endpoint = (env.CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT ?? '').replace(/\/$/, '');
+    return {
+      id: 'telemetry',
+      name: 'Telemetry',
+      url: endpoint || '(not configured)',
+      probeUrl: '',
+      runtime: 'remote',
+      note: `${provider} trace export`,
+      healthyMessage: 'Configured',
+      impactsOverall: false,
+      selfCheck: {
+        status: endpoint ? 'configured' : 'unavailable',
+        message: endpoint ? `OTLP export configured: ${endpoint}` : 'CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT not set',
+      },
+    };
+  }
   const url = (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, '');
   const pubKey = env.CONSTRUCT_TELEMETRY_PUBLIC_KEY || '';
   const secKey = env.CONSTRUCT_TELEMETRY_SECRET_KEY || '';
@@ -486,10 +532,10 @@ function traceBackendDefinition(env) {
     id: 'telemetry',
     name: 'Telemetry',
     url: url || '(not configured)',
-    probeUrl: url ? `${url}/api/public/traces?limit=1` : '',
+    probeUrl: url ? `${url}${backend === 'http' ? '/traces?limit=1' : '/api/public/traces?limit=1'}` : '',
     probeHeaders: auth ? { Authorization: auth } : undefined,
     runtime: 'live',
-    note: 'Trace backend',
+    note: `${provider} trace export`,
     healthyMessage: 'Reachable',
     impactsOverall: false,
   };

package/lib/storage/backend.mjs

@@ -1,17 +1,27 @@
 #!/usr/bin/env node
 /**
  * lib/storage/backend.mjs — shared storage backend helpers for SQL/vector wiring.
+ *
+ * postgres is an optional peer dep. Top-level await catches the case where it is not
+ * installed (fresh installs, test temp dirs) so the module loads cleanly everywhere.
  */
-import postgres from 'postgres';
 import { resolveDatabaseUrl } from '../env-config.mjs';
 
+let postgres = null;
+try {
+  const mod = await import('postgres');
+  postgres = mod.default ?? mod;
+} catch {
+  // postgres not installed — SQL features unavailable; createSqlClient returns null
+}
+
 function cleanUrl(url) {
   return String(url || '').trim();
 }
 
 export function createSqlClient(env = process.env) {
   const databaseUrl = cleanUrl(resolveDatabaseUrl(env));
-  if (!databaseUrl) return null;
+  if (!databaseUrl || !postgres) return null;
   return postgres(databaseUrl, {
     max: Number.parseInt(env.CONSTRUCT_DB_POOL_SIZE || '5', 10),
     idle_timeout: Number.parseInt(env.CONSTRUCT_DB_IDLE_TIMEOUT_MS || '30000', 10),