@geraldmaron/construct 1.0.1 → 1.0.3

package/bin/construct

@@ -160,7 +160,7 @@ async function showInteractiveMenu() {
   
   // Show context-aware suggestions
   if (isConstructProject) {
-    const { readDashboardState } = await import('./lib/service-manager.mjs');
+    const { readDashboardState } = await import('../lib/service-manager.mjs');
     const dashboard = readDashboardState(HOME);
     
     if (!dashboard) {
@@ -288,12 +288,12 @@ async function cmdDoctor() {
     for (const varName of vars) {
       const sources = [];
 
-      // 1. process.env
+      // process.env
       if (process.env[varName]) {
         sources.push(`process.env (${process.env[varName].slice(0, 8)}…)`);
       }
 
-      // 2. .env files
+      // .env files
       for (const envPath of [join(process.cwd(), '.env'), join(homedir(), '.env'), join(homedir(), '.construct', 'config.env')]) {
         if (fs.existsSync(envPath)) {
           try {
@@ -304,7 +304,7 @@ async function cmdDoctor() {
         }
       }
 
-      // 3. Shell rc files
+      // Shell rc files
       const shellFiles = [join(homedir(), '.zshrc'), join(homedir(), '.bashrc'), join(homedir(), '.bash_profile'), join(homedir(), '.profile')];
       for (const rcPath of shellFiles) {
         if (!fs.existsSync(rcPath)) continue;
@@ -904,9 +904,9 @@ async function cmdUp() {
   if (embedConfigExists && autoEmbed) {
     try {
       const { runEmbedCli } = await import('../lib/embed/cli.mjs');
-      await runEmbedCli(['start']);
-    } catch {
-      // best effort
+      await runEmbedCli(['start'], { rootDir: ROOT_DIR });
+    } catch (err) {
+      warn(`embed start failed: ${err.message} — check ~/.cx/runtime/embed-daemon.log`);
     }
   }
 
@@ -2449,6 +2449,44 @@ async function cmdModels(args) {
     await cmdSync([]);
     return;
   }
+  if (args.includes('--cheapest')) {
+    const { selectCheapestProvider, rankConfiguredProvidersByCost, formatCheapestProviderMessage, isCheapestProviderEnabled } =
+      await import('../lib/model-cheapest-provider.mjs');
+    const cheapestTier = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1] ?? 'standard';
+    const verbose = args.includes('--verbose');
+    const enabled = isCheapestProviderEnabled(envPath, { env: process.env });
+    const result = await selectCheapestProvider(cheapestTier, { env: process.env });
+    const msg = formatCheapestProviderMessage(result, { showRanking: verbose });
+    println(msg);
+    if (enabled) println('\nCheapest provider mode: enabled');
+    return;
+  }
+  if (args.includes('--apply-cheapest')) {
+    const { selectCheapestForAllTiers, setCheapestProviderPreference } =
+      await import('../lib/model-cheapest-provider.mjs');
+    const allTiers = args.includes('--all-tiers') || !args.find((arg) => arg.startsWith('--tier='));
+    const tierArg = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1];
+    const tiers = allTiers ? ['reasoning', 'standard', 'fast'] : (tierArg ? [tierArg] : ['standard']);
+    const selections = {};
+    for (const currentTier of tiers) {
+      const { selectCheapestProvider } = await import('../lib/model-cheapest-provider.mjs');
+      const result = await selectCheapestProvider(currentTier, { env: process.env });
+      if (result.modelId) selections[currentTier] = result.modelId;
+    }
+    if (Object.keys(selections).length === 0) {
+      errorln('No configured providers found. Set API keys or install Ollama first.');
+      process.exit(1);
+    }
+    applyToEnv(envPath, selections);
+    println('Applying cheapest models:');
+    for (const [tier, model] of Object.entries(selections)) {
+      println(`  ${tier.padEnd(11)} ${model}`);
+    }
+    println('Written to ~/.construct/config.env. Running construct sync...');
+    setCheapestProviderPreference(envPath, true);
+    await cmdSync([]);
+    return;
+  }
   const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'agents', 'registry.json'), 'utf8'));
   const result = readCurrentModels(envPath, registry.models ?? {});
   const nothingSelected = ['reasoning', 'standard', 'fast'].every((t) => !result[t]);

package/lib/document-ingest.mjs

@@ -77,7 +77,7 @@ function renderMarkdown({ sourcePath, extractedAt, title, extractionMethod, char
   return lines.join('\n');
 }
 
-function collectInputFiles(inputPath) {
+function collectInputFiles(inputPath, { maxDepth = 10 } = {}) {
   const resolvedPath = resolve(inputPath);
   if (!existsSync(resolvedPath)) throw new Error(`Input path not found: ${resolvedPath}`);
 
@@ -90,13 +90,14 @@ function collectInputFiles(inputPath) {
   if (!stat.isDirectory()) return [];
 
   const files = [];
-  const stack = [resolvedPath];
+  const stack = [{ path: resolvedPath, depth: 0 }];
   while (stack.length > 0) {
-    const current = stack.pop();
+    const { path: current, depth } = stack.pop();
+    if (depth >= maxDepth) continue;
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       const full = join(current, entry.name);
       if (entry.isDirectory()) {
-        stack.push(full);
+        stack.push({ path: full, depth: depth + 1 });
         continue;
       }
       if (entry.isFile() && isExtractableDocumentPath(full)) files.push(full);
@@ -135,7 +136,7 @@ export async function ingestDocuments(inputPaths, {
     throw new Error('--out can only be used with a single input path');
   }
 
-  const files = inputPaths.flatMap((inputPath) => collectInputFiles(isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath)));
+  const files = inputPaths.flatMap((inputPath) => collectInputFiles(isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath), { maxDepth: 10 }));
   if (files.length === 0) {
     throw new Error('No supported document files found');
   }

package/lib/embed/cli.mjs

@@ -174,7 +174,7 @@ function parseArgs(args) {
 // Subcommand: start
 // ---------------------------------------------------------------------------
 
-async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir } = {}) {
+async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPath, _livenessCheckMs = 400 } = {}) {
   const existing = readRunningState(homeDir);
   if (existing) {
     process.stdout.write(`embed daemon already running (pid ${existing.pid})\n`);
@@ -188,7 +188,11 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir } = {}) {
       ? path.join(os.homedir(), '.construct', 'embed.yaml')
       : null;
 
-  const workerPath = path.join(rootDir, 'lib', 'embed', 'worker.mjs');
+  const workerPath = _workerPath ?? path.join(rootDir, 'lib', 'embed', 'worker.mjs');
+  if (!fs.existsSync(workerPath)) {
+    throw new Error(`embed worker not found at ${workerPath}`);
+  }
+
   const workerArgs = configPath ? [workerPath, '--config', configPath] : [workerPath];
   const log = logPath(homeDir);
   fs.mkdirSync(path.dirname(log), { recursive: true });
@@ -199,9 +203,18 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir } = {}) {
     stdio: ['ignore', fd, fd],
     env: { ...process.env },
   });
+  fs.closeSync(fd);
   child.unref();
 
   writeState({ pid: child.pid, configPath: configPath ?? 'auto', startedAt: new Date().toISOString() }, homeDir);
+
+  // Brief liveness check — detects immediate crashes (e.g. missing module, bad config path)
+  await new Promise(r => setTimeout(r, _livenessCheckMs));
+  if (!processExists(child.pid)) {
+    clearState(homeDir);
+    throw new Error(`embed worker (pid ${child.pid}) exited immediately — check ${log}`);
+  }
+
   process.stdout.write(`embed daemon started (pid ${child.pid})\n`);
   process.stdout.write(`config: ${configPath ?? 'auto-discover from config.env'}\n`);
   process.stdout.write(`log:    ${log}\n`);
@@ -299,7 +312,7 @@ export async function runEmbedCli(args, opts = {}) {
   const rootDir = opts.rootDir ?? new URL('../..', import.meta.url).pathname;
 
   switch (sub) {
-    case 'start':       return cmdEmbedStart(subArgs, { homeDir, rootDir });
+    case 'start':       return cmdEmbedStart(subArgs, { homeDir, rootDir, _workerPath: opts._workerPath, _livenessCheckMs: opts._livenessCheckMs });
     case 'stop':        return cmdEmbedStop(subArgs, { homeDir });
     case 'status':      return cmdEmbedStatus(subArgs, { homeDir });
     case 'snapshot':    return cmdEmbedSnapshot(subArgs, { homeDir });

package/lib/embed/customer-profiles.mjs

@@ -3,7 +3,7 @@
  *
  * Maintains durable customer/account memory in ~/.cx/product-intel/customer-profiles/.
  * Profiles are additive — history is preserved unless explicitly deleted.
- * Used by intake triage to link signals to customers and detect account-level patterns.
+ * Links signals to customers and detects account-level patterns during intake triage.
  *
  * Storage:
  *   ~/.cx/product-intel/customer-profiles/<customer-id>.md

package/lib/embed/daemon.mjs

@@ -58,8 +58,8 @@ function logCatch(source, err) {
 
 /**
  * Resolve an LLM API key from multiple sources: env → config.env → ~/.env → shell rc.
- * Used by the telemetry-generation probe so it can find keys stored via 1Password
- * op:// refs in .zshrc or other shell config files.
+ * Supports 1Password op:// refs in .zshrc or other shell config files for the
+ * telemetry-generation probe.
  */
 async function resolveLLMKey(varName, env) {
   if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
@@ -575,7 +575,8 @@ this.#scheduler.register(
         const ok = result.results.filter(r => r.success).length;
         const total = result.results.length;
         process.stderr.write(`[embed] Telemetry setup: ${ok}/${total} resources configured\n`);
-      } else if (!result.ok) {
+      } else if (!result.ok && !result.error?.includes('required')) {
+        // Suppress the "keys required" message — normal for solo mode without telemetry configured.
         process.stderr.write(`[embed] Telemetry setup skipped: ${result.error}\n`);
       } else if (result.results?.some(r => !r.success)) {
         const failures = result.results.filter(r => !r.success);
@@ -840,21 +841,23 @@ this.#scheduler.register(
               meta: { gaps: result.gaps.length, conflicts: result.conflicts?.length || 0, recommendations: result.recommendations?.length || 0, autoFixed, queued },
             });
           }
-          emitTraceEvent({
-            rootDir: this.#rootDir,
-            eventType: 'lifecycle.completed',
-            traceId: this.#daemonTraceId,
-            spanId: newSpanId(),
-            env: this.#env,
-            metadata: {
-              gaps: result.gaps.length,
-              conflicts: result.conflicts?.length || 0,
-              recommendations: result.recommendations?.length || 0,
-              autoFixed,
-              queued,
-              targets: result.targets,
-            },
-          }).catch(() => {});
+          try {
+            emitTraceEvent({
+              rootDir: this.#rootDir,
+              eventType: 'lifecycle.completed',
+              traceId: this.#daemonTraceId,
+              spanId: newSpanId(),
+              env: this.#env,
+              metadata: {
+                gaps: result.gaps.length,
+                conflicts: result.conflicts?.length || 0,
+                recommendations: result.recommendations?.length || 0,
+                autoFixed,
+                queued,
+                targets: result.targets,
+              },
+            });
+          } catch { /* observability must not break the caller */ }
         } catch (err) {
           process.stderr.write(`[embed] Docs lifecycle error: ${err.message}\n`);
         }
@@ -1114,18 +1117,20 @@ this.#scheduler.register(
 
     this.#status = 'running';
     this.#daemonTraceId = newTraceId();
-    emitTraceEvent({
-      rootDir: this.#rootDir,
-      eventType: 'daemon.started',
-      traceId: this.#daemonTraceId,
-      spanId: newSpanId(),
-      env: this.#env,
-      metadata: {
-        pid: process.pid,
-        configSnapshotIntervalMs: this.#config.snapshot.intervalMs,
-        version: process.env.CONSTRUCT_VERSION || '0.0.0',
-      },
-    }).catch(() => {});
+    try {
+      emitTraceEvent({
+        rootDir: this.#rootDir,
+        eventType: 'daemon.started',
+        traceId: this.#daemonTraceId,
+        spanId: newSpanId(),
+        env: this.#env,
+        metadata: {
+          pid: process.pid,
+          configSnapshotIntervalMs: this.#config.snapshot.intervalMs,
+          version: process.env.CONSTRUCT_VERSION || '0.0.0',
+        },
+      });
+    } catch { /* observability must not break the caller */ }
     process.stderr.write(`[embed] Daemon started. Snapshot interval: ${this.#config.snapshot.intervalMs}ms\n`);
   }
 
@@ -1134,14 +1139,16 @@ this.#scheduler.register(
     this.#inboxLiveWatcher = null;
     this.#scheduler?.stop();
     this.#status = 'stopped';
-    emitTraceEvent({
-      rootDir: this.#rootDir,
-      eventType: 'daemon.stopped',
-      traceId: this.#daemonTraceId,
-      spanId: newSpanId(),
-      env: this.#env,
-      metadata: { pid: process.pid, uptimeMs: process.uptime() * 1000 },
-    }).catch(() => {});
+    try {
+      emitTraceEvent({
+        rootDir: this.#rootDir,
+        eventType: 'daemon.stopped',
+        traceId: this.#daemonTraceId,
+        spanId: newSpanId(),
+        env: this.#env,
+        metadata: { pid: process.pid, uptimeMs: process.uptime() * 1000 },
+      });
+    } catch { /* observability must not break the caller */ }
     process.stderr.write('[embed] Daemon stopped.\n');
   }
 
@@ -1182,10 +1189,10 @@ this.#scheduler.register(
      try {
        // Query strategy/PRDs/RFCs from knowledge base
        
-       const strategyDocs = searchObservations(this.#rootDir, 'PRD RFC strategy', {
-         category: 'knowledge',
-         limit: 50,
-       });
+        const strategyDocs = searchObservations(this.#rootDir, 'PRD RFC strategy', {
+          category: 'insight',
+          limit: 50,
+        });
        
        // Query existing Jira tickets via Atlassian provider
        

package/lib/embed/inbox.mjs

@@ -36,6 +36,7 @@ const STATE_FILE = '.cx/runtime/inbox-state.json';
 const DEFAULT_INBOX_SUBDIR = '.cx/inbox';
 const DOCS_INTAKE_SUBDIR = 'docs/intake';
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB hard cap
+const STALE_STATE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 function nextAvailablePath(targetPath) {
   if (!existsSync(targetPath)) return targetPath;
@@ -50,6 +51,28 @@ function nextAvailablePath(targetPath) {
   }
 }
 
+// ─── Stale state pruning ─────────────────────────────────────────────────────
+
+/**
+ * Remove state entries for source files absent from disk for more than 7 days.
+ * Returns the count of removed entries.
+ */
+function pruneStaleState(rootDir, state) {
+  const cutoffMs = Date.now() - STALE_STATE_AGE_MS;
+  let removed = 0;
+  for (const key of Object.keys(state)) {
+    const entry = state[key];
+    if (!existsSync(key) && entry.processedAt) {
+      const processedMs = new Date(entry.processedAt).getTime();
+      if (processedMs < cutoffMs) {
+        delete state[key];
+        removed++;
+      }
+    }
+  }
+  return removed;
+}
+
 // ─── State helpers ────────────────────────────────────────────────────────────
 
 function statePath(rootDir) {
@@ -327,6 +350,13 @@ export class InboxWatcher {
       }
     }
 
+    // Prune stale state entries: remove entries for source files absent from disk
+    // for more than 7 days (covers moved/renamed files that linger in state).
+    const staleRemoved = pruneStaleState(this.#rootDir, state);
+    if (staleRemoved > 0) {
+      process.stderr.write(`[inbox] pruned ${staleRemoved} stale state entries\n`);
+    }
+
     if (processed.length || errors.length) {
       writeState(this.#rootDir, state);
     }

package/lib/embed/recommendation-store.mjs

@@ -191,7 +191,7 @@ export function dismissRecommendation(dedupKey, { reason = 'manually dismissed',
 }
 
 /**
- * Supersede a recommendation (mark as replaced by a newer one).
+ * Supersede a recommendation (mark as superseded by a newer one).
  *
  * @param {string} dedupKey - Existing recommendation to supersede
  * @param {string} supersedingId - ID of the recommendation that replaces it

package/lib/evaluator-optimizer.mjs

@@ -26,8 +26,6 @@
  *   }
  */
 
-import { getTemplate } from './templates.mjs';
-
 const DEFAULT_THRESHOLD = 0.7;
 const DEFAULT_MAX_ITERATIONS = 3;
 

package/lib/features.mjs

@@ -287,6 +287,17 @@ function buildFeatures(overrides = {}) {
       if (platforms.length > 0) {
         return { status: 'configured', message: `Configured in ${platforms.join(', ')}` };
       }
+      // If every host explicitly marks this MCP as unsupported, it is delivered
+      // through the built-in construct-mcp stdio server — not a standalone tool.
+      const hostSupportEntries = Object.values(mcp.hostSupport ?? {});
+      const allUnsupported = hostSupportEntries.length > 0 &&
+        hostSupportEntries.every((s) => {
+          const mode = typeof s === 'string' ? s : (s?.mode ?? 'managed');
+          return mode === 'unsupported';
+        });
+      if (allUnsupported) {
+        return { status: 'configured', message: 'Available via construct-mcp (built-in)' };
+      }
       return { status: 'unavailable', message: 'Not configured in any host' };
     },
   }));

package/lib/health-check.mjs

@@ -2,10 +2,8 @@
 /**
  * lib/health-check.mjs — reusable prerequisite and health checks.
  *
- * Used by:
- * - `construct dev` (auto-checks before starting services)
- * - `construct doctor` (comprehensive system audit)
- * - `construct init` (pre-init validation)
+ * Prerequisite and health check runners for `construct dev`, `construct doctor`,
+ * and `construct init`.
  */
 
 import { spawnSync } from 'node:child_process';

package/lib/init-unified.mjs

@@ -1066,10 +1066,10 @@ async function main() {
     if (verbose) console.log('\nStarting services...');
     try {
       const { startServices } = await import('./service-manager.mjs');
-      const { os } = await import('node:os');
+      const { homedir } = await import('node:os');
       const { detectDockerCompose } = await import('./setup.mjs');
       
-      const homeDir = os.homedir();
+      const homeDir = homedir();
       const composeRunner = detectDockerCompose();
       
       const { results } = await startServices({

package/lib/integrations/intake-integrations.mjs

@@ -222,7 +222,7 @@ function buildLabels(t) {
 // ── Jira ─────────────────────────────────────────────────────────────────
 
 /**
- * Create a Jira ticket from an intake packet.
+ * Create a Jira work item from an intake packet.
  *
  * @param {object} packet - Intake packet with triage, excerpt
  * @param {object} [opts]
@@ -276,8 +276,7 @@ export async function createJiraTicket(packet, { host, email, token, project, is
 
     const json = await res.json();
 
-    // We don't have the browse URL directly from the create response,
-    // so construct it from the host + issue key
+    // Browse URL is absent from the create response — construct from host + issue key
     const issueKey = json.key;
     const browseUrl = `${resolvedHost.replace(/\/$/, '')}/browse/${issueKey}`;
 
@@ -474,8 +473,8 @@ async function updateConfluencePage(artifact, { host, email, token, space, fetch
 }
 
 /**
- * Minimal markdown to Confluence storage format conversion.
- * Handles the subset of markdown used by Construct artifacts.
+ * Converts the subset of markdown common to Construct artifacts into
+ * Confluence storage format.
  */
 function markdownToConfluenceStorage(md) {
   if (!md) return '';

package/lib/knowledge/rag.mjs

@@ -155,6 +155,21 @@ function loadSnapshotChunks(rootDir) {
   return chunks;
 }
 
+/**
+ * Load ingested knowledge files from .cx/knowledge/ subdirectories.
+ */
+function loadKnowledgeChunks(rootDir) {
+  const knowledgeRoot = path.resolve(rootDir, '.cx/knowledge');
+  const subdirs = ['internal', 'external', 'decisions', 'how-tos', 'reference'];
+  const chunks = [];
+  for (const subdir of subdirs) {
+    const full = path.join(knowledgeRoot, subdir);
+    if (!fs.existsSync(full)) continue;
+    chunks.push(...loadMarkdownChunks(full, 'knowledge'));
+  }
+  return chunks;
+}
+
 // ── Index builder ──────────────────────────────────────────────────────────
 
 /**
@@ -166,6 +181,7 @@ export function buildCorpus(rootDir = process.cwd()) {
     ...loadObservationChunks(rootDir),
     ...loadArtifactChunks(rootDir),
     ...loadSnapshotChunks(rootDir),
+    ...loadKnowledgeChunks(rootDir),
   ];
 
   // Embed each chunk

package/lib/model-cheapest-provider.mjs

@@ -0,0 +1,231 @@
+/**
+ * lib/model-cheapest-provider.mjs — cheapest configured provider selection.
+ *
+ * Evaluates all configured providers, looks up their per-tier model pricing,
+ * and returns the lowest-cost option. Local providers (Ollama, local) rank
+ * first since they are $0.
+ *
+ * Pricing data comes from getPricingForModels() in model-pricing.mjs, which
+ * has a 5-minute cache from the OpenRouter API. Static tables cover
+ * Anthropic/OpenAI first-party models.
+ *
+ * Usage:
+ *   selectCheapestProvider('standard')          // cheapest for one tier
+ *   rankConfiguredProvidersByCost('fast')       // full ranked list
+ *   isCheapestProviderEnabled()                 // check opt-in preference
+ *   formatCheapestProviderMessage(result)       // user-facing output
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getProviderModelCatalog, PROVIDER_FAMILY_TIERS } from './model-router.mjs';
+import { getPricingForModels, formatPricingLabel } from './model-pricing.mjs';
+
+const CHEAPEST_PREF_KEY = 'CHEAPEST_PROVIDER_ENABLED';
+const CHEAPEST_CHECKED_KEY = 'CHEAPEST_PROVIDER_CHECKED';
+const ENV_PATH = path.join(os.homedir(), '.construct', 'config.env');
+
+/**
+ * Resolve the cheapest configured provider for a given tier.
+ *
+ * @param {string} tier - One of "reasoning", "standard", "fast"
+ * @param {object} [opts]
+ * @param {object} [opts.env] - Environment object (default: process.env)
+ * @param {string} [opts.envPath] - Path to config.env (default: ~/.construct/config.env)
+ * @param {Function} [opts.getPricingForModels] - Injectable pricing fetcher
+ * @returns {Promise<{
+ *   providerId: string|null,
+ *   providerLabel: string|null,
+ *   modelId: string|null,
+ *   inputPrice: number|null,
+ *   outputPrice: number|null,
+ *   isLocal: boolean,
+ *   configuredProviders: string[],
+ *   rankedList: Array<{providerId, providerLabel, modelId, inputPrice, outputPrice, totalPer1M, isLocal}>
+ * }>}
+ */
+export async function selectCheapestProvider(tier, opts = {}) {
+  if (!['reasoning', 'standard', 'fast'].includes(tier)) {
+    return { providerId: null, providerLabel: null, modelId: null, configuredProviders: [], rankedList: [] };
+  }
+
+  const env = opts.env || process.env;
+  const catalog = getProviderModelCatalog({ env });
+  const configured = catalog.providers.filter((p) => p.configured);
+
+  if (configured.length === 0) {
+    return {
+      providerId: null, providerLabel: null, modelId: null,
+      inputPrice: null, outputPrice: null, isLocal: false,
+      configuredProviders: [], rankedList: [],
+    };
+  }
+
+  // Collect tier-specific model IDs from all configured providers
+  const modelIds = [];
+  for (const p of configured) {
+    const modelId = p.tiers[tier];
+    if (modelId) modelIds.push(modelId);
+  }
+
+  const needsRemote = modelIds.filter((id) => /^openrouter\//.test(id));
+  const hasRemote = needsRemote.length > 0;
+
+  // Fetch pricing (uses 5-min cache internally)
+  let pricingMap = {};
+  if (hasRemote) {
+    try {
+      pricingMap = await getPricingForModels(modelIds, {
+        getPricingForModels: opts.getPricingForModels,
+      });
+    } catch { /* pricing unavailable — fall back to nulls */ }
+  }
+
+  // Score each provider
+  const scored = configured.map((p) => {
+    const modelId = p.tiers[tier];
+    const pricing = hasRemote ? pricingMap[modelId] : null;
+    const inputPrice = pricing ? (Number(pricing.input) || 0) : 0;
+    const outputPrice = pricing ? (Number(pricing.output) || 0) : 0;
+    return {
+      providerId: p.id,
+      providerLabel: p.label,
+      modelId,
+      inputPrice,
+      outputPrice,
+      totalPer1M: inputPrice + outputPrice,
+      isLocal: p.local === true,
+    };
+  });
+
+  // Sort ascending by total cost (local/$0 first)
+  scored.sort((a, b) => a.totalPer1M - b.totalPer1M);
+
+  const cheapest = scored[0];
+  return {
+    providerId: cheapest.providerId,
+    providerLabel: cheapest.providerLabel,
+    modelId: cheapest.modelId,
+    inputPrice: cheapest.inputPrice,
+    outputPrice: cheapest.outputPrice,
+    isLocal: cheapest.isLocal,
+    configuredProviders: configured.map((p) => p.id),
+    rankedList: scored,
+  };
+}
+
+/**
+ * Get all configured providers ranked by cost for a tier.
+ *
+ * @param {string} tier
+ * @param {object} [opts]
+ * @returns {Promise<Array<{providerId, providerLabel, modelId, inputPrice, outputPrice, totalPer1M, isLocal}>>}
+ */
+export async function rankConfiguredProvidersByCost(tier, opts = {}) {
+  const result = await selectCheapestProvider(tier, opts);
+  return result.rankedList;
+}
+
+/**
+ * Check if the user has opted into cheapest-provider selection.
+ *
+ * @param {string} [envPath] - Path to config.env (default: ~/.construct/config.env)
+ * @param {object} [opts.env] - Environment override
+ * @returns {boolean}
+ */
+export function isCheapestProviderEnabled(envPath, opts = {}) {
+  const pathToUse = envPath || ENV_PATH;
+  const env = opts.env || process.env;
+
+  // Check env var first
+  if (env[CHEAPEST_PREF_KEY]) {
+    return env[CHEAPEST_PREF_KEY].toLowerCase() === 'yes';
+  }
+
+  // Check config.env file
+  try {
+    const content = fs.readFileSync(pathToUse, 'utf8');
+    const match = content.match(new RegExp(`^${CHEAPEST_PREF_KEY}=(.+)$`, 'm'));
+    if (match) {
+      return match[1].trim().toLowerCase() === 'yes';
+    }
+  } catch { /* file doesn't exist */ }
+
+  return false;
+}
+
+/**
+ * Persist the cheapest-provider opt-in preference.
+ *
+ * @param {string} envPath - Path to config.env
+ * @param {boolean} enabled
+ */
+export function setCheapestProviderPreference(envPath, enabled) {
+  const pathToUse = envPath || ENV_PATH;
+  const existing = fs.existsSync(pathToUse) ? fs.readFileSync(pathToUse, 'utf8') : '';
+  const lines = existing.split('\n');
+  const keyLine = `${CHEAPEST_PREF_KEY}=${enabled ? 'yes' : 'no'}`;
+
+  // Replace existing key or append
+  const idx = lines.findIndex((l) => l.startsWith(`${CHEAPEST_PREF_KEY}=`));
+  if (idx >= 0) {
+    lines[idx] = keyLine;
+  } else {
+    lines.push(keyLine);
+  }
+
+  fs.mkdirSync(path.dirname(pathToUse), { recursive: true });
+  fs.writeFileSync(pathToUse, lines.join('\n'));
+}
+
+/**
+ * Format the cheapest provider selection into a user-facing message.
+ *
+ * @param {object} result - Output from selectCheapestProvider
+ * @param {object} [opts]
+ * @param {boolean} [opts.showRanking] - Include full ranked list
+ * @returns {string}
+ */
+export function formatCheapestProviderMessage(result, opts = {}) {
+  const { providerId, providerLabel, modelId, inputPrice, outputPrice, isLocal, rankedList } = result;
+
+  if (!providerId) {
+    return 'No configured providers found. Set API keys or install Ollama to enable model selection.';
+  }
+
+  const label = formatPricingLabel({ input: inputPrice, output: outputPrice, source: isLocal ? 'local' : 'openrouter' });
+  let msg = `Cheapest provider for this tier:\n`;
+  msg += `  Provider:  ${providerLabel}\n`;
+  msg += `  Model:     ${modelId}\n`;
+  msg += `  Pricing:   ${label}`;
+
+  if (opts.showRanking && rankedList && rankedList.length > 0) {
+    msg += `\n\nConfigured providers ranked by cost:\n`;
+    for (let i = 0; i < rankedList.length; i++) {
+      const r = rankedList[i];
+      const rLabel = formatPricingLabel({
+        input: r.inputPrice,
+        output: r.outputPrice,
+        source: r.isLocal ? 'local' : 'openrouter',
+      });
+      const marker = i === 0 ? '→' : ' ';
+      msg += `  ${marker} ${r.providerLabel.padEnd(28)} ${r.modelId.padEnd(40)} ${rLabel}\n`;
+    }
+  }
+
+  return msg;
+}
+
+/**
+ * Get all tier-specific cheapest selections.
+ *
+ * @param {object} [opts]
+ * @returns {Promise<{reasoning, standard, fast}>}
+ */
+export async function selectCheapestForAllTiers(opts = {}) {
+  const reasoning = await selectCheapestProvider('reasoning', opts);
+  const standard = await selectCheapestProvider('standard', opts);
+  const fast = await selectCheapestProvider('fast', opts);
+  return { reasoning, standard, fast };
+}

package/lib/model-router.mjs

@@ -217,9 +217,8 @@ const PROVIDER_FAMILY_TIERS = [
 export { PROVIDER_FAMILY_TIERS };
 
 /**
- * Map provider family IDs to the env var(s) that indicate the provider
- * is configured (has credentials). Used by getProviderModelCatalog to
- * mark which providers are available.
+ * Maps provider family IDs to the env var(s) that confirm credentials are present.
+ * Consumed by getProviderModelCatalog to mark which providers are available.
  */
 const PROVIDER_ENV_MAP = {
   'anthropic': ['ANTHROPIC_API_KEY'],
@@ -254,14 +253,14 @@ function isProviderConfigured(familyId, env) {
     } catch { /* not available */ }
   }
 
-  // 1. Check passed env (usually process.env)
+  // Check passed env (usually process.env)
   const anyInEnv = varNames.some(name => {
     const val = env?.[name];
     return val && typeof val === 'string' && val.length > 0;
   });
   if (anyInEnv) return true;
 
-  // 2. Check construct config.env
+  // Check construct config.env
   try {
     const homeDir = process.env.HOME || process.env.USERPROFILE || '/tmp';
     const cfgPath = path.join(homeDir, '.construct', 'config.env');
@@ -276,7 +275,7 @@ function isProviderConfigured(familyId, env) {
     }
   } catch { /* skip */ }
 
-  // 3. Special case: GitHub Copilot via gh CLI
+  // GitHub Copilot: detect via gh CLI auth status
   if (familyId === 'github-copilot') {
     try {
       const r = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 3000 });
@@ -284,7 +283,7 @@ function isProviderConfigured(familyId, env) {
     } catch { return false; }
   }
 
-  // 4. Check ~/.env
+  // Check ~/.env
   try {
     const homeEnv = path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.env');
     if (fs.existsSync(homeEnv)) {
@@ -298,7 +297,7 @@ function isProviderConfigured(familyId, env) {
     }
   } catch { /* skip */ }
 
-  // 5. Check shell rc files for op:// refs (1Password CLI integration)
+  // Check shell rc files for op:// refs (1Password CLI integration)
   try {
     const homeDir = process.env.HOME || process.env.USERPROFILE || '/tmp';
     const shellFiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map(f => path.join(homeDir, f));

package/lib/roles/catalog.mjs

@@ -0,0 +1,133 @@
+/**
+ * lib/roles/catalog.mjs — role listing and display helpers.
+ *
+ * Reads agents/registry.json to produce a list of available roles with
+ * optional department grouping and consolidated-role views. Consumed by the
+ * `roles:list` CLI command.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REGISTRY_PATH = join(__dirname, '..', '..', 'agents', 'registry.json');
+
+let cached = null;
+
+function loadRegistry() {
+  if (cached) return cached;
+  cached = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
+  return cached;
+}
+
+/**
+ * Return a list of role descriptors.
+ *
+ * @param {object}  opts
+ * @param {boolean} opts.departments   Group by department when true.
+ * @param {boolean} opts.consolidated  Return consolidated 12-role view when true.
+ * @returns {Array<object>}
+ */
+export function listRoles({ departments = false, consolidated = false } = {}) {
+  const registry = loadRegistry();
+
+  if (consolidated) {
+    const c = registry.consolidatedRoles || {};
+    return (c.roles || []).map((r) => ({
+      id: r.id,
+      absorbs: r.absorbs || [],
+      whenToUse: r.whenToUse || '',
+    }));
+  }
+
+  const agents = Array.isArray(registry.agents)
+    ? registry.agents
+    : Object.values(registry.agents || {});
+
+  if (!departments) {
+    return agents.map((a) => ({
+      id: a.name,
+      name: `cx-${a.name}`,
+      description: a.description || '',
+      internal: !!a.internal,
+    }));
+  }
+
+  // Group by department based on subDepartment membership in registry.departments
+  const depts = registry.departments || {};
+  const grouped = {};
+  for (const [deptId, dept] of Object.entries(depts)) {
+    grouped[deptId] = {
+      name: dept.name || deptId,
+      roles: [],
+    };
+  }
+  grouped._ungrouped = { name: 'Other', roles: [] };
+
+  for (const agent of agents) {
+    let placed = false;
+    for (const [deptId, dept] of Object.entries(depts)) {
+      const subs = dept.subDepartments || {};
+      for (const sub of Object.values(subs)) {
+        if ((sub.roles || []).includes(agent.name) || (sub.roles || []).includes(`cx-${agent.name}`)) {
+          grouped[deptId].roles.push({ id: agent.name, name: `cx-${agent.name}`, description: agent.description || '' });
+          placed = true;
+          break;
+        }
+      }
+      if (placed) break;
+    }
+    if (!placed) {
+      grouped._ungrouped.roles.push({ id: agent.name, name: `cx-${agent.name}`, description: agent.description || '' });
+    }
+  }
+
+  return Object.entries(grouped)
+    .filter(([, g]) => g.roles.length > 0)
+    .map(([id, g]) => ({ departmentId: id, departmentName: g.name, roles: g.roles }));
+}
+
+/**
+ * Format the role list as a human-readable string.
+ *
+ * @param {object}  opts  Same options as listRoles.
+ * @returns {string}
+ */
+export function formatRoleList({ departments = false, consolidated = false } = {}) {
+  const roles = listRoles({ departments, consolidated });
+  const lines = [];
+
+  if (consolidated) {
+    lines.push('Consolidated Roles (12-role simplified structure)');
+    lines.push('=================================================');
+    for (const r of roles) {
+      lines.push(`\n${r.id}`);
+      lines.push(`  Absorbs: ${r.absorbs.join(', ')}`);
+      lines.push(`  Use when: ${r.whenToUse}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  if (departments) {
+    lines.push('Available Roles by Department');
+    lines.push('=============================');
+    for (const group of roles) {
+      lines.push(`\n${group.departmentName}`);
+      for (const role of group.roles) {
+        lines.push(`  ${role.name.padEnd(30)} ${role.description}`);
+      }
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('Available Roles');
+  lines.push('===============');
+  for (const role of roles) {
+    lines.push(`  ${role.name.padEnd(30)} ${role.description}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/lib/roles/preference.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/roles/preference.mjs — per-user primary/secondary role preferences.
+ *
+ * Persists role preferences to ~/.construct/config.env under the keys
+ * CONSTRUCT_ROLE_PRIMARY and CONSTRUCT_ROLE_SECONDARY. Consumed by the
+ * `roles:set` CLI command and the orchestration layer.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+import { getUserEnvPath, ensureUserConfigDir, writeEnvValues, parseEnvFile } from '../env-config.mjs';
+
+const ENV_KEYS = {
+  primary: 'CONSTRUCT_ROLE_PRIMARY',
+  secondary: 'CONSTRUCT_ROLE_SECONDARY',
+};
+
+/**
+ * Read the stored role preference for the given slot.
+ *
+ * @param {'primary'|'secondary'} slot
+ * @returns {string|null}  The stored role id, or null if unset.
+ */
+export function getRolePreference(slot) {
+  const envKey = ENV_KEYS[slot];
+  if (!envKey) return null;
+
+  // Env var takes priority (allows per-session override)
+  if (process.env[envKey]) return process.env[envKey];
+
+  const envPath = getUserEnvPath(os.homedir());
+  const stored = parseEnvFile(envPath);
+  return stored[envKey] || null;
+}
+
+/**
+ * Persist a role preference for the given slot.
+ *
+ * @param {'primary'|'secondary'} slot
+ * @param {string} role  Role id (e.g. "cx-engineer" or "engineer").
+ * @returns {{ slot: string, role: string }}
+ */
+export function setRolePreference(slot, role) {
+  const envKey = ENV_KEYS[slot];
+  if (!envKey) throw new Error(`Unknown role slot "${slot}". Use "primary" or "secondary".`);
+
+  // Normalise: accept both "engineer" and "cx-engineer"
+  const normalised = role.startsWith('cx-') ? role : `cx-${role}`;
+
+  ensureUserConfigDir(os.homedir());
+  const envPath = getUserEnvPath(os.homedir());
+  writeEnvValues(envPath, { [envKey]: normalised });
+
+  // Also set in current process so the change is visible immediately
+  process.env[envKey] = normalised;
+
+  return { slot, role: normalised };
+}
+
+/**
+ * Clear a stored role preference.
+ *
+ * @param {'primary'|'secondary'} slot
+ */
+export function clearRolePreference(slot) {
+  const envKey = ENV_KEYS[slot];
+  if (!envKey) return;
+
+  delete process.env[envKey];
+
+  const envPath = getUserEnvPath(os.homedir());
+  writeEnvValues(envPath, { [envKey]: '' });
+}

package/lib/server/index.mjs

@@ -250,6 +250,25 @@ const MIME = {
   '.js': 'text/javascript; charset=utf-8',
   '.css': 'text/css; charset=utf-8',
   '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.xml': 'application/xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.manifest': 'text/cache-manifest',
+  '.map': 'application/json',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.otf': 'font/otf',
+  '.mp4': 'video/mp4',
+  '.mp3': 'audio/mpeg',
+  '.pdf': 'application/pdf',
 };
 
 function listCommands() {
@@ -1062,56 +1081,10 @@ const server = createServer(async (req, res) => {
     try {
       const env = loadConstructEnv();
       const instanceId = env.CONSTRUCT_INSTANCE_ID || 'default';
-      
-      // Check if we're running inside another Construct instance
-      const parentConstruct = env.CONSTRUCT_PARENT_INSTANCE || null;
-      const parentUrl = env.CONSTRUCT_PARENT_URL || null;
-      
-      // Determine embedding boundary status
-      const isEmbedded = !!parentConstruct;
-      const boundaryStatus = isEmbedded ? 'embedded' : 'standalone';
-      
-      // Get current embed status
-      const embedStatus = resolveEmbedStatus(env);
-      
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ 
-        boundaryStatus,
-        instanceId,
-        parentConstruct,
-        parentUrl,
-        isEmbedded,
-        embedStatus: embedStatus.level,
-        embedConfigExists: existsSync(join(HOME, '.construct', 'embed.yaml')),
-        // Boundary capabilities that could be exposed to parent
-        capabilities: {
-          modeDetection: true,
-          snapshotStatus: true,
-          approvalQueue: true,
-          configManagement: true
-        }
-      }));
-    } catch (err) {
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: err.message }));
-    }
-    return;
-  }
-
-  if (url.pathname === '/api/embed/boundary' && req.method === 'GET') {
-    try {
-      const env = loadConstructEnv();
-      const instanceId = env.CONSTRUCT_INSTANCE_ID || 'default';
-      
-      // Check if we're running inside another Construct instance
       const parentConstruct = env.CONSTRUCT_PARENT_INSTANCE || null;
       const parentUrl = env.CONSTRUCT_PARENT_URL || null;
-      
-      // Determine embedding boundary status
       const isEmbedded = !!parentConstruct;
       const boundaryStatus = isEmbedded ? 'embedded' : 'standalone';
-      
-      // Get current embed status
       const embedStatus = resolveEmbedStatus(env);
       
       res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1123,7 +1096,6 @@ const server = createServer(async (req, res) => {
         isEmbedded,
         embedStatus: embedStatus.level,
         embedConfigExists: existsSync(join(HOME, '.construct', 'embed.yaml')),
-        // Boundary capabilities that could be exposed to parent
         capabilities: {
           modeDetection: true,
           snapshotStatus: true,
@@ -1358,6 +1330,20 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname === '/api/intake/list' && req.method === 'GET') {
+    try {
+      const { createIntakeQueue } = await import('../intake/queue.mjs');
+      const queue = createIntakeQueue(ROOT_DIR, process.env);
+      const items = queue.listPending();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ items, total: items.length }));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
   if (url.pathname === '/api/providers' && req.method === 'GET') {
     try {
       const probe = url.searchParams.get('probe') === '1';

package/lib/services/telemetry-backend.mjs

@@ -53,7 +53,7 @@ export async function verifyPostgresHealth({
   maxRetries = 5,
   intervalMs = 2000,
 } = {}) {
-  // We can't use fetch against Postgres (it's not HTTP), so just check pg_isready via docker
+  // Postgres is not HTTP — health is checked via pg_isready in docker instead
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     try {
       const result = spawnSync('docker', [

package/lib/setup.mjs

@@ -585,6 +585,50 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     console.log(`Embeddings: warmup skipped (${err?.message || 'unknown error'}) — model will load on first use`);
   }
 
+  // Cheapest provider selection — opt-out by default. When user consents,
+  // evaluate all configured providers, pick the lowest-cost model per tier,
+  // and write to config.env. On subsequent runs the preference is persisted
+  // so the prompt is skipped.
+
+  const { isCheapestProviderEnabled, selectCheapestForAllTiers, setCheapestProviderPreference, formatCheapestProviderMessage } =
+    await import('./model-cheapest-provider.mjs');
+  const cheapestAlreadyEnabled = isCheapestProviderEnabled(envPath, { env: process.env });
+  if (!cheapestAlreadyEnabled) {
+    const cheapestConsent = await consentToInstall({
+      name: 'cheapest-provider',
+      isYes,
+      alreadyConfigured: false,
+      envPath,
+      defaultYes: false,
+    });
+    if (cheapestConsent.decision) {
+      try {
+        const selections = await selectCheapestForAllTiers({ env: process.env });
+        const applied = {};
+        for (const tier of ['reasoning', 'standard', 'fast']) {
+          if (selections[tier]?.modelId) applied[tier] = selections[tier].modelId;
+        }
+        if (Object.keys(applied).length > 0) {
+          applyToEnv(envPath, applied);
+          console.log('\nCheapest providers applied:');
+          for (const [tier, model] of Object.entries(applied)) {
+            const label = selections[tier]?.providerLabel || '';
+            console.log(`  ${tier.padEnd(11)} ${model} (${label})`);
+          }
+        } else {
+          console.log('\nCheapest provider: no configured providers found — nothing to apply.');
+        }
+        setCheapestProviderPreference(envPath, true);
+      } catch (err) {
+        console.log(`Cheapest provider: skipped (${err?.message || 'unknown error'})`);
+      }
+    } else {
+      console.log(`Cheapest provider: skipped (${cheapestConsent.note})`);
+    }
+  } else {
+    console.log('Cheapest provider: already enabled — skipping prompt.');
+  }
+
   const hooksResult = ensureGitHooksPath({ cwd: process.cwd() });
   if (hooksResult.status === 'set') console.log(`Git hooks: ${hooksResult.message}`);
   else if (hooksResult.status === 'ok') console.log('Git hooks: wired');

package/lib/status.mjs

@@ -491,6 +491,7 @@ function traceBackendDefinition(env) {
     runtime: 'live',
     note: 'Trace backend',
     healthyMessage: 'Reachable',
+    impactsOverall: false,
   };
 }
 
@@ -588,6 +589,7 @@ function serviceDefinitions(env, dashboardPort, selfDashboard) {
       runtime: 'live',
       note: 'MCP-managed',
       healthyMessage: 'Reachable',
+      impactsOverall: false,
     },
     {
       id: 'opencode',
@@ -772,8 +774,8 @@ export async function buildStatus({
 }
 
 function serviceIcon(status) {
-  if (status === 'healthy') return '✓';
-  if (status === 'degraded' || status === 'configured') return '⚠';
+  if (status === 'healthy' || status === 'configured') return '✓';
+  if (status === 'degraded') return '⚠';
   return '✗';
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {