@geraldmaron/construct 1.0.3 → 1.0.5

package/lib/reflect.mjs

@@ -5,11 +5,13 @@
  * knowledge base with actionable insights for continuous self-improvement.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { execSync } from 'node:child_process';
 import { addObservation } from './observation-store.mjs';
 import { loadConstructEnv } from './env-config.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS, inferKnowledgeTarget } from './knowledge/layout.mjs';
+import { extractSessionObservation } from './reflect/extractor.mjs';
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const USER_ENV_PATH = join(HOME, '.construct', 'config.env');
@@ -125,6 +127,91 @@ export async function runReflectCli(args) {
   console.log(`  Use 'construct ingest --target=${target} <file>' to manually add similar feedback in the future`);
 }
 
+/**
+ * Auto-reflect from a Claude Code Stop hook payload.
+ *
+ * Reads the transcript JSONL, extracts a deterministic session summary, and
+ * persists it via the standard observation store. Contract: exit fast, fail
+ * silent, never throw — every error path returns null so the hook always
+ * exits 0.
+ *
+ * Returns the recorded observation id on success, null on no-op.
+ *
+ * @param {object} args
+ * @param {string} args.transcriptPath — path to the Stop hook's transcript_path
+ * @param {string} args.cwd — session cwd (the project root)
+ * @param {string} [args.sessionId]
+ * @param {number} [args.durationMs]
+ * @returns {Promise<string|null>}
+ */
+export async function runReflectAuto({ transcriptPath, cwd, sessionId, durationMs }) {
+  if (!transcriptPath || !cwd) return null;
+  if (!existsSync(transcriptPath)) return null;
+
+  const entries = parseTranscript(transcriptPath);
+  if (entries.length === 0) return null;
+
+  const observation = extractSessionObservation({ entries, cwd, sessionId, durationMs });
+  if (!observation) return null;
+
+  // Skip trivial sessions: no tool calls AND no substantive final text. Avoids
+  // polluting the observation store with one-line acknowledgements.
+  const trivial =
+    observation.extras?.toolCallCount === 0 &&
+    (observation.content?.length || 0) < 120;
+  if (trivial) return null;
+
+  const project = safeProject(cwd);
+  const gitSha = safeGitSha(cwd);
+
+  // Session-id stays in tags so the index can filter by it without parsing.
+  // Structured metadata goes into the new extras field, not into content.
+  const sessionTag = sessionId ? `session:${sessionId.slice(0, 24)}` : null;
+  const tags = [...observation.tags];
+  if (sessionTag) tags.push(sessionTag);
+
+  const result = await addObservation(cwd, {
+    role: observation.role,
+    category: observation.category,
+    summary: observation.summary,
+    content: observation.content,
+    tags,
+    project,
+    gitSha,
+    confidence: observation.confidence,
+    source: observation.source,
+    extras: observation.extras ?? null,
+  });
+
+  return result?.id ?? null;
+}
+
+function safeProject(cwd) {
+  try { return basename(cwd) || null; } catch { return null; }
+}
+
+function safeGitSha(cwd) {
+  try {
+    return execSync('git rev-parse HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 200 })
+      .toString().trim().slice(0, 40) || null;
+  } catch { return null; }
+}
+
+// Transcripts are JSONL; one JSON object per line. Be permissive — a single
+// malformed line shouldn't lose the rest of the session.
+
+function parseTranscript(path) {
+  let raw = '';
+  try { raw = readFileSync(path, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try { out.push(JSON.parse(trimmed)); } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
 /**
  * CLI entry point for direct execution.
  */

package/lib/sandbox.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/sandbox.mjs — Lightweight isolated environment for QA validation.
+ *
+ * Spins up a fresh tmpdir with a minimal `.cx/` so a specialist (or operator)
+ * can run end-to-end checks against a candidate change without touching the
+ * working repo. Designed to be the cheapest possible alternative to a full
+ * Docker container: when Docker is unavailable, an isolated tmpdir is enough
+ * for almost every validation Construct needs.
+ *
+ * Layout created:
+ *   <sandbox>/.cx/
+ *     context.md             stub
+ *     observations/          empty
+ *     intake/pending/        empty
+ *   <sandbox>/.git/          empty repo init, so git-aware tools work
+ *
+ * Tear-down is opt-in via `construct sandbox prune` or by hand. Each sandbox
+ * lives under `~/.cx/sandboxes/<id>/` so they survive across CLI sessions.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const ROOT = path.join(os.homedir(), '.cx', 'sandboxes');
+
+function ensureRoot() {
+  fs.mkdirSync(ROOT, { recursive: true });
+}
+
+function newSandboxId() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${stamp}-${rand}`;
+}
+
+/**
+ * Create a new sandbox. Returns its absolute path.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.profile] - profile id to write into construct.config.json
+ * @param {string} [opts.seedContext] - text to drop into .cx/context.md
+ * @returns {{ id: string, path: string }}
+ */
+export function createSandbox({ profile = null, seedContext = null } = {}) {
+  ensureRoot();
+  const id = newSandboxId();
+  const root = path.join(ROOT, id);
+  fs.mkdirSync(root, { recursive: true });
+  fs.mkdirSync(path.join(root, '.cx', 'observations'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.cx', 'intake', 'pending'), { recursive: true });
+
+  const ctx = seedContext || `# Sandbox ${id}\n\nIsolated environment for QA validation. Created ${new Date().toISOString()}.\n`;
+  fs.writeFileSync(path.join(root, '.cx', 'context.md'), ctx);
+
+  const cfg = { version: 1, alias: 'Construct', deployment: { mode: 'solo' } };
+  if (profile) cfg.profile = profile;
+  fs.writeFileSync(path.join(root, 'construct.config.json'), JSON.stringify(cfg, null, 2) + '\n');
+
+  spawnSync('git', ['init', '--quiet'], { cwd: root, stdio: 'ignore' });
+
+  return { id, path: root };
+}
+
+/**
+ * List existing sandboxes, newest first.
+ */
+export function listSandboxes() {
+  if (!fs.existsSync(ROOT)) return [];
+  const entries = fs.readdirSync(ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => {
+      const full = path.join(ROOT, d.name);
+      const stat = fs.statSync(full);
+      return { id: d.name, path: full, createdAt: stat.birthtime.toISOString() };
+    });
+  return entries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+/**
+ * Delete a sandbox by id. Returns true if removed, false if not found.
+ */
+export function deleteSandbox(id) {
+  const full = path.join(ROOT, id);
+  if (!fs.existsSync(full)) return false;
+  fs.rmSync(full, { recursive: true, force: true });
+  return true;
+}
+
+/**
+ * Prune sandboxes older than N days. Returns the count removed.
+ */
+export function pruneSandboxes({ olderThanDays = 7 } = {}) {
+  const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+  let removed = 0;
+  for (const s of listSandboxes()) {
+    if (Date.parse(s.createdAt) < cutoff) {
+      if (deleteSandbox(s.id)) removed++;
+    }
+  }
+  return removed;
+}

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) {