@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/document-ingest.mjs

@@ -0,0 +1,230 @@
+/**
+ * lib/document-ingest.mjs — convert local source documents into normalized markdown artifacts.
+ *
+ * Reuses the shared extraction backends from lib/document-extract.mjs, writes
+ * markdown outputs into retrieval-friendly project paths, and can optionally
+ * trigger storage sync for SQL/vector indexing.
+ */
+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 { syncFileStateToSql } from './storage/sync.mjs';
+import { stampFrontmatter } from './doc-stamp.mjs';
+import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
+
+const DEFAULT_TARGET_DIR = '.cx/knowledge/internal';
+
+function slugify(value) {
+  return String(value)
+    .normalize('NFKD')
+    .replace(/[^\w.-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+}
+
+function normalizeOutputPath(value, cwd) {
+  return isAbsolute(value) ? value : resolve(cwd, value);
+}
+
+function formatTitle(sourcePath) {
+  return basename(sourcePath).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').trim() || 'Ingested document';
+}
+
+function inferProjectName(rootDir) {
+  const name = basename(resolve(rootDir)).trim();
+  return slugify(name || 'construct') || 'construct';
+}
+
+function ensureDir(dirPath) {
+  mkdirSync(dirPath, { recursive: true });
+}
+
+function nextAvailablePath(targetPath) {
+  if (!existsSync(targetPath)) return targetPath;
+  const parsed = parse(targetPath);
+  let index = 2;
+  while (true) {
+    const candidate = join(parsed.dir, `${parsed.name}-${index}${parsed.ext}`);
+    if (!existsSync(candidate)) return candidate;
+    index += 1;
+  }
+}
+
+function renderMarkdown({ sourcePath, extractedAt, title, extractionMethod, characters, truncated, text, outputPath, cwd, metadata }) {
+  const relSource = relative(cwd, sourcePath) || basename(sourcePath);
+  const relOutput = relative(cwd, outputPath) || basename(outputPath);
+  const lines = [
+    '---',
+    `source_path: ${JSON.stringify(sourcePath)}`,
+    `source_relative_path: ${JSON.stringify(relSource)}`,
+    `source_extension: ${JSON.stringify(extname(sourcePath).toLowerCase())}`,
+    `extracted_at: ${JSON.stringify(extractedAt)}`,
+    `extraction_method: ${JSON.stringify(extractionMethod)}`,
+    `characters: ${characters}`,
+    `truncated: ${truncated ? 'true' : 'false'}`,
+    `output_path: ${JSON.stringify(outputPath)}`,
+    `output_relative_path: ${JSON.stringify(relOutput)}`,
+  ];
+  if (metadata?.authors?.length) lines.push(`authors: [${metadata.authors.map((a) => JSON.stringify(a)).join(', ')}]`);
+  if (metadata?.dates && Object.keys(metadata.dates).length) {
+    for (const [k, v] of Object.entries(metadata.dates)) lines.push(`source_${k}: ${JSON.stringify(v)}`);
+  }
+  if (metadata?.links?.length) lines.push(`source_links_count: ${metadata.links.length}`);
+  lines.push('---', '', `# ${title}`, '', '## Source', '', `- File: \`${relSource}\``, `- Method: \`${extractionMethod}\``, `- Characters: ${characters}`, `- Truncated: ${truncated ? 'yes' : 'no'}`, `- Extracted at: ${extractedAt}`);
+  if (metadata?.authors?.length) lines.push(`- Authors: ${metadata.authors.join(', ')}`);
+  lines.push('', '## Extracted Content', '', text, '');
+  return lines.join('\n');
+}
+
+function collectInputFiles(inputPath) {
+  const resolvedPath = resolve(inputPath);
+  if (!existsSync(resolvedPath)) throw new Error(`Input path not found: ${resolvedPath}`);
+
+  const stat = statSync(resolvedPath);
+  if (stat.isFile()) {
+    if (!isExtractableDocumentPath(resolvedPath)) return [];
+    return [resolvedPath];
+  }
+
+  if (!stat.isDirectory()) return [];
+
+  const files = [];
+  const stack = [resolvedPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (entry.isFile() && isExtractableDocumentPath(full)) files.push(full);
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
+  if (outputPath) return normalizeOutputPath(outputPath, cwd);
+  if (target === 'sibling') {
+    return join(dirname(sourcePath), `${basename(sourcePath)}.md`);
+  }
+  // knowledge/<subdir> targets land in .cx/knowledge/<subdir>/
+  if (target.startsWith('knowledge/')) {
+    const sub = target.slice('knowledge/'.length);
+    const resolvedDir = normalizeOutputPath(`${KNOWLEDGE_ROOT}/${sub}`, cwd);
+    return join(resolvedDir, `${basename(sourcePath)}.md`);
+  }
+  const resolvedDir = normalizeOutputPath(outputDir || DEFAULT_TARGET_DIR, cwd);
+  return join(resolvedDir, `${basename(sourcePath)}.md`);
+}
+
+export async function ingestDocuments(inputPaths, {
+  cwd = process.cwd(),
+  outputPath = null,
+  outputDir = null,
+  target = 'knowledge/internal',
+  sync = false,
+  env = process.env,
+} = {}) {
+  if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
+    throw new Error('At least one input path is required');
+  }
+  if (outputPath && inputPaths.length > 1) {
+    throw new Error('--out can only be used with a single input path');
+  }
+
+  const files = inputPaths.flatMap((inputPath) => collectInputFiles(isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath)));
+  if (files.length === 0) {
+    throw new Error('No supported document files found');
+  }
+
+  const results = [];
+  for (const sourcePath of files) {
+    const extracted = extractDocumentText(sourcePath, { maxChars: 200_000 });
+    const metadata = extractDocumentMetadata(sourcePath);
+    const targetPath = resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target });
+    ensureDir(dirname(targetPath));
+    const finalPath = nextAvailablePath(targetPath);
+    const extractedAt = new Date().toISOString();
+    const title = metadata?.title || formatTitle(sourcePath);
+    const markdown = renderMarkdown({
+      sourcePath,
+      extractedAt,
+      title,
+      extractionMethod: extracted.extractionMethod,
+      characters: extracted.characters,
+      truncated: extracted.truncated,
+      text: extracted.text,
+      outputPath: finalPath,
+      cwd,
+      metadata,
+    });
+    writeFileSync(finalPath, stampFrontmatter(markdown, { generator: 'construct/ingest' }));
+    results.push({
+      sourcePath,
+      outputPath: finalPath,
+      extension: extracted.extension,
+      extractionMethod: extracted.extractionMethod,
+      truncated: extracted.truncated,
+      characters: extracted.characters,
+      metadata: { title, authors: metadata?.authors || [], dates: metadata?.dates || {} },
+    });
+  }
+
+  let syncResult = null;
+  if (sync) {
+    syncResult = await syncFileStateToSql(cwd, {
+      env,
+      project: inferProjectName(cwd),
+    });
+  }
+
+  return {
+    status: 'ok',
+    target: outputPath ? 'custom' : target,
+    outputDir: outputPath
+      ? dirname(normalizeOutputPath(outputPath, cwd))
+      : target === 'sibling'
+        ? null
+        : target.startsWith('knowledge/')
+          ? normalizeOutputPath(`${KNOWLEDGE_ROOT}/${target.slice('knowledge/'.length)}`, cwd)
+          : normalizeOutputPath(outputDir || DEFAULT_TARGET_DIR, cwd),
+    indexedLocally: true,
+    storageSync: syncResult,
+    files: results,
+  };
+}
+
+export async function runIngestCli(argv = process.argv.slice(2), { cwd = process.cwd(), env = process.env } = {}) {
+  const inputs = [];
+  let outputPath = null;
+  let outputDir = null;
+  let target = 'knowledge/internal';
+  let sync = false;
+
+  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 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` +
+      `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
+    );
+  }
+  const knowledgeTargets = KNOWLEDGE_SUBDIRS.map((s) => `knowledge/${s}`);
+  if (!['sibling', ...knowledgeTargets].includes(target)) {
+    throw new Error(
+      `Unsupported target: ${target}. Valid targets: sibling, ${knowledgeTargets.join(', ')}`,
+    );
+  }
+
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, env });
+}

package/lib/drop.mjs

@@ -0,0 +1,282 @@
+/**
+ * lib/drop.mjs — `construct drop` command, frictionless ingest of recently
+ * saved files from drop-zone directories (~/Downloads, ~/Desktop, etc.).
+ *
+ * The user drops a file in their host session; the host often can't read it
+ * because of sandbox constraints. `construct drop` closes that gap: it
+ * surfaces the N most recent files in configured watch dirs, filters by
+ * ingestable types (PDF, Office, text, etc.), and runs `ingestDocuments`
+ * on the selection. Cross-platform; no external dependencies.
+ *
+ * Watch dirs default to XDG-ish sane values per platform; override via
+ * `CONSTRUCT_DROP_DIRS` env (colon-separated) or `--source <dir>`.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { isExtractableDocumentPath } from './document-extract.mjs';
+import { ingestDocuments } from './document-ingest.mjs';
+
+const DEFAULT_RECENCY_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+function defaultWatchDirs(home = homedir()) {
+  const downloads = join(home, 'Downloads');
+  const desktop = join(home, 'Desktop');
+  const documents = join(home, 'Documents');
+  const dirs = [downloads, desktop, documents];
+  // macOS: include ~/Library/Mobile Documents when it exists (iCloud drop)
+  if (platform() === 'darwin') {
+    const icloud = join(home, 'Library', 'Mobile Documents', 'com~apple~CloudDocs', 'Downloads');
+    dirs.push(icloud);
+  }
+  return dirs.filter((d) => existsSync(d));
+}
+
+function resolveWatchDirs({ env = process.env, override = null, home = homedir() } = {}) {
+  if (override && override.length > 0) return override;
+  const raw = env.CONSTRUCT_DROP_DIRS;
+  if (raw) {
+    return raw.split(':').map((s) => s.trim()).filter(Boolean).filter((p) => existsSync(p));
+  }
+  return defaultWatchDirs(home);
+}
+
+function parseSinceSpec(spec) {
+  if (!spec) return DEFAULT_RECENCY_MS;
+  const match = /^(\d+)([smhd])$/i.exec(String(spec).trim());
+  if (!match) return DEFAULT_RECENCY_MS;
+  const value = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const multipliers = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+  return value * multipliers[unit];
+}
+
+/**
+ * Walks watch dirs (non-recursive) and returns file candidates.
+ * Sorted by most-recent mtime first. Honors extension filter.
+ */
+export function collectCandidates({
+  dirs,
+  sinceMs = DEFAULT_RECENCY_MS,
+  extensionFilter = null,
+  limit = 10,
+  now = Date.now(),
+} = {}) {
+  const cutoff = now - sinceMs;
+  const results = [];
+  for (const dir of dirs) {
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        if (entry.name.startsWith('.')) continue; // hidden / temp files
+        const full = join(dir, entry.name);
+        let stats;
+        try { stats = statSync(full); } catch { continue; }
+        if (stats.mtimeMs < cutoff) continue;
+        const ext = extname(entry.name).slice(1).toLowerCase();
+        if (extensionFilter && ext !== extensionFilter.replace(/^\./, '').toLowerCase()) continue;
+        if (!isExtractableDocumentPath(full)) continue;
+        results.push({
+          path: full,
+          name: entry.name,
+          size: stats.size,
+          mtime: stats.mtime.toISOString(),
+          mtimeMs: stats.mtimeMs,
+          source: dir,
+          ext,
+        });
+      }
+    } catch { /* unreadable dir — skip */ }
+  }
+  results.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return results.slice(0, limit);
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatAge(mtimeMs, now = Date.now()) {
+  const diff = now - mtimeMs;
+  if (diff < 60_000) return `${Math.round(diff / 1000)}s ago`;
+  if (diff < 3_600_000) return `${Math.round(diff / 60_000)}m ago`;
+  if (diff < 86_400_000) return `${Math.round(diff / 3_600_000)}h ago`;
+  return `${Math.round(diff / 86_400_000)}d ago`;
+}
+
+function printCandidates(candidates) {
+  if (candidates.length === 0) {
+    console.log('No recent ingestable files found in drop-zone directories.');
+    return;
+  }
+  console.log(`Recent drop-zone files (${candidates.length}):`);
+  console.log('─'.repeat(90));
+  candidates.forEach((c, i) => {
+    const num = String(i + 1).padStart(2, ' ');
+    const name = c.name.length > 40 ? c.name.slice(0, 37) + '…' : c.name.padEnd(40);
+    const size = formatSize(c.size).padStart(8);
+    const age = formatAge(c.mtimeMs).padStart(8);
+    const src = basename(c.source);
+    console.log(`  ${num}. ${name}  ${size}  ${age}  ${src}`);
+  });
+  console.log('');
+}
+
+async function confirm(question) {
+  if (!process.stdin.isTTY) return true;
+  process.stdout.write(`${question} [Y/n] `);
+  return new Promise((resolve) => {
+    process.stdin.setEncoding('utf8');
+    process.stdin.once('data', (chunk) => {
+      const answer = String(chunk).trim().toLowerCase();
+      resolve(answer === '' || answer === 'y' || answer === 'yes');
+    });
+  });
+}
+
+export function printHelp() {
+  console.log(`Usage: construct drop [options]
+
+Ingests the most recently dropped file(s) from your drop-zone directories
+(Downloads, Desktop, Documents, iCloud Drive Downloads). Closes the gap
+where a host session can't read files outside its sandbox.
+
+Options:
+  --list             Show candidates without ingesting
+  --all              Ingest all listed candidates (default: most recent)
+  --index N[,N...]   Ingest specific candidates by list index
+  --yes, -y          Skip confirmation prompt
+  --source <dir>     Override watch directory (repeatable)
+  --type <ext>       Filter by extension (pdf, docx, xlsx, txt, md, etc.)
+  --since <spec>     Recency window: 30m, 1h, 2d (default: 24h)
+  --target <t>       Ingest target: knowledge/internal (default) | knowledge/<subdir> | sibling
+  --sync             Rebuild hybrid index after ingest
+  --json             Emit machine-readable output
+  -h, --help         Show this message
+
+Environment:
+  CONSTRUCT_DROP_DIRS   Colon-separated override for watch directories
+
+Examples:
+  construct drop                        # ingest most recent ingestable file
+  construct drop --list                 # list candidates, no ingest
+  construct drop --index 2,3            # ingest candidates 2 and 3
+  construct drop --type pdf --since 1h  # PDFs saved in last hour
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    list: false,
+    all: false,
+    indexes: null,
+    yes: false,
+    sources: [],
+    type: null,
+    since: null,
+    target: null,
+    sync: false,
+    json: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--list') options.list = true;
+    else if (arg === '--all') options.all = true;
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--sync') options.sync = true;
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--source') options.sources.push(argv[++i]);
+    else if (arg.startsWith('--source=')) options.sources.push(arg.slice(9));
+    else if (arg === '--type') options.type = argv[++i];
+    else if (arg.startsWith('--type=')) options.type = arg.slice(7);
+    else if (arg === '--since') options.since = argv[++i];
+    else if (arg.startsWith('--since=')) options.since = arg.slice(8);
+    else if (arg === '--target') options.target = argv[++i];
+    else if (arg.startsWith('--target=')) options.target = arg.slice(9);
+    else if (arg === '--index') options.indexes = argv[++i];
+    else if (arg.startsWith('--index=')) options.indexes = arg.slice(8);
+  }
+  return options;
+}
+
+export async function runDropCli(argv = [], { cwd = process.cwd(), env = process.env } = {}) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const dirs = resolveWatchDirs({ env, override: options.sources.length ? options.sources : null });
+  if (dirs.length === 0) {
+    console.error('No drop-zone directories found. Set CONSTRUCT_DROP_DIRS or use --source.');
+    process.exit(1);
+  }
+
+  const sinceMs = parseSinceSpec(options.since);
+  const candidates = collectCandidates({
+    dirs,
+    sinceMs,
+    extensionFilter: options.type,
+    limit: 10,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify({ dirs, candidates }, null, 2));
+    if (options.list || candidates.length === 0) return;
+  } else {
+    printCandidates(candidates);
+    if (candidates.length === 0) return;
+    if (options.list) return;
+  }
+
+  let selection;
+  if (options.indexes) {
+    const picks = String(options.indexes).split(',').map((s) => Number(s.trim()) - 1);
+    selection = picks
+      .filter((i) => Number.isInteger(i) && i >= 0 && i < candidates.length)
+      .map((i) => candidates[i]);
+    if (selection.length === 0) {
+      console.error('No valid indexes provided.');
+      process.exit(1);
+    }
+  } else if (options.all) {
+    selection = candidates;
+  } else {
+    selection = [candidates[0]];
+  }
+
+  if (!options.yes && !options.json) {
+    const names = selection.map((c) => c.name).join(', ');
+    const proceed = await confirm(`Ingest ${selection.length} file${selection.length === 1 ? '' : 's'}: ${names}?`);
+    if (!proceed) {
+      console.log('Aborted.');
+      return;
+    }
+  }
+
+  const inputs = selection.map((c) => c.path);
+  const result = await ingestDocuments(inputs, {
+    cwd,
+    target: options.target || 'knowledge/internal',
+    sync: options.sync,
+    env,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify({ ingested: result }, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(`Ingested ${inputs.length} file${inputs.length === 1 ? '' : 's'} into the current project.`);
+  if (options.sync) {
+    console.log('Hybrid index rebuilt.');
+  } else {
+    console.log('Run `construct storage sync` to rebuild the hybrid index, or re-run with --sync.');
+  }
+}

package/lib/embed/approval-queue.mjs

@@ -0,0 +1,176 @@
+/**
+ * lib/embed/approval-queue.mjs — high-risk action approval queue.
+ *
+ * Actions that match the approval.require list in embed config are held
+ * here until approved, rejected, or timed out.
+ *
+ * Persistence: in-memory by default; optionally writes to a JSONL file
+ * at ~/.cx/approval-queue.jsonl for cross-session visibility.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export class ApprovalQueue {
+  #items = new Map();   // id → ApprovalItem
+  #persistPath = null;
+  #requirePatterns = [];
+  #timeoutMs = 3_600_000;
+  #fallback = 'reject';
+
+  /**
+   * @param {object} opts
+   * @param {string[]} opts.require        - Action type patterns that need approval
+   * @param {number}  [opts.timeoutMs]     - Auto-expiry after this many ms (default: 1h)
+   * @param {string}  [opts.fallback]      - 'reject' | 'proceed' on timeout
+   * @param {string}  [opts.persistPath]   - Path to JSONL persistence file
+   */
+  constructor({ require: requirePatterns = [], timeoutMs, fallback, persistPath } = {}) {
+    this.#requirePatterns = requirePatterns;
+    if (timeoutMs != null) this.#timeoutMs = timeoutMs;
+    if (fallback) this.#fallback = fallback;
+    if (persistPath) {
+      this.#persistPath = persistPath;
+      this.#loadFromDisk();
+    }
+  }
+
+  /**
+   * Check if an action type requires approval.
+   */
+  requiresApproval(actionType) {
+    return this.#requirePatterns.some((p) => {
+      if (p.endsWith('*')) return actionType.startsWith(p.slice(0, -1));
+      return p === actionType;
+    });
+  }
+
+  /**
+   * Determine approval mode for an action type.
+   * Returns 'auto' if autonomous execution is safe, 'human' if gating required.
+   *
+   * Hybrid model rules (in priority order):
+   *   1. If requiresApproval() → 'human'
+   *   2. If action.autoApprove === true → 'auto'
+   *   3. If action type matches low-risk patterns → 'auto'
+   *   4. Default → 'human' (fail-safe)
+   */
+  approvalMode(actionType, { autoApprove = false } = {}) {
+    if (this.requiresApproval(actionType)) return 'human';
+    if (autoApprove) return 'auto';
+    const LOW_RISK = ['webhook.', 'snapshot.', 'observation.', 'search.', 'read.'];
+    if (LOW_RISK.some(prefix => actionType.startsWith(prefix))) return 'auto';
+    return 'human';
+  }
+
+  /**
+   * Enqueue an action for approval. Returns the item id.
+   * @param {object} action - { type, provider, payload, requestedBy?, autoApprove? }
+   *
+   * If approvalMode resolves to 'auto' the item is immediately auto-approved
+   * and persisted with status 'auto-approved'. Callers can check the returned
+   * item's status to decide whether to proceed immediately.
+   */
+  enqueue(action) {
+    const id = `appr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const mode = this.approvalMode(action.type ?? action.action ?? 'unknown', {
+      autoApprove: action.autoApprove === true,
+    });
+    const item = {
+      id,
+      type: action.type ?? action.action ?? 'unknown',
+      provider: action.provider ?? null,
+      payload: action.payload ?? {},
+      requestedBy: action.requestedBy ?? 'construct',
+      approvalMode: mode,
+      status: mode === 'auto' ? 'auto-approved' : 'pending',
+      enqueuedAt: new Date().toISOString(),
+      resolvedAt: mode === 'auto' ? new Date().toISOString() : null,
+      expiresAt: new Date(Date.now() + this.#timeoutMs).toISOString(),
+    };
+    this.#items.set(id, item);
+    this.#persist();
+    return id;
+  }
+
+  /**
+   * Approve a pending item. Returns the resolved item.
+   */
+  approve(id, { approvedBy = 'human' } = {}) {
+    return this.#resolve(id, 'approved', { approvedBy });
+  }
+
+  /**
+   * Reject a pending item.
+   */
+  reject(id, { reason = '' } = {}) {
+    return this.#resolve(id, 'rejected', { reason });
+  }
+
+  /**
+   * Get an item by id.
+   */
+  get(id) {
+    return this.#items.get(id) ?? null;
+  }
+
+  /**
+   * List all items, optionally filtered by status.
+   */
+  list(status = null) {
+    const items = [...this.#items.values()];
+    return status ? items.filter((i) => i.status === status) : items;
+  }
+
+  /**
+   * Expire any pending items past their expiry time.
+   * Returns the list of expired items.
+   */
+  expireStale() {
+    const now = Date.now();
+    const expired = [];
+    for (const item of this.#items.values()) {
+      if (item.status === 'pending' && new Date(item.expiresAt).getTime() < now) {
+        this.#resolve(item.id, this.#fallback === 'proceed' ? 'approved' : 'expired');
+        expired.push(item);
+      }
+    }
+    return expired;
+  }
+
+  #resolve(id, status, extra = {}) {
+    const item = this.#items.get(id);
+    if (!item) throw new Error(`Approval item not found: ${id}`);
+    if (item.status !== 'pending') throw new Error(`Item ${id} is already ${item.status}`);
+    Object.assign(item, { status, resolvedAt: new Date().toISOString(), ...extra });
+    this.#persist();
+    return item;
+  }
+
+  #persist() {
+    if (!this.#persistPath) return;
+    try {
+      fs.mkdirSync(path.dirname(this.#persistPath), { recursive: true });
+      const lines = [...this.#items.values()].map((i) => JSON.stringify(i)).join('\n');
+      fs.writeFileSync(this.#persistPath, lines + '\n', 'utf8');
+    } catch (err) { process.stderr.write('[approval-queue.mjs] persist: ' + (err?.message ?? String(err)) + '\n'); }
+  }
+
+  #loadFromDisk() {
+    try {
+      if (!fs.existsSync(this.#persistPath)) return;
+      const lines = fs.readFileSync(this.#persistPath, 'utf8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try {
+          const item = JSON.parse(line);
+          this.#items.set(item.id, item);
+        } catch { /* skip malformed */ }
+      }
+    } catch (err) { process.stderr.write('[approval-queue.mjs] load-from-disk: ' + (err?.message ?? String(err)) + '\n'); }
+  }
+
+  static defaultPersistPath() {
+    return path.join(os.homedir(), '.cx', 'approval-queue.jsonl');
+  }
+}