@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/doctor/watchers/oracle-liveness.mjs

@@ -0,0 +1,92 @@
+/**
+ * lib/doctor/watchers/oracle-liveness.mjs — oracle producer-liveness watcher.
+ *
+ * Applies the same idle-safe gate as lib/intake/session-prelude.mjs's
+ * buildOraclePrelude()/readOracleDockState(): the oracle daemon idles itself
+ * out after a few no-work ticks, so a stale last-tick record alone is not
+ * death — only heartbeatFreshness().stale AND at least one pending oracle
+ * item (lib/oracle/actions.mjs listPending(projectDir), filtered to
+ * status==='pending') together mean the producer looks stalled rather than
+ * quiet. Escalates once per stale episode (deduped by the last-tick record's
+ * own `asOf`, so a producer stuck stale for hours doesn't spam every tick);
+ * a fresh tick or an empty pending queue clears the episode. Tick: 60s.
+ *
+ * Needs the project directory (not just homeDir) to call listPending — the
+ * doctor daemon's tick loop (lib/doctor/index.mjs) threads `projectDir`
+ * through runWatcher()/tick(ctx) for this reason; every other watcher
+ * ignores that extra argument.
+ */
+
+import { readHeartbeatStatus, formatAge } from '../../oracle/heartbeat.mjs';
+import { listPending } from '../../oracle/actions.mjs';
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+
+export const name = 'oracle-liveness';
+export const intervalMs = 60 * 1000;
+
+let lastEscalatedAsOf = null;
+
+export async function tick({ projectDir = process.cwd(), env = process.env, homeDir } = {}) {
+  const actions = [];
+  const escalations = [];
+  const notes = [];
+
+  const heartbeat = readHeartbeatStatus({ homeDir, env });
+  if (!heartbeat.enabled) {
+    notes.push({ enabled: false });
+    return { actions, escalations, notes };
+  }
+
+  let pending;
+  try {
+    pending = listPending(projectDir).filter((p) => p.status === 'pending');
+  } catch (err) {
+    notes.push({ error: `listPending failed: ${err.message}` });
+    return { actions, escalations, notes };
+  }
+
+  notes.push({ stale: heartbeat.stale, ageMs: heartbeat.ageMs, asOf: heartbeat.asOf, pendingCount: pending.length });
+
+  const stalled = heartbeat.stale && pending.length > 0;
+
+  if (!stalled) {
+    if (lastEscalatedAsOf) {
+      record({
+        kind: 'recovery',
+        watcher: name,
+        summary: `oracle producer recovered (fresh tick or pending queue cleared; was stalled as of ${lastEscalatedAsOf})`,
+        context: { previousAsOf: lastEscalatedAsOf },
+      });
+    }
+    lastEscalatedAsOf = null;
+    return { actions, escalations, notes };
+  }
+
+  const episodeKey = heartbeat.asOf || 'unknown';
+  if (lastEscalatedAsOf === episodeKey) return { actions, escalations, notes };
+
+  const summary = `oracle-producer-stalled: no oracle tick in ${formatAge(heartbeat.ageMs)} while ${pending.length} pending oracle work item(s) wait (last tick as of ${heartbeat.asOf ?? 'unknown'})`;
+  record({
+    kind: 'sample',
+    watcher: name,
+    result: 'stalled',
+    summary,
+    context: { ageMs: heartbeat.ageMs, asOf: heartbeat.asOf, pendingCount: pending.length },
+  });
+
+  const result = await escalate({
+    watcher: name,
+    eventType: 'oracle.producer_stalled',
+    summary,
+    context: { ageMs: heartbeat.ageMs, asOf: heartbeat.asOf, pendingCount: pending.length },
+  });
+  lastEscalatedAsOf = episodeKey;
+  escalations.push({ eventType: 'oracle.producer_stalled', result });
+
+  return { actions, escalations, notes };
+}
+
+export function __resetOracleLivenessWatcherState() {
+  lastEscalatedAsOf = null;
+}

package/lib/doctor/watchers/orchestration-runs.mjs

@@ -0,0 +1,108 @@
+/**
+ * lib/doctor/watchers/orchestration-runs.mjs — surfaces error/degraded and
+ * stale awaiting-host orchestration runs to the doctor audit log.
+ *
+ * lib/orchestration/runtime.mjs persists a terminal 'error' status (thrown
+ * mid-execution) or a 'degraded'/'completed-with-failures' status (a run
+ * that finished but not cleanly) to the run store via getRun/getRuns. Each
+ * tick here scans the most recent runs for the project the daemon is
+ * running in and records a finding when any carry an error or
+ * degraded/failed terminal status, so `construct doctor logs
+ * --watcher=orchestration-runs` (and the audit trail generally) reflects
+ * runs that did not complete cleanly, not just clean completions.
+ *
+ * A host-backend run standing at 'awaiting-host' is not itself an error — it
+ * is the designed non-terminal state while a host executes the materialized
+ * prompts — but a run whose `updatedAt` has not moved in
+ * CONSTRUCT_AWAITING_HOST_STALE_MS (default 30 minutes) means the host that
+ * requested it likely disconnected before submitting every task result.
+ * That is flagged as a separate advisory finding, never a hard failure, so an
+ * abandoned run stays visible rather than silently invisible.
+ *
+ * Read-only and advisory: this watcher never mutates a run or retries it.
+ */
+
+import { record } from '../audit.mjs';
+import { resolveNonNegativeSetting } from '../../env-config.mjs';
+
+const ATTENTION_STATUSES = new Set(['error', 'degraded', 'completed-with-failures']);
+
+// 30 minutes: long enough that a host actively working through a multi-task
+// run (each submission round-trips the calling agent's own reasoning) is never
+// falsely flagged, short enough that a genuinely disconnected session surfaces
+// within one doctor watch cycle or two.
+
+const DEFAULT_AWAITING_HOST_STALE_MS = 30 * 60 * 1000;
+
+export const name = 'orchestration-runs';
+export const intervalMs = 10 * 60 * 1000;
+
+function projectRoot() {
+  return process.env.CONSTRUCT_PROJECT_ROOT || process.cwd();
+}
+
+function needsAttention(run) {
+  return ATTENTION_STATUSES.has(run.status) || run.degraded === true;
+}
+
+function isStaleAwaitingHost(run, staleMs, now) {
+  if (run.status !== 'awaiting-host') return false;
+  const touchedAt = Date.parse(run.updatedAt || run.createdAt || '');
+  if (!Number.isFinite(touchedAt)) return false;
+  return now - touchedAt >= staleMs;
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const root = projectRoot();
+  const now = Date.now();
+  const staleMs = resolveNonNegativeSetting(process.env, 'CONSTRUCT_AWAITING_HOST_STALE_MS', DEFAULT_AWAITING_HOST_STALE_MS);
+
+  const { getRuns } = await import('../../orchestration/runtime.mjs');
+  const runs = await getRuns(root, { env: process.env, limit: 50 });
+  const affected = runs.filter(needsAttention);
+  const staleAwaitingHost = runs.filter((r) => isStaleAwaitingHost(r, staleMs, now));
+
+  if (affected.length > 0) {
+    // getRuns/listRuns sorts newest-first (createdAt desc) across every store
+    // backend, so the first affected entry is the newest.
+    const newest = affected[0];
+    record({
+      kind: 'finding',
+      watcher: name,
+      result: 'attention',
+      summary: `${affected.length} of ${runs.length} recent run(s) carry an error/degraded status; newest is ${newest.runId} (${newest.status})`,
+      context: {
+        scanned: runs.length,
+        affectedCount: affected.length,
+        newestRunId: newest.runId,
+        newestStatus: newest.status,
+        affectedRunIds: affected.map((r) => r.runId).slice(0, 10),
+      },
+    });
+  }
+
+  if (staleAwaitingHost.length > 0) {
+    const newest = staleAwaitingHost[0];
+    record({
+      kind: 'finding',
+      watcher: name,
+      result: 'attention',
+      summary: `${staleAwaitingHost.length} of ${runs.length} recent run(s) have stood 'awaiting-host' for over ${Math.round(staleMs / 60000)} minute(s) with no submitted result; newest is ${newest.runId}`,
+      context: {
+        scanned: runs.length,
+        staleAwaitingHostCount: staleAwaitingHost.length,
+        staleThresholdMs: staleMs,
+        newestRunId: newest.runId,
+        staleRunIds: staleAwaitingHost.map((r) => r.runId).slice(0, 10),
+      },
+    });
+  }
+
+  if (affected.length === 0 && staleAwaitingHost.length === 0) {
+    return { actions, escalations, notes: [{ scanned: runs.length, affected: 0, staleAwaitingHost: 0 }] };
+  }
+
+  return { actions, escalations, notes: [{ scanned: runs.length, affected: affected.length, staleAwaitingHost: staleAwaitingHost.length }] };
+}

package/lib/doctor/watchers/provider-breaker.mjs

@@ -0,0 +1,78 @@
+/**
+ * lib/doctor/watchers/provider-breaker.mjs — surfaces open provider circuit breakers.
+ *
+ * Reads lib/providers/circuit-breaker.mjs's describeBreakers(), which lib/
+ * providers/registry.mjs populates by wrapping every resolved provider's read/
+ * search/watch/write/webhook methods (failureThreshold=5, cooldownMs=30_000).
+ * Surfaces that breaker state continuously, so a downed provider shows as
+ * "provider X circuit OPEN since T, N failures" in the doctor audit log and
+ * role-escalation path instead of a mystery failure.
+ *
+ * Escalates once per open episode (keyed by the breaker's own `openedAt`), not
+ * once per tick, so a provider stuck OPEN for an hour doesn't spam. Recovery
+ * to CLOSED/HALF_OPEN logs a plain recovery record. Tick: 60s.
+ */
+
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+import { describeBreakers } from '../../providers/circuit-breaker.mjs';
+
+export const name = 'provider-breaker';
+export const intervalMs = 60 * 1000;
+
+const PROVIDER_KEY_PREFIX = 'provider:';
+const escalatedOpenedAt = {};
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const notes = [];
+
+  const breakers = describeBreakers().filter((b) => b.key.startsWith(PROVIDER_KEY_PREFIX));
+
+  for (const breaker of breakers) {
+    const providerId = breaker.key.slice(PROVIDER_KEY_PREFIX.length);
+    notes.push({ id: providerId, state: breaker.state, failureCount: breaker.failureCount });
+
+    if (breaker.state !== 'open') {
+      if (escalatedOpenedAt[providerId]) {
+        record({
+          kind: 'recovery',
+          watcher: name,
+          target: providerId,
+          summary: `${providerId} provider circuit recovered (was OPEN since ${new Date(escalatedOpenedAt[providerId]).toISOString()})`,
+          context: { previousOpenedAt: escalatedOpenedAt[providerId] },
+        });
+      }
+      delete escalatedOpenedAt[providerId];
+      continue;
+    }
+
+    if (escalatedOpenedAt[providerId] === breaker.openedAt) continue;
+
+    const summary = `${providerId} provider circuit OPEN since ${new Date(breaker.openedAt).toISOString()} (${breaker.failureCount} consecutive failures)`;
+    record({
+      kind: 'sample',
+      watcher: name,
+      target: providerId,
+      result: 'open',
+      summary,
+      context: { openedAt: breaker.openedAt, failureCount: breaker.failureCount },
+    });
+
+    const result = await escalate({
+      watcher: name,
+      eventType: 'provider.circuit_open',
+      summary,
+      context: { provider: providerId, openedAt: breaker.openedAt, failureCount: breaker.failureCount },
+    });
+    escalatedOpenedAt[providerId] = breaker.openedAt;
+    escalations.push({ eventType: 'provider.circuit_open', provider: providerId, result });
+  }
+
+  return { actions, escalations, notes };
+}
+
+export function __resetProviderBreakerWatcherState() {
+  for (const key of Object.keys(escalatedOpenedAt)) delete escalatedOpenedAt[key];
+}

package/lib/document-export.mjs

@@ -29,28 +29,45 @@ import { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
 import { convertDocxToDoc, libreOfficeInstallHint, libreOfficePresent, resolveLibreOfficeBin } from './libreoffice-export.mjs';
 import { resolveExportBranding } from './export-branding.mjs';
 
-export const EXPORT_FORMATS = ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'];
-
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
-// Pandoc drives typeset formats; pptxgenjs builds slide decks; legacy `.doc` has no
-// pandoc writer — export DOCX first, then LibreOffice headless down-converts.
-
-const FORMAT_ENGINES = {
-  pdf: { engine: 'pandoc', writer: null, pdfEngine: 'typst', extraBinaries: ['typst'] },
-  docx: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
-  doc: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [], via: 'libreoffice', intermediate: 'docx' },
-  deck: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
-  pptx: { engine: 'pptxgenjs', writer: null, pdfEngine: null, extraBinaries: [] },
-  html: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
-  rtf: { engine: 'pandoc', writer: 'rtf', pdfEngine: null, extraBinaries: [] },
-  odt: { engine: 'pandoc', writer: 'odt', pdfEngine: null, extraBinaries: [] },
-  epub: { engine: 'pandoc', writer: 'epub', pdfEngine: null, extraBinaries: [] },
-  tex: { engine: 'pandoc', writer: 'latex', pdfEngine: null, extraBinaries: [] },
-  txt: { engine: 'pandoc', writer: 'plain', pdfEngine: null, extraBinaries: [] },
-  md: { engine: 'copy', writer: null, pdfEngine: null, extraBinaries: [] },
-  mdx: { engine: 'copy', writer: null, pdfEngine: null, extraBinaries: [] },
-};
+// LMCP-B7: the format→engine map ships as lib/registry/manifests/format-engines.default.json
+// (Pandoc drives typeset formats; pptxgenjs builds slide decks; legacy `.doc` has no
+// pandoc writer — export DOCX first, then LibreOffice headless down-converts), with an
+// optional `.cx/registry/format-engines.json` project override merged in per-resolve.
+// An override entry adds a format or replaces a default one; every other default format
+// survives untouched. EXPORT_FORMATS stays the default-only key list (byte-identical to
+// the prior hardcoded array) since it's a static, non-cwd-aware export consumed by CLI
+// help text; detect()/exportMarkdown() resolve the cwd-aware merged map per call instead.
+
+const DEFAULT_FORMAT_ENGINES_PATH = path.join(REPO_ROOT, 'lib', 'registry', 'manifests', 'format-engines.default.json');
+
+function readJsonIfExists(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function loadDefaultFormatEngines() {
+  const manifest = readJsonIfExists(DEFAULT_FORMAT_ENGINES_PATH);
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`lib/document-export.mjs: missing or malformed default manifest at ${DEFAULT_FORMAT_ENGINES_PATH}`);
+  }
+  return manifest;
+}
+
+const DEFAULT_FORMAT_ENGINES = loadDefaultFormatEngines();
+
+export const EXPORT_FORMATS = Object.keys(DEFAULT_FORMAT_ENGINES);
+
+export function resolveFormatEngines({ repoRoot = REPO_ROOT, cwd = process.cwd() } = {}) {
+  const base = repoRoot === REPO_ROOT ? DEFAULT_FORMAT_ENGINES : loadDefaultFormatEngines();
+  const override = readJsonIfExists(path.join(cwd, '.cx', 'registry', 'format-engines.json'));
+  return override && typeof override === 'object' ? { ...base, ...override } : base;
+}
 
 export function htmlTemplatePath(repoRoot = REPO_ROOT) {
   const p = path.join(repoRoot, 'templates', 'distribution', 'construct-web.html');
@@ -190,7 +207,11 @@ function binVersion(name, args = ['--version'], env = process.env) {
   return line || null;
 }
 
-function installHint(name) {
+// Exported so lib/doctor/engine-health.mjs (LMCP-K3) can surface the same
+// per-binary install hint construct doctor reports, without duplicating the
+// hint strings.
+
+export function installHint(name) {
   if (name === 'pandoc') return 'Install pandoc to enable document export (e.g. `brew install pandoc` on macOS, `apt install pandoc` on Debian/Ubuntu, or https://pandoc.org/installing.html).';
   if (name === 'typst') return 'Install typst to enable PDF export via Pandoc (`brew install typst` on macOS, https://github.com/typst/typst/releases for binaries).';
   if (name === 'construct-pdf.typ') return 'Bundled PDF template missing from templates/distribution/construct-pdf.typ (Construct install integrity issue).';
@@ -209,12 +230,14 @@ export function detect(format, env = process.env, {
   branding = 'construct',
   cwd = process.cwd(),
   repoRoot = REPO_ROOT,
+  libreOfficeExistsSyncFn,
 } = {}) {
   const brandingPolicy = resolveExportBranding(format, branding);
+  const formatEngines = resolveFormatEngines({ repoRoot, cwd });
   const config = format === 'pptx' && brandingPolicy.applied === 'plain'
     ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
-    : FORMAT_ENGINES[format];
-  if (!config) return { ok: false, format, branding: brandingPolicy, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+    : formatEngines[format];
+  if (!config) return { ok: false, format, branding: brandingPolicy, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${Object.keys(formatEngines).join(', ')}.` };
   if (config.engine === 'copy') {
     return { ok: true, format, branding: brandingPolicy, figures: false, present: true, binaries: [], missing: [], message: `Ready: source emit (${format})` };
   }
@@ -237,7 +260,7 @@ export function detect(format, env = process.env, {
   // the export passes --reference-doc only when present, so unlike the PDF/HTML/deck templates a
   // missing reference degrades gracefully rather than blocking the export.
 
-  if (format === 'doc' && !libreOfficePresent(env)) {
+  if (format === 'doc' && !libreOfficePresent(env, libreOfficeExistsSyncFn ? { existsSyncFn: libreOfficeExistsSyncFn } : undefined)) {
     required.push('libreoffice');
   }
   if (figures) {
@@ -257,7 +280,8 @@ export function detect(format, env = process.env, {
       return { name, path: pptxgenPresent() ? 'bundled' : null, version: null };
     }
     if (name === 'libreoffice') {
-      return { name, path: libreOfficePresent(env) ? resolveLibreOfficeBin(env) : null, version: null };
+      const loOpts = libreOfficeExistsSyncFn ? { existsSyncFn: libreOfficeExistsSyncFn } : undefined;
+      return { name, path: libreOfficePresent(env, loOpts) ? resolveLibreOfficeBin(env, loOpts) : null, version: null };
     }
     return { name, path: whichBin(name, env), version: null };
   });
@@ -356,7 +380,8 @@ export function exportMarkdown({
   repoRoot = REPO_ROOT,
 } = {}) {
   if (!inputPath) return { ok: false, format, message: 'exportMarkdown: inputPath is required.' };
-  if (!EXPORT_FORMATS.includes(format)) return { ok: false, format, inputPath, message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  const formatEngines = resolveFormatEngines({ repoRoot, cwd });
+  if (!formatEngines[format]) return { ok: false, format, inputPath, message: `Unsupported format: ${format}. Supported: ${Object.keys(formatEngines).join(', ')}.` };
   if (!fs.existsSync(inputPath)) return { ok: false, format, inputPath, message: `exportMarkdown: input does not exist: ${inputPath}` };
 
   const metadata = parseArtifactMetadata(inputPath);
@@ -371,7 +396,7 @@ export function exportMarkdown({
 
   const config = format === 'pptx' && brandingPolicy.applied === 'plain'
     ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
-    : FORMAT_ENGINES[format];
+    : formatEngines[format];
   const target = path.resolve(outputPath || defaultOutputPath(inputPath, format));
   fs.mkdirSync(path.dirname(target), { recursive: true });
 

package/lib/document-extract/docling-client.mjs

@@ -1,16 +1,20 @@
 /**
  * lib/document-extract/docling-client.mjs — Node side of the docling sidecar.
  *
- * Spawns one long-lived Python process per Node session, framed by newline-
- * delimited JSON over stdin/stdout. Avoids per-call uv/venv warm-up
- * (~2s otherwise) and keeps the docling model resident.
+ * Implements the ingestion sidecar process contract (ADR-0068): spawns one
+ * long-lived Python process per Node session, framed by newline-delimited
+ * JSON over stdin/stdout, as a direct child (so the sidecar's own parent-PID
+ * watch resolves the right PID with no explicit handoff needed). Avoids
+ * per-call uv/venv warm-up (~2s otherwise) and keeps the docling model
+ * resident.
  *
  * Public API:
  *   extractViaDocling(filePath) → { markdown, metadata, droppedInfo }
  *   shutdownDoclingSidecar()    → idempotent process exit
  *
- * The first call provisions the venv on demand via ensureDoclingVenv().
- * Subsequent calls reuse the running sidecar.
+ * The first call provisions the shared, machine-scoped venv on demand via
+ * ensureDoclingVenv() — never at `construct init`, only on first extraction
+ * (construct-rf26.16). Subsequent calls reuse the running sidecar.
  */
 import { spawn } from 'node:child_process';
 import path from 'node:path';

package/lib/document-extract/docling-sidecar.py

@@ -2,6 +2,11 @@
 """
 lib/document-extract/docling-sidecar.py — long-lived JSON-RPC wrapper around docling.
 
+Governed by the ingestion sidecar process contract (ADR-0068): one JSON-RPC
+surface, no business logic beyond the extraction call itself — routing,
+fallback selection, and degradation-chain decisions all live on the Node
+side (lib/document-extract/docling-client.mjs, lib/document-ingest.mjs).
+
 Protocol: newline-delimited JSON over stdin/stdout. Each request is
 {"id": <int>, "method": <str>, "params": <obj>}. Each response is
 {"id": <int>, "result": <obj>} or {"id": <int>, "error": {"code": <str>, "message": <str>}}.
@@ -11,6 +16,15 @@ Methods:
   - extract {path}  → {"markdown": "...", "metadata": {...}, "droppedInfo": [...]}
   - shutdown        → {"ok": true}; process exits after acknowledgement
 
+Parent-PID watch (ADR-0068): spawned as a direct child of the Node process
+via child_process.spawn, so os.getppid() at start is that Node process's PID.
+A background thread polls it every PARENT_POLL_INTERVAL_S; a `kill -9` (or
+any other death Node's own `process.on('exit')` handler cannot run for) still
+leaves this sidecar exiting on its own rather than orphaned. POSIX reparents
+an orphan to init (or the platform's subreaper), so a ppid change is a
+reliable signal; on Windows, ppid does not get reparented the same way, so
+this is best-effort there rather than a guarantee.
+
 Best-practice notes (2026-06):
   - One sidecar per Node session, kept warm to avoid uv/venv startup (~2s).
   - Stdio JSON-RPC is the leanest Python↔Node IPC for non-LLM use cases;
@@ -20,10 +34,23 @@ Best-practice notes (2026-06):
     loss is observable to the CLI, not silent.
 """
 import json
+import os
 import sys
+import threading
+import time
 import traceback
 from pathlib import Path
 
+PARENT_POLL_INTERVAL_S = 2.0
+
+
+def watch_parent(initial_ppid):
+    while True:
+        time.sleep(PARENT_POLL_INTERVAL_S)
+        if os.getppid() != initial_ppid:
+            os._exit(3)
+
+
 try:
     from docling.document_converter import DocumentConverter
     from importlib.metadata import version as _pkg_version
@@ -125,6 +152,9 @@ def handle(request):
 
 
 def main():
+    watcher = threading.Thread(target=watch_parent, args=(os.getppid(),), daemon=True)
+    watcher.start()
+
     for line in sys.stdin:
         line = line.strip()
         if not line:

package/lib/document-extract.mjs

@@ -513,7 +513,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   // Throw a typed error so callers can route to .cx/intake/needs-asr/.
   if (AUDIO_VIDEO_EXTS.has(extension)) {
     const err = new Error(
-      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/guides/intake/audio-video.md.`,
+      `Audio/video extraction requires ASR. Install a local whisper ASR (brew install whisper-cpp). See docs/guides/intake/audio-video.md.`,
     );
     err.code = 'ASR_REQUIRED';
     err.extension = extension;

package/lib/document-ingest.mjs

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'nod
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
 import { extractDocumentTextAsync, extractDocumentTextNodeNative, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
 import { syncFileStateToSql } from './storage/sync.mjs';
+import { purgeExpiredData } from './storage/admin.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
 import { loadProjectConfig } from './config/project-config.mjs';
@@ -338,6 +339,14 @@ export async function ingestDocuments(inputPaths, {
       env,
       project: inferProjectName(cwd),
     });
+
+    // Retention purge on every real sync, matching the MCP storage_sync tool
+    // (lib/mcp/tools/storage.mjs) — best-effort since eviction must never
+    // block a successful ingest.
+    try {
+      const purge = await purgeExpiredData(cwd, { env, project: inferProjectName(cwd) });
+      if (purge.status === 'ok') syncResult = { ...syncResult, retention: purge };
+    } catch { /* best effort */ }
   }
 
   if (strict && totalDrops > 0) {