@geraldmaron/construct 1.0.23 → 1.1.0

package/lib/platforms/capabilities.mjs

@@ -0,0 +1,100 @@
+/**
+ * lib/platforms/capabilities.mjs — loader for the platform capability registry.
+ *
+ * Single source of truth for what each host platform can do (native subagent
+ * routing, hooks + their global-scope allowlist, MCP support, config format,
+ * local-model provisioning, instructions-only). The host enumeration, the
+ * displayName-to-id map, the hasNativeSubagents matrix, and the global hook /
+ * MCP allowlists all derive from this one registry so sync and init read host
+ * capabilities as data. See docs/adr/0033-platform-capability-registry.md.
+ *
+ * Hand-rolled validation (no AJV/zod) so this loads dependency-free on the
+ * bootstrap paths that run before npm install — same constraint as
+ * lib/config/schema.mjs. Fails loud on a malformed or unknown-shaped registry:
+ * a silent fall-through to a default would reintroduce exactly the per-host
+ * guesswork this registry exists to remove.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REGISTRY_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "platforms",
+  "capabilities.json",
+);
+
+const CONFIG_FORMATS = ["json", "toml", "markdown"];
+const PROVISIONING = ["modelfile", "none"];
+
+function fail(msg) {
+  throw new Error(`platform capability registry: ${msg}`);
+}
+
+function validateHost(id, host) {
+  if (!host || typeof host !== "object" || Array.isArray(host)) fail(`host '${id}' must be an object`);
+  const bools = ["hasNativeSubagents", "instructionsOnly", "supportsMcp"];
+  for (const k of bools) {
+    if (typeof host[k] !== "boolean") fail(`host '${id}.${k}' must be a boolean`);
+  }
+  if (typeof host.displayName !== "string" || !host.displayName) fail(`host '${id}.displayName' must be a non-empty string`);
+  if (!CONFIG_FORMATS.includes(host.configFormat)) fail(`host '${id}.configFormat' must be one of ${JSON.stringify(CONFIG_FORMATS)}`);
+  if (!PROVISIONING.includes(host.localModelProvisioning)) fail(`host '${id}.localModelProvisioning' must be one of ${JSON.stringify(PROVISIONING)}`);
+  if (!host.hooks || typeof host.hooks !== "object") fail(`host '${id}.hooks' must be an object`);
+  if (typeof host.hooks.supported !== "boolean") fail(`host '${id}.hooks.supported' must be a boolean`);
+  if (!Array.isArray(host.hooks.globalAllowlist)) fail(`host '${id}.hooks.globalAllowlist' must be an array`);
+  if (!Array.isArray(host.globalMcpAllowlist)) fail(`host '${id}.globalMcpAllowlist' must be an array`);
+}
+
+let cached = null;
+
+export function loadCapabilities() {
+  if (cached) return cached;
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(REGISTRY_PATH, "utf8"));
+  } catch (err) {
+    fail(`could not read/parse ${REGISTRY_PATH}: ${err.message}`);
+  }
+  if (raw.version !== 1) fail(`unsupported version ${raw.version}`);
+  if (!raw.hosts || typeof raw.hosts !== "object") fail("missing hosts object");
+  for (const [id, host] of Object.entries(raw.hosts)) validateHost(id, host);
+  cached = raw;
+  return raw;
+}
+
+// HOST_KEYS — the canonical host enumeration, derived from the registry so it
+// has exactly one definition. Order is the registry's declaration order.
+
+export const HOST_KEYS = Object.keys(loadCapabilities().hosts);
+
+export function getCapability(hostKey) {
+  const host = loadCapabilities().hosts[hostKey];
+  if (!host) fail(`unknown host '${hostKey}' (known: ${HOST_KEYS.join(", ")})`);
+  return host;
+}
+
+export function hasNativeSubagents(hostKey) {
+  return getCapability(hostKey).hasNativeSubagents;
+}
+
+// displayName-to-key lookup, built from the registry — the one place sync and
+// init resolve a detected host's display name to its canonical key.
+
+export function displayNameToKey() {
+  const map = {};
+  for (const [key, host] of Object.entries(loadCapabilities().hosts)) {
+    map[host.displayName] = key;
+  }
+  return map;
+}
+
+export function globalHookAllowlist(hostKey) {
+  return new Set(getCapability(hostKey).hooks.globalAllowlist);
+}
+
+export function globalMcpAllowlist(hostKey) {
+  return new Set(getCapability(hostKey).globalMcpAllowlist);
+}

package/lib/prompt-composer.js

@@ -27,7 +27,7 @@ import {
   resolveModelOperatingProfile,
   selectModelTierForWorkCategory,
 } from './model-router.mjs';
-import { searchObservations } from './observation-store.mjs';
+import { listObservations } from './observation-store.mjs';
 import { routeRequest } from './orchestration-policy.mjs';
 import { resolvePromptEntry, resolvePromptMetadata } from './prompt-metadata.mjs';
 import { readRoleFile } from './role-preload.mjs';
@@ -91,14 +91,14 @@ function compactTokens(text, tokenLimit = 300, { modelId = 'default' } = {}) {
   return `${normalized.slice(0, cutIdx)}…`;
 }
 
-function readPromptBody(promptFile, rootDir) {
+export function readPromptBody(promptFile, rootDir) {
   const filePath = path.join(rootDir, promptFile);
   if (!fs.existsSync(filePath)) return '';
   const raw = fs.readFileSync(filePath, 'utf8');
   return stripLeadingYamlFrontmatter(raw).trim();
 }
 
-function stripLeadingYamlFrontmatter(content) {
+export function stripLeadingYamlFrontmatter(content) {
   if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content;
   const closeIdx = content.indexOf('\n---', 4);
   if (closeIdx === -1) return content;
@@ -108,18 +108,22 @@ function stripLeadingYamlFrontmatter(content) {
 }
 
 function buildLearnedPatternsBlock(agentName, {
-  intent = null,
-  workCategory = null,
   project = null,
   modelId = 'default',
   tokenLimit = MODEL_OPERATING_PROFILES.balanced.learnedPatternsTokens,
 } = {}) {
   try {
     const rootDir = homedir();
-    const query = [agentName, intent, workCategory].filter(Boolean).join(' ');
     const shortName = String(agentName).replace(/^cx-/, '');
-    const results = searchObservations(rootDir, query, {
-      limit: MAX_OBSERVATIONS * 2,
+
+    // Prompt composition runs at sync time (config generation). A live semantic
+    // search here would load the 90MB embedding model and stall sync for ~80s on
+    // a cold cache (and searchObservations is async — its Promise can't be
+    // consumed from this synchronous function). Read the durable observation
+    // index synchronously and rank by confidence + role match instead.
+
+    const results = listObservations(rootDir, {
+      limit: MAX_OBSERVATIONS * 4,
       project: project ?? null,
     });
 

package/lib/reconcile/agent-instructions-rewrap.mjs

@@ -22,6 +22,7 @@ import {
   injectIntoAgentFile,
   injectConstructBlock,
   buildConstructIntegrationBody,
+  variantForFile,
   CONSTRUCT_INTEGRATION_VERSION,
 } from '../agent-instructions/inject.mjs';
 
@@ -37,8 +38,11 @@ function hasIntegrationBlock(content) {
 // dedups against a sibling Beads block, so the comparison rebuilds the body
 // the same way injectIntoAgentFile does before hashing.
 
-function wouldChange(content) {
-  const body = buildConstructIntegrationBody({ hasBeadsBlock: BEADS_BLOCK_RE.test(content) });
+function wouldChange(content, name) {
+  const body = buildConstructIntegrationBody({
+    hasBeadsBlock: BEADS_BLOCK_RE.test(content),
+    variant: variantForFile(name),
+  });
   const { action } = injectConstructBlock(content, body, CONSTRUCT_INTEGRATION_VERSION);
   return action !== 'unchanged';
 }
@@ -66,7 +70,7 @@ async function detect() {
   if (candidates.length === 0) {
     return { needsRepair: false, summary: 'No agent file carries a CONSTRUCT INTEGRATION block.' };
   }
-  const stale = candidates.filter((c) => wouldChange(c.content)).map((c) => c.name);
+  const stale = candidates.filter((c) => wouldChange(c.content, c.name)).map((c) => c.name);
   if (stale.length === 0) {
     return { needsRepair: false, summary: 'CONSTRUCT INTEGRATION blocks are current.' };
   }
@@ -81,7 +85,7 @@ async function apply() {
   const candidates = candidateFiles();
   const rewrapped = [];
   for (const c of candidates) {
-    if (!wouldChange(c.content)) continue;
+    if (!wouldChange(c.content, c.name)) continue;
     const result = injectIntoAgentFile(c.full, { version: CONSTRUCT_INTEGRATION_VERSION });
     if (result.changed) rewrapped.push(c.name);
   }

package/lib/reconcile/index.mjs

@@ -35,7 +35,6 @@ import legacyDoctrineStrip from './legacy-doctrine-strip.mjs';
 import legacyGuideDecommit from './legacy-guide-decommit.mjs';
 import mcpEntryReconcile from './mcp-entry-reconcile.mjs';
 import adapterPrune from './adapter-prune.mjs';
-import postgresNamespace from './postgres-namespace.mjs';
 
 export const RECONCILIATIONS = [
   legacySkillsCleanup,
@@ -45,7 +44,6 @@ export const RECONCILIATIONS = [
   legacyGuideDecommit,
   mcpEntryReconcile,
   adapterPrune,
-  postgresNamespace,
 ];
 
 const STAMP_FILE = 'reconcile.json';

package/lib/reflect/extractor.mjs

@@ -7,8 +7,15 @@
  *
  * Caller responsibility: read the transcript file and pass parsed lines.
  * Output is capped at MAX_BYTES to honor the A1 hook's per-session budget.
+ *
+ * Salience: the observation's confidence is the session's deterministic salience
+ * (see lib/reflect/salience.mjs) rather than a flat value, so low-value sessions are
+ * remembered weakly and age out of the live set first under consolidation; a session
+ * with no durable signal is not stored at all.
  */
 
+import { scoreSalience, shouldStore } from './salience.mjs';
+
 // Hard cap on the summary content so a runaway session can't blow up the
 // observation store. 5 KB matches the budget set in the A1 plan.
 const MAX_BYTES = 5 * 1024;
@@ -32,6 +39,10 @@ export function extractSessionObservation({ entries, cwd, sessionId, durationMs
   const stats = collectStats(entries);
   if (stats.assistantTurns === 0 && stats.userTurns === 0) return null;
 
+  // Extraction decision: a session with no durable signal is noise, not memory.
+  if (!shouldStore(stats)) return null;
+  const { salience, signals: salienceSignals } = scoreSalience(stats);
+
   const finalAssistant = stats.lastAssistantText;
   const headline = deriveHeadline(finalAssistant, stats);
 
@@ -64,7 +75,7 @@ export function extractSessionObservation({ entries, cwd, sessionId, durationMs
     summary: headline,
     content,
     tags: buildTags(stats),
-    confidence: 0.7,
+    confidence: salience,
     source: 'auto-reflect',
     extras: {
       sessionId: sessionId || null,
@@ -74,6 +85,8 @@ export function extractSessionObservation({ entries, cwd, sessionId, durationMs
       assistantTurns: stats.assistantTurns,
       toolCallCount: stats.toolCallCount,
       filesTouched: Array.from(stats.filesTouched).slice(0, MAX_FILES),
+      salience,
+      salienceSignals,
     },
   };
 }

package/lib/reflect/salience.mjs

@@ -0,0 +1,65 @@
+/**
+ * lib/reflect/salience.mjs — deterministic "is this worth remembering" score.
+ *
+ * The transcript extractor produces one observation per session and stamped every
+ * one with a flat confidence, so a session that changed the codebase and a trivial
+ * read-only exchange were remembered with equal weight (the mem0/Letta "salience"
+ * gap). This scores a session's durable value from signals already collected — what
+ * tools ran, whether files were mutated, how substantive the exchange was — with no
+ * LLM, matching Construct's offline-first posture.
+ *
+ * The score feeds the observation's `confidence`, so the existing consolidation pass
+ * carries retention on its own — no second mechanism. Consolidation archives a session
+ * only once both older than `archiveAfterDays` and below `archiveBelowConfidence` (0.5),
+ * so a low-salience session ages out of the live set while a high-salience one survives.
+ * `shouldStore` is the extraction decision: a session with no durable signal at all is
+ * not worth an observation.
+ */
+
+// Tools that change durable state are the strongest salience signal; a session
+// that edits the tree is worth more than one that only reads it.
+const MUTATING_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+const READ_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS']);
+
+function countByPredicate(toolTypes, pred) {
+  let n = 0;
+  for (const [name, count] of toolTypes ?? new Map()) if (pred(name)) n += count;
+  return n;
+}
+
+/**
+ * Score a session's salience in [0.05, 0.95] from its collected stats.
+ * @param {{toolTypes?: Map<string,number>, toolCallCount?: number, assistantTurns?: number, filesTouched?: Set<any>}} stats
+ * @returns {{salience: number, signals: string[]}}
+ */
+export function scoreSalience(stats = {}) {
+  const toolTypes = stats.toolTypes ?? new Map();
+  const mutations = countByPredicate(toolTypes, (t) => MUTATING_TOOLS.has(t));
+  const reads = countByPredicate(toolTypes, (t) => READ_TOOLS.has(t));
+  const bash = countByPredicate(toolTypes, (t) => t === 'Bash');
+  const assistantTurns = stats.assistantTurns ?? 0;
+  const filesTouched = stats.filesTouched?.size ?? 0;
+
+  const signals = [];
+  let score = 0.25;
+  if (mutations > 0) { score += 0.45; signals.push(`mutated ${mutations}× (durable change)`); }
+  else if (bash > 0) { score += 0.15; signals.push(`ran ${bash} bash command(s)`); }
+  else if (reads > 0) { signals.push('read-only/exploratory'); }
+  if (assistantTurns >= 5) { score += 0.1; signals.push(`${assistantTurns} assistant turns (substantive)`); }
+  if (filesTouched >= 3) { score += 0.05; signals.push(`${filesTouched} files in scope`); }
+
+  const salience = Math.max(0.05, Math.min(0.95, Number(score.toFixed(2))));
+  return { salience, signals };
+}
+
+/**
+ * The extraction decision: a session carrying no durable signal — no mutations, no
+ * bash, and barely any exchange — is noise, not memory, and is not stored.
+ */
+export function shouldStore(stats = {}) {
+  const toolTypes = stats.toolTypes ?? new Map();
+  const mutations = countByPredicate(toolTypes, (t) => MUTATING_TOOLS.has(t));
+  const bash = countByPredicate(toolTypes, (t) => t === 'Bash');
+  const assistantTurns = stats.assistantTurns ?? 0;
+  return mutations > 0 || bash > 0 || assistantTurns >= 2;
+}

package/lib/rules-delivery.mjs

@@ -0,0 +1,122 @@
+/**
+ * lib/rules-delivery.mjs — deliver glob-scoped rules to hosts with a native rule format.
+ *
+ * Cursor is the one supported host with a native per-rule glob convention
+ * (`.cursor/rules/*.mdc`, comma-separated `globs` frontmatter, auto-attached when a
+ * matching file enters context). Project sync emits one managed `.mdc` per
+ * glob-scoped rule (`rules/<dir>/<name>.md` with `paths:` frontmatter) whose globs
+ * match files actually present in the project — the project's own contents are the
+ * intent signal, so a Go rule lands only in a repo that contains Go. Emitted files
+ * carry the `construct-` prefix and are swept when their rule stops matching, so
+ * user-authored .mdc files are never touched (ADR-0027 ownership contract).
+ * Claude/Codex/OpenCode have no per-rule glob mechanism; for them rules remain
+ * reference-delivered (cited by path in prose) — see docs/concepts/rules-delivery.md.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.cx', 'dist', 'build', '.next', 'vendor', '.beads']);
+const MAX_FILES = 5000;
+
+function parseRule(absPath) {
+  const raw = fs.readFileSync(absPath, 'utf8');
+  const fm = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!fm) return null;
+  const globs = [...fm[1].matchAll(/^\s*-\s+"([^"]+)"\s*$/gm)].map((m) => m[1]);
+  if (!/^paths:/m.test(fm[1]) || globs.length === 0) return null;
+  const desc = fm[1].match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? '';
+  return { globs, description: desc, body: raw.slice(fm[0].length).trim() };
+}
+
+export function collectGlobScopedRules(rulesDir) {
+  const out = [];
+  const walk = (dir, rel = '') => {
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const full = path.join(dir, e.name);
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(full, childRel);
+      else if (e.name.endsWith('.md')) {
+        const parsed = parseRule(full);
+        if (parsed) out.push({ rule: childRel.replace(/\.md$/, ''), ...parsed });
+      }
+    }
+  };
+  walk(rulesDir);
+  return out;
+}
+
+// The rule corpus uses simple glob shapes (`**/*.go`, `**/go.mod`, `*.md`); this
+// translates exactly those: `**/` spans directories, `*` stays within a segment.
+
+export function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*\//g, '\u0001')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\u0001/g, '(?:.*/)?');
+  return new RegExp(`^${escaped}$`);
+}
+
+export function listProjectFiles(targetDir, { maxFiles = MAX_FILES } = {}) {
+  const files = [];
+  const walk = (dir, rel = '') => {
+    if (files.length >= maxFiles) return;
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (files.length >= maxFiles) return;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(path.join(dir, e.name), rel ? `${rel}/${e.name}` : e.name);
+      } else {
+        files.push(rel ? `${rel}/${e.name}` : e.name);
+      }
+    }
+  };
+  walk(targetDir);
+  return files;
+}
+
+/**
+ * Emit managed per-rule .mdc files into <targetDir>/.cursor/rules/ for every
+ * glob-scoped rule matching the project's own files, and sweep managed files
+ * whose rule stopped matching. Returns { emitted, swept }.
+ */
+export function emitCursorRules({ rulesDir, targetDir, dryRun = false } = {}) {
+  const rules = collectGlobScopedRules(rulesDir);
+  const files = listProjectFiles(targetDir);
+  const outDir = path.join(targetDir, '.cursor', 'rules');
+
+  const wanted = new Map();
+  for (const r of rules) {
+    const regs = r.globs.map(globToRegExp);
+    if (!files.some((f) => regs.some((re) => re.test(f)))) continue;
+    const name = `construct-${r.rule.replace(/\//g, '-')}.mdc`;
+    const mdc = `---\ndescription: ${r.description}\nglobs: ${r.globs.join(', ')}\nalwaysApply: false\n---\n\n${r.body}\n`;
+    wanted.set(name, mdc);
+  }
+
+  const emitted = [];
+  const swept = [];
+  if (!dryRun) {
+    if (wanted.size > 0) fs.mkdirSync(outDir, { recursive: true });
+    for (const [name, mdc] of wanted) {
+      const dest = path.join(outDir, name);
+      if (!fs.existsSync(dest) || fs.readFileSync(dest, 'utf8') !== mdc) {
+        fs.writeFileSync(dest, mdc);
+        emitted.push(name);
+      }
+    }
+    // Sweep only construct-<rule>.mdc files this module owns; construct.mdc (the
+    // front-door pointer) and user-authored files are never touched.
+    let existing = [];
+    try { existing = fs.readdirSync(outDir); } catch { /* no rules dir */ }
+    for (const name of existing) {
+      if (name.startsWith('construct-') && name.endsWith('.mdc') && !wanted.has(name)) {
+        fs.rmSync(path.join(outDir, name), { force: true });
+        swept.push(name);
+      }
+    }
+  }
+  return { emitted, swept, matched: [...wanted.keys()] };
+}

package/lib/runtime/uv-bootstrap.mjs

@@ -17,7 +17,7 @@
  * sidecar without relying on PATH state.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 
@@ -37,6 +37,31 @@ function which(bin) {
   return result.stdout.trim().split('\n')[0] || null;
 }
 
+// Provisioning runs on the request path (the first docling ingest), including
+// inside the long-lived MCP server. spawnSync would block the event loop for the
+// whole multi-minute install — freezing every other request and defeating the
+// per-tool dispatch timeout. Run each step via async spawn instead, shaped to
+// mirror spawnSync's result so describeStepFailure reads it unchanged.
+
+function runAsync(cmd, args, { timeoutMs, env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { env });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (d) => { stdout += d; });
+    child.stderr?.on('data', (d) => { stderr += d; });
+    const timer = timeoutMs ? setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, timeoutMs) : null;
+    child.on('error', (error) => { if (timer) clearTimeout(timer); resolve({ status: null, stdout, stderr, error, signal: null }); });
+    child.on('close', (code, signal) => {
+      if (timer) clearTimeout(timer);
+      resolve({ status: code, stdout, stderr, signal: timedOut ? 'SIGTERM' : signal, error: timedOut ? { code: 'ETIMEDOUT' } : null });
+    });
+  });
+}
+
 // First-run docling provisioning blocks for minutes (uv install, venv, then a
 // large `uv pip install docling` that pulls ML deps). Without a heartbeat it
 // reads as a hang. Progress goes to stderr only, so JSON consumers on stdout are
@@ -56,7 +81,7 @@ function describeStepFailure(label, result, timeoutMs) {
   return `${label} failed (${result.status}): ${result.stderr || result.stdout || result.error?.message || 'unknown error'}`;
 }
 
-function ensureUv(installDir) {
+async function ensureUv(installDir) {
   const fromPath = which('uv');
   if (fromPath) return fromPath;
   const cachedUv = path.join(installDir, 'bin', 'uv');
@@ -64,11 +89,7 @@ function ensureUv(installDir) {
   mkdirSync(installDir, { recursive: true });
   progress('Installing uv (Python toolchain) — first run only…');
   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',
-  });
+  const sh = await runAsync('sh', ['-c', `curl -LsSf ${UV_INSTALL_URL} | sh`], { env, timeoutMs: UV_TIMEOUT_MS });
   if (sh.status !== 0) {
     throw new Error(describeStepFailure('uv install', sh, UV_TIMEOUT_MS));
   }
@@ -95,7 +116,7 @@ function writeMarker(markerPath, payload) {
   writeFileSync(markerPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
 }
 
-export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = false } = {}) {
+export async function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = false } = {}) {
   mkdirSync(runtimeDir, { recursive: true });
   const venvDir = path.join(runtimeDir, '.venv');
   const markerPath = path.join(runtimeDir, '.install-marker.json');
@@ -107,22 +128,16 @@ export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = fa
   }
 
   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 = ensureUv(runtimeDir);
+  const uv = await ensureUv(runtimeDir);
 
   progress('Creating Python 3.11 virtualenv…');
-  const venvResult = spawnSync(uv, ['venv', venvDir, '--python', '3.11'], {
-    timeout: VENV_TIMEOUT_MS,
-    encoding: 'utf8',
-  });
+  const venvResult = await runAsync(uv, ['venv', venvDir, '--python', '3.11'], { timeoutMs: VENV_TIMEOUT_MS });
   if (venvResult.status !== 0) {
     throw new Error(describeStepFailure('uv venv', venvResult, VENV_TIMEOUT_MS));
   }
 
   progress(`Installing docling ${DOCLING_PIN} and its dependencies — the slow step (large download)…`);
-  const installResult = spawnSync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], {
-    timeout: INSTALL_TIMEOUT_MS,
-    encoding: 'utf8',
-  });
+  const installResult = await runAsync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], { timeoutMs: INSTALL_TIMEOUT_MS });
   if (installResult.status !== 0) {
     throw new Error(describeStepFailure('docling install', installResult, INSTALL_TIMEOUT_MS));
   }