@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/doctor/command-on-path.mjs

@@ -0,0 +1,24 @@
+/**
+ * lib/doctor/command-on-path.mjs — resolve a command's PATH location the way a
+ * user's terminal would, without requiring zsh.
+ *
+ * `command -v` needs a login-ish shell to see the same PATH a real terminal
+ * session would build (rc files, PATH managers, etc). zsh is the
+ * macOS/most-desktop-Linux default but is not guaranteed present (minimal
+ * containers, some CI images) — spawning it unconditionally turns a missing
+ * zsh into a false "not on PATH" result for every dependent check. Falling
+ * back to `sh -lc` on ENOENT keeps this a real PATH lookup instead.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+export function resolveCommandOnPath(command, { spawnSyncImpl = spawnSync, platform = process.platform } = {}) {
+  if (platform === 'win32') {
+    return spawnSyncImpl('where', [command], { encoding: 'utf8', stdio: 'pipe' });
+  }
+  const viaZsh = spawnSyncImpl('zsh', ['-lc', `command -v ${command}`], { encoding: 'utf8', stdio: 'pipe' });
+  if (viaZsh.error?.code === 'ENOENT') {
+    return spawnSyncImpl('sh', ['-lc', `command -v ${command}`], { encoding: 'utf8', stdio: 'pipe' });
+  }
+  return viaZsh;
+}

package/lib/doctor/diagnosis.mjs

@@ -17,4 +17,93 @@ export const DOCTOR_STATES = {
   'entrypoint-missing': 'A binary or script the runtime expects (construct-mcp, construct) is not found on PATH.',
   'healthy': 'The check passed with no issues detected.',
   'degraded': 'The check passed with warnings; functionality may be reduced.',
+  'stub': 'The capability exists but is a no-op or partial implementation; not production-safe.',
 };
+
+/**
+ * STUB_ICON — the distinct display character rendered next to stub-tier diagnoses.
+ * Renderers that format doctor output should use this rather than hard-coding '~'.
+ */
+export const STUB_ICON = '~';
+
+/**
+ * classifyCapability(capabilityId, mode)
+ *
+ * Reads the capability registry for `mode` and maps the capability's status to one
+ * of three classification strings:
+ *   'implemented'     — fully wired; production-safe.
+ *   'stub'            — code path exists but is a no-op / partial (status: 'stub').
+ *   'not-implemented' — no code path exists yet (status: 'not-implemented').
+ *
+ * Returns 'not-implemented' when the capability is not found in the registry for
+ * the given mode (unknown capability IDs are treated as absent).
+ *
+ * Dynamic import of mode-capabilities happens on first call — in hot paths,
+ * prefer `classifyCapabilitySync` with a pre-fetched capabilities array.
+ */
+export async function classifyCapability(capabilityId, mode) {
+  let getCapabilities;
+  try {
+    ({ getCapabilities } = await import('../mode-capabilities.mjs'));
+  } catch {
+    getCapabilities = () => [];
+  }
+  return classifyCapabilitySync(capabilityId, getCapabilities(mode));
+}
+
+/**
+ * classifyCapabilitySync(capabilityId, caps)
+ *
+ * Synchronous variant that accepts a pre-fetched capabilities array. Avoids
+ * dynamic import overhead in hot paths (e.g., batch diagnosis loops).
+ */
+export function classifyCapabilitySync(capabilityId, caps) {
+  const cap = (caps ?? []).find((c) => c.id === capabilityId);
+  if (!cap) return 'not-implemented';
+  if (cap.status === 'implemented') return 'implemented';
+  if (cap.status === 'stub') return 'stub';
+  return 'not-implemented';
+}
+
+/**
+ * diagnosisLevelForCapability(classification)
+ *
+ * Maps a classifyCapabilitySync result to the doctor diagnosis level:
+ *   'implemented'     → 'healthy'  (green)
+ *   'stub'            → 'stub'     (yellow ~ icon)
+ *   'not-implemented' → 'stub'     (yellow ~ icon, "Not implemented" message)
+ */
+export function diagnosisLevelForCapability(classification) {
+  if (classification === 'implemented') return 'healthy';
+  return 'stub';
+}
+
+/**
+ * diagnosisMessageForCapability(classification)
+ *
+ * Returns the human-readable message for a capability diagnosis entry.
+ */
+export function diagnosisMessageForCapability(classification) {
+  if (classification === 'implemented') return 'Fully implemented';
+  if (classification === 'stub') return 'Partial implementation';
+  return 'Not implemented';
+}
+
+/**
+ * renderDiagnosisLevel(level)
+ *
+ * Returns the display icon for a given diagnosis level. Renderers that format
+ * doctor output should use this rather than embedding icon logic inline.
+ *
+ * Level → icon mapping:
+ *   'healthy'  → '✓'
+ *   'degraded' → '⚠'
+ *   'stub'     → '~'
+ *   anything else → '✗'
+ */
+export function renderDiagnosisLevel(level) {
+  if (level === 'healthy') return '✓';
+  if (level === 'degraded') return '⚠';
+  if (level === 'stub') return STUB_ICON;
+  return '✗';
+}

package/lib/doctor/embedding-health.mjs

@@ -0,0 +1,50 @@
+/**
+ * lib/doctor/embedding-health.mjs — doctor visibility for the active embedding model.
+ *
+ * `local` (lib/storage/embeddings-local.mjs, @huggingface/transformers) is the
+ * embedding engine's DEFAULT_MODEL (lib/storage/embeddings-engine.mjs),
+ * backing knowledge-search and evidence-ingest by default rather than a
+ * rarely-used opt-in path. The adapter's runtime already degrades silently to
+ * the 256d hashing adapter when the model fails to load (embeddings-local.mjs
+ * catch block); doctor visibility surfaces that degradation before a
+ * retrieval-quality drop goes unexplained (LMCP-K4), implementing the
+ * healthCheck declared for @huggingface/transformers in deps/intent.json:
+ * "require this package — absent means local embedding unavailable; hashing
+ * fallback activates automatically." A module-resolution import is the probe
+ * rather than invoking the ONNX pipeline, since presence/absence — not model
+ * inference — is the doctor-relevant signal.
+ */
+import { getEmbeddingModelInfo } from '../storage/embeddings-engine.mjs';
+
+/**
+ * checkEmbeddingModelForDoctor(opts) — the active embedding model's doctor-shaped finding.
+ *
+ * Non-`local` models (openai, ollama, hashing) report their configuration as-is;
+ * only `local` depends on the optional @huggingface/transformers package, so
+ * only that path probes for it.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] injectable env (CONSTRUCT_EMBEDDING_MODEL) for tests
+ * @param {Function} [opts.importTransformers] injectable seam over the dynamic import, for tests
+ * @returns {Promise<{ ok: boolean, degraded: boolean, label: string, optional: boolean }>}
+ */
+export async function checkEmbeddingModelForDoctor(opts = {}) {
+  const { env = process.env, importTransformers = () => import('@huggingface/transformers') } = opts;
+  const info = await getEmbeddingModelInfo({ env });
+
+  if (info.id !== 'local') {
+    return { ok: true, degraded: false, label: `Embedding model: ${info.id} (${info.model}, ${info.dimensions}d)`, optional: true };
+  }
+
+  try {
+    await importTransformers();
+    return { ok: true, degraded: false, label: `Embedding model: local (${info.model}, ${info.dimensions}d) — @huggingface/transformers resolves`, optional: true };
+  } catch (err) {
+    return {
+      ok: true,
+      degraded: true,
+      label: `Embedding model: local requested but @huggingface/transformers is not installed (${err.message}) — degrades to hashing-bow-v1 (256d, no semantic understanding). Install with \`npm install @huggingface/transformers\`, or set CONSTRUCT_EMBEDDING_MODEL=hashing to opt into the degraded model explicitly.`,
+      optional: true,
+    };
+  }
+}

package/lib/doctor/engine-health.mjs

@@ -0,0 +1,93 @@
+/**
+ * lib/doctor/engine-health.mjs — doctor checks for the document-export toolchain.
+ *
+ * lib/document-export.mjs's detect() already probes pandoc/typst/libreoffice/
+ * pptxgenjs per export format and returns binary presence, version, and an
+ * install hint (ADR-0024). This module turns those probes into one doctor-shaped
+ * finding per engine — binary presence, version, and a degradation message naming
+ * the missing binary and the export formats it owns — so `construct doctor`
+ * predicts whether a pdf/doc/pptx export will work before a workflow relies on
+ * it (LMCP-K3), mirroring lib/doctor/sidecar-providers.mjs's pattern of a pure,
+ * directly-testable function rather than inline probe logic in the CLI
+ * entrypoint or the consistency watcher.
+ *
+ * branding: 'plain' isolates the pandoc/typst/libreoffice probes from bundled
+ * distribution-template presence (construct-pdf.typ, construct-web.html), which
+ * is a separate, already-surfaced doctor concern. pptxgenjs is probed with the
+ * default 'construct' branding because detect() only selects the pptxgenjs
+ * engine (vs. pandoc's native pptx writer) outside of 'plain' branding.
+ */
+import { detect, installHint } from '../document-export.mjs';
+
+export const EXPORT_ENGINES = [
+  {
+    id: 'pandoc',
+    format: 'html',
+    branding: 'plain',
+    owningWorkflow: 'document-export (pdf, docx, doc, deck, html, rtf, odt, epub, tex, txt formats)',
+  },
+  {
+    id: 'typst',
+    format: 'pdf',
+    branding: 'plain',
+    owningWorkflow: 'document-export (pdf format, pandoc --pdf-engine)',
+  },
+  {
+    id: 'libreoffice',
+    format: 'doc',
+    branding: 'plain',
+    owningWorkflow: 'document-export (doc format, docx-to-doc down-conversion)',
+  },
+  {
+    id: 'pptxgenjs',
+    format: 'pptx',
+    branding: 'construct',
+    owningWorkflow: 'document-export (pptx format)',
+  },
+];
+
+/**
+ * checkEngineHealthForDoctor(engineId, opts) — one export engine's doctor-shaped finding.
+ *
+ * Absence is reported as an optional (non-fatal) finding carrying the same
+ * install hint `detect()` returns to export preflight, so the message a user
+ * sees in `construct doctor` and the message export preflight refuses with
+ * are the same string.
+ *
+ * @param {string} engineId 'pandoc' | 'typst' | 'libreoffice' | 'pptxgenjs'
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] injectable PATH/env for tests
+ * @param {Function} [opts.detectFn] injectable seam for lib/document-export.mjs detect()
+ * @returns {{ ok: boolean, installed: boolean, label: string, optional: boolean }}
+ */
+export function checkEngineHealthForDoctor(engineId, opts = {}) {
+  const probe = EXPORT_ENGINES.find((p) => p.id === engineId);
+  if (!probe) throw new Error(`Unknown export engine: ${engineId}`);
+
+  const { env = process.env, detectFn = detect } = opts;
+  const result = detectFn(probe.format, env, { branding: probe.branding });
+  const installed = !result.missing.includes(engineId);
+
+  if (installed) {
+    const status = result.binaries?.find((b) => b.name === engineId);
+    const version = status?.version ? ` ${status.version}` : '';
+    return { ok: true, installed: true, label: `Export engine '${engineId}'${version} — ${probe.owningWorkflow}`, optional: true };
+  }
+
+  return {
+    ok: true,
+    installed: false,
+    label: `Export engine '${engineId}' not installed — ${probe.owningWorkflow} degrades. ${installHint(engineId)}`,
+    optional: true,
+  };
+}
+
+/**
+ * checkEngineHealthAllForDoctor(opts) — pandoc + typst + libreoffice + pptxgenjs findings.
+ *
+ * @param {object} [opts] forwarded per-engine to checkEngineHealthForDoctor
+ * @returns {Array<{ ok: boolean, installed: boolean, label: string, optional: boolean }>}
+ */
+export function checkEngineHealthAllForDoctor(opts = {}) {
+  return EXPORT_ENGINES.map((p) => checkEngineHealthForDoctor(p.id, opts));
+}

package/lib/doctor/graph-validate.mjs

@@ -0,0 +1,47 @@
+/**
+ * lib/doctor/graph-validate.mjs — doctor check that runs `graph validate` (LMCP-C7).
+ *
+ * Wraps lib/graph/validate.mjs's validateGraph() into the doctor check shape
+ * ({ ok, label, warning, errors, warnings }) used across lib/doctor/*.mjs
+ * (see project-adapters.mjs for the same contract). Read-only: this module
+ * never writes to the graph store or the runtime-evidence store — it only
+ * classifies what validateGraph already reports, so `construct doctor` and
+ * `construct graph validate` can never disagree about whether the graph is
+ * clean.
+ *
+ * A missing graph (no `construct graph build` run yet) is reported as a
+ * warning, not a hard failure — the graph is an optional living-truth layer
+ * that a fresh project has not built yet, not a broken install.
+ */
+
+import { validateGraph } from '../graph/validate.mjs';
+
+export function checkGraphValidateForDoctor({ rootDir, strict = false, deploymentMode } = {}) {
+  const result = validateGraph(rootDir, { strict, deploymentMode });
+  const noGraph = result.errors.some((e) => e.startsWith('no graph found'));
+
+  if (noGraph) {
+    return {
+      ok: true,
+      warning: true,
+      label: 'Living graph: not built yet (run `construct graph build`)',
+      errors: [],
+      warnings: [],
+      result,
+    };
+  }
+
+  const ok = result.valid;
+  const label = ok
+    ? `Living graph valid (${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'})`
+    : `Living graph invalid: ${result.errors.length} error${result.errors.length === 1 ? '' : 's'} (run \`construct graph validate\`)`;
+
+  return {
+    ok,
+    warning: false,
+    label,
+    errors: result.errors,
+    warnings: result.warnings,
+    result,
+  };
+}

package/lib/doctor/index.mjs

@@ -26,15 +26,28 @@ import * as consistency from './watchers/consistency.mjs';
 import * as mcpProtocol from './watchers/mcp-protocol.mjs';
 import * as cxBudget from './watchers/cx-budget.mjs';
 import * as graphStaleness from './watchers/graph-staleness.mjs';
+import * as providerBreaker from './watchers/provider-breaker.mjs';
+import * as oracleLiveness from './watchers/oracle-liveness.mjs';
+import * as orchestrationRuns from './watchers/orchestration-runs.mjs';
 import { stateDir } from '../config/xdg.mjs';
+import { isMainModule } from '../roots.mjs';
 
 const STATE_PATH = join(stateDir(), 'doctor.json');
-const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness];
+const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness, providerBreaker, oracleLiveness, orchestrationRuns];
 
 let running = false;
 let timers = [];
 let lastTickAt = {};
 
+// Most watchers read only global/XDG state and never needed the project
+// directory. oracle-liveness is the first that does (listPending(projectDir))
+// — threaded here rather than each watcher reaching for process.cwd() itself,
+// so a test can drive tick() against a fixture project without touching the
+// process-wide cwd. start() defaults to process.cwd() because the daemon is
+// always spawned with the project root as its own cwd (lib/service-manager.mjs).
+
+let currentProjectDir = process.cwd();
+
 function writeState(state) {
   const dir = stateDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -68,7 +81,7 @@ async function runWatcher(watcher) {
   if (!running) return;
   const startedAt = Date.now();
   try {
-    const result = await watcher.tick();
+    const result = await watcher.tick({ projectDir: currentProjectDir });
     lastTickAt[watcher.name] = startedAt;
     const tookMs = Date.now() - startedAt;
     if (process.env.CONSTRUCT_DOCTOR_VERBOSE === '1') {
@@ -87,10 +100,11 @@ async function runWatcher(watcher) {
   }
 }
 
-export async function start() {
+export async function start({ projectDir = process.cwd() } = {}) {
   if (running) return;
   running = true;
   lastTickAt = {};
+  currentProjectDir = projectDir;
 
   writeState({ pid: process.pid, startedAt: Date.now(), watchers: WATCHERS.map((w) => w.name) });
   record({
@@ -138,7 +152,7 @@ export function statusSnapshot() {
 }
 
 const isMain = (() => {
-  try { return import.meta.url === `file://${process.argv[1]}`; } catch { return false; }
+  try { return isMainModule(import.meta.url); } catch { return false; }
 })();
 if (isMain) {
   // A long-lived daemon in its own process: wire the audit sink at the entry so any

package/lib/doctor/sidecar-providers.mjs

@@ -0,0 +1,56 @@
+/**
+ * lib/doctor/sidecar-providers.mjs — doctor checks for governed ingestion sidecars.
+ *
+ * docling and whisper are declared as `ingestion-provider` manifests
+ * (lib/extensions/manifests/docling.manifest.json, whisper.manifest.json) with
+ * an install probe, a health check, and a degradation chain. This module turns
+ * those probes into doctor-shaped findings so `construct doctor` reports
+ * install+health accurately whether or not the sidecar is present — mirroring
+ * lib/doctor/project-adapters.mjs's pattern of a pure, directly-testable
+ * function rather than inline logic in the CLI entrypoint.
+ */
+import { probeHealth } from '../ingest/sidecar-providers.mjs';
+
+/**
+ * checkSidecarProviderForDoctor(id, opts) — one provider's doctor-shaped finding.
+ *
+ * Absence is reported as an optional (non-fatal) finding with an actionable
+ * label; presence with a failing health check is reported as a non-optional
+ * finding since an installed-but-broken sidecar is a real defect, not an
+ * expected absence.
+ *
+ * @param {string} id 'docling' | 'whisper'
+ * @param {object} [opts] forwarded to lib/ingest/sidecar-providers.mjs probeHealth (injectable seams for fake probes)
+ * @returns {{ ok: boolean, label: string, optional: boolean }}
+ */
+export function checkSidecarProviderForDoctor(id, opts = {}) {
+  const health = probeHealth(id, opts);
+
+  if (!health.ok) {
+    return { ok: false, label: `Ingestion provider '${id}': check failed (${health.detail})`, optional: false };
+  }
+  if (!health.installProbe.installed) {
+    return {
+      ok: true,
+      label: `Ingestion provider '${id}': not installed (${health.detail}) — ingest degrades per its declared fallback chain`,
+      optional: true,
+    };
+  }
+  if (!health.healthy) {
+    return { ok: false, label: `Ingestion provider '${id}': installed but unhealthy (${health.detail})`, optional: false };
+  }
+  return { ok: true, label: `Ingestion provider '${id}': ${health.detail}`, optional: true };
+}
+
+/**
+ * checkSidecarProvidersForDoctor(opts) — docling + whisper doctor findings.
+ *
+ * @param {object} [opts] forwarded per-provider to checkSidecarProviderForDoctor
+ * @returns {Array<{ ok: boolean, label: string, optional: boolean }>}
+ */
+export function checkSidecarProvidersForDoctor(opts = {}) {
+  return [
+    checkSidecarProviderForDoctor('docling', opts),
+    checkSidecarProviderForDoctor('whisper', opts),
+  ];
+}

package/lib/doctor/watchers/consistency.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/doctor/watchers/consistency.mjs — cross-surface drift watcher.
  *
- * Five drift checks bundled at one cadence:
+ * Drift checks bundled at one cadence, including:
  *   1. Hook manifest ↔ files: every entry in platforms/claude/settings.template.json
  *      points to a real .mjs file in lib/hooks/ that parses.
  *   2. MCP registration ↔ impl: every `name === '<tool>'` branch in the MCP
@@ -13,6 +13,16 @@
  *      registry.agents[].promptFile exists on disk.
  *   5. Contracts ↔ schemas: specialists/org passes validateContractsFile
  *      (cross-file refs, producer/consumer names, schema paths).
+ *   6. Postcondition coverage (construct-rf26.12): reports the executable-
+ *      vs-advisory split across specialists/org/contracts/*.json postconditions
+ *      (lib/contracts/coverage.mjs); a nonzero unclassified count is drift.
+ *   7. Host surfaces: adapter config present for installed AI hosts.
+ *   8. Export engine health: pandoc/typst/libreoffice/pptxgenjs presence via
+ *      lib/doctor/engine-health.mjs (LMCP-K3).
+ *   9. Embedding model health: active embedding model, and whether the default
+ *      local model's @huggingface/transformers dependency resolves, via
+ *      lib/doctor/embedding-health.mjs (LMCP-K4).
+ *   10. Credential parity: see lib/doctor/watchers/credential-parity.mjs.
  *
  * Each violation produces an audit record. Blocking severity escalates to a
  * role intake; advisory severity records only. Tick is cheap — reads JSON +
@@ -27,6 +37,8 @@ import { fileURLToPath } from 'node:url';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
+import { checkEngineHealthAllForDoctor } from '../engine-health.mjs';
+import { checkEmbeddingModelForDoctor } from '../embedding-health.mjs';
 
 export const name = 'consistency';
 export const intervalMs = 15 * 60 * 1000;
@@ -87,9 +99,18 @@ export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
   const contracts = await checkContractsDrift({ repoRoot });
   collect(contracts, findings, passed, 'contracts-drift');
 
+  const postconditionCoverage = await checkPostconditionCoverage({ repoRoot });
+  collect(postconditionCoverage, findings, passed, 'postcondition-coverage');
+
   const hosts = checkHostSurfaces({ repoRoot });
   collect(hosts, findings, passed, 'host-surfaces');
 
+  const engines = checkEngineHealthDrift();
+  collect(engines, findings, passed, 'export-engine-health');
+
+  const embeddingModel = await checkEmbeddingModelDrift();
+  collect(embeddingModel, findings, passed, 'embedding-model-health');
+
   const { runCredentialParityChecks } = await import('./credential-parity.mjs');
   const credentials = await runCredentialParityChecks({ rootDir: repoRoot });
   collect(credentials, findings, passed, 'credential-parity');
@@ -422,6 +443,32 @@ async function checkContractsDrift({ repoRoot }) {
   return { summary: `contracts: ${violations.length} drift`, violations };
 }
 
+// Reports executable-vs-advisory postcondition coverage (construct-rf26.12).
+// Informational only — never fails on a low percentage, since advisory
+// postconditions are a legitimate, deliberate classification, not drift. A
+// nonzero `unclassified` count IS drift: a legacy bare-string postcondition
+// that slipped past the rf26.12 migration.
+
+async function checkPostconditionCoverage({ repoRoot }) {
+  try {
+    const { computePostconditionCoverage, formatCoverageSummary } = await import('../../contracts/coverage.mjs');
+    const coverage = computePostconditionCoverage({ repoRoot });
+    const violations = coverage.unclassified > 0
+      ? [{
+          category: 'postcondition-coverage',
+          severity: 'warning',
+          summary: `${coverage.unclassified} postcondition(s) across contracts have no postconditionType (executable|advisory) classification`,
+        }]
+      : [];
+    return { summary: formatCoverageSummary(coverage), violations };
+  } catch (err) {
+    return {
+      summary: 'postcondition coverage unavailable',
+      violations: [{ category: 'postcondition-coverage', severity: 'warning', summary: `postcondition coverage check failed: ${err.message}` }],
+    };
+  }
+}
+
 // ── Check 6: host surfaces ─────────────────────────────────────────────────
 
 function getVSCodeSettingsDir(homeDir) {
@@ -463,3 +510,48 @@ function checkHostSurfaces({ repoRoot: _repoRoot }) {
 
   return { summary: `host-surfaces: ${surfaces.length - absent.length}/${surfaces.length} present`, violations };
 }
+
+// ── Check 7: export engine health ──────────────────────────────────────────
+//
+// pandoc/typst/libreoffice/pptxgenjs have no preflight today; failures surface
+// mid-export. lib/doctor/engine-health.mjs probes the same detect() export
+// preflight uses, so absence here and an export refusal carry the same
+// install hint (LMCP-K3).
+
+function checkEngineHealthDrift() {
+  const violations = [];
+  const findingsList = checkEngineHealthAllForDoctor();
+  const absent = findingsList.filter((f) => !f.installed);
+
+  for (const f of absent) {
+    violations.push({
+      category: 'export-engine-health',
+      severity: 'warning',
+      tier: 'actionable',
+      summary: f.label,
+    });
+  }
+
+  return {
+    summary: `export-engine-health: ${findingsList.length - absent.length}/${findingsList.length} engines present`,
+    violations,
+  };
+}
+
+// ── Check 8: embedding model health ────────────────────────────────────────
+//
+// `local` (@huggingface/transformers) is the embedding engine's default and
+// degrades silently to hashing on failure; lib/doctor/embedding-health.mjs
+// surfaces that degradation so it is visible before retrieval quality drops
+// unexplained (LMCP-K4).
+
+async function checkEmbeddingModelDrift() {
+  const finding = await checkEmbeddingModelForDoctor();
+  if (finding.degraded) {
+    return {
+      summary: finding.label,
+      violations: [{ category: 'embedding-model-health', severity: 'warning', tier: 'actionable', summary: finding.label }],
+    };
+  }
+  return { summary: finding.label, violations: [] };
+}

package/lib/doctor/watchers/cx-budget.mjs

@@ -65,7 +65,7 @@ export async function tick() {
         kind: 'action',
         watcher: name,
         action: 'emergency-reclaim',
-        target: '.cx/traces|.cx/runtime/worker',
+        target: 'state-root:traces|state-root:runtime/worker',
         summary: `emergency reclaim removed ${emergencyResult.removed.length} file(s), freed ${emergencyResult.bytesFreed} bytes`,
         context: emergencyResult,
       });

package/lib/doctor/watchers/graph-staleness.mjs

@@ -2,7 +2,7 @@
  * lib/doctor/watchers/graph-staleness.mjs — dependency graph freshness watcher.
  *
  * Ticks every 30 minutes. When registry/contracts/workflow seeds changed since
- * the last `construct graph build`, records an audit entry so doctor surfaces
+ * the last `construct matrix build`, records an audit entry so doctor surfaces
  * stale-graph drift without waiting for the next Oracle tick.
  */
 

package/lib/doctor/watchers/mcp-protocol.mjs

@@ -35,10 +35,27 @@ function readJson(file) {
 
 export function collectMcpServers({ home = homedir() } = {}) {
   const servers = [];
+  const seenClaudeIds = new Set();
+
+  // Claude Code's user-scope MCP servers live in ~/.claude.json's top-level
+  // `mcpServers`, not settings.json (settings.json carries hooks/permissions
+  // only — construct-ranh). ~/.claude/settings.json is still checked so a
+  // legacy pre-migration install's (inert, but still worth flagging) entries
+  // are not silently dropped from the probe sweep.
+
+  const claudeUserConfigPath = join(home, '.claude.json');
+  if (existsSync(claudeUserConfigPath)) {
+    const cfg = readJson(claudeUserConfigPath);
+    for (const [id, entry] of Object.entries(cfg?.mcpServers ?? {})) {
+      servers.push({ host: 'claude', id, entry });
+      seenClaudeIds.add(id);
+    }
+  }
   const claudePath = join(home, '.claude', 'settings.json');
   if (existsSync(claudePath)) {
     const cfg = readJson(claudePath);
     for (const [id, entry] of Object.entries(cfg?.mcpServers ?? {})) {
+      if (seenClaudeIds.has(id)) continue;
       servers.push({ host: 'claude', id, entry });
     }
   }