@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/host-disposition.mjs

@@ -1,20 +1,32 @@
 /**
  * lib/host-disposition.mjs — single source of truth for the disposition of
- * every artifact Construct creates in a host project (ADR-0027 §1).
+ * every artifact Construct creates in a host project (ADR-0027 §1, extended
+ * by ADR-0066 §"Decision" for the machine-scoped heavy-state split).
  *
  * Scope model (see docs/guides/concepts/project-scopes.md):
- *   templates/, docs/  — package/repo durable sources (committed)
- *   .construct/        — per-project launcher (ignored)
- *   .cx/               — per-project runtime: intake, oracle, observations, demos (ignored)
- *   ~/.construct/      — user credentials and doctor state
- *   ~/.cx/             — user-scope telemetry fallback
+ *   templates/, docs/            — package/repo durable sources (committed)
+ *   .construct/                  — per-project launcher (ignored)
+ *   .cx/                         — per-project config-layer + small runtime
+ *                                  markers: context.md/json, workflow.json,
+ *                                  intake, oracle, observations, knowledge,
+ *                                  graph, demos (ignored)
+ *   ~/.construct/projects/<key>/ — per-project machine-scoped heavy state:
+ *                                  traces, orchestration runs, worker logs,
+ *                                  the LanceDB vector index, docling/whisper
+ *                                  bootstrap venvs (ADR-0066)
+ *   ~/.construct/                — user credentials and doctor state
+ *   ~/.cx/                       — user-scope telemetry fallback
  *
  * `IGNORED_PATTERNS` enumerates machine-specific, sync-regenerated artifacts
  * that must never be committed; the init `.gitignore` writer and the
  * `gitignore-coverage` reconciliation both read from here, and uninstall /
  * adapter-prune consume `ADAPTER_DIRS`. Keep this 1:1 with the host-relevant
  * subset of Construct's own repo .gitignore so forward-fix and backward-repair
- * never diverge.
+ * never diverge. `.cx/` covers both the config-layer files and the small
+ * runtime markers that remain project-local post-ADR-0066 — the heavy
+ * categories that moved to `~/.construct/projects/<key>/` are resolved
+ * through `lib/state-root.mjs`, not listed here, since they were never
+ * project-relative paths to gitignore in the first place.
  */
 
 import fs from 'node:fs';
@@ -41,13 +53,22 @@ export const IGNORED_PATTERNS = [
   '.construct/',
   '.mcp.json',
   '.github/prompts/',
-  '.github/copilot-instructions.md',
+  '.github/agents/',
   'config.env',
   'embed.yaml',
   'plan.md',
   'inbox/',
 ];
 
+// User-owned files Construct mutates only via replaceManagedBlock (ADR-0027 §2).
+// These are durable repo source, not ignored cache — they must NOT appear in
+// IGNORED_PATTERNS, but they still need an explicit disposition so consumers
+// know not to gitignore or delete them on uninstall.
+
+export const MANAGED_PATTERNS = [
+  '.github/copilot-instructions.md',
+];
+
 // A pattern counts as already-ignored when an existing line matches it exactly,
 // matches its bare/slashed form, or is a broader `*` / `**` catch-all.
 

package/lib/identity.mjs

@@ -0,0 +1,92 @@
+/**
+ * lib/identity.mjs — actor and service identity for the control plane.
+ *
+ * Resolves human vs service identity from request headers (X-Construct-Actor-Id,
+ * -Tenant-Id, -Session-Id) or env fallback, and validates it per deployment mode
+ * (team/enterprise reject implicit-solo identity). Feeds policy, approval, and audit.
+ */
+
+import { getDeploymentMode } from './deployment-mode.mjs';
+import os from 'node:os';
+
+export class IdentityError extends Error {
+  constructor(message) { super(message); this.name = 'IdentityError'; }
+}
+
+export function serviceIdentity({ serviceId, deploymentMode, role, source } = {}) {
+  return {
+    type: 'service',
+    serviceId: serviceId || 'construct-mcp',
+    deploymentMode: deploymentMode || 'solo',
+    pid: process.pid,
+    role: role || null,
+    source: source || 'implicit-solo',
+  };
+}
+
+export function humanIdentity({ userId, tenantId, sessionId, role, source } = {}) {
+  return {
+    type: 'human',
+    userId: userId || null,
+    tenantId: tenantId || null,
+    sessionId: sessionId || null,
+    role: role || null,
+    source: source || 'headers',
+  };
+}
+
+export function resolveIdentity(params = {}, { env = process.env, cwd } = {}) {
+  const mode = getDeploymentMode(env, { cwd });
+  const meta = params?._meta || {};
+
+  const actorId = meta['X-Construct-Actor-Id'] || '';
+  const tenantId = meta['X-Construct-Tenant-Id'] || '';
+  const sessionId = meta['X-Construct-Session-Id'] || '';
+  const hasHeaders = Boolean(actorId);
+
+  if ((mode === 'team' || mode === 'enterprise') && !hasHeaders) {
+    const role = env.CONSTRUCT_ROLE;
+    if (role) {
+      return serviceIdentity({ serviceId: `role:${role}`, deploymentMode: mode, role, source: 'env-fallback' });
+    }
+    throw new IdentityError(`Missing actor identity in ${mode} mode. Set X-Construct-Actor-Id header or CONSTRUCT_ROLE env var.`);
+  }
+
+  if (hasHeaders) {
+    const isHuman = actorId.includes('@');
+    if (isHuman) {
+      return humanIdentity({ userId: actorId, tenantId: tenantId || null, sessionId: sessionId || null, role: env.CONSTRUCT_ROLE || null, source: 'headers' });
+    }
+    return serviceIdentity({ serviceId: actorId, deploymentMode: mode, role: env.CONSTRUCT_ROLE || null, source: 'headers' });
+  }
+
+  return serviceIdentity({ serviceId: `local-${os.hostname()}`, deploymentMode: mode, role: env.CONSTRUCT_ROLE || null, source: 'implicit-solo' });
+}
+
+export function identityRole(identity) {
+  return identity?.role || null;
+}
+
+export function validateIdentity(identity, mode) {
+  if (!identity) return 'Identity is required';
+  if (!identity.type) return 'Identity type is required';
+  if (identity.type === 'human' && !identity.userId) return 'Human identity requires userId';
+  if (identity.type === 'service' && !identity.serviceId) return 'Service identity requires serviceId';
+  if ((mode === 'team' || mode === 'enterprise') && identity.source === 'implicit-solo') {
+    return `Implicit identity not allowed in ${mode} mode`;
+  }
+  return null;
+}
+
+export function identityToRecord(identity) {
+  if (!identity) return {};
+  return {
+    type: identity.type,
+    userId: identity.userId || null,
+    serviceId: identity.serviceId || null,
+    tenantId: identity.tenantId || null,
+    sessionId: identity.sessionId || null,
+    role: identity.role || null,
+    deploymentMode: identity.deploymentMode || null,
+  };
+}

package/lib/ingest/degraded-extract.mjs

@@ -0,0 +1,96 @@
+/**
+ * lib/ingest/degraded-extract.mjs — manifest-governed extraction with a declared fallback chain.
+ *
+ * lib/document-ingest.mjs already bounds a docling attempt with a timeout and
+ * falls back to the node-native extractor on any failure; extractWithChain adds
+ * the governance piece LMCP-K2 requires — the fallback path comes from the
+ * docling ingestion-provider manifest's `degradation.chain` (docling ->
+ * node-native -> refuse) rather than being implicit in the calling code, and
+ * every result is stamped `degraded` so a caller can tell "docling ran" from
+ * "docling was unavailable and a lower-fidelity extractor stood in." A file
+ * type outside the node-native backend's coverage (xlsx/pptx/odt/ods) walks the
+ * chain straight to `refuse` and throws, per the manifest's terminal step.
+ */
+import { degradationChain, probeInstall } from './sidecar-providers.mjs';
+
+const NODE_NATIVE_EXTS = new Set(['.pdf', '.docx']);
+
+function degradedResult(extracted, { chainStep, reason }) {
+  return {
+    ...extracted,
+    degraded: true,
+    degradationStep: chainStep,
+    droppedInfo: [
+      ...(extracted.droppedInfo ?? []),
+      {
+        kind: 'ingestion-provider-degraded',
+        count: 1,
+        reason,
+        recoverable: true,
+      },
+    ],
+  };
+}
+
+/**
+ * extractWithChain(filePath, opts) — run docling extraction governed by the
+ * docling manifest's declared degradation chain.
+ *
+ * @param {object} opts
+ * @param {string} opts.extension lowercased file extension (drives node-native eligibility)
+ * @param {Function} opts.doclingExtract async (filePath) => extraction result; throws on failure
+ * @param {Function} [opts.nodeNativeExtract] async (filePath) => extraction result; throws on failure
+ * @param {Function} [opts.installProbeImpl] injectable probeInstall (fake probes for tests)
+ * @param {boolean} [opts.skipInstallProbe] when true, always attempts doclingExtract
+ *        regardless of the install probe (used when the caller already knows
+ *        docling ran, e.g. contract-test doubles)
+ * @returns {Promise<object>} extraction result; `degraded: true` when the chain fell through
+ */
+export async function extractWithChain(filePath, {
+  extension,
+  doclingExtract,
+  nodeNativeExtract = null,
+  installProbeImpl = probeInstall,
+  skipInstallProbe = false,
+} = {}) {
+  const chain = degradationChain('docling');
+  if (!chain) {
+    throw new Error('docling ingestion-provider manifest is missing or has no degradation chain declared');
+  }
+
+  const installed = skipInstallProbe || installProbeImpl('docling').installed;
+  if (installed) {
+    try {
+      const extracted = await doclingExtract(filePath);
+      return { ...extracted, degraded: false, degradationStep: 'docling' };
+    } catch (err) {
+      return fallToNodeNative(filePath, { extension, nodeNativeExtract, reason: `docling extraction failed: ${err.message}` });
+    }
+  }
+
+  return fallToNodeNative(filePath, { extension, nodeNativeExtract, reason: 'docling is not installed' });
+}
+
+async function fallToNodeNative(filePath, { extension, nodeNativeExtract, reason }) {
+  const nodeNativeEligible = NODE_NATIVE_EXTS.has(extension) && typeof nodeNativeExtract === 'function';
+  if (!nodeNativeEligible) {
+    const err = new Error(
+      `${reason}; no node-native fallback covers '${extension}' — refusing per the docling degradation chain. ` +
+      'Run `construct provider test docling` for diagnosis, or `construct install --with-docling`.',
+    );
+    err.code = 'INGESTION_PROVIDER_REFUSED';
+    err.chainStep = 'refuse';
+    throw err;
+  }
+
+  try {
+    const extracted = await nodeNativeExtract(filePath);
+    return degradedResult(extracted, { chainStep: 'node-native', reason: `${reason}; used the node-native extractor (${extracted.extractionMethod}).` });
+  } catch (err) {
+    const refuseErr = new Error(`${reason}; node-native fallback also failed: ${err.message} — refusing.`);
+    refuseErr.code = 'INGESTION_PROVIDER_REFUSED';
+    refuseErr.chainStep = 'refuse';
+    refuseErr.cause = err;
+    throw refuseErr;
+  }
+}

package/lib/ingest/docling-remote.mjs

@@ -14,6 +14,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveNonNegativeSetting } from '../env-config.mjs';
 
 const DEFAULT_TIMEOUT_MS = 600_000;
 
@@ -38,7 +39,7 @@ export async function extractViaDoclingRemote({ filePath, maxChars = null, env =
     throw err;
   }
 
-  const budget = timeoutMs ?? (Number(env.CONSTRUCT_DOCLING_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS);
+  const budget = timeoutMs ?? resolveNonNegativeSetting(env, 'CONSTRUCT_DOCLING_TIMEOUT_MS', DEFAULT_TIMEOUT_MS);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), budget);
   try {

package/lib/ingest/provider-extract.mjs

@@ -21,10 +21,8 @@
  * end against a mock provider without a live key.
  */
 
-import { readFileSync, existsSync } from 'node:fs';
-import { extname, join } from 'node:path';
-import { homedir } from 'node:os';
-import { configDir } from '../config/xdg.mjs';
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
 
 import {
   AUDIO_VIDEO_EXTS,
@@ -32,6 +30,7 @@ import {
   TRANSCRIPT_EXTS,
   CALENDAR_EXTS,
 } from '../document-extract.mjs';
+import { resolveSecret } from '../providers/secret-resolver.mjs';
 
 export const PROVIDER_IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
 
@@ -67,23 +66,12 @@ function isAnthropic(provider, model) {
   return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
 }
 
-// Key resolution mirrors the daemon's cheap sources (env, then the two dotenv
-// files) without the shell-rc/1Password walk, which belongs to long-running
-// processes rather than a per-file extraction call. Ambient dotenv discovery
-// only augments the real process env; a caller that injects an explicit env
-// object (embedded callers, tests) is authoritative and hermetic.
-
 function resolveKey(varName, env, allowAmbient) {
-  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
-  if (!allowAmbient) return null;
-  for (const file of [join(configDir(), 'config.env'), join(homedir(), '.env')]) {
-    try {
-      if (!existsSync(file)) continue;
-      const m = readFileSync(file, 'utf8').match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
-      if (m && m[1]) return m[1].trim();
-    } catch { /* unreadable dotenv is not authoritative */ }
+  try {
+    return resolveSecret(varName, { env, allowAmbient });
+  } catch {
+    return null;
   }
-  return null;
 }
 
 async function bodyExcerpt(res) {

package/lib/ingest/sidecar-providers.mjs

@@ -0,0 +1,196 @@
+/**
+ * lib/ingest/sidecar-providers.mjs — governed install/health probes for ingestion sidecars.
+ *
+ * docling (document extraction, provisioned via uv venv) and whisper (audio
+ * transcription, provisioned as a system/cached binary) are ingestion providers
+ * declared as `ingestion-provider` manifests under lib/extensions/manifests/.
+ * The single place that turns a manifest's `installProbe` and `healthCheck`
+ * declarations into an actual probe result, and exposes the manifest's
+ * `degradation.chain` for the ingest pipeline to consume.
+ *
+ * Every probe accepts an injectable `exec`/`fs` seam so doctor and CLI tests can
+ * exercise the present AND absent code paths without depending on the real uv
+ * venv or whisper-cli binary being installed on the test machine (FAKE probes).
+ * Nothing here throws on absence — a missing sidecar is a reportable state
+ * (`installed: false`), never a crash.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+import { loadManifestsFromDir, resolveManifestDirs } from '../extensions/loader.mjs';
+
+export const SIDECAR_PROVIDER_IDS = ['docling', 'whisper'];
+
+function loadManifest(id) {
+  const { builtin } = resolveManifestDirs();
+  const { manifests, errors } = loadManifestsFromDir(builtin);
+  const manifest = manifests.find((m) => m.id === id && m.kind === 'ingestion-provider');
+  if (!manifest) {
+    const relevantError = errors.find((e) => e.includes(`${id}.manifest.json`));
+    return { manifest: null, error: relevantError || `no ingestion-provider manifest found for '${id}'` };
+  }
+  return { manifest, error: null };
+}
+
+function which(bin, { execImpl = spawnSync } = {}) {
+  const checker = process.platform === 'win32' ? 'where' : 'which';
+  const result = execImpl(checker, [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+// docling's install probe reads the venv marker the same way
+// lib/runtime/uv-bootstrap.mjs does, but through an injectable fs seam so tests
+// can simulate "marker present, venv missing" (stale install) and "nothing
+// present" without touching the real filesystem.
+
+function probeDoclingInstall({ runtimeDir, existsImpl = existsSync, readFileImpl = readFileSync } = {}) {
+  const pythonBin = join(runtimeDir, '.venv', 'bin', 'python');
+  const pythonBin3 = join(runtimeDir, '.venv', 'bin', 'python3');
+  const venvPython = existsImpl(pythonBin) ? pythonBin : (existsImpl(pythonBin3) ? pythonBin3 : null);
+  const markerPath = join(runtimeDir, '.install-marker.json');
+
+  if (!existsImpl(markerPath)) {
+    return { installed: false, version: null, reason: 'no install marker at ' + markerPath };
+  }
+  let marker;
+  try {
+    marker = JSON.parse(readFileImpl(markerPath, 'utf8'));
+  } catch (err) {
+    return { installed: false, version: null, reason: `install marker unreadable: ${err.message}` };
+  }
+  if (!venvPython) {
+    return { installed: false, version: marker.doclingVersion || null, reason: 'install marker present but venv python binary missing (stale install)' };
+  }
+  return { installed: true, version: marker.doclingVersion || null, reason: null, pythonBin: venvPython, runtimeDir };
+}
+
+// whisper's install probe mirrors lib/runtime/whisper-bootstrap.mjs's PATH +
+// cached-binary lookup, again through an injectable exec/fs seam.
+
+function probeWhisperInstall({ runtimeDir, candidates, cachedBinaryRel, execImpl = spawnSync, existsImpl = existsSync } = {}) {
+  for (const candidate of candidates) {
+    const found = which(candidate, { execImpl });
+    if (found) return { installed: true, version: null, reason: null, binary: found, source: 'system' };
+  }
+  const cached = join(runtimeDir, cachedBinaryRel);
+  if (existsImpl(cached)) {
+    return { installed: true, version: null, reason: null, binary: cached, source: 'cached' };
+  }
+  return { installed: false, version: null, reason: `not found on PATH (${candidates.join(', ')}) or cached at ${cached}` };
+}
+
+/**
+ * probeInstall(id, opts) — install probe for a governed ingestion provider.
+ *
+ * @param {string} id 'docling' | 'whisper'
+ * @param {object} [opts]
+ * @param {string} [opts.runtimeDir] override runtime dir (defaults to manifest's declared default under cwd)
+ * @param {string} [opts.cwd]
+ * @param {Function} [opts.existsImpl] injectable fs.existsSync (fake probes)
+ * @param {Function} [opts.readFileImpl] injectable fs.readFileSync (fake probes)
+ * @param {Function} [opts.execImpl] injectable spawnSync (fake probes)
+ * @returns {{ ok: boolean, installed: boolean, version: (string|null), reason: (string|null), manifest: object }}
+ */
+export function probeInstall(id, { runtimeDir = null, cwd = process.cwd(), existsImpl = existsSync, readFileImpl = readFileSync, execImpl = spawnSync } = {}) {
+  const { manifest, error } = loadManifest(id);
+  if (!manifest) return { ok: false, installed: false, version: null, reason: error, manifest: null };
+
+  const probeSpec = manifest.installProbe;
+  const resolvedRuntimeDir = runtimeDir || join(cwd, probeSpec.defaultRuntimeDir);
+
+  if (probeSpec.kind === 'venv-marker') {
+    const result = probeDoclingInstall({ runtimeDir: resolvedRuntimeDir, existsImpl, readFileImpl });
+    return { ok: true, ...result, manifest };
+  }
+  if (probeSpec.kind === 'binary-on-path') {
+    const result = probeWhisperInstall({
+      runtimeDir: resolvedRuntimeDir,
+      candidates: probeSpec.candidates,
+      cachedBinaryRel: probeSpec.cachedBinary,
+      execImpl,
+      existsImpl,
+    });
+    return { ok: true, ...result, manifest };
+  }
+  return { ok: false, installed: false, version: null, reason: `unknown installProbe.kind '${probeSpec.kind}'`, manifest };
+}
+
+/**
+ * probeHealth(id, opts) — health check for a governed ingestion provider.
+ *
+ * Runs only when the install probe reports `installed: true`; a not-installed
+ * provider is unhealthy by definition and this short-circuits without
+ * spawning a process (so a missing binary never masquerades as an
+ * exec failure).
+ *
+ * @param {string} id 'docling' | 'whisper'
+ * @param {object} [opts] same injectable seams as probeInstall, plus:
+ * @param {Function} [opts.execImpl] injectable spawnSync for the health subprocess (fake probes)
+ * @returns {{ ok: boolean, healthy: boolean, detail: string, installProbe: object }}
+ */
+export function probeHealth(id, { runtimeDir = null, cwd = process.cwd(), existsImpl = existsSync, readFileImpl = readFileSync, execImpl = spawnSync } = {}) {
+  const installProbe = probeInstall(id, { runtimeDir, cwd, existsImpl, readFileImpl, execImpl });
+  if (!installProbe.ok) {
+    return { ok: false, healthy: false, detail: installProbe.reason, installProbe };
+  }
+  if (!installProbe.installed) {
+    return { ok: true, healthy: false, detail: `${id} not installed: ${installProbe.reason}`, installProbe };
+  }
+
+  const check = installProbe.manifest.healthCheck;
+  if (check.kind !== 'subprocess-version') {
+    return { ok: false, healthy: false, detail: `unknown healthCheck.kind '${check.kind}'`, installProbe };
+  }
+
+  const command = check.command === '<resolvedBinary>'
+    ? installProbe.binary
+    : check.command.replace('<runtimeDir>', installProbe.runtimeDir);
+  const args = check.args.map((a) => (a === '<runtimeDir>' ? installProbe.runtimeDir : a));
+  const result = execImpl(command, args, { encoding: 'utf8', timeout: check.timeoutMs });
+
+  if (result.error) {
+    return { ok: true, healthy: false, detail: `${id} health check failed to spawn: ${result.error.message}`, installProbe };
+  }
+  if (result.status !== 0) {
+    return { ok: true, healthy: false, detail: `${id} health check exited ${result.status}: ${(result.stderr || result.stdout || '').trim().slice(0, 200)}`, installProbe };
+  }
+  const output = (result.stdout || result.stderr || '').trim();
+  return { ok: true, healthy: true, detail: output ? `${id} ${output.split('\n')[0]}` : `${id} healthy`, installProbe };
+}
+
+/**
+ * degradationChain(id) — the manifest-declared fallback chain for a provider.
+ *
+ * @param {string} id
+ * @returns {{ chain: Array<{id:string, mode:string, description:string}>, terminal: string, resultMarking: string }|null}
+ */
+export function degradationChain(id) {
+  const { manifest } = loadManifest(id);
+  return manifest?.degradation || null;
+}
+
+/**
+ * testProvider(id, opts) — combined install+health probe shaped for CLI/doctor
+ * consumption (`construct provider test docling`). Never throws: an absent
+ * provider degrades loudly (`ok: true, healthy: false`) rather than crashing.
+ *
+ * @param {string} id
+ * @param {object} [opts] same injectable seams as probeHealth
+ * @returns {{ id: string, installed: boolean, healthy: boolean, version: (string|null), detail: string, degradation: object|null }}
+ */
+export function testProvider(id, opts = {}) {
+  if (!SIDECAR_PROVIDER_IDS.includes(id)) {
+    return { id, installed: false, healthy: false, version: null, detail: `unknown ingestion provider '${id}'; known: ${SIDECAR_PROVIDER_IDS.join(', ')}`, degradation: null };
+  }
+  const health = probeHealth(id, opts);
+  return {
+    id,
+    installed: !!health.installProbe?.installed,
+    healthy: health.healthy,
+    version: health.installProbe?.version || null,
+    detail: health.detail,
+    degradation: degradationChain(id),
+  };
+}

package/lib/ingest-tooling.mjs

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { resolveDoclingServeUrl } from './ingest/docling-remote.mjs';
+import { defaultRuntimeDir } from './runtime/uv-bootstrap.mjs';
 
 function whichBin(name) {
   const cmd = process.platform === 'win32' ? 'where' : 'which';
@@ -17,12 +18,17 @@ function whichBin(name) {
   return (result.stdout || '').trim().split('\n')[0] || null;
 }
 
-export function doclingVenvPath(cwd = process.cwd()) {
-  return path.join(cwd, '.cx', 'runtime', 'docling', '.venv');
+// One shared, machine-scoped venv (construct-rf26.16), not project-keyed —
+// no cwd/project argument, so every caller on this machine resolves the
+// identical path. `defaultRuntimeDir()` (lib/runtime/uv-bootstrap.mjs) is
+// the single source of truth for where the venv lives.
+
+export function doclingVenvPath() {
+  return path.join(defaultRuntimeDir(), '.venv');
 }
 
-export function detectDoclingSidecar({ cwd = process.cwd() } = {}) {
-  const venv = doclingVenvPath(cwd);
+export function detectDoclingSidecar() {
+  const venv = doclingVenvPath();
   const python = process.platform === 'win32'
     ? path.join(venv, 'Scripts', 'python.exe')
     : path.join(venv, 'bin', 'python');
@@ -79,7 +85,7 @@ export function detectDoclingRemote(env = process.env) {
 
 export function detectIngestPipeline({ cwd = process.cwd(), env = process.env, repoRoot = cwd } = {}) {
   const steps = {
-    docling: detectDoclingSidecar({ cwd }),
+    docling: detectDoclingSidecar(),
     nodeNative: detectNodeNativeDeps({ repoRoot }),
     whisper: detectWhisper(env),
     doclingRemote: detectDoclingRemote(env),