create-walle 0.9.21 → 0.9.23

package/template/wall-e/tools/local-tools.js

@@ -4,6 +4,8 @@ const { promisify } = require('util');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
+const http = require('http');
 const https = require('https');
 const execFileAsync = promisify(execFile);
 const execAsync = promisify(exec);
@@ -16,6 +18,15 @@ const MAIL_AUTOMATION_COOLDOWN_PATH = process.env.WALLE_MAIL_COOLDOWN_PATH ||
   path.join(os.tmpdir(), 'wall-e-mail-appleevent-cooldown.json');
 const MAIL_AUTOMATION_COOLDOWN_MS = 5 * 60 * 1000;
 const MAIL_AUTOMATION_SLOW_MS = 30 * 1000;
+const STATIC_SERVER_PROCESSES = new Map();
+
+function expandUserPath(value) {
+  if (typeof value !== 'string' || !value.startsWith('~')) return value;
+  const home = process.env.HOME || HOME;
+  if (value === '~') return home;
+  if (value.startsWith('~/')) return path.join(home, value.slice(2));
+  return value;
+}
 
 function _pidIsAlive(pid) {
   if (!pid || pid <= 0) return false;
@@ -1513,9 +1524,12 @@ function hasShellControlArg(args) {
 async function runShell(commandOrOpts, legacyArgs, legacyOpts) {
   let command, args, timeout_ms, cwd;
 
+  let background = false;
+  let sessionId = '';
+  let persist = false;
   if (typeof commandOrOpts === 'object' && commandOrOpts !== null) {
-    // New format: runShell({ command, args, timeout_ms, cwd })
-    ({ command, args, timeout_ms = 30000, cwd } = commandOrOpts);
+    // New format: runShell({ command, args, timeout_ms, cwd, background })
+    ({ command, args, timeout_ms = 30000, cwd, background = false, sessionId = '', persist = false } = commandOrOpts);
   } else {
     // Legacy format: runShell(command, args, { timeout_ms })
     command = commandOrOpts;
@@ -1542,6 +1556,12 @@ async function runShell(commandOrOpts, legacyArgs, legacyOpts) {
     commandStr = command;
   }
 
+  // Background mode: detach into the session-scoped registry (it runs its
+  // own shell-analyzer gate before spawning).
+  if (background) {
+    return runShellBackground({ command: commandStr, cwd, sessionId, persist });
+  }
+
   // Tree-sitter analysis gates execution
   const analysis = await analyzeShellCommand(commandStr, cwd || process.cwd());
   if (!analysis.allowed) {
@@ -1895,11 +1915,18 @@ async function writeFile(filePath, content, { sessionId, projectRoot } = {}) {
   return { written: true, path: resolved, bytes: Buffer.byteLength(content) };
 }
 
-async function searchFiles(query, { directory, extensions, max_results = 20 } = {}) {
-  const searchDir = directory ? resolveSafePath(directory) : HOME;
+async function searchFiles(query, { directory, extensions, max_results = 20, projectRoot } = {}) {
+  let searchDir;
+  try {
+    searchDir = projectRoot
+      ? resolveToolPath(directory || '.', projectRoot)
+      : (directory ? resolveSafePath(directory) : HOME);
+  } catch (err) {
+    return { error: err.message, count: 0, files: [] };
+  }
   // Use macOS Spotlight (mdfind) for fast indexed search
   const args = [query];
-  if (directory) args.push('-onlyin', searchDir);
+  if (directory || projectRoot) args.push('-onlyin', searchDir);
   try {
     const { stdout } = await execFileAsync('mdfind', args, {
       timeout: 10000,
@@ -1972,12 +1999,260 @@ function findChromeExecutable() {
   return CHROME_CANDIDATES.find((p) => fs.existsSync(p)) || null;
 }
 
-async function browserScreenshot({ url, output_path, viewport = 'desktop' } = {}) {
+function hostAutomationEnv() {
+  const env = { ...process.env };
+  const realHome = process.env.WALL_E_REAL_HOME;
+  if (realHome && fs.existsSync(realHome)) env.HOME = realHome;
+  delete env.WALL_E_DATA_DIR;
+  delete env.WALLE_NOTIFICATIONS;
+  return env;
+}
+
+// Minimal CDP-over-pipe client. Chrome 86+ supports --remote-debugging-pipe
+// which exposes the DevTools Protocol on FD 3 (browser→client) and FD 4
+// (client→browser) with null-byte-delimited JSON messages. Lets us drive
+// Page.captureScreenshot({ captureBeyondViewport: true }) for true full-
+// page captures without depending on puppeteer/playwright/ws.
+function _openCdpPipe(chromePath, extraArgs = []) {
+  const { spawn } = require('node:child_process');
+  const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'walle-chrome-cdp-'));
+  const args = [
+    '--headless=new',
+    '--disable-gpu',
+    '--no-sandbox',
+    '--hide-scrollbars',
+    `--user-data-dir=${userDataDir}`,
+    '--remote-debugging-pipe',
+    ...extraArgs,
+    'about:blank',
+  ];
+  // stdio: stdin, stdout, stderr, FD3 (browser→client), FD4 (client→browser).
+  // Node treats every entry as a pipe when set to 'pipe'.
+  const proc = spawn(chromePath, args, { stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'], env: hostAutomationEnv() });
+  // CDP-over-pipe wire format: Chrome's FD 3 is its READ side (we write commands
+  // there), FD 4 is its WRITE side (we read events/responses there). On the
+  // Node side, proc.stdio[N] is the OTHER end — so stdio[3] is our writable
+  // and stdio[4] is our readable. Flipping these silently hangs every call.
+  const send = proc.stdio[3];
+  const recv = proc.stdio[4];
+  let msgId = 0;
+  const pending = new Map();
+  const events = new Map(); // method -> handler
+  let buffer = Buffer.alloc(0);
+
+  const rejectPending = (err) => {
+    for (const { reject } of pending.values()) reject(err);
+    pending.clear();
+  };
+
+  recv.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    let nul;
+    while ((nul = buffer.indexOf(0)) !== -1) {
+      const frame = buffer.subarray(0, nul).toString('utf8');
+      buffer = buffer.subarray(nul + 1);
+      if (!frame) continue;
+      let msg;
+      try { msg = JSON.parse(frame); } catch { continue; }
+      if (msg.id != null && pending.has(msg.id)) {
+        const { resolve, reject } = pending.get(msg.id);
+        pending.delete(msg.id);
+        if (msg.error) reject(new Error(`CDP ${msg.error.code || ''}: ${msg.error.message || JSON.stringify(msg.error)}`));
+        else resolve(msg.result);
+      } else if (msg.method && events.has(msg.method)) {
+        // Event handlers receive (params, sessionId) so callers can filter
+        // by attached page session vs. browser-level events.
+        events.get(msg.method)(msg.params || {}, msg.sessionId);
+      }
+    }
+  });
+
+  // CDP-over-pipe lands on the Browser target. To send Page.*, Runtime.*,
+  // Emulation.* etc, attach to a page target via Target.attachToTarget
+  // with flatten:true, then pass sessionId on every subsequent message.
+  const call = (method, params = {}, sessionId, timeoutMs = 15000) => new Promise((resolve, reject) => {
+    const id = ++msgId;
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`CDP ${method} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    pending.set(id, {
+      resolve: (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      reject: (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    });
+    const frame = sessionId
+      ? { id, method, params, sessionId }
+      : { id, method, params };
+    try {
+      send.write(JSON.stringify(frame) + '\0');
+    } catch (err) {
+      clearTimeout(timer);
+      pending.delete(id);
+      reject(err);
+    }
+  });
+  const on = (method, handler) => { events.set(method, handler); };
+  const close = () => {
+    try { proc.kill('SIGTERM'); } catch {}
+    setTimeout(() => { try { proc.kill('SIGKILL'); } catch {} }, 1500).unref();
+    try { fs.rmSync(userDataDir, { recursive: true, force: true }); } catch {}
+  };
+
+  // Surface spawn failures (e.g. Chrome binary missing) as a usable error.
+  const readyOrError = new Promise((resolve, reject) => {
+    let resolved = false;
+    proc.on('error', (err) => { if (!resolved) { resolved = true; reject(err); } });
+    // The pipe is open immediately; resolve on next tick so callers can wire up handlers first.
+    setImmediate(() => { if (!resolved) { resolved = true; resolve(); } });
+  });
+  proc.once('error', (err) => rejectPending(err));
+  proc.once('exit', (code, signal) => {
+    rejectPending(new Error(`Chrome exited before completing CDP call: ${code ?? signal}`));
+  });
+
+  return { proc, call, on, close, ready: readyOrError };
+}
+
+async function _fullPageScreenshotViaCdp({ chrome, url, outPath, width, height, settleMs = 2000, timeoutMs = 45000 }) {
+  const cdp = _openCdpPipe(chrome);
+  let timeoutHandle;
+  try {
+    await Promise.race([
+      cdp.ready,
+      new Promise((_, reject) => { timeoutHandle = setTimeout(() => reject(new Error('Chrome CDP startup timed out')), 10000); }),
+    ]);
+    clearTimeout(timeoutHandle);
+
+    // Browser-target call: find the about:blank page and attach to it.
+    // Without an attached page session, Page.*/Runtime.*/Emulation.* are
+    // not routable and Chrome returns "method not found".
+    const { targetInfos } = await cdp.call('Target.getTargets');
+    const pageTarget = (targetInfos || []).find((t) => t.type === 'page');
+    if (!pageTarget) throw new Error('No page target found in headless Chrome');
+    const { sessionId } = await cdp.call('Target.attachToTarget', {
+      targetId: pageTarget.targetId,
+      flatten: true,
+    });
+    if (!sessionId) throw new Error('Target.attachToTarget returned no sessionId');
+
+    // Filter Page.loadEventFired to this session only — other (background)
+    // targets can fire the same event under flattened sessions.
+    const loaded = new Promise((resolve) => {
+      cdp.on('Page.loadEventFired', (_params, sid) => { if (sid === sessionId) resolve(); });
+    });
+    await cdp.call('Page.enable', {}, sessionId);
+    // Emulation lets us simulate the right device pixel + viewport even
+    // when capturing beyond it — important so responsive CSS picks the
+    // right breakpoint.
+    await cdp.call('Emulation.setDeviceMetricsOverride', {
+      width,
+      height,
+      deviceScaleFactor: 1,
+      mobile: false,
+    }, sessionId);
+    await cdp.call('Page.navigate', { url }, sessionId);
+    // Cap how long we wait for `load`; static file:// pages usually fire
+    // immediately, but a remote URL can stall. After that, give JS a beat
+    // to lay out fonts/images before capturing.
+    await Promise.race([
+      loaded,
+      new Promise((resolve) => setTimeout(resolve, Math.max(2000, Math.min(timeoutMs - 5000, 15000)))),
+    ]);
+    await new Promise((resolve) => setTimeout(resolve, settleMs));
+
+    const result = await cdp.call('Page.captureScreenshot', {
+      format: 'png',
+      captureBeyondViewport: true,
+      fromSurface: true,
+    }, sessionId);
+    if (!result?.data) throw new Error('Page.captureScreenshot returned no data');
+    fs.writeFileSync(outPath, Buffer.from(result.data, 'base64'));
+    return outPath;
+  } finally {
+    clearTimeout(timeoutHandle);
+    cdp.close();
+  }
+}
+
+async function _navigateCdpPage({
+  cdp,
+  sessionId,
+  url,
+  width,
+  height,
+  timeoutMs = 45000,
+  settleMs = 750,
+  eventSink,
+}) {
+  const loaded = new Promise((resolve) => {
+    cdp.on('Page.loadEventFired', (_params, sid) => { if (sid === sessionId) resolve({ ok: true }); });
+  });
+  if (eventSink) {
+    cdp.on('Runtime.exceptionThrown', (params, sid) => {
+      if (sid !== sessionId) return;
+      const details = params.exceptionDetails || {};
+      eventSink.runtimeExceptions.push({
+        text: details.text || '',
+        url: details.url || '',
+        lineNumber: details.lineNumber ?? null,
+        columnNumber: details.columnNumber ?? null,
+        exception: details.exception?.description || details.exception?.value || '',
+      });
+    });
+    cdp.on('Runtime.consoleAPICalled', (params, sid) => {
+      if (sid !== sessionId) return;
+      if (!['error', 'assert'].includes(params.type)) return;
+      eventSink.consoleErrors.push({
+        type: params.type,
+        args: (params.args || []).map((arg) => arg.value ?? arg.description ?? '').join(' ').slice(0, 1000),
+      });
+    });
+    cdp.on('Network.loadingFailed', (params, sid) => {
+      if (sid !== sessionId) return;
+      eventSink.failedRequests.push({
+        requestId: params.requestId,
+        type: params.type,
+        errorText: params.errorText || '',
+        canceled: Boolean(params.canceled),
+      });
+    });
+  }
+
+  await cdp.call('Page.enable', {}, sessionId);
+  await cdp.call('Runtime.enable', {}, sessionId);
+  await cdp.call('Network.enable', {}, sessionId);
+  await cdp.call('Emulation.setDeviceMetricsOverride', {
+    width,
+    height,
+    deviceScaleFactor: 1,
+    mobile: width <= 480,
+  }, sessionId);
+  await cdp.call('Page.navigate', { url }, sessionId);
+  await Promise.race([
+    loaded,
+    new Promise((resolve) => setTimeout(resolve, Math.max(2000, Math.min(timeoutMs - 5000, 15000)))),
+  ]);
+  await new Promise((resolve) => setTimeout(resolve, settleMs));
+}
+
+async function browserSmokeTest({
+  url,
+  viewport = 'desktop',
+  click_selectors,
+  max_clicks = 20,
+  settle_ms = 750,
+  timeout_ms = 45000,
+} = {}) {
   if (!url || typeof url !== 'string') {
     return { ok: false, error: 'url is required (string)' };
   }
   const vp = BROWSER_VIEWPORTS[viewport] || BROWSER_VIEWPORTS.desktop;
-  const outPath = output_path || path.join(os.tmpdir(), `walle-shot-${viewport}-${Date.now()}.png`);
   const chrome = findChromeExecutable();
   if (!chrome) {
     return {
@@ -1988,6 +2263,179 @@ async function browserScreenshot({ url, output_path, viewport = 'desktop' } = {}
     };
   }
 
+  const cdp = _openCdpPipe(chrome);
+  let timeoutHandle;
+  const events = { runtimeExceptions: [], consoleErrors: [], failedRequests: [] };
+  try {
+    await Promise.race([
+      cdp.ready,
+      new Promise((_, reject) => { timeoutHandle = setTimeout(() => reject(new Error('Chrome CDP startup timed out')), 10000); }),
+    ]);
+    clearTimeout(timeoutHandle);
+
+    const { targetInfos } = await cdp.call('Target.getTargets');
+    const pageTarget = (targetInfos || []).find((t) => t.type === 'page');
+    if (!pageTarget) throw new Error('No page target found in headless Chrome');
+    const { sessionId } = await cdp.call('Target.attachToTarget', {
+      targetId: pageTarget.targetId,
+      flatten: true,
+    });
+    if (!sessionId) throw new Error('Target.attachToTarget returned no sessionId');
+
+    await _navigateCdpPage({
+      cdp,
+      sessionId,
+      url,
+      width: vp.width,
+      height: vp.height,
+      timeoutMs: timeout_ms,
+      settleMs: settle_ms,
+      eventSink: events,
+    });
+
+    const selectors = Array.isArray(click_selectors) && click_selectors.length
+      ? click_selectors
+      : ['[onclick]', 'button', '[role="button"]', 'a[href^="#"]'];
+    const clickResult = await cdp.call('Runtime.evaluate', {
+      awaitPromise: true,
+      returnByValue: true,
+      expression: `(() => {
+        const selectors = ${JSON.stringify(selectors)};
+        const maxClicks = ${Math.max(0, Math.min(100, Number(max_clicks) || 20))};
+        const seen = new Set();
+        const failures = [];
+        const clicked = [];
+        const describe = (el) => (el.getAttribute('aria-label') || el.textContent || el.id || el.className || el.tagName || '').toString().replace(/\\s+/g, ' ').trim().slice(0, 120);
+        const elements = [];
+        for (const selector of selectors) {
+          for (const el of Array.from(document.querySelectorAll(selector))) {
+            if (seen.has(el)) continue;
+            seen.add(el);
+            if (elements.length >= maxClicks) break;
+            elements.push({ el, selector });
+          }
+          if (elements.length >= maxClicks) break;
+        }
+        for (const { el, selector } of elements) {
+          if (el.disabled || el.getAttribute('aria-disabled') === 'true') continue;
+          try {
+            el.scrollIntoView({ block: 'center', inline: 'center' });
+            el.click();
+            clicked.push({ selector, label: describe(el) });
+          } catch (err) {
+            failures.push({ selector, label: describe(el), error: String(err && (err.message || err)) });
+          }
+        }
+        return {
+          readyState: document.readyState,
+          title: document.title || '',
+          bodyTextLength: document.body ? document.body.innerText.length : 0,
+          clicked,
+          failures,
+        };
+      })()`,
+    }, sessionId);
+    await new Promise((resolve) => setTimeout(resolve, Math.min(1000, Math.max(100, settle_ms))));
+
+    const value = clickResult?.result?.value || {};
+    const failures = [];
+    for (const item of events.runtimeExceptions) failures.push({ type: 'runtime_exception', ...item });
+    for (const item of events.consoleErrors) failures.push({ type: 'console_error', ...item });
+    for (const item of value.failures || []) failures.push({ type: 'click_failure', ...item });
+    const significantFailedRequests = events.failedRequests.filter((item) => !item.canceled);
+    for (const item of significantFailedRequests) failures.push({ type: 'network_failure', ...item });
+
+    return {
+      ok: failures.length === 0,
+      url,
+      viewport,
+      width: vp.width,
+      height: vp.height,
+      chrome,
+      readyState: value.readyState || '',
+      title: value.title || '',
+      bodyTextLength: value.bodyTextLength || 0,
+      clicked: value.clicked || [],
+      runtimeExceptions: events.runtimeExceptions,
+      consoleErrors: events.consoleErrors,
+      failedRequests: significantFailedRequests,
+      failures,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Chrome CDP browser smoke test failed: ${err.message}`,
+      url,
+      viewport,
+      chrome,
+    };
+  } finally {
+    clearTimeout(timeoutHandle);
+    cdp.close();
+  }
+}
+
+async function browserScreenshot({ url, output_path, viewport = 'desktop', full_page = false } = {}) {
+  if (!url || typeof url !== 'string') {
+    return { ok: false, error: 'url is required (string)' };
+  }
+  const vp = BROWSER_VIEWPORTS[viewport] || BROWSER_VIEWPORTS.desktop;
+  const outPath = expandUserPath(output_path) || path.join(os.tmpdir(), `walle-shot-${viewport}${full_page ? '-fullpage' : ''}-${Date.now()}.png`);
+  const chrome = findChromeExecutable();
+  if (!chrome) {
+    return {
+      ok: false,
+      error: 'No Chromium-based browser found at standard /Applications paths. Install Chrome, Chromium, Edge, or Brave; or set WALLE_CHROME_PATH.',
+      url,
+      viewport,
+    };
+  }
+
+  // Full-page path: drive Chrome via CDP and use captureBeyondViewport so
+  // content below the fold is included. Slower (~3-5s) but captures the
+  // entire scrollable page in a single PNG — the only reliable way to
+  // self-critique galleries, footers, etc. that sit below the viewport.
+  if (full_page) {
+    try {
+      await _fullPageScreenshotViaCdp({
+        chrome,
+        url,
+        outPath,
+        width: vp.width,
+        height: vp.height,
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Chrome CDP full-page capture failed: ${err.message}`,
+        url,
+        viewport,
+        chrome,
+      };
+    }
+    const exists = fs.existsSync(outPath);
+    const size = exists ? fs.statSync(outPath).size : 0;
+    return {
+      ok: exists && size > 0,
+      path: outPath,
+      exists,
+      size,
+      viewport,
+      width: vp.width,
+      height: vp.height, // viewport height; actual PNG can be taller
+      full_page: true,
+      url,
+      chrome,
+      artifact: exists && size > 0 ? {
+        kind: 'screenshot',
+        path: outPath,
+        mimeType: 'image/png',
+        bytes: size,
+        metadata: { viewport, width: vp.width, height: vp.height, full_page: true, url },
+      } : null,
+    };
+  }
+
   const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'walle-chrome-'));
   const args = [
     '--headless=new',
@@ -2002,11 +2450,12 @@ async function browserScreenshot({ url, output_path, viewport = 'desktop' } = {}
   ];
 
   try {
-    await execFileAsync(chrome, args, { timeout: 30000, maxBuffer: 4 * 1024 * 1024 });
+    await execFileAsync(chrome, args, { timeout: 30000, maxBuffer: 4 * 1024 * 1024, env: hostAutomationEnv() });
   } catch (err) {
     return {
       ok: false,
       error: `Chrome headless exited with error: ${err.message}`,
+      stderr: String(err.stderr || '').slice(0, 2000),
       url,
       viewport,
       chrome,
@@ -2027,9 +2476,739 @@ async function browserScreenshot({ url, output_path, viewport = 'desktop' } = {}
     height: vp.height,
     url,
     chrome,
+    artifact: exists && size > 0 ? {
+      kind: 'screenshot',
+      path: outPath,
+      mimeType: 'image/png',
+      bytes: size,
+      metadata: { viewport, width: vp.width, height: vp.height, url },
+    } : null,
+  };
+}
+
+const PDF_MAX_BYTES = 32 * 1024 * 1024;
+const PDF_MAX_PAGE_RANGE = 20;
+
+function fileSha256(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function normalizePdfPath(filePath, projectRoot) {
+  if (!filePath || typeof filePath !== 'string') throw new Error('file_path is required');
+  return resolveToolPath(expandUserPath(filePath), projectRoot);
+}
+
+function validatePdfFile(filePath, { maxBytes = PDF_MAX_BYTES } = {}) {
+  if (!fs.existsSync(filePath)) return { ok: false, error: `PDF not found: ${filePath}` };
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile()) return { ok: false, error: `PDF path is not a file: ${filePath}` };
+  if (stat.size <= 0) return { ok: false, error: 'PDF file is empty', path: filePath, bytes: stat.size };
+  if (stat.size > maxBytes) {
+    return { ok: false, error: `PDF file exceeds size limit (${stat.size} > ${maxBytes} bytes)`, path: filePath, bytes: stat.size };
+  }
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const magic = Buffer.alloc(5);
+    fs.readSync(fd, magic, 0, 5, 0);
+    if (magic.toString('utf8') !== '%PDF-') {
+      return { ok: false, error: 'File does not start with %PDF- magic bytes', path: filePath, bytes: stat.size };
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return { ok: true, path: filePath, bytes: stat.size, sha256: fileSha256(filePath) };
+}
+
+async function pdfInfo({ file_path, max_bytes, projectRoot } = {}) {
+  let resolved;
+  try {
+    resolved = normalizePdfPath(file_path, projectRoot);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  const validation = validatePdfFile(resolved, { maxBytes: Number(max_bytes) || PDF_MAX_BYTES });
+  if (!validation.ok) return validation;
+
+  const base = {
+    ok: true,
+    path: resolved,
+    bytes: validation.bytes,
+    sha256: validation.sha256,
+    mimeType: 'application/pdf',
+    page_count: null,
+    encrypted: null,
+  };
+
+  try {
+    const { stdout } = await execFileAsync('pdfinfo', [resolved], {
+      timeout: 15000,
+      maxBuffer: 512 * 1024,
+    });
+    const pages = stdout.match(/^Pages:\s*(\d+)/mi);
+    const encrypted = stdout.match(/^Encrypted:\s*(yes|no)/mi);
+    return {
+      ...base,
+      page_count: pages ? Number(pages[1]) : null,
+      encrypted: encrypted ? encrypted[1].toLowerCase() === 'yes' : null,
+      raw_info: stdout.trim().slice(0, 8000),
+      artifact: {
+        kind: 'pdf',
+        path: resolved,
+        mimeType: 'application/pdf',
+        bytes: validation.bytes,
+        sha256: validation.sha256,
+        metadata: { page_count: pages ? Number(pages[1]) : null },
+      },
+    };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return {
+        ...base,
+        warnings: ['pdfinfo is unavailable; validated file existence, size, sha256, and %PDF- magic bytes only.'],
+        artifact: {
+          kind: 'pdf',
+          path: resolved,
+          mimeType: 'application/pdf',
+          bytes: validation.bytes,
+          sha256: validation.sha256,
+          metadata: { page_count: null, verification: 'magic-bytes-only' },
+        },
+      };
+    }
+    return {
+      ...base,
+      ok: false,
+      error: `pdfinfo failed: ${String(err.stderr || err.message || err).trim().slice(0, 2000)}`,
+      exitCode: err.code,
+    };
+  }
+}
+
+function parsePdfPageRange(pages, { pageCount = null, defaultRange = '1', maxPages = PDF_MAX_PAGE_RANGE } = {}) {
+  const raw = String(pages || defaultRange || '1').trim();
+  const match = raw.match(/^(\d+)(?:-(\d*)?)?$/);
+  if (!match) return { ok: false, error: `Invalid page range "${raw}". Use "1", "1-3", or "2-".` };
+  const start = Number(match[1]);
+  if (!Number.isInteger(start) || start < 1) return { ok: false, error: 'PDF page range must start at page 1 or later.' };
+  let end;
+  if (!raw.includes('-')) end = start;
+  else if (match[2]) end = Number(match[2]);
+  else end = pageCount ? Number(pageCount) : start + maxPages - 1;
+  if (!Number.isInteger(end) || end < start) return { ok: false, error: `Invalid page range "${raw}". End must be >= start.` };
+  if (pageCount && start > pageCount) return { ok: false, error: `PDF page range starts after the last page (${pageCount}).` };
+  if (pageCount) end = Math.min(end, Number(pageCount));
+  const count = end - start + 1;
+  if (count > maxPages) return { ok: false, error: `PDF page range requests ${count} pages; maximum is ${maxPages}.` };
+  return { ok: true, start, end, count, raw };
+}
+
+function resolvePdfOutputDir(outputDir, projectRoot) {
+  const expanded = expandUserPath(outputDir);
+  const resolved = path.isAbsolute(expanded)
+    ? path.resolve(expanded)
+    : path.resolve(projectRoot || process.cwd(), expanded);
+  const roots = [os.tmpdir(), HOME];
+  if (projectRoot) roots.push(projectRoot);
+  const realResolved = realpathBestEffort(resolved);
+  if (!roots.map(realpathBestEffort).some((root) => isPathWithin(root, realResolved))) {
+    throw new Error(`PDF preview output directory ${resolved} must be under the project, HOME, or the system temp directory`);
+  }
+  return realResolved;
+}
+
+async function pdfRenderPages({ file_path, pages = '1', output_dir, dpi = 144, projectRoot } = {}) {
+  const info = await pdfInfo({ file_path, projectRoot });
+  if (!info.ok) return info;
+  const range = parsePdfPageRange(pages, { pageCount: info.page_count, defaultRange: '1' });
+  if (!range.ok) return { ok: false, error: range.error, path: info.path };
+  const renderDpi = Math.max(72, Math.min(200, Number(dpi) || 144));
+  let outDir;
+  try {
+    outDir = output_dir
+      ? resolvePdfOutputDir(output_dir, projectRoot)
+      : fs.mkdtempSync(path.join(os.tmpdir(), 'walle-pdf-pages-'));
+  } catch (err) {
+    return { ok: false, error: err.message, path: info.path };
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+  const prefix = path.join(outDir, `page-${Date.now()}`);
+  try {
+    await execFileAsync('pdftoppm', [
+      '-jpeg',
+      '-r', String(renderDpi),
+      '-f', String(range.start),
+      '-l', String(range.end),
+      info.path,
+      prefix,
+    ], {
+      timeout: 30000,
+      maxBuffer: 1024 * 1024,
+    });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ok: false, error: 'pdftoppm is unavailable; install poppler to render PDF page previews.', dependency: 'pdftoppm', path: info.path };
+    }
+    return { ok: false, error: `pdftoppm failed: ${String(err.stderr || err.message || err).trim().slice(0, 2000)}`, path: info.path };
+  }
+  const base = path.basename(prefix);
+  const previews = fs.readdirSync(outDir)
+    .filter((name) => name.startsWith(base) && /\.(?:jpg|jpeg)$/i.test(name))
+    .map((name) => path.join(outDir, name))
+    .sort((a, b) => a.localeCompare(b));
+  if (!previews.length) return { ok: false, error: 'pdftoppm completed but produced no preview images.', path: info.path, output_dir: outDir };
+  return {
+    ok: true,
+    path: info.path,
+    output_dir: outDir,
+    pages: { start: range.start, end: range.end, count: range.count },
+    dpi: renderDpi,
+    preview_paths: previews,
+    artifacts: previews.map((previewPath, index) => {
+      const stat = fs.statSync(previewPath);
+      return {
+        kind: 'pdf_page_preview',
+        path: previewPath,
+        mimeType: 'image/jpeg',
+        bytes: stat.size,
+        metadata: {
+          source_pdf: info.path,
+          page: range.start + index,
+          page_count: info.page_count,
+          dpi: renderDpi,
+        },
+      };
+    }),
+  };
+}
+
+async function pdfReadPages({ file_path, pages = '1-5', max_chars = 20000, projectRoot } = {}) {
+  const info = await pdfInfo({ file_path, projectRoot });
+  if (!info.ok) return info;
+  const range = parsePdfPageRange(pages, { pageCount: info.page_count, defaultRange: '1-5' });
+  if (!range.ok) return { ok: false, error: range.error, path: info.path };
+  try {
+    const { stdout } = await execFileAsync('pdftotext', [
+      '-f', String(range.start),
+      '-l', String(range.end),
+      '-layout',
+      info.path,
+      '-',
+    ], {
+      timeout: 30000,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    const maxChars = Math.max(1000, Math.min(Number(max_chars) || 20000, 200000));
+    return {
+      ok: true,
+      path: info.path,
+      page_count: info.page_count,
+      pages: { start: range.start, end: range.end, count: range.count },
+      text: stdout.slice(0, maxChars),
+      truncated: stdout.length > maxChars,
+      artifact: info.artifact || {
+        kind: 'pdf',
+        path: info.path,
+        mimeType: 'application/pdf',
+        bytes: info.bytes,
+        sha256: info.sha256,
+      },
+    };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ok: false, error: 'pdftotext is unavailable; install poppler to extract PDF text.', dependency: 'pdftotext', path: info.path };
+    }
+    return { ok: false, error: `pdftotext failed: ${String(err.stderr || err.message || err).trim().slice(0, 2000)}`, path: info.path };
+  }
+}
+
+function makePdfBinaryCandidates(projectRoot) {
+  const env = process.env;
+  return [
+    env.MAKE_PDF_BIN,
+    projectRoot ? path.join(projectRoot, '.agents/skills/gstack/make-pdf/dist/pdf') : '',
+    path.join(HOME, '.codex/skills/gstack/make-pdf/dist/pdf'),
+    path.join(HOME, '.gstack/repos/gstack/.agents/skills/gstack/make-pdf/dist/pdf'),
+    path.join(HOME, '.gstack/repos/gstack/.agents/skills/gstack-make-pdf/dist/pdf'),
+    env.GSTACK_MAKE_PDF ? path.join(HOME, env.GSTACK_MAKE_PDF, 'pdf') : '',
+  ].filter(Boolean);
+}
+
+function findMakePdfBinary(projectRoot) {
+  return makePdfBinaryCandidates(projectRoot).find((candidate) => {
+    try {
+      return fs.existsSync(candidate) && fs.statSync(candidate).isFile() && (fs.statSync(candidate).mode & 0o111);
+    } catch {
+      return false;
+    }
+  }) || '';
+}
+
+function inferPdfOutputPath(inputPath, outputPath, projectRoot) {
+  if (outputPath) return resolveToolPath(expandUserPath(outputPath), projectRoot);
+  return path.join(path.dirname(inputPath), `${path.basename(inputPath, path.extname(inputPath))}.pdf`);
+}
+
+async function makePdf({
+  input_path,
+  output_path,
+  title,
+  author,
+  date,
+  page_size,
+  margins,
+  cover = false,
+  toc = false,
+  watermark = '',
+  allow_network = false,
+  no_confidential = false,
+  render_preview = true,
+  projectRoot,
+} = {}) {
+  const project = projectRoot || process.cwd();
+  const binary = findMakePdfBinary(project);
+  if (!binary) {
+    return {
+      ok: false,
+      error: 'make-pdf renderer is not available. Build gstack make-pdf or set MAKE_PDF_BIN to the renderer binary.',
+      candidates: makePdfBinaryCandidates(project),
+    };
+  }
+  let inputPath;
+  let outputPath;
+  try {
+    if (!input_path || typeof input_path !== 'string') throw new Error('input_path is required');
+    inputPath = resolveToolPath(expandUserPath(input_path), project);
+    outputPath = inferPdfOutputPath(inputPath, output_path, project);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  if (!fs.existsSync(inputPath) || !fs.statSync(inputPath).isFile()) {
+    return { ok: false, error: `Input file not found: ${inputPath}` };
+  }
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const args = ['generate', '--quiet'];
+  if (cover) args.push('--cover');
+  if (toc) args.push('--toc');
+  if (watermark) args.push('--watermark', String(watermark));
+  if (allow_network) args.push('--allow-network');
+  if (no_confidential) args.push('--no-confidential');
+  if (title) args.push('--title', String(title));
+  if (author) args.push('--author', String(author));
+  if (date) args.push('--date', String(date));
+  if (page_size) args.push('--page-size', String(page_size));
+  if (margins) args.push('--margins', String(margins));
+  args.push(inputPath, outputPath);
+
+  let stdout = '';
+  let stderr = '';
+  try {
+    const result = await execFileAsync(binary, args, {
+      timeout: 120000,
+      maxBuffer: 2 * 1024 * 1024,
+      cwd: project,
+    });
+    stdout = result.stdout || '';
+    stderr = result.stderr || '';
+  } catch (err) {
+    return {
+      ok: false,
+      error: `make-pdf failed: ${String(err.stderr || err.message || err).trim().slice(0, 4000)}`,
+      stdout: String(err.stdout || '').slice(0, 4000),
+      stderr: String(err.stderr || '').slice(0, 4000),
+      exitCode: err.code,
+    };
+  }
+
+  const stdoutPath = stdout.trim().split(/\r?\n/).find((line) => /\.pdf$/i.test(line.trim()));
+  const producedPath = stdoutPath ? resolveToolPath(expandUserPath(stdoutPath.trim()), project) : outputPath;
+  const info = await pdfInfo({ file_path: producedPath, projectRoot: project });
+  if (!info.ok) {
+    return {
+      ok: false,
+      error: `Generated PDF failed validation: ${info.error || 'unknown validation error'}`,
+      path: producedPath,
+      stdout: stdout.trim(),
+      stderr: stderr.trim(),
+    };
+  }
+
+  const artifacts = [info.artifact || {
+    kind: 'pdf',
+    path: producedPath,
+    mimeType: 'application/pdf',
+    bytes: info.bytes,
+    sha256: info.sha256,
+    metadata: { page_count: info.page_count },
+  }];
+  let preview = null;
+  if (render_preview !== false && process.env.WALLE_DISABLE_PDF_PREVIEW !== '1') {
+    preview = await pdfRenderPages({
+      file_path: producedPath,
+      pages: '1',
+      output_dir: path.join(os.tmpdir(), `walle-pdf-preview-${Date.now()}`),
+      projectRoot: project,
+    });
+    if (!preview.ok && preview.dependency !== 'pdftoppm') {
+      return {
+        ok: false,
+        error: `Generated PDF preview validation failed: ${preview.error}`,
+        path: producedPath,
+        pdf: info,
+      };
+    }
+    if (preview.ok && Array.isArray(preview.artifacts)) artifacts.push(...preview.artifacts);
+  }
+
+  return {
+    ok: true,
+    path: producedPath,
+    bytes: info.bytes,
+    sha256: info.sha256,
+    page_count: info.page_count,
+    preview_paths: preview?.ok ? preview.preview_paths : [],
+    preview_warning: preview && !preview.ok ? preview.error : '',
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    artifact: artifacts[0],
+    artifacts,
   };
 }
 
+function checkUrl({ url, timeout_ms = 5000 } = {}) {
+  return new Promise((resolve) => {
+    if (!url || typeof url !== 'string') {
+      resolve({ ok: false, error: 'url is required (string)' });
+      return;
+    }
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (err) {
+      resolve({ ok: false, error: `Invalid URL: ${err.message}`, url });
+      return;
+    }
+    const client = parsed.protocol === 'https:' ? https : parsed.protocol === 'http:' ? http : null;
+    if (!client) {
+      resolve({ ok: false, error: 'Only http:// and https:// URLs are supported', url });
+      return;
+    }
+    const started = Date.now();
+    const req = client.request(parsed, { method: 'GET', timeout: timeout_ms }, (res) => {
+      let bytes = 0;
+      res.on('data', (chunk) => {
+        bytes += chunk.length;
+      });
+      res.on('end', () => {
+        resolve({
+          ok: res.statusCode >= 200 && res.statusCode < 400,
+          status: res.statusCode,
+          bytes,
+          elapsed_ms: Date.now() - started,
+          url,
+          reachability_scope: _localUrlScope(parsed),
+          user_browser_reachability: _localUrlScope(parsed) === 'wall-e-host-loopback' ? 'not_proven' : 'not_checked',
+          note: _localUrlScope(parsed) === 'wall-e-host-loopback'
+            ? 'This proves only that Wall-E host loopback can reach the URL. Phone or remote-browser reachability needs CTM remote/tunnel context.'
+            : undefined,
+        });
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy(new Error(`Timed out after ${timeout_ms}ms`));
+    });
+    req.on('error', (err) => {
+      resolve({
+        ok: false,
+        error: err.message,
+        elapsed_ms: Date.now() - started,
+        url,
+        reachability_scope: _localUrlScope(parsed),
+        user_browser_reachability: _localUrlScope(parsed) === 'wall-e-host-loopback' ? 'not_proven' : 'not_checked',
+      });
+    });
+    req.end();
+  });
+}
+
+function _localUrlScope(parsed) {
+  const hostname = String(parsed?.hostname || '').toLowerCase();
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
+    ? 'wall-e-host-loopback'
+    : 'network';
+}
+
+const STATIC_SERVER_SCRIPT = `
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const root = path.resolve(process.argv[1]);
+const port = Number(process.argv[2] || 0);
+const mime = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+};
+function send(res, status, body) {
+  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+  res.end(body);
+}
+const server = http.createServer((req, res) => {
+  let pathname = '/';
+  try { pathname = decodeURIComponent(new URL(req.url, 'http://localhost').pathname); }
+  catch { return send(res, 400, 'bad request'); }
+  let file = path.normalize(path.join(root, pathname));
+  if (file !== root && !file.startsWith(root + path.sep)) return send(res, 403, 'forbidden');
+  try {
+    const stat = fs.existsSync(file) ? fs.statSync(file) : null;
+    if (stat && stat.isDirectory()) file = path.join(file, 'index.html');
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return send(res, 404, 'not found');
+    res.writeHead(200, { 'content-type': mime[path.extname(file).toLowerCase()] || 'application/octet-stream' });
+    fs.createReadStream(file).pipe(res);
+  } catch (err) {
+    send(res, 500, err.message);
+  }
+});
+server.listen(port, '127.0.0.1', () => {
+  const address = server.address();
+  process.stdout.write(JSON.stringify({ port: address.port }) + '\\n');
+});
+`;
+
+async function startStaticServer({ directory, port = 0, route = '/index.html', timeout_ms = 5000, projectRoot } = {}) {
+  let root;
+  try {
+    root = projectRoot
+      ? resolveToolPath(directory || '.', projectRoot)
+      : path.resolve(expandUserPath(directory || process.cwd()));
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return { ok: false, error: `directory is not a directory: ${root}` };
+  }
+  const stdoutLog = path.join(os.tmpdir(), `walle-static-${Date.now()}-${Math.random().toString(36).slice(2)}.out.log`);
+  const stderrLog = stdoutLog.replace(/\.out\.log$/, '.err.log');
+  fs.writeFileSync(stdoutLog, '');
+  fs.writeFileSync(stderrLog, '');
+
+  const child = require('child_process').spawn(process.execPath, ['-e', STATIC_SERVER_SCRIPT, root, String(port || 0)], {
+    cwd: root,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: false,
+    env: hostAutomationEnv(),
+  });
+  child.stdout.on('data', (chunk) => fs.appendFileSync(stdoutLog, chunk));
+  child.stderr.on('data', (chunk) => fs.appendFileSync(stderrLog, chunk));
+
+  const listenInfo = await new Promise((resolve) => {
+    let buffer = '';
+    const timer = setTimeout(() => resolve({ error: `Static server did not start within ${timeout_ms}ms` }), timeout_ms);
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      const line = buffer.split(/\r?\n/).find(Boolean);
+      if (!line) return;
+      try {
+        clearTimeout(timer);
+        resolve(JSON.parse(line));
+      } catch {}
+    });
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer);
+      resolve({ error: `Static server exited before listening: ${code ?? signal}` });
+    });
+  });
+
+  if (!listenInfo || listenInfo.error || !listenInfo.port) {
+    try { child.kill(); } catch {}
+    return { ok: false, error: listenInfo?.error || 'Static server failed to start', stdout_log: stdoutLog, stderr_log: stderrLog };
+  }
+
+  const resourceId = `static-${child.pid}-${listenInfo.port}`;
+  const url = `http://127.0.0.1:${listenInfo.port}${route && route.startsWith('/') ? route : `/${route || ''}`}`;
+  const health = await checkUrl({ url, timeout_ms: Math.min(timeout_ms, 5000) });
+  STATIC_SERVER_PROCESSES.set(resourceId, { child, root, port: listenInfo.port, url, stdoutLog, stderrLog });
+  if (child.unref) child.unref();
+  return {
+    ok: health.ok,
+    resource_id: resourceId,
+    pid: child.pid,
+    port: listenInfo.port,
+    root,
+    url,
+    health,
+    reachability_scope: 'wall-e-host-loopback',
+    user_browser_reachability: 'not_proven',
+    note: 'Managed static servers bind to 127.0.0.1. This verifies Wall-E host loopback only; phone or remote-browser access needs CTM remote/tunnel context.',
+    stdout_log: stdoutLog,
+    stderr_log: stderrLog,
+  };
+}
+
+async function stopStaticServer({ resource_id } = {}) {
+  const resource = STATIC_SERVER_PROCESSES.get(resource_id);
+  if (!resource) return { ok: false, error: `No static server resource found for ${resource_id || '(missing id)'}` };
+  STATIC_SERVER_PROCESSES.delete(resource_id);
+  try {
+    resource.child.kill();
+  } catch (err) {
+    return { ok: false, error: err.message, resource_id };
+  }
+  return { ok: true, resource_id, pid: resource.child.pid, url: resource.url };
+}
+
+// ── Background shell processes ──
+// Dev servers, watchers, and long builds: run_shell {background:true}
+// detaches the command into a session-scoped registry; the agent polls with
+// bg_output and stops with bg_kill. Non-persistent processes are killed at
+// the end of the run (cleanupBackgroundProcesses).
+
+const BACKGROUND_PROCESSES = new Map(); // resourceId -> record
+const BG_OUTPUT_MAX_BYTES = 512 * 1024;
+
+async function runShellBackground({ command, cwd, sessionId = '', persist = false } = {}) {
+  if (!command || typeof command !== 'string') return { ok: false, error: 'command is required' };
+  const { analyzeShellCommand, initParser } = require('./shell-analyzer');
+  await initParser();
+  const analysis = await analyzeShellCommand(command, cwd || process.cwd());
+  if (!analysis.allowed) return { ok: false, error: analysis.reason };
+
+  const logFile = path.join(os.tmpdir(), `walle-bg-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
+  const logFd = fs.openSync(logFile, 'a');
+  let child;
+  try {
+    child = require('child_process').spawn('/bin/bash', ['-c', command], {
+      cwd: cwd || undefined,
+      env: { ...process.env, HOME },
+      stdio: ['ignore', logFd, logFd],
+      detached: true, // own process group so bg_kill can stop child trees
+    });
+  } catch (err) {
+    fs.closeSync(logFd);
+    return { ok: false, error: err.message };
+  }
+  fs.closeSync(logFd);
+
+  const resourceId = `bg-${child.pid}`;
+  const record = {
+    resourceId,
+    pid: child.pid,
+    command,
+    cwd: cwd || process.cwd(),
+    sessionId,
+    persist: Boolean(persist),
+    logFile,
+    startedAt: Date.now(),
+    exited: false,
+    exitCode: null,
+    exitSignal: null,
+    child,
+  };
+  child.once('exit', (code, signal) => {
+    record.exited = true;
+    record.exitCode = code;
+    record.exitSignal = signal;
+    record.endedAt = Date.now();
+  });
+  child.unref();
+  BACKGROUND_PROCESSES.set(resourceId, record);
+  return {
+    ok: true,
+    background: true,
+    resource_id: resourceId,
+    pid: child.pid,
+    log_file: logFile,
+    note: 'Command is running in the background. Poll with bg_output {resource_id}; stop with bg_kill {resource_id}. Non-persistent background processes are stopped when the run ends.',
+  };
+}
+
+function _bgStatus(record) {
+  if (!record.exited && !_pidIsAlive(record.pid)) {
+    record.exited = true; // exited while we weren't looking (e.g. after restart)
+  }
+  return record.exited ? 'exited' : 'running';
+}
+
+async function bgOutput({ resource_id, tail_lines = 100 } = {}) {
+  const record = BACKGROUND_PROCESSES.get(resource_id);
+  if (!record) return { ok: false, error: `No background process found for ${resource_id || '(missing id)'}` };
+  let output = '';
+  try {
+    const stat = fs.statSync(record.logFile);
+    const start = Math.max(0, stat.size - BG_OUTPUT_MAX_BYTES);
+    const fd = fs.openSync(record.logFile, 'r');
+    try {
+      const buf = Buffer.alloc(stat.size - start);
+      fs.readSync(fd, buf, 0, buf.length, start);
+      output = buf.toString('utf8');
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (err) {
+    output = `(could not read log: ${err.message})`;
+  }
+  const lines = output.split('\n');
+  const maxLines = Math.max(1, Math.min(2000, tail_lines || 100));
+  const tail = lines.slice(-maxLines).join('\n');
+  const status = _bgStatus(record);
+  return {
+    ok: true,
+    resource_id,
+    status,
+    exit_code: record.exitCode,
+    exit_signal: record.exitSignal,
+    uptime_ms: (record.endedAt || Date.now()) - record.startedAt,
+    output: tail,
+    truncated: lines.length > maxLines,
+  };
+}
+
+async function bgKill({ resource_id } = {}) {
+  const record = BACKGROUND_PROCESSES.get(resource_id);
+  if (!record) return { ok: false, error: `No background process found for ${resource_id || '(missing id)'}` };
+  if (_bgStatus(record) === 'exited') {
+    return { ok: true, resource_id, status: 'exited', exit_code: record.exitCode, note: 'Process had already exited.' };
+  }
+  try {
+    process.kill(-record.pid, 'SIGTERM'); // whole process group
+  } catch {
+    try { record.child.kill('SIGTERM'); } catch {}
+  }
+  return { ok: true, resource_id, status: 'terminating', pid: record.pid };
+}
+
+/**
+ * Kill all non-persistent background processes for a session (or all
+ * sessions when sessionId is omitted). Returns what was stopped/leaked so
+ * run summaries can report it.
+ */
+function cleanupBackgroundProcesses({ sessionId = null } = {}) {
+  const stopped = [];
+  const persisted = [];
+  for (const [resourceId, record] of BACKGROUND_PROCESSES) {
+    if (sessionId && record.sessionId !== sessionId) continue;
+    if (record.persist) {
+      if (_bgStatus(record) === 'running') persisted.push({ resource_id: resourceId, pid: record.pid, command: record.command });
+      continue;
+    }
+    if (_bgStatus(record) === 'running') {
+      try {
+        process.kill(-record.pid, 'SIGTERM');
+      } catch {
+        try { record.child.kill('SIGTERM'); } catch {}
+      }
+      stopped.push({ resource_id: resourceId, pid: record.pid, command: record.command });
+    }
+    BACKGROUND_PROCESSES.delete(resourceId);
+  }
+  return { stopped, persisted };
+}
+
 async function clipboardRead() {
   const { stdout } = await execFileAsync('pbpaste', [], { timeout: 5000 });
   return { content: stdout.slice(0, 50000) };
@@ -2937,7 +4116,8 @@ async function webFetch(url, { method = 'GET', extract_text = true, max_bytes =
   args.push(url);
   const { stdout, stderr } = await execFileAsync('curl', args, { timeout: timeout_ms + 2000, maxBuffer: max_bytes * 2 });
   if (stderr && !stdout) throw new Error(stderr.slice(0, 500));
-  let content = stdout.slice(0, max_bytes);
+  const rawContent = stdout.slice(0, max_bytes);
+  let content = rawContent;
   // Strip HTML tags if requested to get readable text
   if (extract_text && content.includes('<')) {
     content = content
@@ -2952,7 +4132,72 @@ async function webFetch(url, { method = 'GET', extract_text = true, max_bytes =
       .trim()
       .slice(0, max_bytes);
   }
-  return { url, content, length: content.length, truncated: stdout.length > max_bytes };
+  const result = { url, content, length: content.length, truncated: stdout.length > max_bytes };
+  if (extract_text && rawContent.includes('<') && content.length <= 40 && /<script[\s>]/i.test(rawContent)) {
+    result.fetch_status = 'needs_browser_rendering';
+    result.warning = 'HTTP fetch succeeded, but extracted text is too small and the page appears to require JavaScript/browser rendering.';
+  }
+  return result;
+}
+
+// ── Web search (DuckDuckGo HTML endpoint — no API key) ──
+
+function parseDuckDuckGoResults(html, maxResults = 8) {
+  const results = [];
+  const linkRe = /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+  const snippetRe = /<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+  const snippets = [];
+  let match;
+  while ((match = snippetRe.exec(html))) snippets.push(stripHtmlText(match[1]));
+  let index = 0;
+  while ((match = linkRe.exec(html)) && results.length < maxResults) {
+    let url = match[1];
+    // DDG wraps targets in a redirect: //duckduckgo.com/l/?uddg=<encoded>
+    const uddg = url.match(/[?&]uddg=([^&]+)/);
+    if (uddg) {
+      try { url = decodeURIComponent(uddg[1]); } catch {}
+    }
+    if (!/^https?:\/\//i.test(url)) { index += 1; continue; }
+    results.push({
+      title: stripHtmlText(match[2]),
+      url,
+      snippet: snippets[index] || '',
+    });
+    index += 1;
+  }
+  return results;
+}
+
+function stripHtmlText(html) {
+  return String(html || '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&#x27;|&#39;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+async function webSearch({ query, max_results = 8, timeout_ms = 15000 } = {}) {
+  if (!query || !String(query).trim()) return { ok: false, error: 'query is required' };
+  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(String(query).trim())}`;
+  const { stdout } = await execFileAsync('curl', [
+    '-sS', '-L', '--max-time', String(Math.round(timeout_ms / 1000)),
+    '-A', 'Mozilla/5.0 (compatible; WALL-E/1.0)',
+    url,
+  ], { timeout: timeout_ms + 2000, maxBuffer: 4 * 1024 * 1024 });
+  const results = parseDuckDuckGoResults(stdout, Math.max(1, Math.min(20, max_results)));
+  return {
+    ok: true,
+    query,
+    results,
+    note: results.length === 0
+      ? 'No results parsed. The query may have no hits, or the search endpoint may have changed.'
+      : 'Use web_fetch on a result URL to read the page.',
+  };
 }
 
 // ── Tool definitions for Claude API ──
@@ -2967,10 +4212,34 @@ const LOCAL_TOOL_DEFINITIONS = [
         command: { type: 'string', description: 'Complete shell command string to run, e.g. `npm test`, `git status --short`, or `cd app && npm run build`. Include any pipes/redirects/heredocs here.' },
         args: { type: 'array', items: { type: 'string' }, description: 'Optional legacy argument array for simple commands only. Do not put `-c` scripts, pipes, redirects, heredocs, `<`, `>`, or `|` here.' },
         timeout_ms: { type: 'number', description: 'Timeout in ms (default 15000)' },
+        background: { type: 'boolean', description: 'Run detached in the background (dev servers, watchers, long builds). Returns a resource_id immediately; poll with bg_output, stop with bg_kill. Never use `&` for backgrounding — use this flag.' },
       },
       required: ['command'],
     },
   },
+  {
+    name: 'bg_output',
+    description: 'Read the latest output of a background process started with run_shell {background:true}. Returns status (running/exited), exit code, and the log tail.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        resource_id: { type: 'string', description: 'resource_id returned by run_shell {background:true}' },
+        tail_lines: { type: 'number', description: 'How many trailing log lines to return (default 100, max 2000)' },
+      },
+      required: ['resource_id'],
+    },
+  },
+  {
+    name: 'bg_kill',
+    description: 'Stop a background process started with run_shell {background:true}.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        resource_id: { type: 'string', description: 'resource_id returned by run_shell {background:true}' },
+      },
+      required: ['resource_id'],
+    },
+  },
   {
     name: 'read_file',
     description: 'Read a local text file. In coding sessions, files must be inside the current project/cwd; relative paths resolve from that project. Prefer this over `run_shell` with cat/head/tail/sed when the path is known. Supports max_bytes for partial reads.',
@@ -3022,17 +4291,132 @@ const LOCAL_TOOL_DEFINITIONS = [
   },
   {
     name: 'browser_screenshot',
-    description: 'Render a URL (http:// or file://) in headless Chrome and capture a PNG at a preset viewport. Use after building UI to self-critique what you actually built before claiming done. Capture both desktop (1440×900) and mobile (390×844) for any responsive UI. Returns { ok, path, viewport, width, height }.',
+    description: 'Render a URL (http:// or file://) in headless Chrome and capture a PNG. Use after building UI to self-critique what you actually built before claiming done. Capture both desktop (1440×900) and mobile (390×844) for any responsive UI. Pass full_page: true to capture EVERYTHING below the fold (galleries, footers, long content) — essential before declaring a multi-section page done. Returns { ok, path, viewport, width, height, full_page? }.',
     input_schema: {
       type: 'object',
       properties: {
         url: { type: 'string', description: 'URL to capture — supports file:// for local files (e.g., file:///path/to/index.html) or http://localhost:port for a dev server.' },
-        viewport: { type: 'string', enum: ['desktop', 'mobile', 'tablet'], description: 'Viewport preset: desktop (1440×900), mobile (390×844), tablet (1024×768). Default: desktop.' },
-        output_path: { type: 'string', description: 'Save path. Default: ~/<tmp>/walle-shot-<viewport>-<timestamp>.png' },
+        viewport: { type: 'string', enum: ['desktop', 'mobile', 'tablet'], description: 'Viewport preset: desktop (1440×900), mobile (390×844), tablet (1024×768). Default: desktop. The viewport drives responsive CSS even when full_page is true.' },
+        output_path: { type: 'string', description: 'Save path. Default: ~/<tmp>/walle-shot-<viewport>[-fullpage]-<timestamp>.png' },
+        full_page: { type: 'boolean', description: 'When true, capture the entire scrollable document — not just the viewport. Slower (~3-5s, drives Chrome via CDP) but the only way to see content below the fold. Default: false.' },
       },
       required: ['url'],
     },
   },
+  {
+    name: 'browser_smoke_test',
+    description: 'Render a URL in headless Chrome through CDP, capture JavaScript runtime exceptions, console errors, failed requests, and safely click interactive elements such as [onclick], buttons, role=button, and hash links. Use this after frontend/UI changes before claiming completion; it catches broken HTML-to-JS handlers that screenshots can miss. Returns { ok, failures, runtimeExceptions, consoleErrors, failedRequests, clicked }.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'URL to validate — supports file:// local HTML files or http://localhost URLs from start_static_server.' },
+        viewport: { type: 'string', enum: ['desktop', 'mobile', 'tablet'], description: 'Viewport preset. Default: desktop.' },
+        click_selectors: { type: 'array', items: { type: 'string' }, description: 'Optional selectors to click. Defaults to [onclick], button, [role=button], and hash links.' },
+        max_clicks: { type: 'number', description: 'Maximum interactive elements to click. Default: 20.' },
+        settle_ms: { type: 'number', description: 'Milliseconds to wait after load/clicks. Default: 750.' },
+        timeout_ms: { type: 'number', description: 'Overall timeout. Default: 45000.' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'check_url',
+    description: 'Fetch an http:// or https:// URL and report whether it returns a 2xx/3xx response. Use this before claiming a local dev/static server is actually reachable. For localhost/127.0.0.1, this verifies Wall-E host loopback only; do not claim phone or remote-browser access without CTM remote/tunnel evidence.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'URL to fetch, for example http://127.0.0.1:9090/index.html.' },
+        timeout_ms: { type: 'number', description: 'Timeout in ms (default 5000).' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'start_static_server',
+    description: 'Start a managed local static file server for a directory, wait for it to answer HTTP 200/3xx from Wall-E host loopback, and return the verified local URL plus a resource_id. Prefer this over run_shell background commands such as `python3 -m http.server &`. Do not present the returned localhost/127.0.0.1 URL as phone or remote-browser reachable unless CTM remote/tunnel evidence confirms it.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        directory: { type: 'string', description: 'Directory to serve. Defaults to current project directory.' },
+        port: { type: 'number', description: 'Port to bind. Use 0 or omit for an available port.' },
+        route: { type: 'string', description: 'Route to health-check after start. Default: /index.html.' },
+        timeout_ms: { type: 'number', description: 'Startup timeout in ms (default 5000).' },
+      },
+    },
+  },
+  {
+    name: 'stop_static_server',
+    description: 'Stop a static server started by start_static_server using its resource_id.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        resource_id: { type: 'string', description: 'resource_id returned by start_static_server.' },
+      },
+      required: ['resource_id'],
+    },
+  },
+  {
+    name: 'pdf_info',
+    description: 'Validate a PDF and return metadata (bytes, sha256, page count when pdfinfo is available). Use before reading or claiming a PDF artifact is valid.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'PDF file path.' },
+        max_bytes: { type: 'number', description: 'Maximum allowed bytes, default 32MB.' },
+      },
+      required: ['file_path'],
+    },
+  },
+  {
+    name: 'pdf_render_pages',
+    description: 'Render a bounded PDF page range to JPEG previews using pdftoppm. Use previews to inspect generated PDFs visually before claiming success.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'PDF file path.' },
+        pages: { type: 'string', description: 'Page range like "1", "1-3", or "2-". Default: "1". Max 20 pages.' },
+        output_dir: { type: 'string', description: 'Preview output directory. Must be under HOME, temp, or the project.' },
+        dpi: { type: 'number', description: 'Render DPI from 72 to 200. Default: 144.' },
+      },
+      required: ['file_path'],
+    },
+  },
+  {
+    name: 'pdf_read_pages',
+    description: 'Extract text from a bounded PDF page range using pdftotext and return metadata. Use for PDF analysis and summaries.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'PDF file path.' },
+        pages: { type: 'string', description: 'Page range like "1", "1-3", or "2-". Default: "1-5". Max 20 pages.' },
+        max_chars: { type: 'number', description: 'Maximum text chars to return, default 20000.' },
+      },
+      required: ['file_path'],
+    },
+  },
+  {
+    name: 'make_pdf',
+    description: 'Generate a PDF from Markdown/HTML through the configured make-pdf renderer, validate the generated file, and optionally render a page preview. Use for PDF creation/export work.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        input_path: { type: 'string', description: 'Markdown or HTML source file.' },
+        output_path: { type: 'string', description: 'Optional PDF output path.' },
+        title: { type: 'string', description: 'Optional title metadata.' },
+        author: { type: 'string', description: 'Optional author metadata.' },
+        date: { type: 'string', description: 'Optional cover/metadata date.' },
+        page_size: { type: 'string', description: 'Optional page size such as letter or a4.' },
+        margins: { type: 'string', description: 'Optional margin value such as 1in.' },
+        cover: { type: 'boolean', description: 'Generate a cover page when supported.' },
+        toc: { type: 'boolean', description: 'Generate a table of contents when supported.' },
+        watermark: { type: 'string', description: 'Optional watermark text.' },
+        allow_network: { type: 'boolean', description: 'Allow external network assets when supported. Default false.' },
+        no_confidential: { type: 'boolean', description: 'Suppress the default confidential footer when supported.' },
+        render_preview: { type: 'boolean', description: 'Render first-page preview after generation. Default true.' },
+      },
+      required: ['input_path'],
+    },
+  },
   {
     name: 'clipboard_read',
     description: 'Read the current system clipboard contents.',
@@ -3307,6 +4691,18 @@ const LOCAL_TOOL_DEFINITIONS = [
       required: ['url'],
     },
   },
+  {
+    name: 'web_search',
+    description: 'Search the public web (DuckDuckGo) and return result titles, URLs, and snippets. Use to discover documentation or error-message references when you do not know the URL; then read the page with web_fetch.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        max_results: { type: 'number', description: 'Max results to return (default 8, max 20)' },
+      },
+      required: ['query'],
+    },
+  },
   {
     name: 'glean_search',
     description: 'Search company documents, wikis, Google Docs, Confluence, Jira, and other connected sources via Glean. Use when the user asks to "search docs", "find a document", "look up X in our wiki", "search Glean", or needs information from internal company knowledge bases.',
@@ -3412,12 +4808,22 @@ async function executeLocalTool(name, input) {
   }
 
   switch (name) {
-    case 'run_shell': return runShell({ command: input.command, args: input.args, timeout_ms: input.timeout_ms, cwd: input.cwd });
+    case 'run_shell': return runShell({ command: input.command, args: input.args, timeout_ms: input.timeout_ms, cwd: input.cwd, background: input.background, sessionId: input.sessionId || input.session_id, persist: input.persist });
+    case 'bg_output': return bgOutput(input);
+    case 'bg_kill': return bgKill(input);
     case 'read_file': return readFile(input.file_path, { max_bytes: input.max_bytes, offset: input.offset, limit: input.limit, sessionId: input.sessionId, projectRoot: input.projectRoot });
     case 'write_file': return writeFile(input.file_path, input.content, { sessionId: input.sessionId, projectRoot: input.projectRoot });
     case 'search_files': return searchFiles(input.query, input);
     case 'screenshot': return takeScreenshot(input);
     case 'browser_screenshot': return browserScreenshot(input);
+    case 'browser_smoke_test': return browserSmokeTest(input);
+    case 'check_url': return checkUrl(input);
+    case 'start_static_server': return startStaticServer(input);
+    case 'stop_static_server': return stopStaticServer(input);
+    case 'pdf_info': return pdfInfo(input);
+    case 'pdf_render_pages': return pdfRenderPages(input);
+    case 'pdf_read_pages': return pdfReadPages(input);
+    case 'make_pdf': return makePdf(input);
     case 'clipboard_read': return clipboardRead();
     case 'clipboard_write': return clipboardWrite(input.text);
     case 'open_url': return openUrl(input.url);
@@ -3439,6 +4845,7 @@ async function executeLocalTool(name, input) {
     case 'drive_read': return driveRead(input);
     case 'system_info': return getSystemInfo();
     case 'web_fetch': return webFetch(input.url, input);
+    case 'web_search': return webSearch(input);
     case 'glean_search': return gleanSearch(input);
     case 'glean_people': return gleanPeople(input);
     case 'glean_chat': return gleanChat(input);
@@ -3918,9 +5325,14 @@ module.exports = {
   executeLocalTool,
   LOCAL_TOOL_DEFINITIONS,
   // Individual exports for testing
-  runShell, readFile, writeFile, searchFiles,
+  runShell, runShellBackground, bgOutput, bgKill, cleanupBackgroundProcesses,
+  webSearch, parseDuckDuckGoResults,
+  readFile, writeFile, searchFiles,
   runAppleScript, sendNotification, takeScreenshot,
-  browserScreenshot, findChromeExecutable, BROWSER_VIEWPORTS, CHROME_CANDIDATES,
+  browserScreenshot, browserSmokeTest, findChromeExecutable, BROWSER_VIEWPORTS, CHROME_CANDIDATES,
+  checkUrl, startStaticServer, stopStaticServer,
+  pdfInfo, pdfRenderPages, pdfReadPages, makePdf,
+  parsePdfPageRange, resolvePdfOutputDir, findMakePdfBinary, makePdfBinaryCandidates,
   clipboardRead, clipboardWrite, openUrl, openApp,
   getCalendarEvents, listCalendars, createCalendarEvent, createReminder,
   getMailMessages, readMailMessage, searchMail, mailAttachments, downloadMailAttachment, sendMail, sendMailReply,