@geraldmaron/construct 1.0.6 → 1.0.7

package/lib/intake/daemon.mjs

@@ -0,0 +1,121 @@
+/**
+ * lib/intake/daemon.mjs — Continuous intake daemon with safeguards.
+ *
+ * Polls `.cx/inbox/` for new files, classifies them via the existing intake
+ * classifier, and writes packets to `.cx/intake/pending/`. Packets past their
+ * TTL move to `.cx/intake/dead-letter/`; failed classification retries up to
+ * the budget then dead-letters with the failure reason.
+ *
+ * Built on lib/daemons/contract.mjs — every safeguard (bounded lifetime,
+ * idle shutdown, heartbeat, killswitch, single-writer lock) applies.
+ */
+
+import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+
+import { createDaemon, classifyPacket } from '../daemons/contract.mjs';
+
+const KILLSWITCH_ENV = 'CONSTRUCT_INTAKE_DAEMON';
+
+function inboxDir(cwd) { return join(cwd, '.cx', 'inbox'); }
+function pendingDir(cwd) { return join(cwd, '.cx', 'intake', 'pending'); }
+function deadLetterDir(cwd) { return join(cwd, '.cx', 'intake', 'dead-letter'); }
+function heartbeatPath() { return join(homedir(), '.construct', 'intake-daemon.heartbeat'); }
+
+function ensureDir(dir) {
+  try { mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+}
+
+function listInboxFiles(cwd) {
+  const dir = inboxDir(cwd);
+  if (!existsSync(dir)) return [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  return entries
+    .filter((e) => e.isFile() && !e.name.startsWith('.'))
+    .map((e) => join(dir, e.name));
+}
+
+/**
+ * Process one inbox file: classify, persist packet to pending, remove the
+ * inbox source on success, or move to dead-letter on persistent failure.
+ *
+ * Returns one of:
+ *   { didWork: true,  route: 'pending'|'dead-letter', packetId }
+ *   { didWork: false, reason }
+ */
+export async function processInboxFile(filePath, { cwd, classify, now = () => new Date() }) {
+  ensureDir(pendingDir(cwd));
+  ensureDir(deadLetterDir(cwd));
+
+  let body;
+  try { body = readFileSync(filePath, 'utf8'); }
+  catch (err) { return { didWork: false, reason: `read failed: ${err.message}` }; }
+
+  const id = `intake-${now().getTime()}-${Math.random().toString(36).slice(2, 8)}`;
+  const packet = {
+    id,
+    firstSeenAt: new Date(statSync(filePath).mtimeMs).toISOString(),
+    sourcePath: filePath,
+    excerpt: body.slice(0, 500),
+    attempts: 0,
+  };
+
+  const decision = classifyPacket(packet);
+  if (decision.route === 'dead-letter') {
+    return persistDeadLetter(filePath, packet, decision.reason, cwd);
+  }
+
+  try {
+    packet.triage = await classify({ sourcePath: filePath, extractedText: body });
+  } catch (err) {
+    packet.attempts++;
+    packet.lastError = err.message;
+    if (packet.attempts >= 3) {
+      return persistDeadLetter(filePath, packet, 'retry-budget-exhausted', cwd);
+    }
+    return { didWork: false, reason: `classify failed, will retry: ${err.message}` };
+  }
+
+  const packetPath = join(pendingDir(cwd), `${id}.json`);
+  writeFileSync(packetPath, JSON.stringify(packet, null, 2));
+  try {
+    const consumedPath = join(pendingDir(cwd), `.${basename(filePath)}.consumed`);
+    renameSync(filePath, consumedPath);
+  } catch { /* ignore consume failure */ }
+  return { didWork: true, route: 'pending', packetId: id };
+}
+
+function persistDeadLetter(filePath, packet, reason, cwd) {
+  const dlPath = join(deadLetterDir(cwd), `${packet.id}.json`);
+  writeFileSync(dlPath, JSON.stringify({ ...packet, deadLetterReason: reason, deadLetteredAt: new Date().toISOString() }, null, 2));
+  try { renameSync(filePath, join(deadLetterDir(cwd), `.source.${basename(filePath)}`)); } catch { /* ignore */ }
+  return { didWork: true, route: 'dead-letter', packetId: packet.id, reason };
+}
+
+/**
+ * Build a DaemonRunner for the intake daemon. Caller is responsible for
+ * calling .run() — typically construct intake daemon start.
+ */
+export function buildIntakeDaemon({ cwd = process.cwd(), intervalMs = 60_000, classify } = {}) {
+  const classifyFn = classify || (async () => ({ intakeType: 'unknown', rdStage: 'triage', primaryOwner: 'product-manager', recommendedAction: 'review' }));
+  return createDaemon({
+    name: 'intake',
+    intervalMs,
+    killswitchEnv: KILLSWITCH_ENV,
+    heartbeatPath: heartbeatPath(),
+    maxRuntimeMs: 24 * 60 * 60 * 1000,
+    maxIdleTicks: 6,
+    async tick() {
+      const files = listInboxFiles(cwd);
+      if (files.length === 0) return { didWork: false };
+      let workedAny = false;
+      for (const file of files) {
+        const result = await processInboxFile(file, { cwd, classify: classifyFn });
+        if (result.didWork) workedAny = true;
+      }
+      return { didWork: workedAny };
+    },
+  });
+}

package/lib/intake/filesystem-queue.mjs

@@ -10,6 +10,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const QUEUE_SUBDIR = '.cx/intake';
 
@@ -55,6 +56,7 @@ export class FilesystemIntakeQueue {
   enqueue(entry) {
     if (!entry?.intake?.sourcePath) throw new Error('enqueue: entry.intake.sourcePath is required');
     const dir = pendingDir(this.rootDir);
+    ensureCxDir(this.rootDir);
     mkdirSync(dir, { recursive: true });
 
     const ts = timestamp();
@@ -112,6 +114,7 @@ export class FilesystemIntakeQueue {
     if (notes) data.notes = notes;
 
     const dst = path.join(processedDir(this.rootDir), `${id}.json`);
+    ensureCxDir(this.rootDir);
     mkdirSync(path.dirname(dst), { recursive: true });
     writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
     rmSync(src);
@@ -128,6 +131,7 @@ export class FilesystemIntakeQueue {
     if (reason) data.reason = reason;
 
     const dst = path.join(skippedDir(this.rootDir), `${id}.json`);
+    ensureCxDir(this.rootDir);
     mkdirSync(path.dirname(dst), { recursive: true });
     writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
     rmSync(src);
@@ -148,7 +152,8 @@ export class FilesystemIntakeQueue {
       delete data.reason;
 
       const dst = path.join(pendingDir(this.rootDir), `${id}.json`);
-      mkdirSync(path.dirname(dst), { recursive: true });
+      ensureCxDir(this.rootDir);
+    mkdirSync(path.dirname(dst), { recursive: true });
       writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
       rmSync(src);
       return { id, filePath: dst, from: path.basename(dir) };

package/lib/intake/intake-config.mjs

@@ -24,6 +24,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { shouldCreateCx } from '../project-detection.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 export const INTAKE_CONFIG_FILE = '.cx/intake-config.json';
 export const INTAKE_DEFAULT_MAX_DEPTH = 4;
@@ -115,7 +116,7 @@ export function saveIntakeConfig(rootDir, patch = {}) {
   };
 
   const file = intakeConfigPath(rootDir);
-  mkdirSync(join(rootDir, '.cx'), { recursive: true });
+  ensureCxDir(rootDir);
   writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
   return next;
 }

package/lib/intake/prepare.mjs

@@ -77,7 +77,6 @@ export async function prepareIntakeForIngestedFile({
     extractedText: extracted,
     related,
     profile: activeProfile?.id,
-    cwd: rootDir,
   });
 
   // Detect customer mentions and update profiles

package/lib/intake/session-prelude.mjs

@@ -13,6 +13,7 @@
 import { createIntakeQueue } from './queue.mjs';
 import { formatTriageLine } from './classify.mjs';
 import { isBrokered } from '../mcp/broker.mjs';
+import { getRebrand } from '../profiles/rebrand.mjs';
 
 export function buildIntakePrelude({ cwd, env = process.env } = {}) {
   if (!cwd) return '';
@@ -20,11 +21,16 @@ export function buildIntakePrelude({ cwd, env = process.env } = {}) {
     const queue = createIntakeQueue(cwd, env);
     const pending = queue.listPending();
     if (!pending.length) return '';
+    const { intakeQueueLabel, signalNoun } = getRebrand(cwd);
     const recent = pending.slice(-3).map((p) => {
       const src = p.intake?.sourcePath || p.id;
       return `- ${formatTriageLine(src, p.triage)}`;
     });
-    return `\n## Pending R&D intake (${pending.length})\n${recent.join('\n')}\nEach packet at \`.cx/intake/pending/<id>.json\` carries the new signal, a triage block (intakeType, rdStage, primaryOwner, recommendedChain, recommendedAction, risk), related existing docs, and an excerpt. Process via the recommended chain, then close via \`construct intake done <id>\`.\n`;
+    // Strip a trailing " queue" / " intake" so the heading reads
+    // "## Pending R&D intake (N)" rather than the redundant
+    // "## Pending R&D intake queue queue (N)".
+    const heading = intakeQueueLabel.replace(/\s+queue$/i, '');
+    return `\n## Pending ${heading} (${pending.length})\n${recent.join('\n')}\nEach packet at \`.cx/intake/pending/<id>.json\` carries the new ${signalNoun}, a triage block (intakeType, rdStage, primaryOwner, recommendedChain, recommendedAction, risk), related existing docs, and an excerpt. Process via the recommended chain, then close via \`construct intake done <id>\`.\n`;
   } catch {
     return '';
   }

package/lib/intake/traceability.mjs

@@ -0,0 +1,90 @@
+/**
+ * lib/intake/traceability.mjs — stamps intake provenance into artifact frontmatter.
+ *
+ * Backs `construct intake done <id> --output=<path>`: reads the intake packet,
+ * extracts (id, confidence, rationale), and writes them into the artifact's
+ * YAML frontmatter. Refuses to overwrite a different intake_id (an artifact
+ * can be linked to exactly one intake source). Idempotent on re-stamping.
+ *
+ * Read by docs:verify checkIntakeTraceability to surface artifacts in
+ * intake-fed locations that lack a reference.
+ *
+ * Field schema (in artifact YAML frontmatter):
+ *   intake_id: construct-xxx
+ *   intake_confidence: 0.7
+ *   intake_rationale: "Matched 3 keywords: dashboard, latency, p95"
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+export function parseArtifactFrontmatter(content) {
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: {}, body: content, hasBlock: false };
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const rawValue = line.slice(idx + 1).trim();
+    if (!key) continue;
+    const unquoted = rawValue.replace(/^["']|["']$/g, '');
+    if (/^-?\d+(\.\d+)?$/.test(unquoted)) out[key] = Number(unquoted);
+    else out[key] = unquoted;
+  }
+  return { frontmatter: out, body: content.slice(m[0].length), hasBlock: true };
+}
+
+function serializeFrontmatter(fm) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fm)) {
+    if (v === null || v === undefined) continue;
+    if (typeof v === 'number' || typeof v === 'boolean') {
+      lines.push(`${k}: ${v}`);
+    } else {
+      const s = String(v);
+      const needsQuoting = /[:#"'\n]|^\s|\s$/.test(s);
+      lines.push(`${k}: ${needsQuoting ? JSON.stringify(s) : s}`);
+    }
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+export function stampIntakeProvenance(artifactPath, { intakeId, confidence, rationale }) {
+  if (!existsSync(artifactPath)) {
+    throw new Error(`Output artifact not found: ${artifactPath}`);
+  }
+  if (!intakeId) throw new Error('intakeId required for stamping');
+  const content = readFileSync(artifactPath, 'utf8');
+  const { frontmatter, body, hasBlock } = parseArtifactFrontmatter(content);
+
+  const existing = frontmatter.intake_id;
+  if (existing && existing !== intakeId) {
+    throw new Error(
+      `Refusing to overwrite intake_id: artifact already references ${existing}, not ${intakeId}. Resolve manually or supersede.`,
+    );
+  }
+
+  const next = {
+    ...frontmatter,
+    intake_id: intakeId,
+    ...(confidence !== undefined && confidence !== null ? { intake_confidence: confidence } : {}),
+    ...(rationale ? { intake_rationale: rationale } : {}),
+  };
+
+  const fmText = serializeFrontmatter(next);
+  const out = hasBlock ? `${fmText}\n${body}` : `${fmText}\n\n${content}`;
+  writeFileSync(artifactPath, out, 'utf8');
+  return { intake_id: intakeId, intake_confidence: next.intake_confidence, intake_rationale: next.intake_rationale };
+}
+
+export function hasIntakeReference(artifactPath) {
+  if (!existsSync(artifactPath)) return false;
+  const { frontmatter } = parseArtifactFrontmatter(readFileSync(artifactPath, 'utf8'));
+  if (frontmatter.intake_id) return true;
+  if (frontmatter.intake === 'none') return true;
+  return false;
+}

package/lib/knowledge/research-store.mjs

@@ -19,6 +19,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { syncFileStateToSql } from '../storage/sync.mjs';
 import { resolveActiveProfile } from '../profiles/loader.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const ROOT = '.cx/knowledge/external/research';
 const MAX_BYTES = 50 * 1024;
@@ -68,6 +69,7 @@ export async function addResearchFinding({
   const expiresAt = new Date(now.getTime() + ttlDays * 24 * 60 * 60 * 1000).toISOString();
 
   const outDir = join(cwd, ROOT);
+  ensureCxDir(cwd);
   mkdirSync(outDir, { recursive: true });
   const outPath = join(outDir, `${slug}.md`);
 

package/lib/maintenance/cleanup.mjs

@@ -0,0 +1,315 @@
+/**
+ * lib/maintenance/cleanup.mjs — Construct's self-maintenance primitives.
+ *
+ * Every artifact Construct writes has a lifecycle. This module collects the
+ * primitives that enforce that lifecycle: rotate oversized logs, prune
+ * rotated segments, age-out cache directories. Each primitive is pure and
+ * returns a structured summary; runFullCleanup orchestrates them with sane
+ * defaults.
+ *
+ * Triggered from two entry points:
+ *   - `construct cleanup`            — manual sweep, optionally --dry-run
+ *   - bin/construct startup check    — automatic when the installed version
+ *                                       differs from ~/.construct/.cleanup-stamp,
+ *                                       so an upgrade reclaims disk without
+ *                                       requiring a manual command.
+ *
+ * Scope is deliberately narrow: only artifacts whose retention is owned by
+ * the runtime (logs, caches, rotated segments). Knowledge stores
+ * (.cx/observations/, .cx/handoffs/, .cx/intake/) require explicit retention
+ * policy and are left for a follow-up after policy is agreed.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HARD_BUDGET_MS = 5000;
+
+// Size caps in bytes. Each entry: [filename relative to ~/.cx/, maxBytes].
+// Files that exceed maxBytes are truncated (head-preserving rotation is not
+// useful for append-only event logs — the most-recent events are what matter,
+// not the oldest; tail-preserving truncation keeps the last N% by recopying).
+const JSONL_LOG_CAPS_BYTES = {
+  'audit.jsonl': 25 * 1024 * 1024,
+  'contract-violations.jsonl': 25 * 1024 * 1024,
+  'doctor-log.jsonl': 25 * 1024 * 1024,
+  'role-pending.jsonl': 5 * 1024 * 1024,
+  'role-events.jsonl': 25 * 1024 * 1024,
+};
+
+const EMBED_LOG_DEFAULT_MAX_MB = 50;
+const EMBED_LOG_DEFAULT_KEEP = 3;
+const EMBED_LOG_HARD_CAP_MAX_MB = 500;
+const EMBED_LOG_HARD_CAP_KEEP = 20;
+
+function fileSizeOrZero(p) {
+  try { return fs.statSync(p).size; } catch { return 0; }
+}
+
+function rmSafe(p, dryRun) {
+  if (dryRun) return;
+  try { fs.rmSync(p, { force: true }); } catch (err) {
+    process.stderr.write(`[cleanup] failed to remove ${p}: ${err.message}\n`);
+  }
+}
+
+/**
+ * Tail-preserving truncate: keeps the last `keepBytes` of `file`, drops the
+ * rest. Used for append-only event logs where recent events are valuable but
+ * historical bloat is not.
+ */
+function tailTruncate(file, keepBytes, dryRun) {
+  if (dryRun) return;
+  let stat;
+  try { stat = fs.statSync(file); } catch { return; }
+  if (stat.size <= keepBytes) return;
+  const start = stat.size - keepBytes;
+  const buf = Buffer.alloc(keepBytes);
+  const fd = fs.openSync(file, 'r');
+  try { fs.readSync(fd, buf, 0, keepBytes, start); } finally { fs.closeSync(fd); }
+  // Find the first newline so we don't start mid-record.
+  const nl = buf.indexOf(0x0a);
+  const payload = nl >= 0 && nl < buf.length - 1 ? buf.subarray(nl + 1) : buf;
+  fs.writeFileSync(file, payload);
+}
+
+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, EMBED_LOG_HARD_CAP_MAX_MB) : EMBED_LOG_DEFAULT_MAX_MB;
+  const keep = Number.isFinite(keepRaw) && keepRaw >= 0 ? Math.min(keepRaw, EMBED_LOG_HARD_CAP_KEEP) : EMBED_LOG_DEFAULT_KEEP;
+  return { maxBytes: maxMb * 1024 * 1024, keep };
+}
+
+/**
+ * Walk the embed log + every rotated segment (.1, .2, ...) and drop the ones
+ * that exceed the per-segment cap OR sit beyond the keep count.
+ *
+ * Unlike rotateEmbedLogIfNeeded in lib/embed/cli.mjs (which is called at
+ * daemon spawn time and only rotates the live log), this is the post-upgrade
+ * cleanup: it handles the case where an existing install has segments that
+ * were oversized before the cap existed.
+ */
+export function cleanupEmbedLog({ homeDir = os.homedir(), env = process.env, dryRun = false } = {}) {
+  const dir = path.join(homeDir, '.cx', 'runtime');
+  const baseLog = path.join(dir, 'embed-daemon.log');
+  const { maxBytes, keep } = rotationConfig(env);
+
+  const summary = { removed: [], truncated: [], freedBytes: 0, baseLog };
+
+  // Every existing segment (.log, .log.1, .log.2, ...)
+  if (!fs.existsSync(dir)) return summary;
+  const entries = fs.readdirSync(dir).filter(n => n === 'embed-daemon.log' || n.startsWith('embed-daemon.log.'));
+
+  for (const name of entries) {
+    const full = path.join(dir, name);
+    const size = fileSizeOrZero(full);
+
+    // Drop segments beyond the keep horizon entirely.
+    const dotMatch = name.match(/^embed-daemon\.log\.(\d+)$/);
+    if (dotMatch && Number.parseInt(dotMatch[1], 10) > keep) {
+      summary.removed.push({ path: full, size });
+      summary.freedBytes += size;
+      rmSafe(full, dryRun);
+      continue;
+    }
+
+    // The live log: if oversized, truncate to 0 (it will rotate cleanly on next
+    // daemon spawn via rotateEmbedLogIfNeeded). Truncating in place keeps any
+    // open daemon FDs valid (writes resume at byte 0 on next O_APPEND write).
+    if (name === 'embed-daemon.log' && size > maxBytes) {
+      summary.truncated.push({ path: full, sizeWas: size });
+      summary.freedBytes += size;
+      if (!dryRun) {
+        try {
+          fs.truncateSync(full, 0);
+        } catch (err) {
+          process.stderr.write(`[cleanup] failed to truncate ${full}: ${err.message}\n`);
+        }
+      }
+      continue;
+    }
+
+    // Rotated segments that are individually oversized: drop them. They are
+    // archived noise; keeping them around defeats the cap.
+    if (dotMatch && size > maxBytes) {
+      summary.removed.push({ path: full, size });
+      summary.freedBytes += size;
+      rmSafe(full, dryRun);
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Apply per-file size caps to the user-level JSONL event logs at ~/.cx/.
+ * Truncates oldest events rather than removing the whole file so the most
+ * recent records survive.
+ */
+export function cleanupJsonlLogs({ homeDir = os.homedir(), dryRun = false } = {}) {
+  const dir = path.join(homeDir, '.cx');
+  const summary = { truncated: [], freedBytes: 0 };
+  if (!fs.existsSync(dir)) return summary;
+
+  for (const [name, capBytes] of Object.entries(JSONL_LOG_CAPS_BYTES)) {
+    const file = path.join(dir, name);
+    const size = fileSizeOrZero(file);
+    if (size <= capBytes) continue;
+    // Retain the most recent half-cap so headroom exists before next truncate.
+    const keepBytes = Math.floor(capBytes / 2);
+    summary.truncated.push({ path: file, sizeWas: size, sizeNow: keepBytes });
+    summary.freedBytes += size - keepBytes;
+    tailTruncate(file, keepBytes, dryRun);
+  }
+
+  return summary;
+}
+
+/**
+ * Age out ~/.construct/cache/ entries older than `maxAgeDays`. Cache hits are
+ * idempotent and re-fetched on demand, so pruning is safe.
+ */
+export function cleanupCacheDir({ homeDir = os.homedir(), maxAgeDays = 30, dryRun = false } = {}) {
+  const dir = path.join(homeDir, '.construct', 'cache');
+  const summary = { removed: [], freedBytes: 0 };
+  if (!fs.existsSync(dir)) return summary;
+
+  const cutoff = Date.now() - (maxAgeDays * 24 * 60 * 60 * 1000);
+  const walk = (current) => {
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) { walk(full); continue; }
+      let stat;
+      try { stat = fs.statSync(full); } catch { continue; }
+      if (stat.mtimeMs < cutoff) {
+        summary.removed.push({ path: full, size: stat.size });
+        summary.freedBytes += stat.size;
+        rmSafe(full, dryRun);
+      }
+    }
+  };
+  walk(dir);
+  return summary;
+}
+
+/**
+ * Orchestrator. Runs each primitive under a hard time budget and returns an
+ * aggregated summary. Individual failures are non-fatal: a primitive that
+ * throws is recorded as an error in the summary but does not block the rest.
+ */
+export function runFullCleanup({ homeDir = os.homedir(), env = process.env, dryRun = false } = {}) {
+  const startedAt = Date.now();
+  const summary = {
+    dryRun,
+    startedAt: new Date(startedAt).toISOString(),
+    durationMs: 0,
+    freedBytes: 0,
+    embedLog: null,
+    jsonlLogs: null,
+    cacheDir: null,
+    errors: [],
+  };
+
+  const safelyRun = (label, fn) => {
+    if (Date.now() - startedAt > HARD_BUDGET_MS) {
+      summary.errors.push({ step: label, error: 'time budget exceeded; skipped' });
+      return null;
+    }
+    try { return fn(); }
+    catch (err) { summary.errors.push({ step: label, error: err.message }); return null; }
+  };
+
+  summary.embedLog = safelyRun('embedLog', () => cleanupEmbedLog({ homeDir, env, dryRun }));
+  summary.jsonlLogs = safelyRun('jsonlLogs', () => cleanupJsonlLogs({ homeDir, dryRun }));
+  summary.cacheDir = safelyRun('cacheDir', () => cleanupCacheDir({ homeDir, dryRun }));
+
+  for (const part of [summary.embedLog, summary.jsonlLogs, summary.cacheDir]) {
+    if (part?.freedBytes) summary.freedBytes += part.freedBytes;
+  }
+  summary.durationMs = Date.now() - startedAt;
+  return summary;
+}
+
+/**
+ * Format bytes for one-line operator output. 1234567 → "1.2 MB".
+ */
+export function formatBytes(bytes) {
+  if (!bytes || bytes < 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let n = bytes;
+  let unit = 0;
+  while (n >= 1024 && unit < units.length - 1) { n /= 1024; unit += 1; }
+  return `${n.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Version stamp — drives automatic cleanup on upgrade.
+//
+// ~/.construct/.cleanup-stamp records the last version that ran cleanup.
+// On every CLI invocation, bin/construct compares the current package
+// version to the stamp. A mismatch triggers a single cleanup pass and
+// writes the new version into the stamp. The first ever invocation also
+// triggers cleanup (no stamp present) — this is what unblocks existing
+// installs that already have 34 GB logs sitting around.
+// ---------------------------------------------------------------------------
+
+const STAMP_RELATIVE = path.join('.construct', '.cleanup-stamp');
+
+export function stampPath(homeDir = os.homedir()) {
+  return path.join(homeDir, STAMP_RELATIVE);
+}
+
+export function readVersionStamp({ homeDir = os.homedir() } = {}) {
+  const p = stampPath(homeDir);
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+export function writeVersionStamp({ homeDir = os.homedir(), version, summary } = {}) {
+  const p = stampPath(homeDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const payload = {
+    version,
+    ranAt: new Date().toISOString(),
+    freedBytes: summary?.freedBytes ?? 0,
+    durationMs: summary?.durationMs ?? 0,
+  };
+  fs.writeFileSync(p, JSON.stringify(payload, null, 2));
+}
+
+/**
+ * Run cleanup if and only if the installed version differs from the stamp.
+ * Returns { ran: bool, reason, summary?, previousVersion? }.
+ *
+ * Designed to be called at CLI startup. Never throws — cleanup failures are
+ * surfaced via the returned summary and never block the actual command.
+ */
+export function maybeRunCleanupOnUpgrade({
+  homeDir = os.homedir(),
+  env = process.env,
+  currentVersion,
+  force = false,
+} = {}) {
+  if (env.CONSTRUCT_DISABLE_AUTO_CLEANUP === '1') {
+    return { ran: false, reason: 'disabled via CONSTRUCT_DISABLE_AUTO_CLEANUP' };
+  }
+  const stamp = readVersionStamp({ homeDir });
+  if (!force && stamp && stamp.version === currentVersion) {
+    return { ran: false, reason: 'version matches stamp' };
+  }
+  let summary;
+  try { summary = runFullCleanup({ homeDir, env, dryRun: false }); }
+  catch (err) { return { ran: false, reason: `cleanup threw: ${err.message}` }; }
+  try { writeVersionStamp({ homeDir, version: currentVersion, summary }); }
+  catch (err) { /* stamp write failure is non-fatal */ void err; }
+  return {
+    ran: true,
+    reason: stamp ? 'version changed' : 'first run',
+    previousVersion: stamp?.version ?? null,
+    summary,
+  };
+}