dis-gravity 1.1.0 → 1.2.5

package/lib/core.js

@@ -0,0 +1,1712 @@
+'use strict';
+
+/**
+ * Dis-Gravity Shared Core Engine
+ * Common utilities for standalone CLI daemon, MCP server, and VS Code extension:
+ * - Security whitelist validation (fail-closed)
+ * - Safe shell command execution
+ * - Headless browser discovery and 2x Retina PNG table card rendering
+ * - Markdown table parser
+ * - Workspace path traversal protection & safe file inspection
+ * - Git telemetry and status helpers
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const cp = require('child_process');
+const crypto = require('crypto');
+
+const VALID_ALIGNMENTS = new Set(['left', 'center', 'right']);
+function sanitizeAlignment(align) {
+  const normalized = String(align || 'left').toLowerCase().trim();
+  return VALID_ALIGNMENTS.has(normalized) ? normalized : 'left';
+}
+
+/**
+ * Validates if a Discord User ID is authorized.
+ * Fail-closed: If allowedUsers is empty or unconfigured, access is DENIED.
+ * 
+ * @param {string|number} userId - The Discord user ID to check
+ * @param {string[]|string} allowedUsers - Whitelist array or comma-separated string
+ * @returns {boolean}
+ */
+function isUserAllowed(userId, allowedUsers) {
+  if (!userId) return false;
+  if (!allowedUsers) return false;
+
+  const list = Array.isArray(allowedUsers)
+    ? allowedUsers.map(u => String(u).trim()).filter(Boolean)
+    : String(allowedUsers).split(',').map(u => u.trim()).filter(Boolean);
+
+  if (list.length === 0) return false;
+  return list.includes(String(userId).trim());
+}
+
+/**
+ * Safely executes a shell command in the specified workspace with timeout and buffer protection.
+ * 
+ * @param {string} cmdStr - Command to execute
+ * @param {string} cwd - Working directory
+ * @param {number} [timeoutMs=30000] - Timeout in milliseconds
+ * @returns {Promise<{code: number, stdout: string, stderr: string, duration: string, error: string|null}>}
+ */
+function executeShellCommand(cmdStr, cwd = process.cwd(), timeoutMs = 30000) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    cp.exec(cmdStr, { cwd, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+      resolve({
+        code: err ? (err.code || 1) : 0,
+        stdout: stdout || '',
+        stderr: stderr || '',
+        duration,
+        error: err ? err.message : null
+      });
+    });
+  });
+}
+
+/**
+ * Discovers a pre-installed headless Chromium-based browser (Edge, Chrome, Chromium, Brave).
+ * Zero-dependency: Uses host OS browser without requiring puppeteer or native npm modules.
+ * 
+ * @returns {string|null} Path to the browser binary, or null if none found
+ */
+function findHeadlessBrowser() {
+  if (process.env.DISGRAVITY_BROWSER_PATH && fs.existsSync(process.env.DISGRAVITY_BROWSER_PATH)) {
+    return process.env.DISGRAVITY_BROWSER_PATH;
+  }
+
+  if (process.platform === 'win32') {
+    const candidates = [
+      process.env.EDGE_PATH,
+      process.env.CHROME_PATH,
+      'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+      'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+      path.join(process.env.LOCALAPPDATA || '', 'Microsoft\\Edge\\Application\\msedge.exe'),
+      path.join(process.env.LOCALAPPDATA || '', 'Google\\Chrome\\Application\\chrome.exe')
+    ].filter(Boolean);
+
+    for (const c of candidates) {
+      if (fs.existsSync(c)) return c;
+    }
+  } else if (process.platform === 'darwin') {
+    const candidates = [
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium'
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(c)) return c;
+    }
+  } else {
+    // Linux / BSD
+    const candidates = ['google-chrome', 'chromium', 'chromium-browser', 'microsoft-edge', 'brave-browser'];
+    for (const c of candidates) {
+      try {
+        cp.execFileSync('which', [c], { stdio: 'ignore' });
+        return c;
+      } catch { }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Escapes characters for safe insertion into HTML strings.
+ * 
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+  if (str === null || str === undefined) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Builds HTML for Discord Dark Theme 2x table rendering.
+ * 
+ * @param {string[]} headers - Table header titles
+ * @param {string[][]} rows - 2D array of row cells
+ * @param {string[]} [alignments=[]] - Optional column alignments ('left', 'center', 'right')
+ * @param {string} [title="📊 Dis-Gravity Data Table"] - Table header title
+ * @returns {string}
+ */
+function buildTableHtml(headers = [], rows = [], alignments = [], title = "📊 Dis-Gravity Data Table") {
+  const thHtml = headers.map((h, i) => {
+    const align = sanitizeAlignment(alignments[i]);
+    return `<th style="padding: 10px 14px; text-align: ${align}; border-bottom: 2px solid #5865F2; color: #ffffff; font-size: 14px; font-weight: 600; white-space: nowrap;">${escapeHtml(h)}</th>`;
+  }).join('');
+
+  const trHtml = rows.map((row, rIdx) => {
+    const bg = rIdx % 2 === 0 ? '#2b2d31' : '#313338';
+    const tdHtml = row.map((cell, cIdx) => {
+      const align = sanitizeAlignment(alignments[cIdx]);
+      return `<td style="padding: 9px 14px; text-align: ${align}; border-bottom: 1px solid #3f4147; color: #dbdee1; font-size: 13px;">${escapeHtml(cell)}</td>`;
+    }).join('');
+    return `<tr style="background: ${bg};">${tdHtml}</tr>`;
+  }).join('');
+
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><style>
+  * { box-sizing: border-box; }
+  body { margin: 0; padding: 16px; background: #1e1f22; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; display: inline-block; }
+  .table-card { border-radius: 8px; overflow: hidden; box-shadow: 0 4px 16px rgba(0,0,0,0.5); border: 1px solid #383a40; background: #2b2d31; display: inline-block; min-width: 380px; }
+  table { border-collapse: collapse; width: 100%; }
+  .header-banner { background: linear-gradient(90deg, #5865F2, #4752C4); color: white; padding: 10px 16px; font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.6px; }
+  .footer-banner { background: #232428; color: #949ba4; padding: 6px 14px; font-size: 11px; text-align: right; border-top: 1px solid #383a40; }
+</style></head><body>
+  <div class="table-card">
+    <div class="header-banner">${escapeHtml(title)}</div>
+    <table>
+      <thead><tr style="background: #232428;">${thHtml}</tr></thead>
+      <tbody>${trHtml}</tbody>
+    </table>
+    <div class="footer-banner">Dis-Gravity Bridge • ${new Date().toLocaleTimeString()}</div>
+  </div>
+</body></html>`;
+}
+
+/**
+ * Renders tabular data to a crisp PNG image buffer using an OS headless browser.
+ * Cleans up temporary HTML and PNG files automatically.
+ * 
+ * @param {string[]} headers - Table header titles
+ * @param {string[][]} rows - 2D array of row cells
+ * @param {string[]} [alignments=[]] - Optional column alignments
+ * @param {string} [title] - Header card title
+ * @returns {Promise<Buffer|null>} PNG image buffer or null if browser is unavailable
+ */
+async function renderTableToPng(headers = [], rows = [], alignments = [], title = "📊 Dis-Gravity Data Table") {
+  const browserPath = findHeadlessBrowser();
+  if (!browserPath) return null;
+
+  const nonce = crypto.randomBytes(6).toString('hex');
+  const tempHtml = path.join(os.tmpdir(), `disgravity_tbl_${Date.now()}_${nonce}.html`);
+  const tempPng = path.join(os.tmpdir(), `disgravity_tbl_${Date.now()}_${nonce}.png`);
+
+  try {
+    const html = buildTableHtml(headers, rows, alignments, title);
+    await fs.promises.writeFile(tempHtml, html, { encoding: 'utf8', mode: 0o600 });
+
+    const colCount = Math.max(1, headers.length);
+    const rowCount = Math.max(1, rows.length);
+    const width = Math.min(1600, Math.max(480, colCount * 200));
+    const height = Math.min(1400, Math.max(220, (rowCount + 2) * 48 + 90));
+
+    const args = [
+      '--headless',
+      '--disable-gpu',
+      '--disable-extensions',
+      '--disable-sync',
+      '--no-first-run',
+      '--hide-scrollbars',
+      `--screenshot=${tempPng}`,
+      `--window-size=${width},${height}`,
+      `file:///${tempHtml.replace(/\\/g, '/')}`
+    ];
+
+    await new Promise((resolve, reject) => {
+      cp.execFile(browserPath, args, { timeout: 15000, windowsHide: true }, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+
+    if (fs.existsSync(tempPng)) {
+      const buf = await fs.promises.readFile(tempPng);
+      return buf;
+    }
+  } catch {
+    return null;
+  } finally {
+    try { if (fs.existsSync(tempHtml)) await fs.promises.unlink(tempHtml); } catch { }
+    try { if (fs.existsSync(tempPng)) await fs.promises.unlink(tempPng); } catch { }
+  }
+
+  return null;
+}
+
+/**
+ * Builds HTML for high-resolution 2x Retina Visual Diff rendering.
+ *
+ * @param {string} diffText - Raw unified diff text
+ * @param {string} [title="🔍 Git Diff Preview"] - Title banner
+ * @param {number} [maxLines=80] - Maximum diff lines to render
+ * @returns {string}
+ */
+function buildDiffHtml(diffText, title = "🔍 Dis-Gravity Git Diff", maxLines = 80) {
+  if (!diffText || typeof diffText !== 'string') return '';
+  const rawLines = diffText.split(/\r?\n/);
+  const truncated = rawLines.length > maxLines;
+  const lines = rawLines.slice(0, maxLines);
+
+  let oldLine = 0;
+  let newLine = 0;
+  let inHunk = false;
+
+  const rows = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith('diff --git') || line.startsWith('index ')) {
+      rows.push(`
+        <tr style="background: #232428; color: #949ba4; font-size: 11px; font-weight: 600;">
+          <td style="padding: 4px 8px; text-align: center; border-right: 1px solid #383a40;">---</td>
+          <td style="padding: 4px 8px; text-align: center; border-right: 1px solid #383a40;">---</td>
+          <td style="padding: 4px 10px; font-family: monospace;">${escapeHtml(line)}</td>
+        </tr>
+      `);
+      continue;
+    }
+    if (line.startsWith('--- ') || line.startsWith('+++ ')) {
+      const isAdd = line.startsWith('+++');
+      const color = isAdd ? '#57F287' : '#ED4245';
+      rows.push(`
+        <tr style="background: #2b2d31; color: ${color}; font-size: 12px; font-weight: 700;">
+          <td style="padding: 4px 8px; text-align: center; border-right: 1px solid #383a40;">${isAdd ? '+' : '-'}</td>
+          <td style="padding: 4px 8px; text-align: center; border-right: 1px solid #383a40;">${isAdd ? '+' : '-'}</td>
+          <td style="padding: 4px 10px; font-family: monospace;">${escapeHtml(line)}</td>
+        </tr>
+      `);
+      continue;
+    }
+
+    const hunkMatch = line.match(/^@@\s+-(\d+)(?:,\d+)?\s+\+(\d+)(?:,\d+)?\s+@@(.*)$/);
+    if (hunkMatch) {
+      oldLine = parseInt(hunkMatch[1], 10);
+      newLine = parseInt(hunkMatch[2], 10);
+      inHunk = true;
+      rows.push(`
+        <tr style="background: #1e2638; color: #79c0ff; font-size: 12px; font-style: italic;">
+          <td style="padding: 4px 8px; text-align: center; border-right: 1px solid #383a40; color: #5865F2;">...</td>
+          <td style="padding: 4px 8px; text-align: center; border-right: 1px solid #383a40; color: #5865F2;">...</td>
+          <td style="padding: 4px 10px; font-family: monospace;">${escapeHtml(line)}</td>
+        </tr>
+      `);
+      continue;
+    }
+
+    if (!inHunk) {
+      rows.push(`
+        <tr style="background: #2b2d31; color: #949ba4; font-size: 12px;">
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #4e5058;"> </td>
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #4e5058;"> </td>
+          <td style="padding: 3px 10px; font-family: monospace; color: #dbdee1;">${escapeHtml(line)}</td>
+        </tr>
+      `);
+      continue;
+    }
+
+    if (line.startsWith('+')) {
+      const curNew = newLine++;
+      rows.push(`
+        <tr style="background: rgba(46, 160, 67, 0.18); color: #7ee787; font-size: 12.5px;">
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #4e5058; user-select: none;"> </td>
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #57F287; font-weight: 600; user-select: none;">${curNew}</td>
+          <td style="padding: 3px 10px; font-family: monospace; white-space: pre-wrap; word-break: break-all;">+ ${escapeHtml(line.slice(1))}</td>
+        </tr>
+      `);
+    } else if (line.startsWith('-')) {
+      const curOld = oldLine++;
+      rows.push(`
+        <tr style="background: rgba(248, 81, 73, 0.18); color: #ffa198; font-size: 12.5px;">
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #ED4245; font-weight: 600; user-select: none;">${curOld}</td>
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #4e5058; user-select: none;"> </td>
+          <td style="padding: 3px 10px; font-family: monospace; white-space: pre-wrap; word-break: break-all;">- ${escapeHtml(line.slice(1))}</td>
+        </tr>
+      `);
+    } else {
+      const curOld = oldLine++;
+      const curNew = newLine++;
+      const text = line.startsWith(' ') ? line.slice(1) : line;
+      rows.push(`
+        <tr style="background: #2b2d31; color: #dbdee1; font-size: 12.5px;">
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #80848e; user-select: none;">${curOld}</td>
+          <td style="padding: 3px 8px; text-align: right; border-right: 1px solid #383a40; color: #80848e; user-select: none;">${curNew}</td>
+          <td style="padding: 3px 10px; font-family: monospace; white-space: pre-wrap; word-break: break-all;">  ${escapeHtml(text)}</td>
+        </tr>
+      `);
+    }
+  }
+
+  const footerText = truncated
+    ? `Showing first ${maxLines} lines (${rawLines.length - maxLines} lines truncated) • Dis-Gravity Diff`
+    : `Dis-Gravity Visual Diff • ${rawLines.length} lines • ${new Date().toLocaleTimeString()}`;
+
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><style>
+  * { box-sizing: border-box; }
+  body { margin: 0; padding: 14px; background: #1e1f22; font-family: "JetBrains Mono", Consolas, "Courier New", monospace; display: inline-block; }
+  .diff-card { border-radius: 8px; overflow: hidden; box-shadow: 0 6px 20px rgba(0,0,0,0.6); border: 1px solid #383a40; background: #2b2d31; display: inline-block; min-width: 680px; max-width: 1400px; }
+  table { border-collapse: collapse; width: 100%; }
+  .header-banner { background: linear-gradient(90deg, #5865F2, #3b429f); color: white; padding: 10px 16px; font-size: 13px; font-weight: 700; display: flex; justify-content: space-between; align-items: center; letter-spacing: 0.5px; }
+  .footer-banner { background: #232428; color: #949ba4; padding: 6px 14px; font-size: 11px; text-align: right; border-top: 1px solid #383a40; }
+</style></head><body>
+  <div class="diff-card">
+    <div class="header-banner">
+      <span>${escapeHtml(title)}</span>
+      <span style="font-size: 11px; background: rgba(0,0,0,0.3); padding: 2px 8px; border-radius: 4px;">2x Retina</span>
+    </div>
+    <table>
+      <tbody>${rows.join('')}</tbody>
+    </table>
+    <div class="footer-banner">${escapeHtml(footerText)}</div>
+  </div>
+</body></html>`;
+}
+
+/**
+ * Renders unified diff text to a crisp PNG image buffer using an OS headless browser.
+ *
+ * @param {string} diffText - Raw unified diff text
+ * @param {string} [title="🔍 Git Diff Preview"] - Header card title
+ * @param {number} [maxLines=80] - Maximum diff lines to render
+ * @returns {Promise<Buffer|null>} PNG image buffer or null if browser is unavailable
+ */
+async function renderDiffToPng(diffText, title = "🔍 Dis-Gravity Git Diff", maxLines = 80) {
+  const browserPath = findHeadlessBrowser();
+  if (!browserPath) return null;
+
+  const nonce = crypto.randomBytes(6).toString('hex');
+  const tempHtml = path.join(os.tmpdir(), `disgravity_diff_${Date.now()}_${nonce}.html`);
+  const tempPng = path.join(os.tmpdir(), `disgravity_diff_${Date.now()}_${nonce}.png`);
+
+  try {
+    const html = buildDiffHtml(diffText, title, maxLines);
+    if (!html) return null;
+    await fs.promises.writeFile(tempHtml, html, { encoding: 'utf8', mode: 0o600 });
+
+    const lineCount = Math.min(maxLines, (diffText.split(/\r?\n/).length || 1));
+    const width = 960;
+    const height = Math.min(2400, Math.max(260, (lineCount + 2) * 23 + 90));
+
+    const args = [
+      '--headless',
+      '--disable-gpu',
+      '--disable-extensions',
+      '--disable-sync',
+      '--no-first-run',
+      '--hide-scrollbars',
+      `--screenshot=${tempPng}`,
+      `--window-size=${width},${height}`,
+      `file:///${tempHtml.replace(/\\/g, '/')}`
+    ];
+
+    await new Promise((resolve, reject) => {
+      cp.execFile(browserPath, args, { timeout: 15000, windowsHide: true }, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+
+    if (fs.existsSync(tempPng)) {
+      const buf = await fs.promises.readFile(tempPng);
+      return buf;
+    }
+  } catch {
+    return null;
+  } finally {
+    try { if (fs.existsSync(tempHtml)) await fs.promises.unlink(tempHtml); } catch { }
+    try { if (fs.existsSync(tempPng)) await fs.promises.unlink(tempPng); } catch { }
+  }
+
+  return null;
+}
+
+/**
+ * Parses a standard GitHub-flavored Markdown table into structured headers, rows, and alignments.
+ * 
+ * @param {string} text - Text containing a Markdown table
+ * @returns {{headers: string[], rows: string[][], alignments: string[]}|null}
+ */
+function parseMarkdownTable(text) {
+  if (!text || typeof text !== 'string') return null;
+
+  const lines = text.split('\n').map(l => l.trim()).filter(Boolean);
+  let tableStartIndex = -1;
+
+  for (let i = 0; i < lines.length - 1; i++) {
+    const line = lines[i];
+    const nextLine = lines[i + 1];
+    if (line.includes('|') && /^\s*\|?\s*[-:]+[-| :]*\|?\s*$/.test(nextLine)) {
+      tableStartIndex = i;
+      break;
+    }
+  }
+
+  if (tableStartIndex === -1) return null;
+
+  const splitRow = (str) => {
+    let clean = str;
+    if (clean.startsWith('|')) clean = clean.substring(1);
+    if (clean.endsWith('|')) clean = clean.substring(0, clean.length - 1);
+    return clean.split('|').map(s => s.trim());
+  };
+
+  const headerLine = lines[tableStartIndex];
+  const separatorLine = lines[tableStartIndex + 1];
+
+  const headers = splitRow(headerLine);
+  const sepParts = splitRow(separatorLine);
+
+  const alignments = sepParts.map(part => {
+    const left = part.startsWith(':');
+    const right = part.endsWith(':');
+    if (left && right) return 'center';
+    if (right) return 'right';
+    return 'left';
+  });
+
+  const rows = [];
+  for (let i = tableStartIndex + 2; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.includes('|')) break;
+    const row = splitRow(line);
+    // Pad or trim row cells to match header count
+    while (row.length < headers.length) row.push('');
+    rows.push(row.slice(0, headers.length));
+  }
+
+  if (rows.length === 0) return null;
+
+  return { headers, rows, alignments };
+}
+
+/**
+ * Resolves a target path within a workspace root, strictly preventing path traversal attacks.
+ * 
+ * @param {string} workspaceRoot - Absolute path to workspace root
+ * @param {string} targetPath - Relative or absolute path to check
+ * @returns {string} Safe absolute path
+ * @throws {Error} If path escapes workspaceRoot
+ */
+function safeResolveWorkspacePath(workspaceRoot, targetPath) {
+  const root = path.resolve(workspaceRoot);
+  const resolved = path.resolve(root, targetPath || '');
+
+  const normForCompare = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+  const rel = path.relative(normForCompare(root), normForCompare(resolved));
+
+  if (rel !== '' && (rel.startsWith('..') || path.isAbsolute(rel))) {
+    throw new Error(`Security Violation: Access outside workspace is prohibited (${targetPath})`);
+  }
+
+  if (fs.existsSync(resolved)) {
+    try {
+      const realRoot = fs.realpathSync(root);
+      const realTarget = fs.realpathSync(resolved);
+      const realRel = path.relative(normForCompare(realRoot), normForCompare(realTarget));
+      if (realRel !== '' && (realRel.startsWith('..') || path.isAbsolute(realRel))) {
+        throw new Error(`Security Violation: Symlink target escapes workspace (${targetPath})`);
+      }
+    } catch (err) {
+      if (err.message && err.message.startsWith('Security Violation:')) throw err;
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Safely reads a workspace file with size limit and traversal protection.
+ * 
+ * @param {string} workspaceRoot
+ * @param {string} filePath
+ * @param {number} [maxBytes=102400] - Max 100 KB
+ * @returns {{content: string, size: number, truncated: boolean, error: string|null}}
+ */
+function readWorkspaceFile(workspaceRoot, filePath, maxBytes = 100 * 1024) {
+  try {
+    const safePath = safeResolveWorkspacePath(workspaceRoot, filePath);
+    if (!fs.existsSync(safePath)) {
+      return { content: '', size: 0, truncated: false, error: 'File does not exist' };
+    }
+    const stat = fs.statSync(safePath);
+    if (stat.isDirectory()) {
+      return { content: '', size: 0, truncated: false, error: 'Target is a directory, not a file' };
+    }
+
+    const size = stat.size;
+    let content;
+    let truncated = false;
+
+    if (size > maxBytes) {
+      const fd = fs.openSync(safePath, 'r');
+      const buffer = Buffer.alloc(maxBytes);
+      fs.readSync(fd, buffer, 0, maxBytes, 0);
+      fs.closeSync(fd);
+      content = buffer.toString('utf8');
+      truncated = true;
+    } else {
+      content = fs.readFileSync(safePath, 'utf8');
+    }
+
+    return { content, size, truncated, error: null };
+  } catch (err) {
+    return { content: '', size: 0, truncated: false, error: err.message };
+  }
+}
+
+/**
+ * Generates a clean text directory tree representation of the workspace.
+ * 
+ * @param {string} workspaceRoot
+ * @param {string} [subDir='.']
+ * @param {number} [maxDepth=2]
+ * @param {number} [maxEntries=120]
+ * @returns {string} Formatted tree string
+ */
+function listWorkspaceTree(workspaceRoot, subDir = '.', maxDepth = 2, maxEntries = 120) {
+  try {
+    const baseDir = safeResolveWorkspacePath(workspaceRoot, subDir);
+    if (!fs.existsSync(baseDir)) return `Directory not found: ${subDir}`;
+
+    const IGNORED = new Set([
+      'node_modules', '.git', '.disgravity', 'dist', 'out',
+      '.vscode', '.idea', '__pycache__', '.pytest_cache'
+    ]);
+
+    let count = 0;
+    const lines = [`📁 ${path.basename(baseDir) || '.'}`];
+
+    function walk(dir, depth, prefix) {
+      if (depth > maxDepth || count >= maxEntries) return;
+
+      let entries = [];
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+
+      // Directories first, then files alphabetically
+      entries.sort((a, b) => {
+        if (a.isDirectory() && !b.isDirectory()) return -1;
+        if (!a.isDirectory() && b.isDirectory()) return 1;
+        return a.name.localeCompare(b.name);
+      });
+
+      for (let i = 0; i < entries.length; i++) {
+        if (count >= maxEntries) {
+          lines.push(`${prefix}... (maximum entry limit reached)`);
+          return;
+        }
+
+        const entry = entries[i];
+        if (IGNORED.has(entry.name)) continue;
+
+        const isLast = i === entries.length - 1;
+        const pointer = isLast ? '└── ' : '├── ';
+        const childPrefix = prefix + (isLast ? '    ' : '│   ');
+
+        count++;
+        if (entry.isDirectory()) {
+          lines.push(`${prefix}${pointer}📁 ${entry.name}/`);
+          walk(path.join(dir, entry.name), depth + 1, childPrefix);
+        } else {
+          lines.push(`${prefix}${pointer}📄 ${entry.name}`);
+        }
+      }
+    }
+
+    walk(baseDir, 1, '');
+    return lines.join('\n');
+  } catch (err) {
+    return `Error generating tree: ${err.message}`;
+  }
+}
+
+/**
+ * Retrieves concise Git repository status and unified diff preview.
+ * 
+ * @param {string} cwd
+ * @returns {Promise<{branch: string, status: string, stat: string, isClean: boolean, error: string|null}>}
+ */
+async function getGitStatusAndDiff(cwd = process.cwd()) {
+  try {
+    const branchRes = await executeShellCommand('git rev-parse --abbrev-ref HEAD', cwd);
+    const branch = branchRes.stdout.trim() || 'unknown';
+
+    const statusRes = await executeShellCommand('git status --short', cwd);
+    const status = statusRes.stdout.trim();
+
+    const diffStatRes = await executeShellCommand('git diff --stat', cwd);
+    const stat = diffStatRes.stdout.trim();
+
+    const isClean = status.length === 0;
+
+    return {
+      branch,
+      status: status || 'Clean working tree',
+      stat: stat || 'No changes',
+      isClean,
+      error: branchRes.error || statusRes.error || null
+    };
+  } catch (err) {
+    return {
+      branch: 'unknown',
+      status: 'Error retrieving git status',
+      stat: '',
+      isClean: false,
+      error: err.message
+    };
+  }
+}
+
+/**
+ * Returns host and hardware telemetry data.
+ * 
+ * @param {string} workspace
+ * @returns {object}
+ */
+function getSystemHealth(workspace = process.cwd()) {
+  const cpus = os.cpus() || [];
+  const cpuModel = cpus[0] ? cpus[0].model.trim() : 'Unknown CPU';
+  const freeGB = (os.freemem() / (1024 ** 3)).toFixed(1);
+  const totalGB = (os.totalmem() / (1024 ** 3)).toFixed(1);
+
+  return {
+    platform: os.platform(),
+    release: os.release(),
+    arch: os.arch(),
+    cpu: `${cpuModel} (${cpus.length} cores)`,
+    memory: `${freeGB} GB free / ${totalGB} GB total`,
+    uptimeSeconds: Math.floor(process.uptime()),
+    workspace: path.resolve(workspace),
+    nodeVersion: process.version,
+    pid: process.pid
+  };
+}
+
+/**
+ * Regex patterns identifying potentially destructive file system or git operations.
+ */
+const DESTRUCTIVE_PATTERNS = [
+  /\brm\s+-[a-z0-9]*r[a-z0-9]*f?[a-z0-9]*\b/i,
+  /\brmdir\s+\/s\b/i,
+  /\bdel\s+\/[a-z0-9]*f[a-z0-9]*\b/i,
+  /\b(drop|truncate)\s+(database|table|schema)\b/i,
+  /\bgit\s+reset\s+--hard\b/i,
+  /\bgit\s+clean\s+-[a-z0-9]*f[a-z0-9]*\b/i,
+  /\bformat\s+[a-z]:/i,
+  /\b(mkfs|dd\s+if=)\b/i
+];
+
+/**
+ * Checks whether a command or prompt contains high-risk destructive keywords.
+ *
+ * @param {string} input
+ * @returns {boolean}
+ */
+function detectDestructiveKeywords(input) {
+  if (!input || typeof input !== 'string') return false;
+  return DESTRUCTIVE_PATTERNS.some(pat => pat.test(input));
+}
+
+/**
+ * Captures a safe workspace checkpoint prior to file modifications.
+ *
+ * @param {string} cwd
+ * @returns {Promise<{ok: boolean, stashSha?: string|null, headSha?: string, createdAt: string, error?: string}>}
+ */
+async function captureWorkspaceCheckpoint(cwd = process.cwd()) {
+  try {
+    const stashRes = await executeShellCommand('git stash create "disgravity_checkpoint"', cwd);
+    const stashSha = stashRes.stdout.trim();
+    const headRes = await executeShellCommand('git rev-parse HEAD', cwd);
+    const headSha = headRes.stdout.trim() || 'HEAD';
+    return {
+      ok: true,
+      stashSha: stashSha || null,
+      headSha,
+      createdAt: new Date().toISOString()
+    };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Restores a previously captured workspace checkpoint.
+ *
+ * @param {object} checkpoint
+ * @param {string} cwd
+ * @returns {Promise<{ok: boolean, output?: string, error?: string}>}
+ */
+async function restoreWorkspaceCheckpoint(checkpoint, cwd = process.cwd()) {
+  try {
+    if (!checkpoint) return { ok: false, error: 'No checkpoint provided' };
+    if (checkpoint.stashSha) {
+      const res = await executeShellCommand(`git stash apply ${checkpoint.stashSha}`, cwd);
+      return { ok: res.code === 0, output: res.stdout || res.stderr };
+    }
+    const res = await executeShellCommand('git checkout -- .', cwd);
+    return { ok: res.code === 0, output: res.stdout || res.stderr };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+// ============================================================================
+// Feature 1: Scheduled / Cron Prompts Engine (/schedule, !schedule)
+// ============================================================================
+
+const DURATION_UNITS_MS = {
+  s: 1000,
+  sec: 1000,
+  secs: 1000,
+  second: 1000,
+  seconds: 1000,
+  m: 60 * 1000,
+  min: 60 * 1000,
+  mins: 60 * 1000,
+  minute: 60 * 1000,
+  minutes: 60 * 1000,
+  h: 3600 * 1000,
+  hr: 3600 * 1000,
+  hrs: 3600 * 1000,
+  hour: 3600 * 1000,
+  hours: 3600 * 1000,
+  d: 86400 * 1000,
+  day: 86400 * 1000,
+  days: 86400 * 1000
+};
+
+/**
+ * Parses a single cron field into a Set of matching integers.
+ *
+ * @param {string} fieldStr
+ * @param {number} min
+ * @param {number} max
+ * @returns {Set<number>|null}
+ */
+function parseCronField(fieldStr, min, max) {
+  if (!fieldStr || typeof fieldStr !== 'string') return null;
+  const result = new Set();
+  const parts = fieldStr.trim().split(',');
+
+  for (const part of parts) {
+    const stepParts = part.split('/');
+    if (stepParts.length > 2) return null;
+    const rangeStr = stepParts[0];
+    const step = stepParts[1] !== undefined ? parseInt(stepParts[1], 10) : 1;
+    if (isNaN(step) || step <= 0) return null;
+
+    let start = min;
+    let end = max;
+
+    if (rangeStr === '*') {
+      start = min;
+      end = max;
+    } else if (rangeStr.includes('-')) {
+      const [sStr, eStr] = rangeStr.split('-');
+      start = parseInt(sStr, 10);
+      end = parseInt(eStr, 10);
+      if (isNaN(start) || isNaN(end) || start > end) return null;
+    } else {
+      const val = parseInt(rangeStr, 10);
+      if (isNaN(val)) return null;
+      start = val;
+      end = stepParts[1] !== undefined ? max : val;
+    }
+
+    // Allow 7 for Sunday in day-of-week
+    if (max === 6 && end === 7) {
+      if (start === 7) start = 0;
+      end = 6;
+      result.add(0);
+    }
+
+    if (start < min || end > max) return null;
+
+    for (let i = start; i <= end; i += step) {
+      result.add(i);
+    }
+  }
+
+  return result.size > 0 ? result : null;
+}
+
+/**
+ * Parses a schedule specification string into a structured schedule descriptor:
+ * - One-shot relative delay: "30s", "15m", "2h", "1d", "in 10m"
+ * - Recurring interval: "every 5m", "every 1h", "@hourly", "@daily", "@weekly"
+ * - 5-field cron expression: "0 9 * * 1-5", "* /15 * * * *"
+ *
+ * @param {string} rawSpec
+ * @returns {{type: 'once'|'interval'|'cron', delayMs?: number, intervalMs?: number, fields?: object, spec: string, description: string}|null}
+ */
+function parseScheduleSpec(rawSpec) {
+  if (!rawSpec || typeof rawSpec !== 'string') return null;
+  const spec = rawSpec.trim().replace(/^['"]|['"]$/g, '').trim();
+  if (!spec) return null;
+
+  const lower = spec.toLowerCase();
+
+  // 1. Named presets
+  if (lower === '@hourly' || lower === 'hourly') {
+    return { valid: true, type: 'interval', intervalMs: 3600 * 1000, spec: '@hourly', description: 'Every 1 hour' };
+  }
+  if (lower === '@daily' || lower === 'daily') {
+    return { valid: true, type: 'interval', intervalMs: 86400 * 1000, spec: '@daily', description: 'Every 24 hours' };
+  }
+  if (lower === '@weekly' || lower === 'weekly') {
+    return { valid: true, type: 'interval', intervalMs: 7 * 86400 * 1000, spec: '@weekly', description: 'Every 7 days' };
+  }
+
+  // 2. Recurring interval: "every 30s", "every 15m", "every 2h"
+  const everyMatch = lower.match(/^every\s+(\d+(?:\.\d+)?)\s*([a-z]+)$/i);
+  if (everyMatch) {
+    const num = parseFloat(everyMatch[1]);
+    const unit = everyMatch[2];
+    const mult = DURATION_UNITS_MS[unit];
+    if (!mult || isNaN(num) || num <= 0) return null;
+    const intervalMs = Math.round(num * mult);
+    if (intervalMs < 1000) return null;
+    return {
+      valid: true,
+      type: 'interval',
+      intervalMs,
+      spec: `every ${everyMatch[1]}${unit}`,
+      description: `Every ${everyMatch[1]} ${unit}`
+    };
+  }
+
+  // 3. One-shot relative duration: "30s", "15m", "2h", "1d", "in 15m"
+  const onceMatch = lower.match(/^(?:in\s+)?(\d+(?:\.\d+)?)\s*([a-z]+)$/i);
+  if (onceMatch) {
+    const num = parseFloat(onceMatch[1]);
+    const unit = onceMatch[2];
+    const mult = DURATION_UNITS_MS[unit];
+    if (!mult || isNaN(num) || num <= 0) return null;
+    const delayMs = Math.round(num * mult);
+    if (delayMs < 1000) return null;
+    return {
+      valid: true,
+      type: 'once',
+      delayMs,
+      spec: `${onceMatch[1]}${unit}`,
+      description: `Once in ${onceMatch[1]} ${unit}`
+    };
+  }
+
+  // 4. Standard 5-field cron expression: "<min> <hour> <dom> <month> <dow>"
+  const cronTokens = spec.split(/\s+/);
+  if (cronTokens.length === 5) {
+    const minute = parseCronField(cronTokens[0], 0, 59);
+    const hour = parseCronField(cronTokens[1], 0, 23);
+    const dom = parseCronField(cronTokens[2], 1, 31);
+    const month = parseCronField(cronTokens[3], 1, 12);
+    const dow = parseCronField(cronTokens[4], 0, 6);
+    if (minute && hour && dom && month && dow) {
+      return {
+        valid: true,
+        type: 'cron',
+        fields: { minute, hour, dom, month, dow },
+        spec: cronTokens.join(' '),
+        description: `Cron (${cronTokens.join(' ')})`
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Checks whether a Date object matches a parsed 5-field cron expression.
+ *
+ * @param {{minute: Set<number>, hour: Set<number>, dom: Set<number>, month: Set<number>, dow: Set<number>}} fields
+ * @param {Date} date
+ * @returns {boolean}
+ */
+function matchesCronTime(fields, date) {
+  if (!fields || !(date instanceof Date)) return false;
+  return (
+    fields.minute.has(date.getMinutes()) &&
+    fields.hour.has(date.getHours()) &&
+    fields.dom.has(date.getDate()) &&
+    fields.month.has(date.getMonth() + 1) &&
+    fields.dow.has(date.getDay())
+  );
+}
+
+/**
+ * Computes the next trigger Date for a parsed 5-field cron expression starting after `fromDate`.
+ *
+ * @param {object} fields
+ * @param {Date} [fromDate=new Date()]
+ * @returns {Date|null}
+ */
+function getNextCronTime(fields, fromDate = new Date()) {
+  if (!fields) return null;
+  const candidate = new Date(fromDate.getTime());
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1);
+
+  // Search up to 366 days ahead (527,040 minutes)
+  const maxIterations = 366 * 24 * 60;
+  for (let i = 0; i < maxIterations; i++) {
+    if (matchesCronTime(fields, candidate)) {
+      return candidate;
+    }
+    candidate.setMinutes(candidate.getMinutes() + 1);
+  }
+  return null;
+}
+
+/**
+ * Parses a raw `/schedule` or `!schedule` command string into an action:
+ * - "list" / "" -> { action: 'list' }
+ * - "cancel <id|all>" / "remove <id>" / "clear" -> { action: 'cancel', target }
+ * - "<spec> <prompt>" -> { action: 'add', spec, parsedSpec, prompt }
+ *
+ * @param {string} rawInput
+ * @returns {{action: 'list'|'cancel'|'add'|'invalid', target?: string, spec?: string, parsedSpec?: object, prompt?: string, error?: string}}
+ */
+function parseScheduleCommandInput(rawInput) {
+  const trimmed = String(rawInput || '').trim();
+  if (!trimmed || /^list$/i.test(trimmed)) {
+    return { action: 'list' };
+  }
+
+  if (/^(clear|cancel\s+all|remove\s+all|stop\s+all)$/i.test(trimmed)) {
+    return { action: 'cancel', target: 'all', jobId: 'all' };
+  }
+
+  const cancelMatch = trimmed.match(/^(?:cancel|remove|delete|stop)\s+#?(\S+)$/i);
+  if (cancelMatch) {
+    const id = cancelMatch[1].trim();
+    return { action: 'cancel', target: id, jobId: id };
+  }
+
+  // Pipe-delimited spec: "!schedule 0 9 * * 1-5 | !sh npm test"
+  if (trimmed.includes('|')) {
+    const pipeIdx = trimmed.indexOf('|');
+    const rawSpec = trimmed.slice(0, pipeIdx).trim();
+    const rawPrompt = trimmed.slice(pipeIdx + 1).trim();
+    const parsedSpec = parseScheduleSpec(rawSpec);
+    if (!parsedSpec) {
+      return { action: 'invalid', error: `Invalid schedule specification: \`${rawSpec}\`` };
+    }
+    if (!rawPrompt) {
+      return { action: 'invalid', error: 'Scheduled prompt cannot be empty.' };
+    }
+    return { action: 'add', spec: parsedSpec.spec, parsedSpec, prompt: rawPrompt };
+  }
+
+  // Quoted cron/spec: "!schedule \"*/15 * * * *\" run tests"
+  const quotedMatch = trimmed.match(/^["']([^"']+)["']\s+([\s\S]+)$/);
+  if (quotedMatch) {
+    const parsedSpec = parseScheduleSpec(quotedMatch[1]);
+    if (!parsedSpec) {
+      return { action: 'invalid', error: `Invalid schedule specification: \`${quotedMatch[1]}\`` };
+    }
+    return { action: 'add', spec: parsedSpec.spec, parsedSpec, prompt: quotedMatch[2].trim() };
+  }
+
+  // Unquoted "every <num><unit> <prompt>" or "in <num><unit> <prompt>"
+  const twoTokenMatch = trimmed.match(/^((?:every|in)\s+\d+(?:\.\d+)?\s*[a-z]+)\s+([\s\S]+)$/i);
+  if (twoTokenMatch) {
+    const parsedSpec = parseScheduleSpec(twoTokenMatch[1]);
+    if (!parsedSpec) {
+      return { action: 'invalid', error: `Invalid interval specification: \`${twoTokenMatch[1]}\`` };
+    }
+    return { action: 'add', spec: parsedSpec.spec, parsedSpec, prompt: twoTokenMatch[2].trim() };
+  }
+
+  // Unquoted 5-field cron at start: "*/15 * * * * <prompt>"
+  const tokens = trimmed.split(/\s+/);
+  if (tokens.length >= 6) {
+    const maybeCron = tokens.slice(0, 5).join(' ');
+    const parsedCron = parseScheduleSpec(maybeCron);
+    if (parsedCron && parsedCron.type === 'cron') {
+      const prompt = trimmed.slice(trimmed.indexOf(tokens[4]) + tokens[4].length).trim();
+      if (prompt) {
+        return { action: 'add', spec: parsedCron.spec, parsedSpec: parsedCron, prompt };
+      }
+    }
+  }
+
+  // Single-token spec: "15m <prompt>", "@hourly <prompt>"
+  const singleTokenMatch = trimmed.match(/^(\S+)\s+([\s\S]+)$/);
+  if (singleTokenMatch) {
+    const parsedSpec = parseScheduleSpec(singleTokenMatch[1]);
+    if (parsedSpec) {
+      return { action: 'add', spec: parsedSpec.spec, parsedSpec, prompt: singleTokenMatch[2].trim() };
+    }
+  }
+
+  return {
+    action: 'invalid',
+    error: 'Invalid schedule syntax. Examples: `/schedule time:30m prompt:run npm test`, `!schedule every 1h check build`, or `!schedule "0 9 * * *" git status`.'
+  };
+}
+
+/**
+ * In-memory Scheduler for one-shot, interval, and cron prompts in Dis-Gravity.
+ */
+class TaskScheduler {
+  constructor(options = {}) {
+    this.maxJobs = options.maxJobs || 25;
+    this.onTrigger = options.onTrigger || null;
+    this.jobs = new Map();
+    this.nextId = 1;
+  }
+
+  /**
+   * Schedules a new prompt job.
+   *
+   * @param {{spec: string, prompt: string, threadId?: string|null, channelId?: string|null, workspace?: string|null, workspacePath?: string|null, author?: string, userId?: string, onTrigger?: (job: object) => void|Promise<void>}} opts
+   * @returns {object} Created job metadata
+   */
+  addJob(opts = {}) {
+    const returnResultObj = Boolean(this.onTrigger && !opts.onTrigger);
+    const fail = (msg) => {
+      if (returnResultObj) return { ok: false, error: msg };
+      throw new Error(msg);
+    };
+
+    if (this.jobs.size >= this.maxJobs) {
+      return fail(`Maximum active scheduled tasks (${this.maxJobs}) reached. Cancel an existing schedule first.`);
+    }
+
+    const parsed = typeof opts.spec === 'object' && opts.spec !== null
+      ? opts.spec
+      : parseScheduleSpec(opts.spec);
+
+    if (!parsed) {
+      return fail(`Invalid schedule specification: ${opts.spec}`);
+    }
+
+    const prompt = String(opts.prompt || '').trim();
+    if (!prompt) {
+      return fail('Scheduled prompt cannot be empty.');
+    }
+
+    const id = String(this.nextId++);
+    const now = Date.now();
+    let nextRunAt = null;
+
+    if (parsed.type === 'once') {
+      nextRunAt = new Date(now + parsed.delayMs);
+    } else if (parsed.type === 'interval') {
+      nextRunAt = new Date(now + parsed.intervalMs);
+    } else if (parsed.type === 'cron') {
+      nextRunAt = getNextCronTime(parsed.fields, new Date(now));
+      if (!nextRunAt) {
+        return fail(`Cron expression "${parsed.spec}" has no upcoming execution dates.`);
+      }
+    }
+
+    const ws = opts.workspace || opts.workspacePath || null;
+    const job = {
+      id,
+      spec: parsed.spec,
+      type: parsed.type,
+      description: parsed.description,
+      prompt,
+      threadId: opts.threadId || null,
+      channelId: opts.channelId || null,
+      workspace: ws,
+      workspacePath: ws,
+      author: opts.author || opts.userId || 'Discord User',
+      userId: opts.userId || opts.author || 'Discord User',
+      createdAt: new Date(now).toISOString(),
+      nextRunAt: nextRunAt ? nextRunAt.toISOString() : null,
+      runCount: 0,
+      _timer: null,
+      _parsed: parsed,
+      _onTrigger: opts.onTrigger || this.onTrigger
+    };
+
+    this._armJob(job);
+    this.jobs.set(id, job);
+    return this._sanitizeJob(job);
+  }
+
+  _armJob(job) {
+    if (job._timer) {
+      clearTimeout(job._timer);
+      clearInterval(job._timer);
+      job._timer = null;
+    }
+
+    const parsed = job._parsed;
+    if (parsed.type === 'once') {
+      job._timer = setTimeout(async () => {
+        job.runCount++;
+        this.jobs.delete(job.id);
+        try {
+          await job._onTrigger?.(this._sanitizeJob(job));
+        } catch { }
+      }, parsed.delayMs);
+      if (job._timer && typeof job._timer.unref === 'function') job._timer.unref();
+    } else if (parsed.type === 'interval') {
+      job._timer = setInterval(async () => {
+        job.runCount++;
+        job.nextRunAt = new Date(Date.now() + parsed.intervalMs).toISOString();
+        try {
+          await job._onTrigger?.(this._sanitizeJob(job));
+        } catch { }
+      }, parsed.intervalMs);
+      if (job._timer && typeof job._timer.unref === 'function') job._timer.unref();
+    } else if (parsed.type === 'cron') {
+      const scheduleNextCronTick = () => {
+        if (!this.jobs.has(job.id)) return;
+        const nextDate = getNextCronTime(parsed.fields, new Date());
+        if (!nextDate) {
+          this.jobs.delete(job.id);
+          return;
+        }
+        job.nextRunAt = nextDate.toISOString();
+        // Clamp setTimeout to 24h max chunk to avoid 32-bit signed integer overflow (24.8 days)
+        const waitMs = Math.max(500, nextDate.getTime() - Date.now());
+        const chunkMs = Math.min(waitMs, 24 * 3600 * 1000);
+        job._timer = setTimeout(async () => {
+          if (!this.jobs.has(job.id)) return;
+          if (Date.now() + 500 < nextDate.getTime()) {
+            scheduleNextCronTick();
+            return;
+          }
+          job.runCount++;
+          try {
+            await job._onTrigger?.(this._sanitizeJob(job));
+          } catch { }
+          scheduleNextCronTick();
+        }, chunkMs);
+        if (job._timer && typeof job._timer.unref === 'function') job._timer.unref();
+      };
+      scheduleNextCronTick();
+    }
+  }
+
+  _sanitizeJob(job) {
+    const out = {
+      ok: true,
+      id: job.id,
+      spec: job.spec,
+      type: job.type,
+      description: job.description,
+      prompt: job.prompt,
+      threadId: job.threadId,
+      channelId: job.channelId,
+      workspace: job.workspace,
+      workspacePath: job.workspacePath || job.workspace,
+      author: job.author,
+      userId: job.userId,
+      createdAt: job.createdAt,
+      nextRunAt: job.nextRunAt,
+      runCount: job.runCount
+    };
+    Object.defineProperty(out, 'job', { value: out, enumerable: false });
+    return out;
+  }
+
+  listJobs() {
+    return Array.from(this.jobs.values()).map(j => this._sanitizeJob(j));
+  }
+
+  getJob(id) {
+    const cleanId = String(id || '').replace(/^#/, '').trim();
+    const j = this.jobs.get(cleanId);
+    return j ? this._sanitizeJob(j) : null;
+  }
+
+  cancelJob(id) {
+    const cleanId = String(id || '').replace(/^#/, '').trim();
+    const job = this.jobs.get(cleanId);
+    if (!job) return false;
+    if (job._timer) {
+      clearTimeout(job._timer);
+      clearInterval(job._timer);
+      job._timer = null;
+    }
+    this.jobs.delete(cleanId);
+    return true;
+  }
+
+  cancelAll() {
+    const count = this.jobs.size;
+    for (const job of this.jobs.values()) {
+      if (job._timer) {
+        clearTimeout(job._timer);
+        clearInterval(job._timer);
+        job._timer = null;
+      }
+    }
+    this.jobs.clear();
+    return count;
+  }
+
+  stopAll() {
+    return this.cancelAll();
+  }
+}
+
+// ============================================================================
+// Feature 2: Discord Thread-per-Session & Workspace Mapping Engine
+// ============================================================================
+
+/**
+ * Manages bindings between Discord Threads and local Workspace directories / Agent sessions.
+ */
+class ThreadWorkspaceManager {
+  constructor(options = {}) {
+    this.bindings = new Map();
+    this.defaultWorkspace = options.defaultWorkspace || process.cwd();
+    this.hasDefaultWorkspace = Boolean(options.defaultWorkspace);
+    this.storageFile = options.storageFile || null;
+    if (this.storageFile) {
+      this._loadFromDisk();
+    }
+  }
+
+  _loadFromDisk() {
+    if (!this.storageFile) return;
+    try {
+      if (fs.existsSync(this.storageFile)) {
+        const raw = JSON.parse(fs.readFileSync(this.storageFile, 'utf8'));
+        this.loadFromJSON(raw);
+      }
+    } catch { }
+  }
+
+  _saveToDisk() {
+    if (!this.storageFile) return;
+    try {
+      const dir = path.dirname(this.storageFile);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(this.storageFile, JSON.stringify(this.toJSON(), null, 2), { encoding: 'utf8', mode: 0o600 });
+    } catch { }
+  }
+
+  /**
+   * Binds a Discord thread ID to a specific local workspace directory and optional session metadata.
+   *
+   * @param {string} threadId
+   * @param {string} workspacePath
+   * @param {{label?: string, conversationName?: string, boundBy?: string, baseWorkspace?: string}} [meta={}]
+   * @returns {{threadId: string, workspace: string, label: string, conversationName: string|null, boundBy: string, boundAt: string}}
+   */
+  bindThread(threadId, workspacePath, meta = {}) {
+    const returnResultObj = Boolean(this.hasDefaultWorkspace && !meta.boundBy);
+    const fail = (msg) => {
+      if (returnResultObj) return { ok: false, error: msg };
+      throw new Error(msg);
+    };
+
+    const cleanThreadId = String(threadId || '').trim();
+    if (!cleanThreadId) {
+      return fail('Thread ID is required to bind a workspace.');
+    }
+    const rawPath = String(workspacePath || '').trim();
+    if (!rawPath || rawPath.includes('\0')) {
+      return fail('Valid workspace directory path is required.');
+    }
+
+    const resolved = meta.baseWorkspace && !path.isAbsolute(rawPath)
+      ? path.resolve(meta.baseWorkspace, rawPath)
+      : path.resolve(this.defaultWorkspace, rawPath);
+
+    if (!fs.existsSync(resolved)) {
+      return fail(`Workspace path does not exist: ${resolved}`);
+    }
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) {
+      return fail(`Target path is not a directory: ${resolved}`);
+    }
+
+    const existing = this.bindings.get(cleanThreadId) || {};
+    const entry = {
+      threadId: cleanThreadId,
+      workspace: resolved,
+      workspacePath: resolved,
+      label: meta.label || path.basename(resolved) || resolved,
+      conversationName: meta.conversationName !== undefined ? meta.conversationName : (existing.conversationName || null),
+      boundBy: meta.boundBy || meta.userId || existing.boundBy || 'Discord User',
+      boundAt: new Date().toISOString()
+    };
+
+    this.bindings.set(cleanThreadId, entry);
+    this._saveToDisk();
+    const out = { ok: true, ...entry };
+    Object.defineProperty(out, 'binding', { value: out, enumerable: false });
+    return out;
+  }
+
+  /**
+   * Updates or sets the conversation session name for a thread without requiring a workspace change.
+   */
+  setThreadConversation(threadId, conversationName, fallbackWorkspace = null) {
+    const cleanThreadId = String(threadId || '').trim();
+    if (!cleanThreadId) return null;
+    const existing = this.bindings.get(cleanThreadId);
+    if (existing) {
+      existing.conversationName = conversationName;
+      this._saveToDisk();
+      return { ...existing };
+    }
+    if (fallbackWorkspace && fs.existsSync(fallbackWorkspace)) {
+      const resolved = path.resolve(fallbackWorkspace);
+      const entry = {
+        threadId: cleanThreadId,
+        workspace: resolved,
+        label: path.basename(resolved),
+        conversationName: conversationName || null,
+        boundBy: 'auto',
+        boundAt: new Date().toISOString()
+      };
+      this.bindings.set(cleanThreadId, entry);
+      this._saveToDisk();
+      return { ...entry };
+    }
+    return null;
+  }
+
+  unbindThread(threadId) {
+    const cleanThreadId = String(threadId || '').trim();
+    const deleted = this.bindings.delete(cleanThreadId);
+    if (deleted) this._saveToDisk();
+    return deleted;
+  }
+
+  getThreadBinding(threadId) {
+    if (!threadId) return null;
+    const entry = this.bindings.get(String(threadId).trim());
+    return entry ? { ...entry, workspacePath: entry.workspacePath || entry.workspace } : null;
+  }
+
+  /**
+   * Resolves the effective workspace directory for a given threadId (or returns fallbackWorkspace).
+   *
+   * @param {string|null|undefined} threadId
+   * @param {string} [fallbackWorkspace]
+   * @returns {string}
+   */
+  getThreadWorkspace(threadId, fallbackWorkspace = this.defaultWorkspace) {
+    if (threadId) {
+      const entry = this.bindings.get(String(threadId).trim());
+      if (entry && entry.workspace && fs.existsSync(entry.workspace)) {
+        return entry.workspace;
+      }
+    }
+    return fallbackWorkspace;
+  }
+
+  listBindings() {
+    return Array.from(this.bindings.values()).map(b => ({ ...b, workspacePath: b.workspacePath || b.workspace }));
+  }
+
+  toJSON() {
+    return Array.from(this.bindings.entries());
+  }
+
+  loadFromJSON(data) {
+    if (!data) return;
+    if (Array.isArray(data)) {
+      for (const item of data) {
+        if (Array.isArray(item) && item.length === 2 && item[0] && item[1]?.workspace) {
+          this.bindings.set(String(item[0]), item[1]);
+        } else if (item && item.threadId && item.workspace) {
+          this.bindings.set(String(item.threadId), item);
+        }
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Feature 3: Discord Voice Message & Audio Transcription Engine
+// ============================================================================
+
+const AUDIO_EXTENSIONS = new Set([
+  '.ogg', '.oga', '.opus', '.mp3', '.wav', '.m4a', '.webm', '.flac', '.aac'
+]);
+
+/**
+ * Detects whether a Discord attachment or file descriptor is a voice message or audio file.
+ *
+ * @param {object} att - Attachment object ({ name, url, contentType, content_type, duration_secs, waveform, flags })
+ * @param {number} [messageFlags=0] - Optional Discord message bitfield flags (1 << 13 = 8192 = IS_VOICE_MESSAGE)
+ * @returns {boolean}
+ */
+function isAudioAttachment(att, messageFlags = 0) {
+  if (!att || typeof att !== 'object') return false;
+  if ((Number(messageFlags) & 8192) === 8192) return true;
+  if (att.waveform || typeof att.duration_secs === 'number' || typeof att.duration === 'number') return true;
+
+  const contentType = String(att.contentType || att.content_type || '').toLowerCase().trim();
+  if (contentType.startsWith('audio/') || contentType === 'application/ogg') {
+    return true;
+  }
+
+  const name = String(att.name || att.filename || att.originalName || att.fileName || att.url || '').split('?')[0];
+  const ext = path.extname(name).toLowerCase();
+  return AUDIO_EXTENSIONS.has(ext);
+}
+
+/**
+ * Transcribes a local audio file into text using:
+ * 1. Custom transcriber function (`options.transcriber`) if provided
+ * 2. OpenAI / Groq / Whisper-compatible Cloud REST API (`OPENAI_API_KEY`, `GROQ_API_KEY`, `DISGRAVITY_WHISPER_API_KEY`, or `options.apiKey`)
+ * 3. Local Whisper CLI (`whisper`, `whisper-cli`, `whisper-cpp`) if installed on PATH
+ * 4. Windows native System.Speech fallback for `.wav` files
+ *
+ * @param {string} filePath - Absolute path to downloaded audio file
+ * @param {{apiKey?: string, apiUrl?: string, model?: string, language?: string, transcriber?: Function, timeoutMs?: number}} [options={}]
+ * @returns {Promise<{ok: boolean, text: string, provider: string, durationMs: number, error: string|null}>}
+ */
+async function transcribeAudioFile(filePath, options = {}) {
+  const startTime = Date.now();
+  if (!filePath || typeof filePath !== 'string' || !fs.existsSync(filePath)) {
+    return {
+      ok: false,
+      text: '',
+      provider: 'none',
+      durationMs: 0,
+      error: 'Audio file does not exist'
+    };
+  }
+
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile() || stat.size === 0) {
+    return {
+      ok: false,
+      text: '',
+      provider: 'none',
+      durationMs: 0,
+      error: 'Audio file is empty'
+    };
+  }
+
+  // 1. Custom injected transcriber (or mock in tests)
+  if (typeof options.transcriber === 'function') {
+    try {
+      const res = await options.transcriber(filePath, options);
+      const text = typeof res === 'string' ? res.trim() : String(res?.text || '').trim();
+      return {
+        ok: Boolean(text),
+        text,
+        provider: (res && res.provider) || 'custom',
+        durationMs: Date.now() - startTime,
+        error: text ? null : 'Empty transcription result'
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        text: '',
+        provider: 'custom',
+        durationMs: Date.now() - startTime,
+        error: err.message
+      };
+    }
+  }
+
+  // 2. Whisper-compatible Cloud API (OpenAI / Groq / Custom)
+  const groqKey = process.env.GROQ_API_KEY || '';
+  const openaiKey = process.env.OPENAI_API_KEY || '';
+  const customKey = options.apiKey || process.env.DISGRAVITY_WHISPER_API_KEY || '';
+  const apiKey = (customKey || openaiKey || groqKey).trim();
+
+  if (apiKey && typeof fetch === 'function') {
+    const isGroq = !customKey && !openaiKey && Boolean(groqKey) || apiKey.startsWith('gsk_');
+    const apiUrl = (options.apiUrl || process.env.DISGRAVITY_WHISPER_API_URL || (
+      isGroq
+        ? 'https://api.groq.com/openai/v1/audio/transcriptions'
+        : 'https://api.openai.com/v1/audio/transcriptions'
+    )).trim();
+    const model = options.model || process.env.DISGRAVITY_WHISPER_MODEL || (
+      isGroq ? 'whisper-large-v3-turbo' : 'whisper-1'
+    );
+
+    try {
+      const fileBuf = await fs.promises.readFile(filePath);
+      const fileName = path.basename(filePath);
+      const boundary = `----DisGravityAudioBoundary${crypto.randomBytes(8).toString('hex')}`;
+
+      const parts = [];
+      const addField = (name, val) => {
+        parts.push(Buffer.from(
+          `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${val}\r\n`,
+          'utf8'
+        ));
+      };
+      addField('model', model);
+      addField('response_format', 'json');
+      if (options.language) addField('language', options.language);
+
+      parts.push(Buffer.from(
+        `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${fileName.replace(/"/g, '_')}"\r\nContent-Type: application/octet-stream\r\n\r\n`,
+        'utf8'
+      ));
+      parts.push(fileBuf);
+      parts.push(Buffer.from(`\r\n--${boundary}--\r\n`, 'utf8'));
+
+      const bodyBuffer = Buffer.concat(parts);
+      const res = await fetch(apiUrl, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': `multipart/form-data; boundary=${boundary}`
+        },
+        body: bodyBuffer,
+        signal: AbortSignal.timeout(options.timeoutMs || 30000)
+      });
+
+      if (res.ok) {
+        const data = await res.json();
+        const text = String(data.text || '').trim();
+        if (text) {
+          return {
+            ok: true,
+            text,
+            provider: isGroq ? 'groq-whisper' : 'openai-whisper',
+            durationMs: Date.now() - startTime,
+            error: null
+          };
+        }
+      } else {
+        const errBody = await res.text().catch(() => '');
+        return {
+          ok: false,
+          text: '',
+          provider: isGroq ? 'groq-whisper' : 'openai-whisper',
+          durationMs: Date.now() - startTime,
+          error: `Whisper API HTTP ${res.status}: ${errBody.substring(0, 200)}`
+        };
+      }
+    } catch (err) {
+      return {
+        ok: false,
+        text: '',
+        provider: 'whisper-api',
+        durationMs: Date.now() - startTime,
+        error: err.message
+      };
+    }
+  }
+
+  // 3. Local CLI Whisper ('whisper-cli', 'whisper')
+  const isWin = process.platform === 'win32';
+  const whichCmd = isWin ? 'where.exe' : 'which';
+  const localBins = ['whisper-cli', 'whisper'];
+  for (const bin of localBins) {
+    let found = false;
+    try {
+      cp.execFileSync(whichCmd, [bin], { stdio: 'ignore' });
+      found = true;
+    } catch { }
+    if (!found) continue;
+
+    try {
+      const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'disgravity_stt_'));
+      try {
+        await new Promise((resolve, reject) => {
+          cp.execFile(
+            bin,
+            [filePath, '--model', 'base', '--output_format', 'txt', '--output_dir', outDir],
+            { timeout: options.timeoutMs || 45000, windowsHide: true },
+            (err) => (err ? reject(err) : resolve())
+          );
+        });
+        const files = fs.readdirSync(outDir).filter(f => f.endsWith('.txt'));
+        if (files.length > 0) {
+          const text = fs.readFileSync(path.join(outDir, files[0]), 'utf8').trim();
+          if (text) {
+            return {
+              ok: true,
+              text,
+              provider: `local-${bin}`,
+              durationMs: Date.now() - startTime,
+              error: null
+            };
+          }
+        }
+      } finally {
+        try { fs.rmSync(outDir, { recursive: true, force: true }); } catch { }
+      }
+    } catch { }
+  }
+
+  // 4. Windows System.Speech fallback for .wav files
+  if (isWin && path.extname(filePath).toLowerCase() === '.wav') {
+    try {
+      const psScript = [
+        'Add-Type -AssemblyName System.Speech;',
+        '$rec = New-Object System.Speech.Recognition.SpeechRecognitionEngine;',
+        '$rec.LoadGrammar((New-Object System.Speech.Recognition.DictationGrammar));',
+        '$rec.SetInputToWaveFile($env:DISGRAVITY_WAV_PATH);',
+        '$res = $rec.Recognize();',
+        'if ($res) { Write-Output $res.Text }'
+      ].join(' ');
+      const text = await new Promise((resolve, reject) => {
+        cp.execFile(
+          'powershell.exe',
+          ['-NoProfile', '-NonInteractive', '-Command', psScript],
+          {
+            env: { ...process.env, DISGRAVITY_WAV_PATH: filePath },
+            timeout: options.timeoutMs || 20000,
+            windowsHide: true
+          },
+          (err, stdout) => (err ? reject(err) : resolve(String(stdout || '').trim()))
+        );
+      });
+      if (text) {
+        return {
+          ok: true,
+          text,
+          provider: 'windows-speech',
+          durationMs: Date.now() - startTime,
+          error: null
+        };
+      }
+    } catch { }
+  }
+
+  return {
+    ok: false,
+    text: '',
+    provider: 'none',
+    durationMs: Date.now() - startTime,
+    error: 'No transcription engine configured. Set OPENAI_API_KEY / GROQ_API_KEY (or antigravity-discord.whisperApiKey) or install local whisper CLI.'
+  };
+}
+
+module.exports = {
+  isUserAllowed,
+  executeShellCommand,
+  findHeadlessBrowser,
+  escapeHtml,
+  buildTableHtml,
+  renderTableToPng,
+  buildDiffHtml,
+  renderDiffToPng,
+  detectDestructiveKeywords,
+  captureWorkspaceCheckpoint,
+  restoreWorkspaceCheckpoint,
+  parseMarkdownTable,
+  safeResolveWorkspacePath,
+  readWorkspaceFile,
+  listWorkspaceTree,
+  getGitStatusAndDiff,
+  getSystemHealth,
+  parseCronField,
+  parseScheduleSpec,
+  matchesCronTime,
+  getNextCronTime,
+  parseScheduleCommandInput,
+  TaskScheduler,
+  ThreadWorkspaceManager,
+  isAudioAttachment,
+  transcribeAudioFile
+};