@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/security/trust.mjs

@@ -0,0 +1,132 @@
+/**
+ * lib/security/trust.mjs — Trust taxonomy and stamping primitives.
+ *
+ * Provides a machine-checkable trust hierarchy for all content that flows
+ * through Construct: ingested documents, recalled observations, provider
+ * responses, and built-in prompts. Callers stamp records at ingestion time
+ * and downstream consumers check the stamp before assembling model context.
+ *
+ * Integration into callers (ingest/embed/storage paths) is handled by
+ * follow-on beads (N2, N4). This module is additive — it exports utilities
+ * only; no existing code is modified.
+ *
+ * References: CX-AUDIT-LLMSEC-001, OWASP LLM01 [S12][S13], construct-9oi4.14.1
+ */
+
+// ---------------------------------------------------------------------------
+// Trust level taxonomy (ordered lowest → highest trust)
+// ---------------------------------------------------------------------------
+
+/** @type {Record<string, string>} */
+export const TRUST_LEVELS = {
+  /** Scraped or parsed content with no authorship verification (web pages,
+   *  docling-extracted text, unknown origin). Highest risk of injection. */
+  EXTERNAL_UNAUTHENTICATED: 'external-unauthenticated',
+
+  /** Content from an authenticated external actor: a known GitHub user's
+   *  issue-tracker comment, a named Jira reporter, a Confluence page with
+   *  attributed authorship. Lower risk but still untrusted. */
+  EXTERNAL_AUTHENTICATED: 'external-authenticated',
+
+  /** Authored by a member of the Construct team or project (e.g. a local
+   *  markdown file committed by the team). Trusted but not built-in. */
+  TEAM_AUTHORED: 'team-authored',
+
+  /** Built-in prompts, validated skill packs, and internal system content.
+   *  Full trust — assembled directly into the instruction channel. */
+  TRUSTED_INTERNAL: 'trusted-internal',
+};
+
+// Ordered list for comparison (index = rank, higher index = higher trust).
+const LEVEL_ORDER = [
+  TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  TRUST_LEVELS.TEAM_AUTHORED,
+  TRUST_LEVELS.TRUSTED_INTERNAL,
+];
+
+// ---------------------------------------------------------------------------
+// Stamping
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamp a trust label onto an observation or record object.
+ *
+ * @param {Record<string, unknown>} record  Source object (not mutated).
+ * @param {string}                  level   One of TRUST_LEVELS values.
+ * @param {string}                  source  Human-readable source descriptor.
+ * @returns {Record<string, unknown>} New object with `_trust` metadata added.
+ */
+export function stampTrust(record, level, source) {
+  if (!Object.values(TRUST_LEVELS).includes(level)) {
+    throw new TypeError(
+      `stampTrust: unknown trust level "${level}". ` +
+      `Valid values: ${Object.values(TRUST_LEVELS).join(', ')}`,
+    );
+  }
+  return {
+    ...record,
+    _trust: {
+      level,
+      source: String(source ?? 'unknown'),
+      stampedAt: Date.now(),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Level comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if `level` meets or exceeds `required` in the trust hierarchy.
+ *
+ * @param {string} level    The trust level of the content being checked.
+ * @param {string} required The minimum acceptable trust level.
+ * @returns {boolean}
+ */
+export function meetsMinTrustLevel(level, required) {
+  const levelIdx = LEVEL_ORDER.indexOf(level);
+  const requiredIdx = LEVEL_ORDER.indexOf(required);
+  if (levelIdx === -1 || requiredIdx === -1) return false;
+  return levelIdx >= requiredIdx;
+}
+
+// ---------------------------------------------------------------------------
+// Context assembly helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap external content with explicit untrusted delimiters so the model
+ * context assembler can visually and programmatically distinguish data from
+ * instructions.
+ *
+ * @param {string}                              content   Raw text content.
+ * @param {{ level: string, source: string }}   trustMeta Trust metadata.
+ * @returns {string} Delimited content string.
+ */
+export function wrapUntrusted(content, trustMeta) {
+  const level = trustMeta?.level ?? TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED;
+  const source = trustMeta?.source ?? 'unknown';
+  return `[UNTRUSTED:${level}:${source}]\n${content}\n[/UNTRUSTED]`;
+}
+
+// ---------------------------------------------------------------------------
+// Recall re-grading
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-grade a recalled record — returns the `_trust` meta object if present,
+ * or null if the record was stored without a trust stamp.
+ *
+ * Callers should treat a null return as EXTERNAL_UNAUTHENTICATED per policy.
+ *
+ * @param {Record<string, unknown>} record A recalled observation or document.
+ * @returns {{ level: string, source: string, stampedAt: number } | null}
+ */
+export function recallTrustGrade(record) {
+  if (record && typeof record._trust === 'object' && record._trust !== null) {
+    return record._trust;
+  }
+  return null;
+}

package/lib/service-manager.mjs

@@ -6,13 +6,14 @@
  * spawns whatever is available and returns a result per service.
  */
 import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { findAvailablePort } from './host-capabilities.mjs';
+import { findAvailablePort, detectActiveSessions } from './host-capabilities.mjs';
 import { wrapWithOpRun } from './providers/op-run.mjs';
 import { getUserEnvPath, loadConstructEnv, parseEnvFile, writeEnvValues } from './env-config.mjs';
 import { runPressureRelease } from './runtime-pressure.mjs';
@@ -22,6 +23,7 @@ import { readHeartbeat } from './daemons/contract.mjs';
 import { heartbeatPath } from './oracle/index.mjs';
 import { stateDir } from './config/xdg.mjs';
 import { doctorRoot } from './config/xdg.mjs';
+import { resolveStateDir } from './state-root.mjs';
 
 const INSTALL_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -163,13 +165,19 @@ async function isCopilotBridgeRunning(port) {
   return probeRuntimePort(port);
 }
 
-// Opt-in 1Password resolution (ADR-0049 Design A): each long-lived service launches
-// under `op run --env-file -- <cmd>` so op:// references resolve once at this stable
-// parent and every child inherits resolved provider keys. wrapWithOpRun returns the
-// command unchanged when CONSTRUCT_OP_ENV_FILE is unset, the file is missing, or `op`
-// is absent, so the un-opted path is byte-for-byte the prior behavior. The env that
-// carries CONSTRUCT_OP_ENV_FILE is options.env when a site sets one (doctor, oracle)
-// and process.env otherwise (cm, opencode, copilot bridge).
+// Opt-in 1Password resolution (ADR-0049 Design A): under `construct dev` the process
+// re-execs once under a single `op run --env-file` (maybeReExecUnderOpRun), so op://
+// references resolve one time at that stable parent and every daemon here inherits the
+// resolved keys through liveEnv — the CONSTRUCT_OP_RUN_ACTIVE sentinel then makes
+// wrapWithOpRun a no-op so no daemon nests a second op run. wrapWithOpRun stays the
+// fallback for daemons started outside that parent (an opencode/copilot-bridge restart
+// from a hook), wrapping them individually. It returns the command unchanged when
+// CONSTRUCT_OP_ENV_FILE is unset, the file is missing, `op` is absent, or the sentinel
+// is set, so the un-opted path is byte-for-byte the prior behavior. doctor, oracle, and
+// cm consume no provider API keys (construct-0wmj) and are spawned unwrapped; every
+// service is still spawned with the merged liveEnv, so config.env-only vars (including
+// CONSTRUCT_OP_ENV_FILE and an OP_SERVICE_ACCOUNT_TOKEN) reach the child rather than
+// only the wrapped op-run subset.
 
 function wrapServiceSpawn(command, args, homeDir, options = {}) {
   const env = options.env || process.env;
@@ -225,9 +233,9 @@ export function startDoctor({ rootDir, homeDir = os.homedir() } = {}) {
   if (existing) return { started: false, reused: true, pid: existing.pid };
   const indexPath = path.join(INSTALL_ROOT, 'lib', 'doctor', 'index.mjs');
   if (!fs.existsSync(indexPath)) return { started: false, reason: 'missing-binary' };
+  // doctor consumes no provider API keys (construct-0wmj) — no op-run wrap needed.
   const doctorEnv = { ...process.env };
-  const launch = wrapServiceSpawn('node', [indexPath], homeDir, { env: doctorEnv });
-  const { logPath } = spawnDetached(launch.command, launch.args, homeDir, 'doctor.log', { cwd: rootDir, env: doctorEnv });
+  const { logPath } = spawnDetached('node', [indexPath], homeDir, 'doctor.log', { cwd: rootDir, env: doctorEnv });
   return { started: true, logPath };
 }
 
@@ -244,8 +252,8 @@ export function startOracle({ rootDir, homeDir = os.homedir(), projectDir = root
     CONSTRUCT_ORACLE_ROOT: rootDir,
     CONSTRUCT_ORACLE_PROJECT: projectDir,
   };
-  const launch = wrapServiceSpawn('node', [entry], homeDir, { env: oracleEnv });
-  const { logPath } = spawnDetached(launch.command, launch.args, homeDir, 'oracle-daemon.log', {
+  // oracle consumes no provider API keys (construct-0wmj) — no op-run wrap needed.
+  const { logPath } = spawnDetached('node', [entry], homeDir, 'oracle-daemon.log', {
     cwd: projectDir,
     env: oracleEnv,
   });
@@ -338,6 +346,17 @@ export async function startServices({
   const operatorKeepAlive = resolveOllamaKeepAlive(liveEnv);
   if (operatorKeepAlive) liveEnv.OLLAMA_KEEP_ALIVE = operatorKeepAlive;
 
+  // The Copilot bridge fronts the user's Copilot entitlement over loopback HTTP, so it
+  // requires a bearer token. Generate a stable token once, persist it to the 0600
+  // config.env, and set it on liveEnv before OpenCode (the only caller) spawns so both
+  // the bridge and OpenCode inherit it; writeOpenCodeConfig wires it as an {env:} auth
+  // header. Reusing the persisted value keeps a restarted bridge and OpenCode in sync.
+  if (wants('copilot-bridge') && support.gh && detectActiveSessions().includes('github-copilot') && !liveEnv.CONSTRUCT_COPILOT_BRIDGE_TOKEN) {
+    const copilotBridgeToken = randomBytes(24).toString('hex');
+    liveEnv.CONSTRUCT_COPILOT_BRIDGE_TOKEN = copilotBridgeToken;
+    writeEnvValues(envPath, { CONSTRUCT_COPILOT_BRIDGE_TOKEN: copilotBridgeToken });
+  }
+
   const pressureReport = runPressureReleaseFn({ env: { ...liveEnv, HOME: homeDir } });
   if (pressureReport?.killed?.length) {
     results.push({
@@ -354,14 +373,14 @@ export async function startServices({
     if (traceBackend === 'local') {
       results.push({
         name: 'Telemetry',
-        url: path.join(rootDir, '.cx', 'traces'),
+        url: resolveStateDir(rootDir, 'traces', { ensureDir: false }),
         status: 'configured',
         note: 'local JSONL traces; remote export not configured',
       });
     } else if (traceBackend === 'none') {
       results.push({
         name: 'Telemetry',
-        url: path.join(rootDir, '.cx', 'traces'),
+        url: resolveStateDir(rootDir, 'traces', { ensureDir: false }),
         status: 'configured',
         note: 'remote export disabled; local JSONL traces preserved',
       });
@@ -390,8 +409,17 @@ export async function startServices({
     if (await memoryProbeFn(ports.memory)) {
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'reused' });
     } else {
-      const cm = wrapServiceSpawn('cm', ['serve', '--port', String(ports.memory)], homeDir, { env: liveEnv });
-      spawnDetachedFn(cm.command, cm.args, homeDir, 'cm.log');
+      // cm consumes no provider API keys (construct-0wmj) — no op-run wrap needed.
+      const cmSpawn = spawnDetachedFn('cm', ['serve', '--port', String(ports.memory)], homeDir, 'cm.log', { env: liveEnv });
+      try {
+        if (cmSpawn?.child?.pid) {
+          writeJson(portOwnershipPath(ports.memory, homeDir), {
+            pid: cmSpawn.child.pid, command: `cm serve --port ${ports.memory}`,
+            cwd: process.cwd(), marker: 'construct', constructManaged: true,
+            startedAt: new Date().toISOString(),
+          });
+        }
+      } catch { /* ownership record is advisory */ }
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'started' });
     }
   } else if (wants('memory')) {
@@ -404,7 +432,16 @@ export async function startServices({
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'reused' });
     } else {
       const opencode = wrapServiceSpawn('opencode', ['serve', '--port', String(ports.bridge)], homeDir, { env: liveEnv });
-      spawnDetachedFn(opencode.command, opencode.args, homeDir, 'opencode.log');
+      const ocSpawn = spawnDetachedFn(opencode.command, opencode.args, homeDir, 'opencode.log', { env: liveEnv });
+      try {
+        if (ocSpawn?.child?.pid) {
+          writeJson(portOwnershipPath(ports.bridge, homeDir), {
+            pid: ocSpawn.child.pid, command: `${opencode.command} ${opencode.args.join(' ')}`,
+            cwd: process.cwd(), marker: 'construct', constructManaged: true,
+            startedAt: new Date().toISOString(),
+          });
+        }
+      } catch { /* ownership record is advisory */ }
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'started' });
     }
   }
@@ -420,7 +457,16 @@ export async function startServices({
         const proxyPath = path.join(INSTALL_ROOT, 'lib', 'bridges', 'copilot-proxy.mjs');
         if (fs.existsSync(proxyPath)) {
           const copilot = wrapServiceSpawn('node', [proxyPath, '--port', String(ports.copilotBridge)], homeDir, { env: liveEnv });
-          spawnDetachedFn(copilot.command, copilot.args, homeDir, 'copilot-bridge.log');
+          const copilotSpawn = spawnDetachedFn(copilot.command, copilot.args, homeDir, 'copilot-bridge.log', { env: liveEnv });
+          try {
+            if (copilotSpawn?.child?.pid) {
+              writeJson(portOwnershipPath(ports.copilotBridge, homeDir), {
+                pid: copilotSpawn.child.pid, command: `${copilot.command} ${copilot.args.join(' ')}`,
+                cwd: process.cwd(), marker: 'construct', constructManaged: true,
+                startedAt: new Date().toISOString(),
+              });
+            }
+          } catch { /* ownership record is advisory */ }
           results.push({ name: 'Copilot Bridge', url: `http://127.0.0.1:${ports.copilotBridge}`, status: 'started' });
         } else {
           results.push({ name: 'Copilot Bridge', status: 'unavailable', note: 'copilot-proxy binary missing in lib/bridges/' });
@@ -476,16 +522,39 @@ async function emitServiceFailures(results) {
   } catch { /* best effort */ }
 }
 
-function killPortOwners(port, spawnSyncFn = spawnSync) {
+// Ownership record path for a port. startServices writes one when it spawns a service;
+// killPortOwners reads it before sending SIGTERM so a foreign process that happens to
+// occupy a configured port is never signalled.
+
+function portOwnershipPath(port, homeDir) {
+  return path.join(runtimeStateDir(homeDir), `port-${port}.json`);
+}
+
+// Predicate: does a process record represent a Construct-owned service? A record is
+// owned when it carries a Construct env/marker set at spawn time. A foreign process or
+// a record from before the ownership contract was introduced is not owned.
+
+export function isConstructOwnedPort(processRecord, { port } = {}) {
+  if (!processRecord || typeof processRecord !== 'object') return false;
+  return Boolean(processRecord.marker === 'construct' || processRecord.constructManaged === true);
+}
+
+function killPortOwners(port, spawnSyncFn = spawnSync, homeDir = os.homedir()) {
   if (!port || !Number.isInteger(port) || port <= 0) return false;
   try {
     const result = spawnSyncFn('lsof', ['-t', `-i:${port}`], { encoding: 'utf8' });
     const pids = (result.stdout || '').trim().split(/\s+/).filter(Boolean).map(Number).filter((n) => n > 0);
     if (pids.length === 0) return false;
+
+    // Only signal a PID if we have a durable Construct ownership record for this port
+    // AND it names this exact PID. A foreign owner gets reported, not killed.
+    const ownerRecord = readJson(portOwnershipPath(port, homeDir));
+    let killed = false;
     for (const pid of pids) {
-      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+      if (!ownerRecord || ownerRecord.pid !== pid || !isConstructOwnedPort(ownerRecord)) continue;
+      try { process.kill(pid, 'SIGTERM'); killed = true; } catch { /* already gone */ }
     }
-    return true;
+    return killed;
   } catch {
     return false;
   }
@@ -507,15 +576,15 @@ export async function stopServices({
   const envPath = getUserEnvPath(homeDir);
   const envValues = parseEnvFile(envPath);
   const memoryPort = Number(envValues.MEMORY_PORT) || derivedMemoryPort();
-  const cmKilled = killPortOwners(memoryPort, spawnSyncFn);
+  const cmKilled = killPortOwners(memoryPort, spawnSyncFn, homeDir);
   results.push({ name: 'Memory (cm)', status: cmKilled ? 'stopped' : 'not-running' });
 
   const bridgePort = Number(envValues.BRIDGE_PORT) || 5173;
-  const openCodeKilled = killPortOwners(bridgePort, spawnSyncFn);
+  const openCodeKilled = killPortOwners(bridgePort, spawnSyncFn, homeDir);
   results.push({ name: 'OpenCode', status: openCodeKilled ? 'stopped' : 'not-running' });
 
   const copilotBridgePort = Number(envValues.COPILOT_BRIDGE_PORT) || 5174;
-  const copilotBridgeKilled = killPortOwners(copilotBridgePort, spawnSyncFn);
+  const copilotBridgeKilled = killPortOwners(copilotBridgePort, spawnSyncFn, homeDir);
   results.push({ name: 'Copilot Bridge', status: copilotBridgeKilled ? 'stopped' : 'not-running' });
 
   const stopped = results.filter((r) => r.status === 'stopped' || r.status === 'cleaned').map((r) => r.name);

package/lib/setup.mjs

@@ -2,10 +2,14 @@
 /**
  * lib/setup.mjs — Machine-scoped first-run setup wizard for Construct.
  *
- * Installs cm/cass, configures managed defaults, pre-warms the embedding model,
- * wires MCP integrations, and writes the XDG user config (~/.config/construct/config.env).
- * Invoked by `construct install` and by lib/install/first-invocation.mjs
- * when a TTY user is missing resources.
+ * Installs cm/cass, configures managed defaults, wires MCP integrations, and
+ * writes the XDG user config (~/.config/construct/config.env). Invoked by
+ * `construct install` and by lib/install/first-invocation.mjs when a TTY
+ * user is missing resources.
+ *
+ * The embedding model and LanceDB vector store provision lazily by default
+ * (construct-rf26.17) — pass --with-embeddings to warm both up during
+ * install instead of at first semantic-search use, mirroring --with-docling.
  *
  * Project-scoped scaffolding (`.cx/`, AGENTS.md, plan.md, adapters) lives
  * in lib/init-unified.mjs — invoked by `construct init`. These two flows
@@ -35,6 +39,7 @@ import { getEmbeddingModelInfo, warmupEmbeddingModel } from './storage/embedding
 import { buildPressureGuardValues, installPressureGuardLaunchAgent, loadPressureGuardLaunchAgent } from './runtime-pressure.mjs';
 import { consentToInstall } from './setup-prompts.mjs';
 import { cleanupLegacyGlobalConstruct } from './install/legacy-global-cleanup.mjs';
+import { isMainModule } from './roots.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
@@ -59,6 +64,9 @@ Flags:
   --with-docling    eagerly provision the docling document-extraction venv now
                       (heavy, ~10 min via uv; otherwise provisioned lazily on
                       first document ingest)
+  --with-embeddings warm the embedding model + LanceDB vector store dir now
+                      (loads from local cache only, offline-safe; otherwise
+                      both provision lazily on first semantic-search use)
   --cleanup-legacy-global
                     remove legacy user-global Construct adapters/MCP/history
                       before setup; does not uninstall a global construct CLI
@@ -330,7 +338,7 @@ function runLegacyGlobalCleanup({ homeDir, dryRun }) {
 // network call, or service registration that the real run would perform — and
 // returns before touching disk so the preview is provably side-effect-free.
 
-function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupLegacyGlobal }) {
+function printInstallPlan({ scope, homeDir, withDocling, withEmbeddings, noLaunchAgent, cleanupLegacyGlobal }) {
   console.log('Construct install — dry-run (no changes written)');
   console.log('────────────────────────────────────────────────');
   console.log(`Scope: ${scope}`);
@@ -350,11 +358,11 @@ function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupL
   console.log(`  · ${getCanonicalOpenCodeConfigPath(homeDir)} (OpenCode config)`);
   console.log(`  · ${path.join(configDir(homeDir), 'lib')} → ${path.join(ROOT_DIR, 'lib')} (hook lib symlink)`);
   console.log(`  · ${path.join(stateDir(homeDir), 'workspace')} (workspace docs scaffold)`);
-  console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
+  if (withEmbeddings) console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
   console.log('\nWould check / install runtime tooling:');
   console.log('  · cm (memory CLI) and cass (session search) when available on PATH');
-  console.log('\nWould reach the network / external services:');
-  console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
+  if (withEmbeddings || withDocling) console.log('\nWould reach the network / external services:');
+  if (withEmbeddings) console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
   if (withDocling) console.log('  · docling Python venv provisioning via uv (~10 min)');
   console.log('  · construct sync --quiet, construct sync --global, construct doctor');
   if (process.platform === 'darwin' && !noLaunchAgent) {
@@ -375,9 +383,10 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     return;
   }
 
-  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--cleanup-legacy-global', '--help', '-h']);
+  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--with-embeddings', '--cleanup-legacy-global', '--help', '-h']);
   const dryRun = argSet.has('--dry-run');
   const withDocling = argSet.has('--with-docling');
+  const withEmbeddings = argSet.has('--with-embeddings');
   const unknownFlags = args.filter((a) => {
     if (!a.startsWith('-')) return false;
     if (a.startsWith('--scope=') || a === '--scope') return false;
@@ -402,7 +411,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
       printProjectScopeGuidance();
       return;
     }
-    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent'), cleanupLegacyGlobal });
+    printInstallPlan({ scope, homeDir, withDocling, withEmbeddings, noLaunchAgent: argSet.has('--no-launch-agent'), cleanupLegacyGlobal });
     return;
   }
 
@@ -470,20 +479,29 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
 
   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' };
+    : { status: 'local', note: 'local JSONL traces in the machine-scoped state root; remote export optional' };
   console.log(`Telemetry: ${telemetryResult.note}`);
 
-  fs.mkdirSync(path.dirname(defaultVectorIndexPath(homeDir)), { recursive: true });
-
-  try {
-    const warm = await warmupEmbeddingModel({ env: process.env });
-    if (warm.degraded) {
-      console.log(`Embeddings: degraded fallback (${warm.fallbackReason || 'model unavailable'}) — semantic search will use the hashing backend`);
-    } else {
-      console.log(`Embeddings: ${warm.model} ready (${warm.dimensions}d, warmed in ${warm.durationMs}ms)`);
+  // The embedding model and LanceDB vector store dir are provisioned lazily
+  // by default (construct-rf26.17): a project that never runs semantic
+  // search never pays for the ONNX model cache or an index directory. Both
+  // provision on first real use (`construct ingest`, first observation
+  // store/search) exactly like docling below. --with-embeddings opts into
+  // warming both up now instead of at first query.
+  if (withEmbeddings) {
+    fs.mkdirSync(path.dirname(defaultVectorIndexPath(homeDir)), { recursive: true });
+    try {
+      const warm = await warmupEmbeddingModel({ env: process.env });
+      if (warm.degraded) {
+        console.log(`Embeddings: degraded fallback (${warm.fallbackReason || 'model unavailable'}) — semantic search will use the hashing backend`);
+      } else {
+        console.log(`Embeddings: ${warm.model} ready (${warm.dimensions}d, warmed in ${warm.durationMs}ms)`);
+      }
+    } catch (err) {
+      console.log(`Embeddings: warmup skipped (${err?.message || 'unknown error'}) — model will load on first use`);
     }
-  } catch (err) {
-    console.log(`Embeddings: warmup skipped (${err?.message || 'unknown error'}) — model will load on first use`);
+  } else {
+    console.log('Embeddings: will provision on first semantic-search use (pass --with-embeddings to warm up now)');
   }
 
   // Docling (document/PDF extraction) provisions a pinned Python venv via uv,
@@ -592,7 +610,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   console.log('Setup complete.');
 
   console.log('\nLocal services:');
-  console.log('  Traces:      local JSONL (.cx/traces)');
+  console.log('  Traces:      local JSONL (machine-scoped state root)');
   console.log(`  Vector:      LanceDB (embedded)`);
   console.log(`    ${managedValues.CONSTRUCT_LANCEDB_PATH}`);
   console.log(`  Credentials are saved to ${getUserEnvPath(homeDir)} for later reference.`);
@@ -623,6 +641,6 @@ export function ensureWorkspace(homeDir = HOME) {
   return wsPath;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   runSetup({ args: process.argv.slice(2) });
 }

package/lib/skills-apply.mjs

@@ -87,8 +87,10 @@ export function writeConstructManifest(cwd, profile, classification) {
  * that records the recommended per-project scoping for Claude Code.
  *
  * Why a sidecar and not `settings.json`? Claude Code today only reads
- * `permissions`, `hooks`, and `mcpServers` from settings.json. A
- * `disabledPlugins` key would be ignored silently. Writing a sidecar is
+ * `permissions`, `hooks`, and policy keys (`allowedMcpServers`,
+ * `deniedMcpServers`, etc.) from settings.json — MCP server definitions
+ * live in `~/.claude.json` or `.mcp.json` instead (construct-ranh). A
+ * `disabledPlugins` key would be ignored silently either way. Writing a sidecar is
  * honest — it documents the recommendation without pretending the harness
  * enforces it. The construct-mcp session-start path can read this sidecar
  * and inject a "skills out of scope for this project" note.

package/lib/specialists/postconditions.mjs

@@ -18,7 +18,7 @@
  *   - cx-reviewer       prevents silent rubber-stamp reviews
  *   - cx-security       prevents post-hoc threat models
  *   - cx-debugger       prevents symptom-only fixes
- *   - cx-docs-keeper    prevents stale-doc PRs
+ *   - cx-operations     prevents stale-doc PRs (docs-keeper folded in, construct-rf26.11)
  *   - cx-designer       prevents post-hoc accessibility
  */
 
@@ -75,7 +75,7 @@ export const POSTCONDITIONS = {
       reason: `rootCauseConfirmedVia must be one of: ${[...ROOT_CAUSE_SOURCES].join(', ')}.`,
     },
   ],
-  'cx-docs-keeper': [
+  'cx-operations': [
     {
       id: 'docs-keeper.cross-doc-coherence-check-ran',
       description: 'Docs-keeper must run the cross-doc coherence check and attach a named diff.',