wisp-agents 0.14.0 → 0.16.0

package/server/adapters/opencode.js

@@ -1,8 +1,22 @@
 // opencode adapter — drives `opencode run --format json` (one JSON event per line).
 
-import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { toolsDir } from '../util.js';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
 
-const BIN = process.env.WISP_OPENCODE_BIN || 'opencode';
+const exe = process.platform === 'win32' ? 'opencode.cmd' : 'opencode';
+// Where opencode lives when it isn't on PATH: the copy wisp installs (POST /agents/install),
+// and the official install script's folder (it edits your shell profile, which an app started
+// from the Dock or a service never reads).
+export const fallbackBins = () => [path.join(toolsDir(), 'node_modules', '.bin', exe), path.join(os.homedir(), '.opencode', 'bin', process.platform === 'win32' ? 'opencode.exe' : 'opencode')];
+let BIN = process.env.WISP_OPENCODE_BIN || 'opencode';
+// Rate-limited (the free models, mostly), `opencode run` keeps retrying and prints nothing, so
+// the task would sit at "Starting up" for good. Its error log says so: give it this long to get
+// through, then stop and tell the user what to do.
+const rateLimitGrace = () => Number(process.env.WISP_RATE_LIMIT_GRACE_MS) || 60_000;
+const RATE_LIMITED = /Rate limit exceeded|Too Many Requests|status(?:Code)?[=: ]+429\b/i;
 
 export default {
   id: 'opencode',
@@ -16,7 +30,16 @@ export default {
   },
 
   async detect() {
-    const found = await detectVersion(BIN);
+    let found = await detectVersion(BIN);
+    if (!found.available && !process.env.WISP_OPENCODE_BIN) {
+      for (const bin of fallbackBins().filter((b) => fs.existsSync(b))) {
+        const there = await detectVersion(bin);
+        if (!there.available) continue;
+        BIN = bin;
+        found = there;
+        break;
+      }
+    }
     if (!found.available) return found;
     // `opencode models --verbose` prints each provider/model id followed by its JSON metadata;
     // the metadata's `variants` are the reasoning efforts `run --variant` accepts for that model.
@@ -40,7 +63,8 @@ export default {
 
   run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, mcpServers = {}, delegating = false, onEvent }) {
     // The prompt goes on stdin; `run` appends piped stdin to the (empty) message.
-    const args = ['run', '--format', 'json'];
+    // Errors to stderr: the only place a rate limit shows up (see RATE_LIMITED).
+    const args = ['run', '--format', 'json', '--print-logs', '--log-level', 'ERROR'];
     if (mode === 'plan') args.push('--agent', 'plan');
     if (mode === 'auto') args.push('--auto');
     if (model) args.push('--model', model);
@@ -75,14 +99,22 @@ export default {
     const tokens = { input: 0, output: 0 };
     let cost = 0;
 
-    return spawnJsonl({
+    let limitTimer = null;
+    let limited = false;
+    const proc = spawnJsonl({
       bin: BIN,
       args,
       cwd,
       env,
       input,
       onEvent,
+      onStderr(chunk) {
+        if (limitTimer || limited || !RATE_LIMITED.test(chunk)) return;
+        limitTimer = setTimeout(() => ((limited = true), proc.stop()), rateLimitGrace());
+      },
       onJson(msg) {
+        // Anything coming through means a retry got an answer.
+        if (limitTimer && msg.type !== 'error') (clearTimeout(limitTimer), (limitTimer = null));
         if (msg.sessionID && msg.sessionID !== session) onEvent({ type: 'session', id: (session = msg.sessionID) });
         const part = msg.part || {};
         switch (msg.type) {
@@ -118,19 +150,28 @@ export default {
         }
       },
       onClose({ code, signal, stderr, stopped }) {
+        clearTimeout(limitTimer);
+        if (limited) {
+          const which = model ? `\`${model}\`` : 'opencode’s default model';
+          return onEvent({ type: 'result', isError: true, text: `${which} is rate-limited right now: opencode kept retrying for ${Math.round(rateLimitGrace() / 1000)}s without an answer. Try again in a few minutes, pick another model, or connect your own provider with \`opencode auth login\`.`, stats: { durationMs: Date.now() - started } });
+        }
         const ok = code === 0 && !error;
         onEvent({
           type: 'result',
           isError: !ok,
           stopped,
-          text: ok ? text.join('\n') : error || stderr || `opencode exited with ${signal || `code ${code}`}`,
+          text: ok ? text.join('\n') : error || lastLoggedError(stderr) || exitText('opencode', code, signal),
           stats: { durationMs: Date.now() - started, costUsd: cost || undefined, inputTokens: tokens.input, outputTokens: tokens.output },
         });
       },
     });
+    return proc;
   },
 };
 
+// stderr with --print-logs: the last logged error's message, else stderr as it is.
+const lastLoggedError = (stderr) => [...stderr.matchAll(/error\.error="((?:[^"\\]|\\.)*)"/g)].at(-1)?.[1] || stderr;
+
 function safeJson(s) {
   try {
     return JSON.parse(s) || {};

package/server/checkpoint.js

@@ -1,22 +1,13 @@
-// Per-turn git checkpoints, single-file revert, turn rollback, and action command execution.
+// Per-turn git checkpoints, single-file revert and turn rollback.
 
-import { execFileSync, spawn as nodeSpawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { killTree } from './proc.js';
-import { MAX_SNAPSHOT, rel } from './adapters/common.js';
+import { gitSync } from './git.js';
+import { MAX_SNAPSHOT, rel } from './paths.js';
+import { bad } from './util.js';
 
-const MAX_EXEC_OUTPUT = 32 * 1024;
-const EXEC_TIMEOUT_MS = 60_000;
 
-function git(cwd, args, opts = {}) {
-  return execFileSync('git', args, {
-    cwd,
-    stdio: ['ignore', 'pipe', 'ignore'],
-    timeout: 5000,
-    ...opts,
-  });
-}
+const git = gitSync;
 
 function tryGit(cwd, args, opts) {
   try {
@@ -100,12 +91,12 @@ function writeDiskSnapshot(abs, content) {
 
 function resolveInsideCwd(cwd, file) {
   if (!file || typeof file !== 'string') {
-    throw Object.assign(new Error('file path required'), { status: 400 });
+    throw bad('file path required');
   }
   const abs = path.resolve(cwd, file);
   const relPath = path.relative(cwd, abs);
   if (!relPath || relPath.startsWith('..') || path.isAbsolute(relPath)) {
-    throw Object.assign(new Error(`File lies outside the project folder: ${file}`), { status: 400 });
+    throw bad(`File lies outside the project folder: ${file}`);
   }
   return { abs, relPath: rel(file, cwd) || relPath };
 }
@@ -128,7 +119,7 @@ export function revertFileChange(session, turn, file, { restore = false } = {})
   const entry = findChangeEntry(turn, file, cwd);
   const commit = turn.checkpoint?.commit;
   if (!entry && !commit) {
-    throw Object.assign(new Error(`No captured changes or checkpoint for ${relPath}`), { status: 404 });
+    throw bad(`No captured changes or checkpoint for ${relPath}`, 404);
   }
 
   if (restore) {
@@ -145,7 +136,7 @@ export function revertFileChange(session, turn, file, { restore = false } = {})
         writeDiskSnapshot(abs, cur);
       }
     } else {
-      throw Object.assign(new Error(`Nothing to re-apply for ${relPath}`), { status: 400 });
+      throw bad(`Nothing to re-apply for ${relPath}`);
     }
     if (entry) entry.reverted = false;
     if (turn.changes?.every((c) => !c.reverted)) delete turn.rolledBackAt;
@@ -200,7 +191,7 @@ function reverseEditsOnDisk(abs, entry) {
 export function rollbackToTurn(session, turn, { restore = false } = {}) {
   const cwd = sessionDir(session);
   const idx = session.turns.indexOf(turn);
-  if (idx < 0) throw Object.assign(new Error('No such turn'), { status: 404 });
+  if (idx < 0) throw bad('No such turn', 404);
   const affected = session.turns.slice(idx);
   const touchedFiles = [...new Set(affected.flatMap((t) => (t.changes || []).map((c) => c.file)))];
 
@@ -297,52 +288,5 @@ export function rollbackToTurn(session, turn, { restore = false } = {}) {
   return { files: touchedFiles, rolledBack: true, commit: cp?.head || cp?.commit || null };
 }
 
-// Run a shell command from an actionable presentation block inside `cwd`.
-export function execCommand(cwd, command, { timeoutMs = EXEC_TIMEOUT_MS } = {}) {
-  const cmd = String(command || '').trim();
-  if (!cmd) return Promise.reject(Object.assign(new Error('command required'), { status: 400 }));
-  const t0 = Date.now();
-
-  return new Promise((resolve) => {
-    const child = nodeSpawn(cmd, {
-      cwd,
-      env: { ...process.env, PAGER: 'cat', GIT_TERMINAL_PROMPT: '0', CI: '1' },
-      shell: true,
-      windowsHide: true,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let out = '';
-    const append = (chunk) => {
-      if (out.length < MAX_EXEC_OUTPUT) out += chunk.toString('utf8').slice(0, MAX_EXEC_OUTPUT - out.length);
-    };
-    child.stdout.on('data', append);
-    child.stderr.on('data', append);
-
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      killTree(child);
-    }, timeoutMs);
-
-    child.on('error', (err) => {
-      clearTimeout(timer);
-      resolve({
-        command: cmd,
-        output: (out ? `${out}\n` : '') + err.message,
-        exitCode: 1,
-        durationMs: Date.now() - t0,
-      });
-    });
-
-    child.on('close', (code) => {
-      clearTimeout(timer);
-      const suffix = timedOut ? `\n[timed out after ${Math.round(timeoutMs / 1000)}s]` : '';
-      resolve({
-        command: cmd,
-        output: (out.replace(/\s+$/, '') + suffix).trim(),
-        exitCode: timedOut ? 124 : (code ?? 1),
-        durationMs: Date.now() - t0,
-      });
-    });
-  });
-}
+// Moved to proc.js; kept here for anything that still imports it from checkpoint.
+export { execCommand } from './proc.js';

package/server/client.js

@@ -13,8 +13,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { DEFAULT_PORT } from './util.js';
 
-export const DEFAULT_PORT = 4477;
+export { DEFAULT_PORT };
 const BIN = fileURLToPath(new URL('../bin/wisp.js', import.meta.url));
 const MAX_WAIT_CALL = 280; // seconds per long-poll; fetch gives up on headers after 300s
 
@@ -154,8 +155,9 @@ export class WispClient {
   usage = ({ days } = {}) => this.request('GET', `/usage${days ? `?days=${days}` : ''}`);
 
   // A follow-up. If the agent is blocked on ask_user, this answers it. queue: wait for the
-  // current run instead of interrupting it (default: the user's setting).
-  reply = (id, text, { attachments, queue, mode } = {}) => this.request('POST', `/sessions/${id}/reply`, { text, attachments, queue, mode });
+  // current run instead of interrupting it (default: the user's setting). agent / model / effort:
+  // run it, and the follow-ups after it, on another harness, model or thinking level.
+  reply = (id, text, { attachments, queue, mode, agent, model, effort } = {}) => this.request('POST', `/sessions/${id}/reply`, { text, attachments, queue, mode, agent, model, effort });
 
   // Upload a file (path, Buffer or Uint8Array) to attach to a launch or reply. Returns { id, … }.
   async upload(file, { name, type } = {}) {

package/server/git.js

@@ -3,7 +3,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { execFile } from './proc.js';
+import { bad } from './util.js';
 
 const GIT = () => process.env.WISP_GIT_BIN || 'git';
 const GH = () => process.env.WISP_GH_BIN || 'gh';
@@ -22,6 +24,9 @@ export function run(bin, args, { cwd, timeout = 60_000 } = {}) {
   });
 }
 export const git = (cwd, args, opts) => run(GIT(), args, { cwd, ...opts });
+// Synchronous, for the few places that must not yield (checkpoints taken right before a turn
+// starts, file snapshots while a harness streams). Returns a Buffer; throws on failure.
+export const gitSync = (cwd, args, opts = {}) => execFileSync(GIT(), args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, env: { ...process.env, ...QUIET_ENV }, ...opts });
 export const gh = (cwd, args, opts) => run(GH(), args, { cwd, timeout: 120_000, ...opts });
 const quiet = (p) => p.catch(() => '');
 
@@ -161,13 +166,13 @@ export async function ship(wt, { title, body = '', draft = false, pr }) {
   await ensureWorktree(wt);
   const dir = wt.path;
   if (await quiet(git(dir, ['status', '--porcelain']))) {
-    if (!String(title || '').trim()) throw Object.assign(new Error('A commit message is required.'), { status: 400 });
+    if (!String(title || '').trim()) throw bad('A commit message is required.');
     await git(dir, ['add', '-A']);
     await git(dir, ['commit', '--quiet', '--no-verify', '-m', title.trim(), ...(body.trim() ? ['-m', body.trim()] : [])]);
   }
   const { ahead } = await worktreeStatus(wt);
-  if (!ahead) throw Object.assign(new Error('Nothing to ship: this branch has no changes.'), { status: 400 });
-  if (!wt.remote) throw Object.assign(new Error('This repo has no origin remote to push to.'), { status: 400 });
+  if (!ahead) throw bad('Nothing to ship: this branch has no changes.');
+  if (!wt.remote) throw bad('This repo has no origin remote to push to.');
   await git(dir, ['push', '--quiet', '-u', wt.remote, `HEAD:refs/heads/${wt.branch}`], { timeout: 120_000 });
   if (pr?.state === 'OPEN') return prView(dir, pr.number);
   const url = (await gh(dir, ['pr', 'create', '--base', wt.base, '--head', wt.branch, '--title', title.trim(), '--body', body.trim() || ' ', ...(draft ? ['--draft'] : [])])).split('\n').pop();
@@ -178,7 +183,7 @@ export async function ship(wt, { title, body = '', draft = false, pr }) {
 export async function merge(wt, number) {
   const dir = fs.existsSync(wt.path) ? wt.path : wt.root;
   let pr = await prView(dir, number);
-  if (pr.state !== 'OPEN') throw Object.assign(new Error(`PR #${number} is ${pr.state.toLowerCase()}.`), { status: 400 });
+  if (pr.state !== 'OPEN') throw bad(`PR #${number} is ${pr.state.toLowerCase()}.`);
   if (pr.draft) await gh(dir, ['pr', 'ready', String(number)]);
   await gh(dir, ['pr', 'merge', String(number), '--squash', '--match-head-commit', pr.head]);
   pr = await prView(dir, number);

package/server/handoff.js

@@ -0,0 +1,70 @@
+// Switching harness in a follow-up. Each harness keeps its own conversation (native session id),
+// so a harness picked up mid-task hasn't seen the turns that ran elsewhere. handoffNote() writes
+// those turns out (requests, reports, files touched) and goes ahead of the follow-up's prompt.
+// A harness that ran earlier in the task resumes its own session and only hears what it missed.
+
+import { blocksToMarkdown } from './render.js';
+import { clip, truncate } from './util.js';
+
+const BUDGET = 24_000; // characters of earlier turns, newest kept first
+const PER_TURN = 6_000;
+// The parts of a report worth passing on. Diffs, code and terminal output are on disk or in git.
+const KEEP = new Set(['hero', 'markdown', 'steps', 'stats', 'files', 'tests', 'commits', 'checklist', 'callout', 'question', 'next']);
+
+// The turns before the current one that `agent` hasn't seen: everything after the last turn it
+// ran, or all of them when it has no conversation of its own to resume (resumeId). Only a gap
+// that another harness filled counts: on its own, a harness has nothing to catch up on.
+export function missedTurns(session, agent, resumeId) {
+  const prior = session.turns.slice(0, -1);
+  const missed = resumeId ? prior.slice(prior.findLastIndex((t) => (t.agent || agent) === agent) + 1) : prior;
+  return missed.some((t) => (t.agent || agent) !== agent) ? missed : [];
+}
+
+function turnText(t, n, name) {
+  const blocks = (t.presentation?.blocks || []).filter((b) => KEEP.has(b?.type));
+  const report = t.status === 'running' ? '' : blocksToMarkdown(blocks, t) || clip(t.raw, 1500);
+  const files = (t.changes || []).filter((c) => !c.reverted).map((c) => `\`${c.file}\``);
+  return truncate(
+    [
+      `### Turn ${n} · ${name(t)}${t.model ? ` (${t.model})` : ''}${t.status === 'stopped' ? ' · stopped' : t.status === 'error' ? ' · failed' : ''}${t.rolledBackAt ? ' · rolled back, its edits were undone' : ''}`,
+      `**User:** ${t.prompt}`,
+      report && `**Report:**\n\n${report}`,
+      files.length && `**Files it edited:** ${files.join(', ')}`,
+    ]
+      .filter(Boolean)
+      .join('\n\n'),
+    PER_TURN,
+  );
+}
+
+// The note for `agent` taking the next turn, or '' when it has seen everything.
+// name(turn) → the harness's display name for that turn.
+export function handoffNote(session, agent, resumeId, name) {
+  const missed = missedTurns(session, agent, resumeId);
+  if (!missed.length) return '';
+  const all = session.turns.slice(0, -1);
+  const parts = [];
+  let used = 0;
+  for (let i = missed.length - 1; i >= 0; i--) {
+    const text = turnText(missed[i], all.indexOf(missed[i]) + 1, name);
+    if (used + text.length > BUDGET && parts.length) break;
+    parts.unshift(text);
+    used += text.length;
+  }
+  const dropped = missed.length - parts.length;
+  const fresh = !resumeId;
+  const others = [...new Set(missed.filter((t) => t.agent !== agent).map(name))].join(', ');
+  const intro = fresh
+    ? `You are taking over a task that another coding agent (${others}) has been working on. Its work is already in this folder. Below is what happened so far, oldest first; read the files and \`git diff\` for the details, then carry on with the follow-up.`
+    : `While you were away, this task continued on another coding agent (${others}). Its work is already in this folder. Below is what happened since your last turn, oldest first; check the files and \`git diff\` before you rely on what you remember.`;
+  return [
+    '## Earlier in this task',
+    intro,
+    dropped ? `_${dropped} earlier turn${dropped > 1 ? 's' : ''} left out for length._` : '',
+    ...parts,
+    '---',
+    '## Follow-up',
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}

package/server/http/respond.js

@@ -0,0 +1,59 @@
+// Writing responses and reading request bodies. The API speaks JSON; a few routes stream.
+
+const MAX_BODY = 2e6;
+
+export function send(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+export function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    let tooLarge = false;
+    req.on('data', (c) => {
+      if (tooLarge) return;
+      data += c;
+      if (data.length > MAX_BODY) {
+        // Stop buffering: the rest of the body is dropped, not held in memory.
+        tooLarge = true;
+        data = '';
+        reject(Object.assign(new Error('body too large'), { status: 413 }));
+      }
+    });
+    req.on('end', () => {
+      if (tooLarge) return;
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        reject(Object.assign(new Error('invalid json'), { status: 400 }));
+      }
+    });
+  });
+}
+
+// Pass a machine's raw response (images, markdown, uploads) straight through.
+export function pipeFrom(res, r) {
+  const headers = { 'content-type': r.headers['content-type'] || 'application/octet-stream' };
+  if (r.headers['content-length']) headers['content-length'] = r.headers['content-length'];
+  res.writeHead(r.statusCode, headers);
+  r.pipe(res);
+}
+
+// Server-sent events: every open /api/events stream gets every broadcast.
+export function eventStream() {
+  const clients = new Set();
+  return {
+    clients,
+    attach(req, res) {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      res.write(`event: hello\ndata: {}\n\n`);
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+    },
+    broadcast(event, data) {
+      const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+      for (const res of clients) res.write(frame);
+    },
+  };
+}

package/server/http/router.js

@@ -0,0 +1,64 @@
+// A small route table: `route('PATCH', '/sessions/:id', handler)`. Patterns match whole path
+// segments under /api; `:name` captures one (URI-decoded). Routes are tried in the order they
+// were added, so a fixed segment (`/projects/discover`) goes before a capture (`/projects/:id`).
+//
+// A handler gets one context object and answers through it:
+//   { req, res, url, query, params, body(), send(status, data) }
+// body() reads and parses the JSON request body (once). Options: `doc: false` marks a route that
+// is not part of the public API (left out of openapi.json on purpose); `when(params)` narrows a
+// pattern further (a route whose `when` says no is skipped, as if it didn't match).
+
+import { readJson, send } from './respond.js';
+
+export class Routes {
+  #list = [];
+
+  route(method, pattern, handler, { doc = true, when = null } = {}) {
+    const segs = pattern.split('/').filter(Boolean);
+    for (const m of [method].flat()) this.#list.push({ method: m, pattern, segs, handler, doc, when });
+    return this;
+  }
+
+  // Every route, for the docs check in the tests.
+  list() {
+    return this.#list.map(({ method, pattern, doc }) => ({ method, pattern, doc }));
+  }
+
+  // Handles the request and returns true, or returns false when nothing matched.
+  async handle(req, res, url) {
+    const parts = url.pathname.split('/').filter(Boolean).slice(1); // drop "api"
+    for (const r of this.#list) {
+      if (r.method !== req.method) continue;
+      const params = match(r.segs, parts);
+      if (!params || (r.when && !r.when(params))) continue;
+      let parsed;
+      const ctx = {
+        req,
+        res,
+        url,
+        params,
+        query: url.searchParams,
+        body: () => (parsed ??= readJson(req)),
+        send: (status, data) => send(res, status, data),
+      };
+      await r.handler(ctx);
+      return true;
+    }
+    return false;
+  }
+}
+
+function match(segs, parts) {
+  if (segs.length !== parts.length) return null;
+  const params = {};
+  for (let i = 0; i < segs.length; i++) {
+    if (segs[i].startsWith(':')) {
+      try {
+        params[segs[i].slice(1)] = decodeURIComponent(parts[i]);
+      } catch {
+        return null;
+      }
+    } else if (segs[i] !== parts[i]) return null;
+  }
+  return params;
+}

package/server/http/static.js

@@ -0,0 +1,36 @@
+// The web UI: files under web/, with index.html for every other path (the app routes itself).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const WEB = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'web');
+
+export const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mov': 'video/quicktime',
+  '.pdf': 'application/pdf',
+};
+
+export function serveStatic(res, pathname) {
+  const p = path.normalize(path.join(WEB, pathname === '/' ? 'index.html' : pathname));
+  // Inside web/ only: a sibling folder whose name starts with "web" doesn't count.
+  if (!p.startsWith(WEB + path.sep) || !fs.existsSync(p) || fs.statSync(p).isDirectory()) {
+    // SPA fallback
+    res.writeHead(200, { 'content-type': MIME['.html'] });
+    return fs.createReadStream(path.join(WEB, 'index.html')).pipe(res);
+  }
+  res.writeHead(200, { 'content-type': MIME[path.extname(p)] || 'application/octet-stream', 'cache-control': 'no-cache' });
+  fs.createReadStream(p).pipe(res);
+}