@geraldmaron/construct 1.0.6 → 1.0.7

package/lib/document-extract.mjs

@@ -10,6 +10,11 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
+// 50 MB hard cap mirrors lib/embed/inbox.mjs and lib/observation-store.mjs.
+// Anything larger is intentionally not extracted to keep the daemon path
+// bounded; callers receive an empty text plus a `skipped` marker.
+const MAX_EML_BYTES = 50 * 1024 * 1024;
+
 export const UTF8_TEXT_EXTS = new Set([
   '.md', '.txt', '.rst', '.adoc', '.json', '.yaml', '.yml', '.toml',
   '.js', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.sh', '.bash',
@@ -21,11 +26,13 @@ export const UTF8_TEXT_EXTS = new Set([
 export const ZIP_DOCUMENT_EXTS = new Set(['.docx', '.xlsx', '.pptx', '.odt', '.ods']);
 export const RICH_TEXT_EXTS = new Set(['.doc', '.rtf']);
 export const MDLS_DOCUMENT_EXTS = new Set(['.xls', '.ppt', '.pages', '.numbers', '.key']);
+export const EMAIL_DOCUMENT_EXTS = new Set(['.eml']);
 export const EXTRACTABLE_DOCUMENT_EXTS = new Set([
   ...UTF8_TEXT_EXTS,
   ...ZIP_DOCUMENT_EXTS,
   ...RICH_TEXT_EXTS,
   ...MDLS_DOCUMENT_EXTS,
+  ...EMAIL_DOCUMENT_EXTS,
   '.pdf',
 ]);
 
@@ -176,6 +183,203 @@ export function isExtractableDocumentPath(filePath) {
   return EXTRACTABLE_DOCUMENT_EXTS.has(extname(filePath).toLowerCase());
 }
 
+// Minimal RFC 5322 header decoder. Unfolds continuation lines (a line that
+// begins with whitespace continues the previous header) and splits each
+// header into (name, value). Stops at the first blank line, which RFC 5322
+// defines as the header/body separator.
+function parseRfc5322Headers(headerBlock) {
+  const lines = headerBlock.split('\n');
+  const unfolded = [];
+  for (const line of lines) {
+    if (/^[ \t]/.test(line) && unfolded.length > 0) {
+      unfolded[unfolded.length - 1] += ' ' + line.trim();
+    } else {
+      unfolded.push(line);
+    }
+  }
+  const headers = {};
+  for (const line of unfolded) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const name = line.slice(0, idx).trim().toLowerCase();
+    const value = line.slice(idx + 1).trim();
+    if (!name) continue;
+    // Multiple Received headers are common; keep the first occurrence of
+    // any header so From/Subject/Date pick the outermost value.
+    if (!(name in headers)) headers[name] = value;
+  }
+  return headers;
+}
+
+// Split a Content-Type header value into the bare type and a parameter map.
+// Returns { type, params } where type is lowercased and stripped, params is
+// keyed by lowercased name with values stripped of surrounding quotes.
+function parseContentType(value) {
+  if (!value) return { type: '', params: {} };
+  const parts = value.split(';').map((s) => s.trim()).filter(Boolean);
+  const type = (parts.shift() || '').toLowerCase();
+  const params = {};
+  for (const part of parts) {
+    const idx = part.indexOf('=');
+    if (idx === -1) continue;
+    const k = part.slice(0, idx).trim().toLowerCase();
+    let v = part.slice(idx + 1).trim();
+    if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+    params[k] = v;
+  }
+  return { type, params };
+}
+
+// Split a multipart body on the boundary marker. Each returned segment is
+// itself a mini MIME entity (its own header block, blank line, body). The
+// closing `--boundary--` terminator is honored by stripping anything past
+// it. Boundaries that do not appear in the body produce a single segment.
+function splitMultipart(body, boundary) {
+  if (!boundary) return [body];
+  const marker = '--' + boundary;
+  const closer = marker + '--';
+  const closeIdx = body.indexOf(closer);
+  const scoped = closeIdx === -1 ? body : body.slice(0, closeIdx);
+  const segments = scoped.split(marker);
+  // The piece before the first boundary is the preamble; discard it.
+  return segments.slice(1).map((seg) => seg.replace(/^\r?\n/, '').replace(/\r?\n$/, ''));
+}
+
+// Decode a quoted-printable body. Tolerant: malformed `=XX` sequences are
+// passed through verbatim rather than throwing, which matches real-world
+// mailers more closely than a strict decoder.
+function decodeQuotedPrintable(text) {
+  return text
+    .replace(/=\r?\n/g, '')
+    .replace(/=([0-9A-Fa-f]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+
+function decodeTransferEncoded(text, encoding) {
+  const enc = String(encoding || '').toLowerCase();
+  if (enc === 'quoted-printable') return decodeQuotedPrintable(text);
+  if (enc === 'base64') {
+    try { return Buffer.from(text.replace(/\s+/g, ''), 'base64').toString('utf8'); } catch { return text; }
+  }
+  return text;
+}
+
+// Walk a parsed MIME entity, returning the first text/plain body it finds
+// and a flat list of attachment filenames encountered along the way. The
+// walker stops at depth 8 so a hand-crafted pathological message cannot
+// exhaust the stack.
+function walkMimeForPlainText(rawEntity, depth = 0) {
+  if (depth > 8) return { text: '', attachments: [] };
+  const sepIdx = rawEntity.indexOf('\n\n') !== -1
+    ? rawEntity.indexOf('\n\n')
+    : rawEntity.indexOf('\r\n\r\n');
+  if (sepIdx === -1) return { text: '', attachments: [] };
+  const headerBlock = rawEntity.slice(0, sepIdx);
+  const body = rawEntity.slice(sepIdx).replace(/^\r?\n\r?\n/, '');
+  const headers = parseRfc5322Headers(headerBlock);
+  const { type, params } = parseContentType(headers['content-type'] || 'text/plain');
+  const disposition = parseContentType(headers['content-disposition'] || '');
+  const filename = disposition.params.filename || params.name || null;
+
+  if (type.startsWith('multipart/')) {
+    const attachments = [];
+    let firstPlain = '';
+    for (const seg of splitMultipart(body, params.boundary)) {
+      const child = walkMimeForPlainText(seg, depth + 1);
+      attachments.push(...child.attachments);
+      if (!firstPlain && child.text) firstPlain = child.text;
+    }
+    return { text: firstPlain, attachments };
+  }
+
+  if (disposition.type === 'attachment' && filename) {
+    return { text: '', attachments: [filename] };
+  }
+
+  if (type === '' || type === 'text/plain') {
+    return {
+      text: decodeTransferEncoded(body, headers['content-transfer-encoding']),
+      attachments: [],
+    };
+  }
+
+  // Non-plain leaves with an explicit filename are treated as attachments.
+  if (filename) return { text: '', attachments: [filename] };
+  return { text: '', attachments: [] };
+}
+
+/**
+ * Extract a normalized representation of an .eml message.
+ *
+ * Returns { text, headers, attachments, skipped } where:
+ *   text         concatenates Subject, From, Date and the first text/plain
+ *                body, suitable for direct hand-off to the classifier.
+ *   headers      decoded From, Subject, Date, To (raw strings).
+ *   attachments  filenames of every non-plain part with a Content-Disposition
+ *                of `attachment` or a filename parameter. Bodies are skipped.
+ *   skipped      set to `'too large'` if the message exceeded MAX_EML_BYTES;
+ *                in that case text is empty and no parsing was attempted.
+ *
+ * The parser is intentionally minimal: it understands header folding, the
+ * `--boundary` framing of multipart messages, and quoted-printable / base64
+ * transfer encodings. It does not decode RFC 2047 encoded-word headers, does
+ * not chase nested message/rfc822 envelopes, and does not validate signatures.
+ */
+export function extractEmlMessage(filePath) {
+  const stat = statSync(filePath);
+  if (stat.size > MAX_EML_BYTES) {
+    return { text: '', headers: {}, attachments: [], skipped: 'too large' };
+  }
+  const raw = readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  const sepIdx = raw.indexOf('\n\n');
+  if (sepIdx === -1) {
+    // No header/body separator. Treat the whole file as the body.
+    return {
+      text: normalizeText(raw),
+      headers: {},
+      attachments: [],
+    };
+  }
+  const headerBlock = raw.slice(0, sepIdx);
+  const body = raw.slice(sepIdx + 2);
+  const headers = parseRfc5322Headers(headerBlock);
+  const { type, params } = parseContentType(headers['content-type'] || 'text/plain');
+
+  let bodyText = '';
+  const attachments = [];
+  if (type.startsWith('multipart/')) {
+    for (const seg of splitMultipart(body, params.boundary)) {
+      const child = walkMimeForPlainText(seg);
+      attachments.push(...child.attachments);
+      if (!bodyText && child.text) bodyText = child.text;
+    }
+  } else {
+    bodyText = decodeTransferEncoded(body, headers['content-transfer-encoding']);
+  }
+
+  const subject = headers.subject || '';
+  const from = headers.from || '';
+  const date = headers.date || '';
+  const to = headers.to || '';
+  const text = normalizeText(
+    `Subject: ${subject}\nFrom: ${from}\nDate: ${date}\n\n${bodyText}`,
+  );
+  return {
+    text,
+    headers: { subject, from, date, to },
+    attachments,
+  };
+}
+
+function extractEml(filePath) {
+  const message = extractEmlMessage(filePath);
+  return {
+    text: message.text,
+    method: message.skipped ? 'eml-skipped' : 'eml',
+    skipped: message.skipped || null,
+    attachments: message.attachments,
+  };
+}
+
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 const URL_RE = /https?:\/\/[^\s)>\]"'`]+/g;
 const DATE_KEYS = ['date', 'created', 'created_at', 'updated', 'updated_at', 'published', 'last_modified'];
@@ -268,6 +472,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   else if (ZIP_DOCUMENT_EXTS.has(extension)) extracted = extractZipDocument(resolvedPath, extension);
   else if (RICH_TEXT_EXTS.has(extension)) extracted = extractRichText(resolvedPath);
   else if (MDLS_DOCUMENT_EXTS.has(extension) && process.platform === 'darwin' && commandExists('mdls')) extracted = { text: extractWithMdls(resolvedPath), method: 'mdls' };
+  else if (EMAIL_DOCUMENT_EXTS.has(extension)) extracted = extractEml(resolvedPath);
   else if (extension === '.pdf') extracted = extractPdf(resolvedPath);
   else throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
 
@@ -277,7 +482,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
     : null;
   const truncated = limit !== null && text.length > limit;
 
-  return {
+  const result = {
     filePath: resolvedPath,
     extension,
     extractionMethod: extracted.method,
@@ -285,4 +490,9 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
     truncated,
     characters: text.length,
   };
+  // Surface eml-specific metadata so callers (intake, ingest) can route
+  // attachment filenames and oversize-skip markers without re-parsing.
+  if (extracted.attachments) result.attachments = extracted.attachments;
+  if (extracted.skipped) result.skipped = extracted.skipped;
+  return result;
 }

package/lib/embed/cli.mjs

@@ -41,6 +41,83 @@ function logPath(homeDir = os.homedir()) {
   return path.join(runtimeDir(homeDir), LOG_FILE);
 }
 
+// ---------------------------------------------------------------------------
+// Log rotation
+//
+// The embed daemon writes its stdout/stderr to a single appended file. The
+// file descriptor is opened by the parent process at spawn time; the daemon
+// has no opportunity to reopen mid-flight. Rotation therefore happens at
+// each daemon spawn: if the existing log exceeds the size cap we shift
+// segments (.log → .log.1 → .log.2 → …) and drop the oldest, then the
+// spawn opens a fresh empty file.
+//
+// CONSTRUCT_EMBED_LOG_MAX_MB sets the rotation threshold (default 50 MB).
+// CONSTRUCT_EMBED_LOG_KEEP    sets retained segment count (default 3).
+// Worst-case disk footprint is (MAX_MB * (KEEP + 1)).
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_MB = 50;
+const DEFAULT_KEEP = 3;
+const HARD_CAP_MAX_MB = 500;     // refuse absurd configured values
+const HARD_CAP_KEEP = 20;
+
+function rotationConfig(env = process.env) {
+  const maxMbRaw = Number.parseInt(env.CONSTRUCT_EMBED_LOG_MAX_MB ?? '', 10);
+  const keepRaw = Number.parseInt(env.CONSTRUCT_EMBED_LOG_KEEP ?? '', 10);
+  const maxMb = Number.isFinite(maxMbRaw) && maxMbRaw > 0 ? Math.min(maxMbRaw, HARD_CAP_MAX_MB) : DEFAULT_MAX_MB;
+  const keep = Number.isFinite(keepRaw) && keepRaw >= 0 ? Math.min(keepRaw, HARD_CAP_KEEP) : DEFAULT_KEEP;
+  return { maxBytes: maxMb * 1024 * 1024, keep };
+}
+
+/**
+ * Rotate the embed daemon log if it exceeds the size cap. Exported for tests.
+ *
+ * @param {string} log        - Absolute path to the live log file
+ * @param {object} [env]      - Env object (default: process.env)
+ * @returns {{ rotated: boolean, sizeBytes: number, droppedSegment?: string }}
+ */
+export function rotateEmbedLogIfNeeded(log, env = process.env) {
+  let sizeBytes = 0;
+  try {
+    sizeBytes = fs.statSync(log).size;
+  } catch (err) {
+    if (err.code === 'ENOENT') return { rotated: false, sizeBytes: 0 };
+    process.stderr.write(`[cli.mjs] rotateEmbedLog stat: ${err.message}\n`);
+    return { rotated: false, sizeBytes: 0 };
+  }
+
+  const { maxBytes, keep } = rotationConfig(env);
+  if (sizeBytes <= maxBytes) return { rotated: false, sizeBytes };
+
+  // Shift segments oldest-first: .{keep} gets dropped, .{n} → .{n+1}, .log → .log.1
+  let droppedSegment;
+  try {
+    const oldest = `${log}.${keep}`;
+    if (keep === 0) {
+      // Retention of 0 means rotate-and-discard: the existing log is removed,
+      // no segment is kept.
+      fs.rmSync(log, { force: true });
+      droppedSegment = log;
+      return { rotated: true, sizeBytes, droppedSegment };
+    }
+    if (fs.existsSync(oldest)) {
+      fs.rmSync(oldest, { force: true });
+      droppedSegment = oldest;
+    }
+    for (let n = keep - 1; n >= 1; n--) {
+      const from = `${log}.${n}`;
+      const to = `${log}.${n + 1}`;
+      if (fs.existsSync(from)) fs.renameSync(from, to);
+    }
+    fs.renameSync(log, `${log}.1`);
+  } catch (err) {
+    process.stderr.write(`[cli.mjs] rotateEmbedLog: ${err.message}\n`);
+    return { rotated: false, sizeBytes };
+  }
+
+  return { rotated: true, sizeBytes, droppedSegment };
+}
+
 // ---------------------------------------------------------------------------
 // State helpers
 // ---------------------------------------------------------------------------
@@ -140,6 +217,7 @@ export async function autoStartEmbedIfNeeded(env = process.env, rootDir, homeDir
     const workerPath = path.join(resolvedRoot, 'lib', 'embed', 'worker.mjs');
     const log = logPath(homeDir);
     fs.mkdirSync(path.dirname(log), { recursive: true });
+    rotateEmbedLogIfNeeded(log, env);
     const fd = fs.openSync(log, 'a');
 
     const child = spawn(process.execPath, [workerPath], {
@@ -149,7 +227,18 @@ export async function autoStartEmbedIfNeeded(env = process.env, rootDir, homeDir
     });
     child.unref();
 
-    writeState({ pid: child.pid, configPath: 'auto', startedAt: new Date().toISOString() }, homeDir);
+    let resolvedRootDir = homeDir;
+    try {
+      const { resolveRootDir } = await import('./daemon.mjs');
+      resolvedRootDir = resolveRootDir(env, process.cwd());
+    } catch { /* fall back to homeDir */ }
+
+    writeState({
+      pid: child.pid,
+      configPath: 'auto',
+      startedAt: new Date().toISOString(),
+      rootDir: resolvedRootDir,
+    }, homeDir);
     return { started: true, pid: child.pid };
   } catch (err) {
     return { started: false, reason: `spawn_failed: ${err.message}` };
@@ -196,6 +285,7 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPat
   const workerArgs = configPath ? [workerPath, '--config', configPath] : [workerPath];
   const log = logPath(homeDir);
   fs.mkdirSync(path.dirname(log), { recursive: true });
+  rotateEmbedLogIfNeeded(log, process.env);
   const fd = fs.openSync(log, 'a');
 
   const child = spawn(process.execPath, workerArgs, {
@@ -206,7 +296,21 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPat
   fs.closeSync(fd);
   child.unref();
 
-  writeState({ pid: child.pid, configPath: configPath ?? 'auto', startedAt: new Date().toISOString() }, homeDir);
+  // Resolve rootDir using the same precedence the spawned worker will so the
+  // operator can see which inbox is being watched via `construct embed status`.
+
+  let resolvedRootDir = homeDir;
+  try {
+    const { resolveRootDir } = await import('./daemon.mjs');
+    resolvedRootDir = resolveRootDir(process.env, process.cwd());
+  } catch { /* fall back to homeDir */ }
+
+  writeState({
+    pid: child.pid,
+    configPath: configPath ?? 'auto',
+    startedAt: new Date().toISOString(),
+    rootDir: resolvedRootDir,
+  }, homeDir);
 
   // Brief liveness check — detects immediate crashes (e.g. missing module, bad config path)
   await new Promise(r => setTimeout(r, _livenessCheckMs));
@@ -245,15 +349,32 @@ function cmdEmbedStop(_args, { homeDir = os.homedir() } = {}) {
 // Subcommand: status
 // ---------------------------------------------------------------------------
 
-function cmdEmbedStatus(_args, { homeDir = os.homedir() } = {}) {
+async function cmdEmbedStatus(_args, { homeDir = os.homedir() } = {}) {
   const state = readRunningState(homeDir);
   if (!state) {
     process.stdout.write('embed daemon: stopped\n');
     return;
   }
+
+  // Re-resolve rootDir using the same precedence the daemon would so the
+  // operator sees which inbox is actually being watched (CX_DATA_DIR override,
+  // walked-up project root, or homedir fallback).
+
+  let rootDir = state.rootDir;
+  if (!rootDir) {
+    try {
+      const { resolveRootDir } = await import('./daemon.mjs');
+      rootDir = resolveRootDir(process.env, process.cwd());
+    } catch {
+      rootDir = homeDir;
+    }
+  }
+
   process.stdout.write(`embed daemon: running\n`);
   process.stdout.write(`  pid:        ${state.pid}\n`);
   process.stdout.write(`  config:     ${state.configPath}\n`);
+  process.stdout.write(`  rootDir:    ${rootDir}\n`);
+  process.stdout.write(`  inbox:      ${path.join(rootDir, '.cx', 'inbox')}\n`);
   process.stdout.write(`  started at: ${state.startedAt}\n`);
   process.stdout.write(`  log:        ${logPath(homeDir)}\n`);
 }

package/lib/embed/daemon.mjs

@@ -26,7 +26,7 @@
 
 import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 import { loadEmbedConfig } from './config.mjs';
 import { Scheduler } from './scheduler.mjs';
@@ -109,8 +109,44 @@ async function resolveLLMKey(varName, env) {
 
 // ─── Root dir resolution ─────────────────────────────────────────────────────
 
-function resolveRootDir(env = process.env) {
-  return (env.CX_DATA_DIR ?? '').trim() || homedir();
+// Cap upward search so a daemon launched from deep in the filesystem cannot
+// fan out to thousands of stat() calls in pathological layouts.
+
+const PROJECT_WALKUP_MAX = 10;
+
+/**
+ * Walk up from `startDir` looking for a directory that contains `.cx/context.md`.
+ * Returns the project root path, or null if nothing is found within the cap.
+ * Exported for unit tests.
+ */
+export function findProjectRoot(startDir, { maxLevels = PROJECT_WALKUP_MAX } = {}) {
+  if (!startDir || typeof startDir !== 'string') return null;
+  let current = startDir;
+  for (let i = 0; i <= maxLevels; i++) {
+    try {
+      if (existsSync(join(current, '.cx', 'context.md'))) return current;
+    } catch { /* skip unreadable dir */ }
+    const parent = dirname(current);
+    if (!parent || parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+
+/**
+ * Resolve the daemon's rootDir.
+ *
+ * Precedence:
+ *   1. `CX_DATA_DIR` env override (operator authority)
+ *   2. Project root discovered by walking up from `cwd` looking for `.cx/context.md`
+ *   3. `homedir()` fallback
+ */
+export function resolveRootDir(env = process.env, cwd = process.cwd()) {
+  const override = (env.CX_DATA_DIR ?? '').trim();
+  if (override) return override;
+  const projectRoot = findProjectRoot(cwd);
+  if (projectRoot) return projectRoot;
+  return homedir();
 }
 
 function resolveWorkspaceDir(env = process.env) {
@@ -708,7 +744,10 @@ this.#scheduler.register(
       async () => {
         const result = await this.#inboxWatcher.poll();
         if (result.processed.length) {
-          process.stderr.write(`[embed] Inbox: ingested ${result.processed.length} file(s) from [${result.dirs.join(', ')}]\n`);
+          const { getRebrand } = await import('../profiles/rebrand.mjs');
+          const { signalNoun } = getRebrand(this.#rootDir);
+          const noun = result.processed.length === 1 ? signalNoun : `${signalNoun}s`;
+          process.stderr.write(`[embed] Classified ${result.processed.length} ${noun} from [${result.dirs.join(', ')}]\n`);
           addObservation(this.#rootDir, {
             role: 'construct',
             category: 'insight',

package/lib/embed/docs-lifecycle.mjs

@@ -64,7 +64,7 @@ export function detectDocGaps(target, opts = {}) {
   const gaps = [];
 
   if (target.access === 'remote') {
-    // Remote-only targets: can't inspect filesystem, skip for now
+    // Remote-only targets have no local filesystem to inspect; gap detection requires the local docs tree.
     return gaps;
   }
 

package/lib/embed/inbox.mjs

@@ -29,6 +29,7 @@ import { addObservation } from '../observation-store.mjs';
 import { inferKnowledgeTarget, knowledgeDirForCategory } from '../knowledge/layout.mjs';
 import { docLaneDir, suggestDocsLaneForFile } from '../docs-routing.mjs';
 import { shouldCreateCx } from '../project-detection.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 import { prepareIntakeForIngestedFile } from '../intake/prepare.mjs';
 import { loadIntakeConfig, INTAKE_DEFAULT_MAX_DEPTH } from '../intake/intake-config.mjs';
 
@@ -90,6 +91,7 @@ function writeState(rootDir, state) {
   
   // Only create .cx directories if this is an initialized project
   if (shouldCreateCx(rootDir)) {
+    ensureCxDir(rootDir);
     mkdirSync(join(rootDir, '.cx', 'runtime'), { recursive: true });
     writeFileSync(p, JSON.stringify(state, null, 2) + '\n');
   }

package/lib/embed/scheduler.mjs

@@ -4,24 +4,30 @@
  * Lightweight alternative to a full cron library — runs tasks at fixed
  * intervals, tracks last-run times, and supports graceful shutdown.
  * Zero external deps.
+ *
+ * One-shot startup jobs MUST set `repeat: false`. With `repeat: true`
+ * (the default) and `intervalMs: 0`, the timer fires on every event-loop
+ * tick — the bug that filled embed-daemon.log to 34 GB before this option
+ * was added.
  */
 
 export class Scheduler {
-  #tasks = new Map();   // id → { fn, intervalMs, lastRun, timer, label }
+  #tasks = new Map();   // id → { fn, intervalMs, lastRun, timer, label, repeat }
   #running = false;
 
   /**
    * Register a task. Returns the task id.
    * @param {string} label       - Human-readable name for logging
-   * @param {number} intervalMs  - How often to run (ms)
+   * @param {number} intervalMs  - How often to run (ms); ignored when repeat is false
    * @param {Function} fn        - Async function to call; receives { label, lastRun }
    * @param {object} [opts]
    * @param {boolean} [opts.runImmediately=false] - Run once before first interval fires
    * @param {boolean} [opts.unref=false]           - Call timer.unref() so this task does not keep the event loop alive (use in tests)
+   * @param {boolean} [opts.repeat=true]           - When false, the task is one-shot: it runs once (immediately if runImmediately, otherwise after intervalMs) and never re-arms. Required for startup jobs that pass intervalMs: 0.
    */
-  register(label, intervalMs, fn, { runImmediately = false, unref = false } = {}) {
+  register(label, intervalMs, fn, { runImmediately = false, unref = false, repeat = true } = {}) {
     const id = `${label}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    const task = { label, intervalMs, fn, lastRun: null, timer: null, runImmediately, unref };
+    const task = { label, intervalMs, fn, lastRun: null, timer: null, runImmediately, unref, repeat };
     this.#tasks.set(id, task);
 
     if (this.#running) {
@@ -50,6 +56,7 @@ export class Scheduler {
     for (const task of this.#tasks.values()) {
       if (task.timer) {
         clearInterval(task.timer);
+        clearTimeout(task.timer);
         task.timer = null;
       }
     }
@@ -60,7 +67,10 @@ export class Scheduler {
    */
   unregister(id) {
     const task = this.#tasks.get(id);
-    if (task?.timer) clearInterval(task.timer);
+    if (task?.timer) {
+      clearInterval(task.timer);
+      clearTimeout(task.timer);
+    }
     this.#tasks.delete(id);
   }
 
@@ -74,6 +84,7 @@ export class Scheduler {
       intervalMs: t.intervalMs,
       lastRun: t.lastRun,
       active: Boolean(t.timer),
+      repeat: t.repeat,
     }));
   }
 
@@ -83,6 +94,23 @@ export class Scheduler {
         process.stderr.write(`[scheduler] ${task.label} error: ${err.message}\n`);
       });
     }
+
+    // One-shot jobs do not re-arm. When runImmediately is true, the task has
+    // already executed and no further scheduling is needed. When false, a
+    // single setTimeout fires once at intervalMs.
+    if (!task.repeat) {
+      if (!runImmediately) {
+        task.timer = setTimeout(() => {
+          task.timer = null;
+          this.#runTask(task).catch((err) => {
+            process.stderr.write(`[scheduler] ${task.label} error: ${err.message}\n`);
+          });
+        }, task.intervalMs);
+        if (task.unref && task.timer.unref) task.timer.unref();
+      }
+      return;
+    }
+
     task.timer = setInterval(() => {
       this.#runTask(task).catch((err) => {
         process.stderr.write(`[scheduler] ${task.label} error: ${err.message}\n`);

package/lib/evaluator-optimizer.mjs

@@ -95,9 +95,8 @@ export async function evaluateDocument({ content, docType, evaluatorFn = null })
     return await evaluatorFn({ content, docType, rubric });
   }
   
-  // Default: deterministic rubric-based evaluation
-  // In production, this would call an LLM evaluator
-  // For now, we use structural checks as a proxy
+  // Default path: deterministic structural-rubric evaluation.
+  // Consumers wanting LLM-graded evaluation supply `evaluatorFn` (handled above).
   
   const scores = [];
   const feedback = [];

package/lib/hooks/comment-lint.mjs

@@ -40,8 +40,24 @@ const rootDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const result = lintFile(filePath, { rootDir });
 if (!result.errors.length && !result.warnings.length) process.exit(0);
 
+// Artifact-prose violations are advisory at write-time (no-fabrication policy
+// enforces them at CI/release-gate time via CONSTRUCT_ARTIFACT_LINT_MODE=block).
+// Surface them on stderr but do not block the edit.
+const artifactOnly = (
+  result.errors.length === 0 &&
+  result.warnings.every((w) => w.kind === 'artifact')
+);
+
 const { output } = formatResults([result]);
 process.stderr.write(output);
+
+if (artifactOnly) {
+  process.stderr.write(
+    '\nArtifact-lint advisory (no-fabrication). The edit is not blocked, but these will fail the release gate. Fix before push.\n',
+  );
+  process.exit(0);
+}
+
 process.stderr.write(
   '\nComment policy blocked this edit. Remove the violations or set CONSTRUCT_SKIP_COMMENT_LINT=1.\n',
 );

package/lib/hooks/mcp-audit.mjs

@@ -10,6 +10,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { shouldCreateCx } from '../project-detection.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
@@ -47,7 +48,7 @@ if (audit[mcpServer].length > 200) audit[mcpServer] = audit[mcpServer].slice(-20
 
 try {
   if (shouldCreateCxDir) {
-    mkdirSync(join(cwd, '.cx'), { recursive: true });
+    ensureCxDir(cwd);
     writeFileSync(auditPath, JSON.stringify(audit, null, 2));
   }
 } catch { /* best effort */ }