@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/profiles/lifecycle.mjs

@@ -3,7 +3,7 @@
  *
  * A profile is a curated description of an org's work loop, intake taxonomy,
  * role set, and rebrand language. Creating one is a research task, not a
- * code task. This module enforces that by producing a draft + a requirements
+ * code task. The module enforces that by producing a draft + a requirements
  * brief that names which existing Construct specialists are expected to
  * complete each section. Operators dispatch those specialists, collect the
  * answers, then promote the draft.
@@ -16,12 +16,17 @@
  *
  * Health: per-profile observation and outcome counts pulled from the existing
  * stores, so profile health travels alongside the rest of the learning loops.
+ *
+ * Lifecycle events: createDraftProfile and archiveProfile each fire a
+ * profile.updated role event so subscribers can react to taxonomy changes
+ * without polling the filesystem.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { listProfiles, loadProfile } from './loader.mjs';
+import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
@@ -256,9 +261,21 @@ export function createDraftProfile({ cwd, id, displayName, seedRoles = [], seedD
     departmentPaths.push(p);
   }
 
+  emitProfileUpdated({ id, stage: 'draft', dir });
   return { dir, briefPath, draftPath, personaPaths, departmentPaths };
 }
 
+// Lifecycle bridge: emits profile.updated whenever the curated catalog gains
+// or loses an entry, so subscribers (none by default; project overlays can
+// bind) can react to taxonomy changes.
+
+function emitProfileUpdated(context) {
+  emitRoleEvent('profile.updated', {
+    summary: `profile ${context.stage}: ${context.id}`,
+    context,
+  });
+}
+
 /**
  * List drafts under .cx/profiles/. Returns [{ id, dir, hasProfile, hasBrief }].
  */
@@ -320,6 +337,7 @@ export function archiveProfile({ id, reason }) {
     'Observations and outcomes recorded under this profile remain in `.cx/observations/` and `.cx/outcomes/` and continue to be searchable. The intake table and profile JSON were moved into this directory. To restore: move the files back to their original paths and re-run `npm run lint:profiles`.',
     '',
   ].join('\n'));
+  emitProfileUpdated({ id, stage: 'archived', dir: dstDir, reason: reason.trim() });
   return { archived: dstDir };
 }
 

package/lib/project-init-shared.mjs

@@ -11,14 +11,14 @@ import path from "node:path";
 
 import { stampFrontmatter } from "./doc-stamp.mjs";
 
-export function writeStampedIfMissing({ targetRoot, created, skipped, filePath, content, generator }) {
+export function writeStampedIfMissing({ targetRoot, created, skipped, filePath, content, generator, attribution = null }) {
   if (fs.existsSync(filePath)) {
     skipped.push(path.relative(targetRoot, filePath));
     return false;
   }
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const stamped = filePath.endsWith(".md")
-    ? stampFrontmatter(content, { generator })
+    ? stampFrontmatter(content, { generator, attribution })
     : content;
   fs.writeFileSync(filePath, stamped, "utf8");
   created.push(path.relative(targetRoot, filePath));
@@ -270,8 +270,8 @@ instead of letting it turn into a historical log. Durable task status belongs in
 `;
 }
 
-export function buildContextJson(projectName) {
-  return `${JSON.stringify({
+export function buildContextJson(projectName, { attribution = null } = {}) {
+  const base = {
     format: "json",
     savedAt: new Date().toISOString(),
     source: "construct-init",
@@ -280,5 +280,11 @@ export function buildContextJson(projectName) {
     recentDecisions: [],
     architectureNotes: [],
     openQuestions: [],
-  }, null, 2)}\n`;
+  };
+  if (attribution) {
+    base.createdBy = attribution.createdBy;
+    base.createdByAgent = attribution.createdByAgent;
+    base.createdAt = attribution.createdAt;
+  }
+  return `${JSON.stringify(base, null, 2)}\n`;
 }

package/lib/project-root.mjs

@@ -0,0 +1,104 @@
+/**
+ * lib/project-root.mjs — resolve "what Construct project am I in?" from any cwd.
+ *
+ * Writers that own per-project state (contract violations, audit reads, agent
+ * dispatches, intent verifications) call `resolveProjectScope()` to decide
+ * which `<project>/.cx/<file>.jsonl` to write to. When no project is
+ * detected, the call returns `null` and writers fall back to the legacy
+ * user-scope path (`~/.cx/<file>.jsonl`) so existing standalone hook
+ * invocations don't lose data.
+ *
+ * Writers that own cross-project telemetry (skill calls, role-pending,
+ * session cost) keep using `~/.cx/` but tag each entry with the
+ * `projectId` from `resolveProjectId()` so a reader can attribute the
+ * entry to a specific project later.
+ *
+ * The project marker is `.cx/` or `.construct/` at the project root. The
+ * lookup walks upward from cwd; the first ancestor matching either marker
+ * wins. Result is memoized per cwd so the hot path doesn't restat the
+ * filesystem on every append.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+
+const HOME = os.homedir();
+const MARKERS = ['.cx', '.construct'];
+const cache = new Map();   // cwd → { projectRoot, projectId, scope } | null
+
+/**
+ * Walk upward from `start` until a directory containing `.cx/` or
+ * `.construct/` is found. Returns the absolute project-root path or null.
+ * Stops at the filesystem root and at $HOME (so `~/.cx/` doesn't make
+ * the user's entire home directory look like a project).
+ */
+export function findProjectRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  const stop = path.resolve(HOME);
+  while (true) {
+    if (MARKERS.some((m) => fs.existsSync(path.join(dir, m)))) return dir;
+    if (dir === stop) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Deterministic short identifier for a project. Stable across sessions on
+ * the same machine, derived from the absolute project-root path. Useful for
+ * tagging cross-project telemetry entries (`projectId: "a7c4f2"`) without
+ * leaking the absolute filesystem path.
+ */
+export function projectIdFor(projectRoot) {
+  if (!projectRoot) return null;
+  return createHash('sha256').update(path.resolve(projectRoot)).digest('hex').slice(0, 12);
+}
+
+/**
+ * Resolve the project scope for a writer call site. Returns:
+ *   { projectRoot, projectId, cxDir }
+ *     when the cwd (or a parent) is a Construct project. `cxDir` is the
+ *     absolute path to `<projectRoot>/.cx/` (created on demand by callers).
+ *   null
+ *     when no project is detected; the caller should fall back to the
+ *     legacy user-scope path.
+ */
+export function resolveProjectScope(cwd = process.cwd()) {
+  if (cache.has(cwd)) return cache.get(cwd);
+  const projectRoot = findProjectRoot(cwd);
+  if (!projectRoot) {
+    cache.set(cwd, null);
+    return null;
+  }
+  const result = {
+    projectRoot,
+    projectId: projectIdFor(projectRoot),
+    cxDir: path.join(projectRoot, '.cx'),
+  };
+  cache.set(cwd, result);
+  return result;
+}
+
+/**
+ * For project-scoped writers: returns the `<project>/.cx/<basename>` path
+ * when cwd is inside a Construct project, otherwise the legacy
+ * `~/.cx/<basename>` path. Callers pass just the file basename; this helper
+ * resolves the directory side. ensureDir=true creates the parent dir.
+ */
+export function resolveProjectScopedPath(basename, { cwd, ensureDir = true } = {}) {
+  const scope = resolveProjectScope(cwd ?? process.cwd());
+  const dir = scope ? scope.cxDir : path.join(HOME, '.cx');
+  if (ensureDir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, basename);
+}
+
+/**
+ * Clear the memoization cache. Test-only — every other caller benefits
+ * from the cache surviving across calls in the same process.
+ */
+export function _resetCache() {
+  cache.clear();
+}

package/lib/prompt-composer.js

@@ -94,7 +94,17 @@ function compactTokens(text, tokenLimit = 300, { modelId = 'default' } = {}) {
 function readPromptBody(promptFile, rootDir) {
   const filePath = path.join(rootDir, promptFile);
   if (!fs.existsSync(filePath)) return '';
-  return fs.readFileSync(filePath, 'utf8').trim();
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return stripLeadingYamlFrontmatter(raw).trim();
+}
+
+function stripLeadingYamlFrontmatter(content) {
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content;
+  const closeIdx = content.indexOf('\n---', 4);
+  if (closeIdx === -1) return content;
+  const afterClose = content.indexOf('\n', closeIdx + 1);
+  if (afterClose === -1) return '';
+  return content.slice(afterClose + 1);
 }
 
 function buildLearnedPatternsBlock(agentName, {

package/lib/roles/catalog.mjs

@@ -11,7 +11,7 @@ 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');
+const REGISTRY_PATH = join(__dirname, '..', '..', 'specialists', 'registry.json');
 
 let cached = null;
 

package/lib/roles/event-bus.mjs

@@ -1,28 +1,34 @@
 /**
- * lib/roles/event-bus.mjs — append-only event log at ~/.cx/events.jsonl.
+ * lib/roles/event-bus.mjs — append-only event log per project.
  *
  * Hook processes emit failure/signal events here. The router + gateway read
  * recent events to decide escalation. Lines are rotated to keep the file
  * bounded. Fingerprint = sha1(type + project + first summary line) so the
  * same failure dedups across emits.
+ *
+ * Path resolution: events.jsonl lives at <project>/.cx/ when the cwd sits
+ * inside a Construct project, otherwise at ~/.cx/. Without per-project
+ * isolation, fingerprints from project A suppress real events in project B.
+ * Override the directory with CONSTRUCT_ROLES_ROOT for tests.
  */
 
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { resolveProjectScopedPath } from '../project-root.mjs';
 
 const MAX_LINES = 1000;
 
-function rootDir() {
-  return process.env.CONSTRUCT_ROLES_ROOT || join(homedir(), '.cx');
-}
 function eventsPath() {
-  return join(rootDir(), 'events.jsonl');
+  if (process.env.CONSTRUCT_ROLES_ROOT) {
+    return join(process.env.CONSTRUCT_ROLES_ROOT, 'events.jsonl');
+  }
+  return resolveProjectScopedPath('events.jsonl', { ensureDir: false });
 }
 function ensureDir() {
-  const r = rootDir();
-  if (!existsSync(r)) mkdirSync(r, { recursive: true });
+  const dir = dirname(eventsPath());
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
 export function fingerprintOf(type, project, summary) {
@@ -50,6 +56,20 @@ export function emit(eventType, payload = {}) {
   return line;
 }
 
+// Best-effort variant for writers that emit lifecycle events as a side
+// effect of their primary work (e.g. recommendation-store.createRecommendation,
+// docs-lifecycle.runDocsLifecycle). A bus write failure must not surface as
+// an error in the writer that just succeeded — the primary artifact already
+// landed. Returns the emitted line on success, null on failure.
+
+export function emitBestEffort(eventType, payload = {}) {
+  try {
+    return emit(eventType, payload);
+  } catch {
+    return null;
+  }
+}
+
 export function recent({ since = 0, type, fingerprint, limit = 200 } = {}) {
   const ep = eventsPath();
   if (!existsSync(ep)) return [];
@@ -76,4 +96,4 @@ function rotate() {
   } catch { /* rotate is best-effort */ }
 }
 
-export const _paths = { rootDir, eventsPath };
+export const _paths = { eventsPath };

package/lib/roles/router.mjs

@@ -1,19 +1,20 @@
 /**
  * lib/roles/router.mjs — pure event → persona resolver.
  *
- * Uses EVENT_OWNERSHIP from orchestration-policy and validates against
- * the loaded role manifest. Returns null (no owner) silently if the
- * event has no declared owner or the persona is not yet onboarded —
- * letting us declare ownership ahead of full wiring.
+ * Reads ownership from the declarative routing tables built off of
+ * specialists/registry.json, then validates against the loaded role
+ * manifest. Returns null silently when the event has no declared owner
+ * or the persona is not yet onboarded — letting ownership be declared
+ * ahead of full wiring.
  */
 
-import { EVENT_OWNERSHIP } from '../orchestration-policy.mjs';
+import { ownerForEvent } from '../orchestration/routing-tables.mjs';
 import { loadManifest, isOnboarded } from './manifest.mjs';
 
 export function route(event) {
   const type = event?.type;
   if (!type) return null;
-  const ownerCxId = EVENT_OWNERSHIP[type];
+  const ownerCxId = ownerForEvent(type);
   if (!ownerCxId) return null;
   const personaId = ownerCxId.replace(/^cx-/, '');
   if (!isOnboarded(personaId)) return null;
@@ -23,5 +24,5 @@ export function route(event) {
 }
 
 export function ownerOf(eventType) {
-  return EVENT_OWNERSHIP[eventType] || null;
+  return ownerForEvent(eventType);
 }

package/lib/runtime/uv-bootstrap.mjs

@@ -0,0 +1,129 @@
+/**
+ * lib/runtime/uv-bootstrap.mjs — idempotent uv + docling venv provisioner.
+ *
+ * On first use: downloads uv via the official Astral installer, creates
+ * `<rootDir>/.cx/runtime/docling/.venv`, installs the pinned docling release.
+ * Subsequent calls are no-ops if the venv is already present.
+ *
+ * Best-practice notes (2026-06):
+ *   - uv (Astral) is the consensus Python tooling, ~10× faster than pip, single
+ *     binary, lockfile-based. OpenAI acquired Astral on 2026-03-19; the project
+ *     remains Apache-2.0 and actively maintained, but single-vendor governance
+ *     is a documented concern — flagged for re-evaluation if licensing shifts.
+ *   - docling (IBM, MIT, donated to LF AI & Data early 2026) is the consensus
+ *     multi-format doc parser for layout-aware MD/JSON output.
+ *
+ * Returns the path to the venv's python binary so callers can spawn the
+ * sidecar without relying on PATH state.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+
+const DOCLING_PIN = '2.45.0';
+const UV_INSTALL_URL = 'https://astral.sh/uv/install.sh';
+const UV_TIMEOUT_MS = 120_000;
+const VENV_TIMEOUT_MS = 240_000;
+const INSTALL_TIMEOUT_MS = 600_000;
+
+export function defaultRuntimeDir(cwd = process.cwd()) {
+  return path.join(cwd, '.cx', 'runtime', 'docling');
+}
+
+function which(bin) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+function ensureUv(installDir) {
+  const fromPath = which('uv');
+  if (fromPath) return fromPath;
+  const cachedUv = path.join(installDir, 'bin', 'uv');
+  if (existsSync(cachedUv)) return cachedUv;
+  mkdirSync(installDir, { recursive: true });
+  const env = { ...process.env, UV_INSTALL_DIR: path.join(installDir, 'bin'), UV_NO_MODIFY_PATH: '1' };
+  const sh = spawnSync('sh', ['-c', `curl -LsSf ${UV_INSTALL_URL} | sh`], {
+    env,
+    timeout: UV_TIMEOUT_MS,
+    encoding: 'utf8',
+  });
+  if (sh.status !== 0) {
+    throw new Error(`uv install failed (${sh.status}): ${sh.stderr || sh.stdout}`);
+  }
+  if (!existsSync(cachedUv)) {
+    throw new Error(`uv install reported success but binary not found at ${cachedUv}`);
+  }
+  return cachedUv;
+}
+
+function pythonBinFor(venvDir) {
+  const candidates = process.platform === 'win32'
+    ? [path.join(venvDir, 'Scripts', 'python.exe')]
+    : [path.join(venvDir, 'bin', 'python'), path.join(venvDir, 'bin', 'python3')];
+  return candidates.find((p) => existsSync(p));
+}
+
+function readMarker(markerPath) {
+  try { return JSON.parse(readFileSync(markerPath, 'utf8')); }
+  catch { return null; }
+}
+
+function writeMarker(markerPath, payload) {
+  mkdirSync(path.dirname(markerPath), { recursive: true });
+  writeFileSync(markerPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+}
+
+export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = false } = {}) {
+  mkdirSync(runtimeDir, { recursive: true });
+  const venvDir = path.join(runtimeDir, '.venv');
+  const markerPath = path.join(runtimeDir, '.install-marker.json');
+  const existingMarker = readMarker(markerPath);
+  const existingPython = pythonBinFor(venvDir);
+
+  if (!force && existingPython && existingMarker?.doclingVersion === DOCLING_PIN) {
+    return { pythonBin: existingPython, venvDir, runtimeDir, fresh: false };
+  }
+
+  const uv = ensureUv(runtimeDir);
+
+  const venvResult = spawnSync(uv, ['venv', venvDir, '--python', '3.11'], {
+    timeout: VENV_TIMEOUT_MS,
+    encoding: 'utf8',
+  });
+  if (venvResult.status !== 0) {
+    throw new Error(`uv venv failed (${venvResult.status}): ${venvResult.stderr}`);
+  }
+
+  const installResult = spawnSync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], {
+    timeout: INSTALL_TIMEOUT_MS,
+    encoding: 'utf8',
+  });
+  if (installResult.status !== 0) {
+    throw new Error(`docling install failed (${installResult.status}): ${installResult.stderr}`);
+  }
+
+  const pythonBin = pythonBinFor(venvDir);
+  writeMarker(markerPath, {
+    doclingVersion: DOCLING_PIN,
+    installedAt: new Date().toISOString(),
+    pythonBin,
+    uvVersion: spawnSync(uv, ['--version'], { encoding: 'utf8' }).stdout.trim() || null,
+    platform: `${process.platform}-${process.arch}`,
+    node: process.version,
+  });
+
+  return { pythonBin, venvDir, runtimeDir, fresh: true };
+}
+
+export function describeDoclingRuntime({ runtimeDir = defaultRuntimeDir() } = {}) {
+  const venvDir = path.join(runtimeDir, '.venv');
+  return {
+    runtimeDir,
+    venvDir,
+    pythonBin: pythonBinFor(venvDir),
+    marker: readMarker(path.join(runtimeDir, '.install-marker.json')),
+    available: !!pythonBinFor(venvDir),
+  };
+}

package/lib/runtime/whisper-bootstrap.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/runtime/whisper-bootstrap.mjs — provision whisper.cpp binary + ASR model.
+ *
+ * Strategy (2026-06):
+ *   1. Prefer system-installed whisper-cli (or legacy `main`) on PATH —
+ *      `brew install whisper-cpp` (macOS, Metal-accelerated) or distro
+ *      package on Linux.
+ *   2. Fall back to bundled `whisper-cli` cached at <runtimeDir>/bin/ if a
+ *      previous bootstrap fetched one.
+ *   3. If neither, return a structured "not-available" descriptor — caller
+ *      surfaces a user-actionable install hint rather than crashing.
+ *
+ * Model files are downloaded directly from Hugging Face the first time the
+ * default `base.en` (or env-overridden) model is requested. Models cache at
+ * <runtimeDir>/models/. base.en is ~150MB; smaller than the small.en or
+ * medium.en model that callers can opt into via CONSTRUCT_WHISPER_MODEL.
+ *
+ * No bundled distribution: whisper.cpp upstream does not publish stable
+ * pre-built CLI binaries across platforms, and building from source via
+ * cmake adds a heavyweight first-run path. Defer that to a future opt-in.
+ */
+import { existsSync, mkdirSync, statSync, createWriteStream } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { pipeline } from 'node:stream/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const HF_MODEL_BASE_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main';
+const DEFAULT_MODEL = process.env.CONSTRUCT_WHISPER_MODEL || 'base.en';
+const KNOWN_MODELS = new Set(['tiny', 'tiny.en', 'base', 'base.en', 'small', 'small.en', 'medium', 'medium.en', 'large-v3', 'large-v3-turbo']);
+
+export function defaultRuntimeDir(cwd = process.cwd()) {
+  return path.join(cwd, '.cx', 'runtime', 'whisper');
+}
+
+function which(bin) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+export function locateWhisperBinary({ runtimeDir = defaultRuntimeDir() } = {}) {
+  for (const candidate of ['whisper-cli', 'whisper-cpp', 'main']) {
+    const found = which(candidate);
+    if (found) return { binary: found, source: 'system', name: candidate };
+  }
+  const cached = path.join(runtimeDir, 'bin', 'whisper-cli');
+  if (existsSync(cached)) return { binary: cached, source: 'cached', name: 'whisper-cli' };
+  return null;
+}
+
+export function describeWhisperRuntime({ runtimeDir = defaultRuntimeDir() } = {}) {
+  const located = locateWhisperBinary({ runtimeDir });
+  const modelPath = modelPathFor(DEFAULT_MODEL, runtimeDir);
+  return {
+    runtimeDir,
+    binary: located,
+    defaultModel: DEFAULT_MODEL,
+    modelPath,
+    modelInstalled: existsSync(modelPath),
+    available: !!located,
+  };
+}
+
+export function installHint() {
+  if (process.platform === 'darwin') return 'brew install whisper-cpp';
+  if (process.platform === 'linux') return 'See https://github.com/ggml-org/whisper.cpp#quick-start (build from source via cmake or install via your distro package manager).';
+  return 'See https://github.com/ggml-org/whisper.cpp#quick-start';
+}
+
+function modelPathFor(modelName, runtimeDir) {
+  return path.join(runtimeDir, 'models', `ggml-${modelName}.bin`);
+}
+
+export async function ensureWhisperModel({ runtimeDir = defaultRuntimeDir(), model = DEFAULT_MODEL } = {}) {
+  if (!KNOWN_MODELS.has(model)) {
+    throw new Error(`unknown whisper model: ${model} (allowed: ${[...KNOWN_MODELS].join(', ')})`);
+  }
+  const target = modelPathFor(model, runtimeDir);
+  if (existsSync(target) && statSync(target).size > 1024) return target;
+  mkdirSync(path.dirname(target), { recursive: true });
+  const url = `${HF_MODEL_BASE_URL}/ggml-${model}.bin`;
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok) {
+    throw new Error(`failed to download whisper model ${model}: ${response.status} ${response.statusText} (${url})`);
+  }
+  await pipeline(response.body, createWriteStream(target));
+  return target;
+}
+
+export async function ensureWhisperRuntime({ runtimeDir = defaultRuntimeDir(), model = DEFAULT_MODEL } = {}) {
+  mkdirSync(runtimeDir, { recursive: true });
+  const located = locateWhisperBinary({ runtimeDir });
+  if (!located) {
+    const err = new Error(`whisper-cli not found; install via: ${installHint()}`);
+    err.code = 'WHISPER_BINARY_MISSING';
+    err.installHint = installHint();
+    throw err;
+  }
+  const modelPath = await ensureWhisperModel({ runtimeDir, model });
+  return { binary: located.binary, source: located.source, modelPath, model };
+}

package/lib/server/index.mjs

@@ -33,10 +33,30 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const ROOT_DIR = join(__dirname, '..', '..');
 const HOME = homedir();
 const PORT = parseInt(process.env.PORT ?? '4242', 10);
-const BIND_HOST = process.env.BIND_HOST ?? (process.env.NODE_ENV === 'production' ? '0.0.0.0' : '127.0.0.1');
+
+// Default bind is loopback regardless of NODE_ENV. Exposing the dashboard to
+// non-loopback interfaces is opt-in via BIND_HOST and gated on configured
+// auth (see assertSafeBind below).
+
+const BIND_HOST = process.env.BIND_HOST ?? '127.0.0.1';
+
+function isLoopbackHost(host) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+
+function assertSafeBind() {
+  if (isLoopbackHost(BIND_HOST)) return;
+  if (!isAuthConfigured()) {
+    process.stderr.write(
+      `[dashboard] refuses to bind to non-loopback host ${BIND_HOST} without auth configured. ` +
+      `Set CONSTRUCT_DASHBOARD_TOKEN (or run \`construct dashboard auth init\`) before exposing the dashboard.\n`,
+    );
+    process.exit(1);
+  }
+}
 
 const STATIC_DIR = join(__dirname, 'static');
-const REGISTRY_FILE = join(ROOT_DIR, 'agents', 'registry.json');
+const REGISTRY_FILE = join(ROOT_DIR, 'specialists', 'registry.json');
 const FEATURES_FILE = join(HOME, '.construct', 'features.json');
 const WORKFLOW_FILE = join(ROOT_DIR, 'plan.md');
 const SKILLS_DIR = join(ROOT_DIR, 'skills');
@@ -775,9 +795,9 @@ const server = createServer(async (req, res) => {
         try {
           const dir =
             category === 'contracts' || category === 'role-manifests'
-              ? join(root, 'agents')
+              ? join(root, 'specialists')
               : category === 'agents'
-                ? join(root, 'agents', 'prompts')
+                ? join(root, 'specialists', 'prompts')
                 : join(root, category);
           if (existsSync(dir)) {
             const walk = (rel = '') => {
@@ -1406,15 +1426,32 @@ const server = createServer(async (req, res) => {
         env: { ...process.env, NO_COLOR: '1' },
         timeout: 5000,
       });
+      // bd can return non-zero for legitimate reasons that don't warrant a
+      // server 500: bd not installed, dolt lock held by a concurrent bd, no
+      // .beads/ in cwd. Degrade gracefully — return an empty issue list with
+      // `degraded: true` so the dashboard UI shows "no beads" instead of
+      // breaking, and the dashboard-endpoints test (which sweeps every read
+      // endpoint for 5xx) stays green when bd's runtime is wobbly.
+
       if (result.status !== 0) {
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: `bd list failed: ${(result.stderr || result.stdout || '').slice(0, 300)}` }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          issues: [],
+          counts: { total: 0, byStatus: {}, byPriority: {} },
+          degraded: true,
+          reason: (result.stderr || result.stdout || 'bd list failed').slice(0, 300).trim(),
+        }));
         return;
       }
       let raw = [];
       try { raw = JSON.parse(result.stdout); } catch (parseErr) {
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: `bd list JSON parse failed: ${parseErr.message}` }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          issues: [],
+          counts: { total: 0, byStatus: {}, byPriority: {} },
+          degraded: true,
+          reason: `bd list JSON parse failed: ${parseErr.message}`,
+        }));
         return;
       }
       const issues = raw.map(obj => ({
@@ -1441,8 +1478,13 @@ const server = createServer(async (req, res) => {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ issues, counts: { total: issues.length, byStatus, byPriority } }));
     } catch (err) {
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: err.message }));
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        issues: [],
+        counts: { total: 0, byStatus: {}, byPriority: {} },
+        degraded: true,
+        reason: err.message,
+      }));
     }
     return;
   }
@@ -2215,6 +2257,7 @@ if (process.env.CX_AUTO_EMBED === '1') {
   setInterval(runEmbedSync, intervalMs).unref();
   console.log(`Embed scheduler active — syncing every ${intervalMs / 60_000} min`);
 }
+assertSafeBind();
 server.listen(PORT, BIND_HOST, () => {
   console.log(`Construct dashboard running at http://${BIND_HOST}:${PORT}`);
 });