@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/doc-stamp.mjs

@@ -102,12 +102,17 @@ function splitStamp(content) {
  *   sessionId   {string}  - Construct session ID if available
  *   model       {string}  - Model name/version if available
  *   preserve_id {boolean} - Keep existing cx_doc_id if present (default: true)
+ *   attribution {object}  - Optional { createdBy, createdByAgent } pair. When
+ *                           provided, written into the stamp and (on stamp
+ *                           refresh) carried forward via existing_fields so a
+ *                           later write does not erase the original author.
  */
 export function stampFrontmatter(content, {
   generator = 'construct',
   sessionId = null,
   model = null,
   preserve_id = true,
+  attribution = null,
 } = {}) {
   const existing = hasStamp(content) ? splitStamp(content) : null;
   const existingFields = existing ? parseStamp(content) : {};
@@ -116,6 +121,11 @@ export function stampFrontmatter(content, {
   const createdAt = existingFields.created_at || new Date().toISOString();
   const updatedAt = new Date().toISOString();
 
+  const createdBy = existingFields.created_by ?? attribution?.createdBy ?? null;
+  const createdByAgent = existingFields.created_by_agent ?? attribution?.createdByAgent ?? null;
+  const lastModifiedBy = attribution?.createdBy ?? existingFields.last_modified_by ?? null;
+  const lastModifiedByAgent = attribution?.createdByAgent ?? existingFields.last_modified_by_agent ?? null;
+
   // Body is everything after stamp (or all content if no prior stamp)
   const body = existing ? existing.body : content;
   const hash = bodyHash(body);
@@ -127,6 +137,12 @@ export function stampFrontmatter(content, {
     `updated_at: ${updatedAt}`,
     `generator: ${generator}`,
   ];
+  if (createdBy) lines.push(`created_by: ${createdBy}`);
+  if (createdByAgent) lines.push(`created_by_agent: ${createdByAgent}`);
+  if (lastModifiedBy && lastModifiedBy !== createdBy) lines.push(`last_modified_by: ${lastModifiedBy}`);
+  if (lastModifiedByAgent && lastModifiedByAgent !== createdByAgent) {
+    lines.push(`last_modified_by_agent: ${lastModifiedByAgent}`);
+  }
   if (model) lines.push(`model: ${model}`);
   if (sessionId) lines.push(`session_id: ${sessionId}`);
   lines.push(`body_hash: ${hash}`);

package/lib/docs-verify.mjs

@@ -52,18 +52,11 @@ if (stagedMode) {
   if (changedCode.length === 0) process.exit(0);
   if (changedDocs.length > 0) process.exit(0);
 
-  if (process.env.CONSTRUCT_SKIP_DOCS === "1") {
-    process.stderr.write(
-      `[docs:verify --staged] CONSTRUCT_SKIP_DOCS=1 — skipping doc-coupling check for ${changedCode.length} code file(s).\n`,
-    );
-    process.exit(0);
-  }
-
   const sample = changedCode.slice(0, 6).map((f) => `  - ${f}`).join("\n");
   process.stderr.write(
     `[docs:verify --staged] ${changedCode.length} code file(s) staged but no CHANGELOG.md / docs/* / .cx/context.* updates.\n` +
     `${sample}${changedCode.length > 6 ? `\n  ... (${changedCode.length - 6} more)` : ""}\n` +
-    `Update docs in this commit, or override with CONSTRUCT_SKIP_DOCS=1.\n`,
+    `Update docs in this commit before pushing.\n`,
   );
   process.exit(1);
 }

package/lib/doctor/watchers/bd-watch.mjs

@@ -12,8 +12,10 @@
  * as a label, regardless of how it got there (manual, ai, automated).
  */
 
-import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { appendBounded } from '../../logging/rotate.mjs';
+import { resolveProjectScope } from '../../project-root.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -86,6 +88,7 @@ export async function tick() {
       if (seen[key]) continue;
       seen[key] = { ts: Date.now(), id: issue.id };
       const manifest = loadManifest(personaId);
+      const scope = resolveProjectScope();
       const entry = {
         ts: Date.now(),
         personaId,
@@ -96,8 +99,9 @@ export async function tick() {
         summary: `bd ${issue.id} labeled next:cx-${personaId} — ${(issue.title || '').slice(0, 120)}`,
         killSwitchEnv: manifest?.killSwitchEnv || '',
         source: 'bd-watch',
+        ...(scope?.projectId ? { projectId: scope.projectId } : {}),
       };
-      appendFileSync(PENDING_PATH, JSON.stringify(entry) + '\n');
+      appendBounded('role-pending', PENDING_PATH, JSON.stringify(entry) + '\n');
       record({
         kind: 'action',
         watcher: name,

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

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureDoclingVenv } from '../runtime/uv-bootstrap.mjs';
+
+const SIDECAR_SCRIPT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'docling-sidecar.py');
+const REQUEST_TIMEOUT_MS = 300_000;
+
+let activeSidecar = null;
+let requestSeq = 0;
+
+function spawnSidecar({ runtimeDir } = {}) {
+  const { pythonBin } = ensureDoclingVenv({ runtimeDir });
+  const child = spawn(pythonBin, [SIDECAR_SCRIPT], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, PYTHONUNBUFFERED: '1' },
+  });
+
+  const pending = new Map();
+  let stdoutBuffer = '';
+  let stderrBuffer = '';
+  let exitReason = null;
+
+  child.stdout.setEncoding('utf8');
+  child.stderr.setEncoding('utf8');
+
+  child.stdout.on('data', (chunk) => {
+    stdoutBuffer += chunk;
+    let newlineIdx;
+    while ((newlineIdx = stdoutBuffer.indexOf('\n')) !== -1) {
+      const line = stdoutBuffer.slice(0, newlineIdx);
+      stdoutBuffer = stdoutBuffer.slice(newlineIdx + 1);
+      if (!line.trim()) continue;
+      let message;
+      try { message = JSON.parse(line); }
+      catch { continue; }
+      const id = message.id;
+      const handler = pending.get(id);
+      if (!handler) continue;
+      pending.delete(id);
+      clearTimeout(handler.timer);
+      if (message.error) handler.reject(Object.assign(new Error(message.error.message || 'docling sidecar error'), { code: message.error.code, trace: message.error.trace }));
+      else handler.resolve(message.result);
+    }
+  });
+
+  child.stderr.on('data', (chunk) => { stderrBuffer += chunk; });
+
+  child.on('exit', (code) => {
+    exitReason = `exit code ${code}`;
+    for (const [, handler] of pending) {
+      clearTimeout(handler.timer);
+      handler.reject(new Error(`docling sidecar exited (${exitReason}); stderr: ${stderrBuffer.slice(-500)}`));
+    }
+    pending.clear();
+    if (activeSidecar === sidecar) activeSidecar = null;
+  });
+
+  function send(method, params = {}) {
+    if (child.killed || child.exitCode !== null) {
+      return Promise.reject(new Error(`docling sidecar not running: ${exitReason || 'killed'}`));
+    }
+    const id = ++requestSeq;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`docling sidecar timeout after ${REQUEST_TIMEOUT_MS}ms (method=${method})`));
+      }, REQUEST_TIMEOUT_MS);
+      pending.set(id, { resolve, reject, timer });
+      child.stdin.write(JSON.stringify({ id, method, params }) + '\n');
+    });
+  }
+
+  const sidecar = { send, child, get stderr() { return stderrBuffer; } };
+  return sidecar;
+}
+
+function getSidecar() {
+  if (activeSidecar && activeSidecar.child.exitCode === null && !activeSidecar.child.killed) return activeSidecar;
+  activeSidecar = spawnSidecar();
+  return activeSidecar;
+}
+
+export async function extractViaDocling(filePath) {
+  const sidecar = getSidecar();
+  const result = await sidecar.send('extract', { path: path.resolve(filePath) });
+  return result;
+}
+
+export async function shutdownDoclingSidecar() {
+  if (!activeSidecar) return;
+  const sidecar = activeSidecar;
+  activeSidecar = null;
+  try { await sidecar.send('shutdown'); } catch { /* sidecar already gone */ }
+  if (sidecar.child.exitCode === null && !sidecar.child.killed) {
+    sidecar.child.kill('SIGTERM');
+  }
+}
+
+process.on('exit', () => { if (activeSidecar) activeSidecar.child.kill('SIGTERM'); });

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+lib/document-extract/docling-sidecar.py — long-lived JSON-RPC wrapper around docling.
+
+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>}}.
+
+Methods:
+  - ping            → {"ok": true, "doclingVersion": "<x.y.z>"}
+  - extract {path}  → {"markdown": "...", "metadata": {...}, "droppedInfo": [...]}
+  - shutdown        → {"ok": true}; process exits after acknowledgement
+
+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;
+    MCP rides the same transport but adds protocol overhead unsuitable
+    for the parser sidecar.
+  - Drops are surfaced explicitly (kind/count/reason/recoverable) so info
+    loss is observable to the CLI, not silent.
+"""
+import json
+import sys
+import traceback
+from pathlib import Path
+
+try:
+    from docling.document_converter import DocumentConverter
+    from importlib.metadata import version as _pkg_version
+    DOCLING_VERSION = _pkg_version("docling")
+except ImportError as exc:
+    sys.stderr.write(json.dumps({"fatal": "docling-import-failed", "detail": str(exc)}) + "\n")
+    sys.exit(2)
+
+
+_converter = None
+
+
+def get_converter():
+    global _converter
+    if _converter is None:
+        _converter = DocumentConverter()
+    return _converter
+
+
+def extract(params):
+    path_raw = params.get("path")
+    if not path_raw:
+        raise ValueError("missing 'path' parameter")
+    path = Path(path_raw)
+    if not path.exists():
+        raise FileNotFoundError(f"file not found: {path}")
+
+    result = get_converter().convert(str(path))
+    doc = result.document
+    markdown = doc.export_to_markdown()
+
+    metadata = {
+        "format": result.input.format.value if hasattr(result.input, "format") else None,
+        "pageCount": len(doc.pages) if hasattr(doc, "pages") and doc.pages is not None else None,
+        "doclingVersion": DOCLING_VERSION,
+        "sourcePath": str(path),
+    }
+
+    dropped_info = []
+    try:
+        page_count = metadata.get("pageCount") or 0
+        if page_count and len(markdown) / max(page_count, 1) < 50:
+            dropped_info.append({
+                "kind": "low-text-yield",
+                "count": page_count,
+                "reason": "Extracted text density below 50 chars/page suggests image-heavy or scanned content; OCR may have partial coverage.",
+                "recoverable": True,
+            })
+    except Exception:
+        pass
+
+    return {
+        "markdown": markdown,
+        "metadata": metadata,
+        "droppedInfo": dropped_info,
+    }
+
+
+def handle(request):
+    method = request.get("method")
+    params = request.get("params") or {}
+    if method == "ping":
+        return {"ok": True, "doclingVersion": DOCLING_VERSION}
+    if method == "extract":
+        return extract(params)
+    if method == "shutdown":
+        return {"ok": True}
+    raise ValueError(f"unknown method: {method}")
+
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        request_id = None
+        try:
+            request = json.loads(line)
+            request_id = request.get("id")
+            result = handle(request)
+            sys.stdout.write(json.dumps({"id": request_id, "result": result}) + "\n")
+            sys.stdout.flush()
+            if request.get("method") == "shutdown":
+                return
+        except Exception as exc:
+            error = {
+                "code": type(exc).__name__,
+                "message": str(exc),
+                "trace": traceback.format_exc() if not isinstance(exc, (ValueError, FileNotFoundError)) else None,
+            }
+            sys.stdout.write(json.dumps({"id": request_id, "error": error}) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,79 @@
+/**
+ * lib/document-extract/whisper-client.mjs — invoke whisper.cpp on audio/video.
+ *
+ * Returns `{ markdown, metadata, droppedInfo }` matching the shape returned
+ * by docling-client for symmetry with the document-extract dispatcher.
+ *
+ * Strategy: run whisper-cli with the source file → text transcript. The
+ * transcript is wrapped as a fenced "## Transcript" section in markdown so
+ * the format-converter pipeline downstream gets a uniform shape.
+ *
+ * 2026-06 notes:
+ *   - whisper.cpp + Metal hits ~10× real-time on M-series for large-v3.
+ *     Default model is `base.en` for speed; override via
+ *     CONSTRUCT_WHISPER_MODEL for non-English or higher-quality runs.
+ *   - Non-audio formats are rejected up front so the docling sidecar stays
+ *     the single owner of PDF/Office/HTML parsing.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { ensureWhisperRuntime } from '../runtime/whisper-bootstrap.mjs';
+
+const CLI_TIMEOUT_MS = 600_000;
+
+function runWhisperCli({ binary, modelPath, sourcePath, outputBase }) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-m', modelPath,
+      '-f', sourcePath,
+      '-otxt',
+      '-of', outputBase,
+      '-l', 'auto',
+      '-nt',
+    ];
+    const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (c) => { stdout += c; });
+    child.stderr.on('data', (c) => { stderr += c; });
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`whisper-cli timeout after ${CLI_TIMEOUT_MS}ms`));
+    }, CLI_TIMEOUT_MS);
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) reject(new Error(`whisper-cli exited ${code}: ${stderr.slice(-500)}`));
+      else resolve({ stdout, stderr });
+    });
+    child.on('error', (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
+export async function extractViaWhisper(filePath, { runtimeDir, model } = {}) {
+  const absolutePath = path.resolve(filePath);
+  const { binary, modelPath, model: resolvedModel } = await ensureWhisperRuntime({ runtimeDir, model });
+  const tmpDir = mkdtempSync(path.join(os.tmpdir(), 'construct-whisper-'));
+  const outputBase = path.join(tmpDir, 'transcript');
+  try {
+    const { stderr } = await runWhisperCli({ binary, modelPath, sourcePath: absolutePath, outputBase });
+    const transcript = readFileSync(`${outputBase}.txt`, 'utf8').trim();
+    const detectedLanguage = stderr.match(/auto-detected language: (\w+)/)?.[1] || null;
+    const markdown = `## Transcript\n\n${transcript}\n`;
+    return {
+      markdown,
+      metadata: {
+        sourcePath: absolutePath,
+        whisperModel: resolvedModel,
+        binarySource: binary,
+        detectedLanguage,
+      },
+      droppedInfo: transcript.length === 0
+        ? [{ kind: 'empty-transcript', count: 1, reason: 'whisper-cli returned no text — silent file, unsupported codec, or model mismatch.', recoverable: true }]
+        : [],
+    };
+  } finally {
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* tmp cleanup best-effort */ }
+  }
+}

package/lib/document-extract.mjs

@@ -1,15 +1,19 @@
 /**
  * lib/document-extract.mjs — shared local document extraction for retrieval and MCP reads.
  *
- * Handles plain-text formats directly, XML/HTML via lightweight tag stripping,
- * Office zip containers via unzip, and PDFs via pdftotext or macOS-native fallbacks.
- * Also provides extractDocumentMetadata() for structured metadata (title, authors,
- * dates, links) from source document frontmatter and content.
+ * Two extraction paths:
+ *   - Async (preferred): `extractDocumentTextAsync` routes PDF/Office/HTML
+ *     through the docling Python sidecar and audio/video through whisper.cpp.
+ *     Returns { text, markdown, metadata, droppedInfo, ... }.
+ *   - Sync (legacy): `extractDocumentText` keeps regex/CLI extractors.
+ *     PDF/Office output is lower fidelity (tables flattened, formulas
+ *     dropped, scanned pages return empty). Audio/video throws
+ *     { code: 'ASR_REQUIRED' } on this path.
  *
- * All paths now return { text, structured, droppedInfo, method, ... } where
- * droppedInfo is an array of { kind, count, reason, recoverable } objects
- * describing information that was silently dropped during extraction.
- * Audio/video files throw a typed { code: 'ASR_REQUIRED' } error.
+ * `extractDocumentMetadata` returns frontmatter + title/authors/dates.
+ *
+ * All paths return droppedInfo as { kind, count, reason, recoverable }[] so
+ * info loss is observable rather than silent.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
@@ -689,3 +693,64 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   if (extracted.skipped) result.skipped = extracted.skipped;
   return result;
 }
+
+// Async high-fidelity extraction path. Routes PDF/Office/HTML through the
+// docling Python sidecar (layout-aware markdown) and audio/video through
+// whisper.cpp (Metal-accelerated on macOS). Text/transcript/calendar/email
+// paths reuse the sync extraction since regex-stripping is the right tool
+// for those formats. Returns the same { text, droppedInfo, ... } shape as
+// the sync extractor plus a `markdown` field for paths that produce it.
+//
+// 2026-06 best practice: this is the path new callers should use. The sync
+// extractDocumentText is preserved for backwards compatibility with
+// pre-async callers; PDF/Office output via that path is lower fidelity
+// (tables flattened, formulas dropped) and emits a droppedInfo notice.
+
+export async function extractDocumentTextAsync(filePath, { maxChars = null } = {}) {
+  const resolvedPath = resolve(filePath);
+  if (!existsSync(resolvedPath)) throw new Error(`File not found: ${resolvedPath}`);
+  const extension = extname(resolvedPath).toLowerCase();
+  if (!EXTRACTABLE_DOCUMENT_EXTS.has(extension)) {
+    throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
+  }
+
+  if (AUDIO_VIDEO_EXTS.has(extension)) {
+    const { extractViaWhisper } = await import('./document-extract/whisper-client.mjs');
+    const out = await extractViaWhisper(resolvedPath);
+    return finalizeAsyncResult({ resolvedPath, extension, extractionMethod: 'whisper', extracted: out, maxChars });
+  }
+
+  const doclingFormats = new Set([
+    '.pdf',
+    ...ZIP_DOCUMENT_EXTS,
+    ...RICH_TEXT_EXTS,
+    ...MDLS_DOCUMENT_EXTS,
+  ]);
+  if (doclingFormats.has(extension)) {
+    const { extractViaDocling } = await import('./document-extract/docling-client.mjs');
+    const out = await extractViaDocling(resolvedPath);
+    return finalizeAsyncResult({ resolvedPath, extension, extractionMethod: 'docling', extracted: out, maxChars });
+  }
+
+  return extractDocumentText(resolvedPath, { maxChars });
+}
+
+function finalizeAsyncResult({ resolvedPath, extension, extractionMethod, extracted, maxChars }) {
+  const text = extracted.markdown ?? extracted.text ?? '';
+  const limit = Number.isFinite(Number(maxChars)) && Number(maxChars) > 0
+    ? Math.min(Number(maxChars), 200_000)
+    : null;
+  const truncated = limit !== null && text.length > limit;
+  return {
+    filePath: resolvedPath,
+    extension,
+    extractionMethod,
+    text: truncated ? `${text.slice(0, limit)}\n` : text,
+    markdown: extracted.markdown ?? null,
+    metadata: extracted.metadata ?? null,
+    truncated,
+    characters: text.length,
+    droppedInfo: extracted.droppedInfo ?? [],
+    structured: extracted.structured ?? null,
+  };
+}

package/lib/document-ingest.mjs

@@ -7,7 +7,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve } from 'node:path';
-import { extractDocumentText, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
+import { extractDocumentText, extractDocumentTextAsync, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
 import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
@@ -127,6 +127,8 @@ export async function ingestDocuments(inputPaths, {
   outputDir = null,
   target = 'knowledge/internal',
   sync = false,
+  strict = false,
+  highFidelity = true,
   env = process.env,
 } = {}) {
   if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
@@ -142,8 +144,12 @@ export async function ingestDocuments(inputPaths, {
   }
 
   const results = [];
+  let totalDrops = 0;
   for (const sourcePath of files) {
-    const extracted = extractDocumentText(sourcePath, { maxChars: 200_000 });
+    const extracted = highFidelity
+      ? await extractDocumentTextAsync(sourcePath, { maxChars: 200_000 })
+      : extractDocumentText(sourcePath, { maxChars: 200_000 });
+    totalDrops += (extracted.droppedInfo ?? []).reduce((a, d) => a + (Number(d.count) || 1), 0);
     const metadata = extractDocumentMetadata(sourcePath);
     const targetPath = resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target });
     ensureDir(dirname(targetPath));
@@ -184,6 +190,13 @@ export async function ingestDocuments(inputPaths, {
     });
   }
 
+  if (strict && totalDrops > 0) {
+    const err = new Error(`--strict: ${totalDrops} dropped items across ${results.filter(r => r.droppedInfo.length).length} files`);
+    err.code = 'INGEST_DROPS';
+    err.droppedInfo = results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath })));
+    throw err;
+  }
+
   return {
     status: 'ok',
     target: outputPath ? 'custom' : target,
@@ -197,6 +210,9 @@ export async function ingestDocuments(inputPaths, {
     indexedLocally: true,
     storageSync: syncResult,
     files: results,
+    droppedInfo: results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath }))),
+    droppedCount: totalDrops,
+    highFidelity,
   };
 }
 
@@ -206,19 +222,25 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let outputDir = null;
   let target = 'knowledge/internal';
   let sync = false;
+  let strict = false;
+  let highFidelity = true;
 
   for (const arg of argv) {
     if (arg.startsWith('--out=')) outputPath = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--out-dir=')) outputDir = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--target=')) target = arg.split('=').slice(1).join('=');
     else if (arg === '--sync') sync = true;
+    else if (arg === '--strict') strict = true;
+    else if (arg === '--legacy-extractor') highFidelity = false;
     else inputs.push(arg);
   }
 
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--sync]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--sync] [--strict] [--legacy-extractor]\n` +
+      `  --strict: exit non-zero if any extraction drops occur\n` +
+      `  --legacy-extractor: use the pre-docling regex extractor (lower fidelity)\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
     );
   }
@@ -229,5 +251,5 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     );
   }
 
-  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, env });
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, env });
 }

package/lib/embed/daemon.mjs

@@ -30,6 +30,7 @@ import { dirname, join } from 'node:path';
 
 import { loadEmbedConfig } from './config.mjs';
 import { Scheduler } from './scheduler.mjs';
+import { rotateIfOversized } from '../logging/rotate.mjs';
 import { SnapshotEngine, renderMarkdown } from './snapshot.mjs';
 import { ApprovalQueue } from './approval-queue.mjs';
 import { dispatchOutputs } from './output.mjs';
@@ -594,6 +595,25 @@ export class EmbedDaemon {
       },
     );
 
+    // ── Job 6: daemon-log-rotation ────────────────────────────────────────────
+    // OS supervisors (launchd/systemd/schtasks) redirect daemon stdout to
+    // ~/.cx/runtime/embed-daemon.log with no rotation. A stuck telemetry
+    // log line filled it to 34 GB on one local install; rotate proactively.
+    // CONSTRUCT_EMBED_LOG_MAX_MB overrides the default 50 MB cap.
+
+    this.#scheduler.register(
+      'daemon-log-rotation',
+      60_000,
+      async () => {
+        const logPath = join(homedir(), '.cx', 'runtime', 'embed-daemon.log');
+        const capMb = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_MB) || 50;
+        const maxBytes = Math.floor(capMb * 1024 * 1024);
+        const maxSegments = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_SEGMENTS) || 5;
+        await rotateIfOversized(logPath, { maxBytes, maxSegments, gzip: true });
+      },
+      { runImmediately: true },
+    );
+
     // ── Job 0: telemetry-setup ───────────────────────────────────────────────────
 // On startup — ensure annotation queues and eval configs exist (idempotent)
 this.#scheduler.register(
@@ -1075,7 +1095,12 @@ this.#scheduler.register(
                 outputTokens = data.usage?.completion_tokens || 0;
               }
             }
-          } catch { /* probe call failed — still record timing */ }
+          } catch (probeErr) {
+            // Probe call failed; record the timing entry but surface the
+            // failure to the daemon log so operators can distinguish a 0ms
+            // success from a hard error. Don't crash the daemon.
+            process.stderr.write(`[embed] Probe call failed: ${probeErr.message}\n`);
+          }
 
           const endTime = Date.now();