@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/resources/budget.mjs

@@ -1,11 +1,12 @@
 /**
- * lib/resources/budget.mjs — disk-budget enforcement for .cx/ assets.
+ * lib/resources/budget.mjs — disk-budget enforcement for Construct's
+ * generated project state.
  *
  * Construct generates data continuously: traces, intake archives, task
  * graphs, worker logs, session records, backups. None of it has a
- * natural ceiling, so left unchecked the .cx/ tree grows until it
- * threatens the operator's disk. The budget primitive caps each
- * category against a config-defined ceiling.
+ * natural ceiling, so left unchecked the tree grows until it threatens
+ * the operator's disk. The budget primitive caps each category against
+ * a config-defined ceiling.
  *
  * Two enforcement modes:
  *   - **Hard-reject** (traces, worker logs): observability is
@@ -17,6 +18,13 @@
  *     load-bearing — never reject; emit a warning the operator can
  *     see in the doctor surface, and pruning gets aggressive.
  *
+ * Category locations (ADR-0066): traces and worker-logs are the two
+ * hard-reject, highest-volume categories, so they resolve through the
+ * machine-scoped state root (`resolveStateDir`) rather than the
+ * project's own `.cx/`. The remaining soft-warn categories are smaller
+ * and still project-local. "Total .cx/ cap" therefore really means
+ * "total generated-state cap" and sums bytes across both locations.
+ *
  * Defaults live in DEFAULT_PROJECT_CONFIG.resources. The operator
  * raises them in construct.config.json or via the dashboard. Doctor
  * surfaces usage vs cap at 80% (warn) and 100% (fail).
@@ -24,13 +32,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadProjectConfig } from '../config/project-config.mjs';
+import { resolveStateDir } from '../state-root.mjs';
 
 export const HARD_REJECT_CATEGORIES = new Set(['traces', 'worker-logs']);
 export const SOFT_WARN_CATEGORIES = new Set(['intake-archive', 'task-graphs', 'sessions', 'backups', 'handoffs']);
 
-const CATEGORY_PATHS = {
-  traces: '.cx/traces',
-  'worker-logs': '.cx/runtime/worker',
+const STATE_ROOT_CATEGORY_SEGMENTS = {
+  traces: ['traces'],
+  'worker-logs': ['runtime', 'worker'],
+};
+
+const PROJECT_LOCAL_CATEGORY_PATHS = {
   'intake-archive': '.cx/intake/processed',
   'intake-skipped': '.cx/intake/skipped',
   'task-graphs': '.cx/task-graphs',
@@ -39,6 +51,19 @@ const CATEGORY_PATHS = {
   handoffs: '.cx/handoffs',
 };
 
+const CATEGORY_NAMES = [...Object.keys(STATE_ROOT_CATEGORY_SEGMENTS), ...Object.keys(PROJECT_LOCAL_CATEGORY_PATHS)];
+
+// ensureDir:false — this module only measures/prunes usage, it never itself
+// writes a trace or worker-log file, so a measurement call must not conjure
+// the directory it is merely checking.
+
+function categoryDir(projectRoot, name) {
+  const stateSegments = STATE_ROOT_CATEGORY_SEGMENTS[name];
+  if (stateSegments) return resolveStateDir(projectRoot, ...stateSegments, { ensureDir: false });
+  const rel = PROJECT_LOCAL_CATEGORY_PATHS[name];
+  return rel ? path.join(projectRoot, rel) : null;
+}
+
 function loadResourceBudgets(projectRoot, env) {
   const { config } = loadProjectConfig(projectRoot, env);
   return config?.resources ?? {};
@@ -67,13 +92,13 @@ function walkDirSize(dir) {
 export function measureUsage(projectRoot, env = process.env) {
   const budgets = loadResourceBudgets(projectRoot, env);
   const result = { categories: {}, totalCxBytes: 0, totalCxCap: (budgets?.disk?.totalCxMaxMb ?? 2000) * 1024 * 1024 };
-  for (const [name, rel] of Object.entries(CATEGORY_PATHS)) {
-    const full = path.join(projectRoot, rel);
+  for (const name of CATEGORY_NAMES) {
+    const full = categoryDir(projectRoot, name);
     const { bytes, files } = walkDirSize(full);
     result.categories[name] = {
       bytes,
       files,
-      path: rel,
+      path: full,
       enforcement: HARD_REJECT_CATEGORIES.has(name) ? 'hard-reject' : 'soft-warn',
     };
     result.totalCxBytes += bytes;
@@ -93,7 +118,7 @@ export function warnBudgetOnce(message, env = process.env) {
 }
 
 export function reserveOrReject(projectRoot, category, sizeBytes, env = process.env) {
-  if (!CATEGORY_PATHS[category]) {
+  if (!CATEGORY_NAMES.includes(category)) {
     return { ok: true, source: 'unknown-category' };
   }
   const usage = measureUsage(projectRoot, env);
@@ -123,10 +148,8 @@ export function reserveOrReject(projectRoot, category, sizeBytes, env = process.
 function listHardRejectFiles(projectRoot) {
   const files = [];
   for (const cat of HARD_REJECT_CATEGORIES) {
-    const rel = CATEGORY_PATHS[cat];
-    if (!rel) continue;
-    const dir = path.join(projectRoot, rel);
-    if (!fs.existsSync(dir)) continue;
+    const dir = categoryDir(projectRoot, cat);
+    if (!dir || !fs.existsSync(dir)) continue;
     const walk = (current) => {
       for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
         const full = path.join(current, entry.name);
@@ -199,7 +222,7 @@ export function planPrune(projectRoot, env = process.env, opts = {}) {
   const actions = [];
 
   const tracesMaxDays = disk.tracesMaxDays ?? 30;
-  const tracesDir = path.join(projectRoot, '.cx/traces');
+  const tracesDir = categoryDir(projectRoot, 'traces');
   if (fs.existsSync(tracesDir)) {
     const cutoff = now - tracesMaxDays * 24 * 60 * 60 * 1000;
     for (const f of fs.readdirSync(tracesDir)) {
@@ -258,7 +281,7 @@ export function planPrune(projectRoot, env = process.env, opts = {}) {
     }
   }
 
-  const workerDir = path.join(projectRoot, '.cx/runtime/worker');
+  const workerDir = categoryDir(projectRoot, 'worker-logs');
   const workerMaxMb = disk.workerLogsMaxMb ?? 100;
   const workerMaxDays = disk.workerLogsMaxDays ?? 14;
   if (fs.existsSync(workerDir)) {

package/lib/roles/flavor-bindings.mjs

@@ -7,33 +7,39 @@
  *
  * baseOnly: classifier value "core" loads the base role file (no .flavor suffix).
  * See ADR-0047 for when to split specialists vs add flavors.
+ *
+ * construct-rf26.11 folded 15 of the 29 legacy specialists into 11 surviving
+ * worker anchors as skill bundles rather than separate personas. rolePrefix
+ * and classifierKey are unchanged (the skills/roles/*.md overlay files and
+ * the classifier heuristics that detect them are untouched); only
+ * specialistId is repointed to the anchor that now loads that overlay.
  */
 
 export const SPECIALIST_FLAVOR_BINDINGS = {
   engineer: { classifierKey: 'engineer', rolePrefix: 'engineer', specialistId: 'cx-engineer' },
-  'ai-engineer': { classifierKey: 'aiEngineer', rolePrefix: 'ai-engineer', specialistId: 'cx-ai-engineer', baseOnly: true },
-  'platform-engineer': { classifierKey: 'platformEngineer', rolePrefix: 'platform-engineer', specialistId: 'cx-platform-engineer', baseOnly: true },
-  'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer', specialistId: 'cx-data-engineer' },
+  'ai-engineer': { classifierKey: 'aiEngineer', rolePrefix: 'ai-engineer', specialistId: 'cx-engineer', baseOnly: true },
+  'platform-engineer': { classifierKey: 'platformEngineer', rolePrefix: 'platform-engineer', specialistId: 'cx-engineer', baseOnly: true },
+  'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer', specialistId: 'cx-engineer' },
   architect: { classifierKey: 'architect', rolePrefix: 'architect', specialistId: 'cx-architect' },
   'product-manager': { classifierKey: 'productManager', rolePrefix: 'product-manager', specialistId: 'cx-product-manager' },
-  'business-strategist': { classifierKey: 'businessStrategist', rolePrefix: 'business-strategist', specialistId: 'cx-business-strategist', baseOnly: true },
+  'business-strategist': { classifierKey: 'businessStrategist', rolePrefix: 'business-strategist', specialistId: 'cx-product-manager', baseOnly: true },
   qa: { classifierKey: 'qa', rolePrefix: 'qa', specialistId: 'cx-qa' },
-  'test-automation': { classifierKey: 'testAutomation', rolePrefix: 'test-automation', specialistId: 'cx-test-automation', baseOnly: true },
+  'test-automation': { classifierKey: 'testAutomation', rolePrefix: 'test-automation', specialistId: 'cx-qa', baseOnly: true },
   security: { classifierKey: 'security', rolePrefix: 'security', specialistId: 'cx-security' },
   'data-analyst': { classifierKey: 'dataAnalyst', rolePrefix: 'data-analyst', specialistId: 'cx-data-analyst' },
-  sre: { classifierKey: 'sre', rolePrefix: 'sre', specialistId: 'cx-sre', baseOnly: true },
+  sre: { classifierKey: 'sre', rolePrefix: 'sre', specialistId: 'cx-operations', baseOnly: true },
   operations: { classifierKey: 'operations', rolePrefix: 'operations', specialistId: 'cx-operations', baseOnly: true },
-  'release-manager': { classifierKey: 'releaseManager', rolePrefix: 'release-manager', specialistId: 'cx-release-manager', baseOnly: true },
-  'docs-keeper': { classifierKey: 'docsKeeper', rolePrefix: 'docs-keeper', specialistId: 'cx-docs-keeper', baseOnly: true },
+  'release-manager': { classifierKey: 'releaseManager', rolePrefix: 'release-manager', specialistId: 'cx-operations', baseOnly: true },
+  'docs-keeper': { classifierKey: 'docsKeeper', rolePrefix: 'docs-keeper', specialistId: 'cx-operations', baseOnly: true },
   reviewer: { classifierKey: 'reviewer', rolePrefix: 'reviewer', specialistId: 'cx-reviewer' },
-  'devil-advocate': { classifierKey: 'devilAdvocate', rolePrefix: 'devil-advocate', specialistId: 'cx-devil-advocate', baseOnly: true },
-  evaluator: { classifierKey: 'evaluator', rolePrefix: 'evaluator', specialistId: 'cx-evaluator', baseOnly: true },
-  'trace-reviewer': { classifierKey: 'traceReviewer', rolePrefix: 'trace-reviewer', specialistId: 'cx-trace-reviewer', baseOnly: true },
+  'devil-advocate': { classifierKey: 'devilAdvocate', rolePrefix: 'devil-advocate', specialistId: 'cx-reviewer', baseOnly: true },
+  evaluator: { classifierKey: 'evaluator', rolePrefix: 'evaluator', specialistId: 'cx-reviewer', baseOnly: true },
+  'trace-reviewer': { classifierKey: 'traceReviewer', rolePrefix: 'trace-reviewer', specialistId: 'cx-reviewer', baseOnly: true },
   researcher: { classifierKey: 'researcher', rolePrefix: 'researcher', specialistId: 'cx-researcher' },
-  'ux-researcher': { classifierKey: 'uxResearcher', rolePrefix: 'ux-researcher', specialistId: 'cx-ux-researcher', baseOnly: true },
-  explorer: { classifierKey: 'explorer', rolePrefix: 'explorer', specialistId: 'cx-explorer', baseOnly: true },
+  'ux-researcher': { classifierKey: 'uxResearcher', rolePrefix: 'ux-researcher', specialistId: 'cx-researcher', baseOnly: true },
+  explorer: { classifierKey: 'explorer', rolePrefix: 'explorer', specialistId: 'cx-researcher', baseOnly: true },
   designer: { classifierKey: 'designer', rolePrefix: 'designer', specialistId: 'cx-designer' },
-  accessibility: { classifierKey: 'accessibility', rolePrefix: 'designer.accessibility', specialistId: 'cx-accessibility', baseOnly: true },
+  accessibility: { classifierKey: 'accessibility', rolePrefix: 'designer.accessibility', specialistId: 'cx-designer', baseOnly: true },
   debugger: { classifierKey: 'debugger', rolePrefix: 'debugger', specialistId: 'cx-debugger', baseOnly: true },
 };
 
@@ -45,10 +51,26 @@ const BY_SPECIALIST = Object.fromEntries(
   Object.entries(SPECIALIST_FLAVOR_BINDINGS).map(([name, b]) => [name, b]),
 );
 
+// Reverse index: since construct-rf26.11, several short-name keys above share
+// a single specialistId (e.g. engineer/ai-engineer/platform-engineer/
+// data-engineer all point at cx-engineer). bindingForSpecialist(shortName)
+// only ever returns the entry whose OWN key matches the short name, so a
+// caller resolving a flavor by specialistId (rather than by the historical
+// short name) needs every candidate binding for that id, not just one.
+const BY_SPECIALIST_ID = new Map();
+for (const binding of Object.values(SPECIALIST_FLAVOR_BINDINGS)) {
+  if (!BY_SPECIALIST_ID.has(binding.specialistId)) BY_SPECIALIST_ID.set(binding.specialistId, []);
+  BY_SPECIALIST_ID.get(binding.specialistId).push(binding);
+}
+
 export function bindingForSpecialist(shortName) {
   return BY_SPECIALIST[shortName] ?? null;
 }
 
+export function bindingsForSpecialistId(specialistId) {
+  return BY_SPECIALIST_ID.get(specialistId) ?? [];
+}
+
 export function bindingForClassifier(classifierKey) {
   return BY_CLASSIFIER[classifierKey] ?? null;
 }

package/lib/roles/gateway.mjs

@@ -196,7 +196,14 @@ export function shouldEscalate(event, manifest, now = Date.now()) {
   return { escalate: false, reason: 'below-threshold', count: hits };
 }
 
-async function createBdIncident(event, routeResult) {
+// The bd client is injectable so tests can intercept the escalation path
+// without reaching the real, shared bd/dolt database (construct-y4iv) --
+// CONSTRUCT_ROLES_ROOT isolates the dedup-fingerprint state but is also set
+// legitimately in production (lib/oracle/execute.mjs), so it can't double as
+// a "we're in a test" signal. Callers that don't inject a client get the real
+// one, so production behavior (and every other existing caller) is unchanged.
+
+async function createBdIncident(event, routeResult, { runBd: runBdImpl = runBd } = {}) {
    // Dedup: check if this fingerprint has already been raised as a bead
    if (fingerprintAlreadyRaised(event.fingerprint)) {
      return { success: true, skipped: true, reason: 'fingerprint-already-raised', fingerprint: event.fingerprint };
@@ -221,7 +228,7 @@ async function createBdIncident(event, routeResult) {
      null,
      2
    );
-   const result = await runBd(
+   const result = await runBdImpl(
      ['create', title, '-t', 'bug', '-l', labels, '-d', body],
      { actor: `roles:${routeResult.personaId}`, silent: true, timeoutSeconds: 10, commandTimeoutSeconds: 30 }
    );
@@ -246,7 +253,7 @@ async function emitToastBestEffort(payload) {
   } catch { /* dashboard not loaded; toast is best-effort */ }
 }
 
-export async function tryEscalate(event) {
+export async function tryEscalate(event, deps = {}) {
   const r = routeEvent(event);
   if (!r) return { escalated: false, event, reason: 'no-owner' };
 
@@ -267,7 +274,7 @@ export async function tryEscalate(event) {
     }
   } catch { /* cost ledger optional — never block on missing module */ }
 
-  const bd = await createBdIncident(event, r);
+  const bd = await createBdIncident(event, r, deps);
   if (!bd.success) {
     return { escalated: false, event, reason: 'bd-create-failed', error: bd.error };
   }
@@ -299,12 +306,12 @@ export async function tryEscalate(event) {
   return { escalated: true, event, personaId: r.personaId, bdIssueId: bd.issueId, decision };
 }
 
-export async function recordAndMaybeInvoke(eventType, payload = {}) {
+export async function recordAndMaybeInvoke(eventType, payload = {}, deps = {}) {
   if (process.env.CONSTRUCT_ROLES === 'off') {
     return { recorded: false, escalated: false, reason: 'global-off' };
   }
   const event = emit(eventType, payload);
-  const r = await tryEscalate(event);
+  const r = await tryEscalate(event, deps);
   return { recorded: true, ...r };
 }
 
@@ -366,7 +373,7 @@ export function prunePending({ now = Date.now() } = {}) {
 // events.jsonl, runs each unescalated one through tryEscalate. Bounded by
 // `sinceMs` and `maxProcess` so a long-quiet machine can't trigger a flood.
 
-export async function processBacklog({ sinceMs = 60 * 60 * 1000, maxProcess = 10 } = {}) {
+export async function processBacklog({ sinceMs = 60 * 60 * 1000, maxProcess = 10, deps = {} } = {}) {
   if (process.env.CONSTRUCT_ROLES === 'off') return { processed: 0, escalated: 0, reason: 'global-off' };
 
   const ep = _paths.eventsPath();
@@ -390,7 +397,7 @@ export async function processBacklog({ sinceMs = 60 * 60 * 1000, maxProcess = 10
   for (const e of candidates.reverse()) {
     if (processed >= maxProcess) break;
     processed++;
-    const r = await tryEscalate(e);
+    const r = await tryEscalate(e, deps);
     if (r.escalated) escalated++;
   }
   return { processed, escalated };

package/lib/roots.mjs

@@ -0,0 +1,107 @@
+/**
+ * lib/roots.mjs — canonical resolution of the three directory concepts in Construct.
+ *
+ * packageRoot  — where the construct npm package is installed. Resolved from
+ *                import.meta.url, stable across global install, npx, and local
+ *                dev symlinks. Points to the directory that contains
+ *                construct's own package.json. Locate bundled assets here:
+ *                personas, skills, templates, schemas, hooks.
+ *
+ * projectRoot  — the user's repo being operated on. Discovered at runtime by
+ *                inspecting --project <dir> in argv, then walking up from cwd
+ *                looking for .cx/ or package.json. Falls back to cwd when no
+ *                marker is found. Services (oracle, embed, telemetry) that
+ *                read or write to the user's repo must use this, not
+ *                packageRoot.
+ *
+ * cwd          — process.cwd(). Useful for relative-path resolution before
+ *                projectRoot is determined. Callers should prefer
+ *                projectRoot once it is resolved.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Under `bun build --compile`, every module's import.meta.url/dirname resolves
+// inside the bundle's virtual filesystem (`/$bunfs/root/...`) rather than a
+// real on-disk path, so any install-root resolution derived from it collapses
+// to a directory that does not exist and every sibling-data-dir read (skills/,
+// specialists/, templates/, config/, registry/) throws ENOENT. process.execPath
+// still reports the compiled binary's real on-disk location, so callers whose
+// naive resolution lands inside /$bunfs fall back to the binary's own
+// directory. This assumes the data directories ship next to the binary
+// (true for the CI/dev smoke path — dist/<binary> sits one level below the
+// checkout root, the same depth bin/construct and lib/roots.mjs assume); a
+// fully standalone end-user install still needs its own asset story
+// (embedded assets or a co-installed data tree), tracked separately.
+
+const BUN_VIRTUAL_FS_PREFIX = '/$bunfs';
+
+export function isBunCompiledVirtualPath(candidatePath) {
+  return typeof process.versions?.bun === 'string' && candidatePath.startsWith(BUN_VIRTUAL_FS_PREFIX);
+}
+
+export function resolveInstallRoot(naiveRoot, { execPath = process.execPath, upFromBinary = 1 } = {}) {
+  if (!isBunCompiledVirtualPath(naiveRoot)) return naiveRoot;
+  return path.resolve(path.dirname(execPath), ...Array(upFromBinary).fill('..'));
+}
+
+// Two dozen lib/*.mjs files use the standard Node "was I run directly"
+// idiom (`import.meta.url === file://${process.argv[1]}`) so they double as
+// standalone scripts. Under a Bun-compiled binary, every bundled module's
+// import.meta.url collapses to the same virtual bunfs path as process.argv[1]
+// (both point at the single compiled executable), so that comparison is true
+// for every one of those files simultaneously — each runs its own top-level
+// CLI logic as an unwanted side effect of merely being imported, and the
+// first one whose logic throws (e.g. lib/headhunt.mjs's bare invocation
+// requiring --for) takes the whole binary down before bin/construct's real
+// dispatch ever executes. There is exactly one legitimate entry point inside
+// a compiled binary (bin/construct itself), so this always resolves false
+// under Bun-compile regardless of the module asking.
+
+export function isMainModule(moduleUrl) {
+  if (typeof process.versions?.bun === 'string' && isBunCompiledVirtualPath(process.argv[1] || '')) {
+    return false;
+  }
+  return moduleUrl === `file://${process.argv[1]}`;
+}
+
+// lib/roots.mjs lives one level below the package root (<package>/lib/roots.mjs).
+
+export const packageRoot = resolveInstallRoot(path.resolve(fileURLToPath(import.meta.url), '..', '..'));
+
+// Walk upward from `start`, looking for .cx/ first (Construct project marker),
+// then package.json (generic JS project root). Stops at filesystem root.
+
+function walkUp(start) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.cx'))) return dir;
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve the project root for the user's repo.
+ *
+ * Resolution order:
+ *   1. --project <dir> in process.argv (explicit override)
+ *   2. Walk upward from cwd looking for .cx/ or package.json
+ *   3. cwd itself as a last resort
+ *
+ * Pass a cwd argument when the caller controls the starting directory (tests,
+ * sub-process workers). Omit it in top-level CLI code to use process.cwd().
+ */
+export function resolveProjectRoot(cwd = process.cwd()) {
+  const argv = process.argv;
+  const flagIndex = argv.indexOf('--project');
+  if (flagIndex !== -1 && argv[flagIndex + 1]) {
+    return path.resolve(argv[flagIndex + 1]);
+  }
+
+  return walkUp(cwd) ?? path.resolve(cwd);
+}

package/lib/runtime/uv-bootstrap.mjs

@@ -1,9 +1,19 @@
 /**
  * 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.
+ * One venv per machine, not one per project (construct-rf26.16; ADR-0066
+ * called this out as the docling venv's terminal shape). On first use:
+ * downloads uv via the official Astral installer, creates
+ * `~/.construct/runtime/docling/.venv` (or `$CX_TOOLKIT_DIR/runtime/docling/.venv`)
+ * via `resolveSharedRuntimeDir`, installs the pinned docling release.
+ * Subsequent calls from any project on this machine are no-ops once the
+ * venv is present — there is no project key anywhere in this path.
+ *
+ * Version pin is the lockfile: `.install-marker.json`'s `doclingVersion`
+ * field is compared against DOCLING_PIN on every call. A mismatch (a
+ * construct upgrade that bumps the pin) is not silent drift — it clears the
+ * stale venv directory and re-provisions from scratch under `force`
+ * semantics, rather than layering a new install over an old one.
  *
  * Best-practice notes (2026-06):
  *   - uv (Astral) is the consensus Python tooling, ~10× faster than pip, single
@@ -16,19 +26,25 @@
  * 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 { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
 import { spawn, spawnSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 
+import { resolveSharedRuntimeDir } from '../state-root.mjs';
+
 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');
+// ensureDir:false — shared by the provisioner (ensureDoclingVenv, which
+// already mkdirs before it writes) and the read-only detector
+// (describeDoclingRuntime); a detect-only call must not conjure the dir.
+
+export function defaultRuntimeDir() {
+  return resolveSharedRuntimeDir('docling', { ensureDir: false });
 }
 
 function which(bin) {
@@ -127,6 +143,16 @@ export async function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), forc
     return { pythonBin: existingPython, venvDir, runtimeDir, fresh: false };
   }
 
+  // A version-pin mismatch (existingMarker present but doclingVersion !== DOCLING_PIN)
+  // is a controlled re-provision, not silent drift: clear the stale venv outright
+  // rather than trust `uv venv` to reconcile an existing directory left by a
+  // different docling/Python pin.
+
+  if (existingMarker && existingMarker.doclingVersion !== DOCLING_PIN) {
+    progress(`Pinned docling version changed (${existingMarker.doclingVersion} → ${DOCLING_PIN}) — re-provisioning.`);
+    try { rmSync(venvDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+
   progress('Provisioning the docling document extractor (first run). This downloads a Python runtime and ML dependencies and can take several minutes; later runs are instant.');
   const uv = await ensureUv(runtimeDir);
 

package/lib/runtime/whisper-bootstrap.mjs

@@ -12,8 +12,9 @@
  *
  * 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.
+ * <stateRoot>/runtime/whisper/models/ (ADR-0066: machine-scoped, not
+ * project-local). 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
@@ -25,12 +26,19 @@ import { pipeline } from 'node:stream/promises';
 import path from 'node:path';
 import os from 'node:os';
 
+import { resolveStateDir } from '../state-root.mjs';
+
 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']);
 
+// ensureDir:false — shared by the provisioner (ensureWhisperRuntime, which
+// already mkdirs before it writes) and the read-only detector
+// (describeWhisperRuntime/locateWhisperBinary); a detect-only call must not
+// conjure the dir.
+
 export function defaultRuntimeDir(cwd = process.cwd()) {
-  return path.join(cwd, '.cx', 'runtime', 'whisper');
+  return resolveStateDir(cwd, 'runtime', 'whisper', { ensureDir: false });
 }
 
 function which(bin) {

package/lib/runtime-env.mjs

@@ -1,8 +1,11 @@
 /**
  * lib/runtime-env.mjs — Construct runtime environment with credential bootstrap.
  *
- * prepareConstructEnv merges ~/.config/construct/config.env into the process environment.
- * Credential auto-link from 1Password runs only when autoLink:true (setup-credentials).
+ * prepareConstructEnv merges the user's ~/.config/construct/config.env and,
+ * when the caller passes `rootDir` (the resolved project root, not the
+ * toolkit install checkout), the project .env into the process environment —
+ * project .env wins. Credential auto-link from 1Password runs only when
+ * autoLink:true (setup-credentials).
  */
 
 import { loadConstructEnv } from './env-config.mjs';

package/lib/scheduler/index.mjs

@@ -8,11 +8,15 @@
  *
  * Jobs registered here: 'tag-candidate-mining', 'skill-usage-rollup', 'doc-hygiene-scan'
  *
- * Deployment mode is determined by getDeploymentMode(env), which inspects env vars.
+ * Deployment mode is resolved through the canonical lib/deployment-mode.mjs
+ * getDeploymentMode (CONSTRUCT_DEPLOYMENT_MODE env, then project config, then solo),
+ * so the scheduler agrees with the broker, session prelude, and status surfaces.
  * Registration is in-memory: no persistence across process restarts beyond the
  * native trigger files written by solo.mjs or the DB rows in 009_scheduler.sql.
  */
 
+import { getDeploymentMode } from '../deployment-mode.mjs';
+
 // ---------------------------------------------------------------------------
 // In-memory job registry
 // ---------------------------------------------------------------------------
@@ -57,22 +61,6 @@ export function listJobs() {
   }));
 }
 
-/**
- * Derives the deployment mode from environment variables.
- * Returns 'enterprise' | 'team' | 'solo'.
- *
- * CONSTRUCT_DEPLOYMENT=enterprise or CONSTRUCT_ENTERPRISE=1 => enterprise
- * CONSTRUCT_DEPLOYMENT=team or CONSTRUCT_TEAM=1             => team
- * Otherwise                                                  => solo
- */
-export function getDeploymentMode(env = process.env) {
-  const explicit = env.CONSTRUCT_DEPLOYMENT;
-  if (explicit === 'enterprise' || env.CONSTRUCT_ENTERPRISE === '1') return 'enterprise';
-  if (explicit === 'team' || env.CONSTRUCT_TEAM === '1') return 'team';
-  if (explicit === 'solo') return 'solo';
-  return 'solo';
-}
-
 // ---------------------------------------------------------------------------
 // Built-in job registrations
 // ---------------------------------------------------------------------------
@@ -104,8 +92,8 @@ registerJob({
 const DOC_HYGIENE_SOLO_CRON = '0 2 * * *';
 const DOC_HYGIENE_TEAM_CRON = '0 * * * *';
 
-export function resolveDocHygieneSchedule(env = process.env) {
-  const mode = getDeploymentMode(env);
+export function resolveDocHygieneSchedule(env = process.env, { cwd } = {}) {
+  const mode = getDeploymentMode(env, { cwd });
   const isTeamish = mode === 'team' || mode === 'enterprise';
   return {
     mode: isTeamish ? 'team' : 'solo',
@@ -121,7 +109,7 @@ registerJob({
   mode: docHygiene.mode,
   handler: async ({ cwd, env }) => {
     const { findHygieneCandidates } = await import('../hygiene/scan.mjs');
-    const { limit } = resolveDocHygieneSchedule(env);
+    const { limit } = resolveDocHygieneSchedule(env, { cwd });
     const candidates = findHygieneCandidates({ cwd, limit });
     return {
       status: 'ok',

package/lib/schema-infer.mjs

@@ -25,6 +25,7 @@ import { extractDocumentTextNodeNative, extractDocumentTextAsync } from './docum
 import { readCurrentModels, readOpenRouterApiKeyFromOpenCodeConfig } from './model-router.mjs';
 import { getUserEnvPath } from './env-config.mjs';
 import { pollFreeModels, topForTier } from './model-free-selector.mjs';
+import { extractOpRef, resolveOpRef, resolveSecret } from './providers/secret-resolver.mjs';
 import { execSync } from 'node:child_process';
 
 // ---------------------------------------------------------------------------
@@ -187,9 +188,37 @@ async function fetchWithTimeout(url, options) {
   }
 }
 
+function resolveSecretOrNull(varName, { env = process.env, allowAmbient = true } = {}) {
+  try {
+    return resolveSecret(varName, { env, allowAmbient });
+  } catch {
+    return null;
+  }
+}
+
+function materializeConfiguredKey(rawValue) {
+  if (typeof rawValue !== 'string' || rawValue.length === 0) return null;
+  const ref = extractOpRef(rawValue);
+  try {
+    return ref ? resolveOpRef(ref) : rawValue;
+  } catch {
+    return null;
+  }
+}
+
+function resolveOpenRouterApiKey() {
+  const envKey = resolveSecretOrNull('OPENROUTER_API_KEY');
+  if (envKey) return envKey;
+  try {
+    return materializeConfiguredKey(readOpenRouterApiKeyFromOpenCodeConfig());
+  } catch {
+    return null;
+  }
+}
+
 async function callModel(userContent, { traceId } = {}) {
-  const orKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
-  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  const orKey = resolveOpenRouterApiKey();
+  const anthropicKey = resolveSecretOrNull('ANTHROPIC_API_KEY');
 
   if (!orKey && !anthropicKey) {
     throw new Error('No API key found. Set ANTHROPIC_API_KEY or OPENROUTER_API_KEY to use schema inference.');