@wrongstack/webui 0.273.0 → 0.274.0

package/dist/server/entry.js

@@ -897,7 +897,7 @@ async function handleApiSessionEvents(res, globalRoot, sessionId, limit) {
     return;
   }
   try {
-    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths2, DefaultSessionStore: DefaultSessionStore4, DefaultSessionReader: DefaultSessionReader2 } = await import("@wrongstack/core");
+    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths2, DefaultSessionStore: DefaultSessionStore3, DefaultSessionReader: DefaultSessionReader2 } = await import("@wrongstack/core");
     const registry = new SessionRegistry(globalRoot);
     const entry = await registry.get(sessionId);
     if (!entry) {
@@ -906,7 +906,7 @@ async function handleApiSessionEvents(res, globalRoot, sessionId, limit) {
       return;
     }
     const paths = resolveWstackPaths2({ projectRoot: entry.projectRoot, globalRoot });
-    const store = new DefaultSessionStore4({ dir: paths.projectSessions });
+    const store = new DefaultSessionStore3({ dir: paths.projectSessions });
     const reader = new DefaultSessionReader2({ store });
     const rawEntries = [];
     for await (const ev of reader.replay(sessionId)) {
@@ -1167,7 +1167,7 @@ function isTrustedLoopbackOrigin(origin) {
   try {
     const url = new URL(origin);
     if (url.protocol !== "http:" && url.protocol !== "https:") return false;
-    return url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
   } catch {
     return false;
   }
@@ -1178,6 +1178,14 @@ function isLoopbackBind(wsHost) {
 function isWildcardBind(wsHost) {
   return wsHost === "0.0.0.0" || wsHost === "::" || wsHost === "[::]";
 }
+function normalizeHostname(hostname) {
+  const h = hostname.trim().toLowerCase();
+  return h.startsWith("[") && h.endsWith("]") ? h.slice(1, -1) : h;
+}
+function allowedHostname(hostname, allowedHostnames) {
+  const normalized = normalizeHostname(hostname);
+  return (allowedHostnames ?? []).some((candidate) => normalizeHostname(candidate) === normalized);
+}
 function tokenMatches(provided, expected) {
   if (!provided) return false;
   const a = Buffer.from(provided);
@@ -1216,28 +1224,37 @@ function hostHeaderOk(input) {
   } catch {
     return false;
   }
-  return isLoopbackHostname(hostname);
+  return isLoopbackHostname(hostname) || allowedHostname(hostname, input.allowedHostnames);
 }
 function verifyClient(input) {
-  const { origin, url, hostHeader, remoteAddress, cookieHeader, wsHost, expectedToken } = input;
+  const {
+    origin,
+    url,
+    hostHeader,
+    remoteAddress,
+    cookieHeader,
+    wsHost,
+    expectedToken,
+    requireToken,
+    allowedHostnames,
+    allowBrowserUrlToken
+  } = input;
   const urlTokenOk = tokenMatches(extractToken(url ?? ""), expectedToken);
   const cookieTokenOk = tokenMatches(extractTokenFromCookie(cookieHeader), expectedToken);
-  if (!hostHeaderOk({ hostHeader, wsHost })) return false;
+  if (!hostHeaderOk({ hostHeader, wsHost, allowedHostnames })) return false;
   if (!origin) {
     const remoteIp = remoteAddress ?? "";
     const isRemoteLoopback = remoteIp === "127.0.0.1" || remoteIp === "::1";
     if (!isRemoteLoopback && isWildcardBind(wsHost)) return false;
-    return urlTokenOk || cookieTokenOk || isLoopbackBind(wsHost);
+    return urlTokenOk || cookieTokenOk || isLoopbackBind(wsHost) && !requireToken;
   }
   try {
-    const { hostname } = new URL(origin);
-    if (isLoopbackHostname(hostname)) {
-      if (isWildcardBind(wsHost) && !isTrustedLoopbackOrigin(origin)) {
-        return false;
-      }
-      return true;
+    const { hostname: originHostname } = new URL(origin);
+    if (isLoopbackHostname(originHostname)) {
+      if (requireToken || !isLoopbackBind(wsHost)) return cookieTokenOk;
+      return isTrustedLoopbackOrigin(origin);
     }
-    return cookieTokenOk;
+    return cookieTokenOk || Boolean(allowBrowserUrlToken) && urlTokenOk && allowedHostname(originHostname, allowedHostnames);
   } catch {
     return false;
   }
@@ -1263,8 +1280,69 @@ function injectWsPort(html, wsPort) {
   return `${tag}
 ${html}`;
 }
-function buildCspHeader(wsPort) {
-  return `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' ws://127.0.0.1:${wsPort} wss://127.0.0.1:${wsPort}; img-src 'self' data:; font-src 'self' data:; worker-src 'self' blob:; object-src 'none'; base-uri 'self'; frame-ancestors 'none'; form-action 'self'`;
+function escapeHtmlAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function injectWsConfig(html, opts) {
+  let out = injectWsPort(html, opts.wsPort);
+  if (!opts.publicWsUrl || out.includes('name="wrongstack-ws-url"')) return out;
+  const tag = `<meta name="wrongstack-ws-url" content="${escapeHtmlAttr(opts.publicWsUrl)}" />`;
+  if (out.includes("</head>")) {
+    return out.replace("</head>", `  ${tag}
+  </head>`);
+  }
+  return `${tag}
+${out}`;
+}
+function firstHeader(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+function wsTokenCookie(token) {
+  return `ws_token=${encodeURIComponent(token)}; HttpOnly; SameSite=Strict; Path=/; Max-Age=3600`;
+}
+function requestToken(req, url) {
+  return url.searchParams.get("token") ?? firstHeader(req.headers["x-ws-token"]) ?? extractTokenFromCookie(req.headers.cookie);
+}
+function requestHostForCsp(hostHeader) {
+  const raw = firstHeader(hostHeader)?.trim();
+  if (!raw) return void 0;
+  try {
+    return new URL(`http://${raw}`).hostname;
+  } catch {
+    return void 0;
+  }
+}
+function formatCspHostname(hostname) {
+  return hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
+}
+function cspSourceFromUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    if (url.protocol !== "ws:" && url.protocol !== "wss:") return void 0;
+    return `${url.protocol}//${formatCspHostname(url.hostname)}${url.port ? `:${url.port}` : ""}`;
+  } catch {
+    return void 0;
+  }
+}
+var ALLOWED_INLINE_SCRIPT_HASHES = [
+  "'sha256-6PXDy0zrpXa6mvYOl11bZ8nubNUL7ushPUhGDZtaexg='",
+  "'sha256-6sIdwbEBx7jj0drqSHHm7MqvmoYD3CQ4lp8Zp8blcb0='"
+];
+function buildCspHeader(wsPort, requestHost, publicWsUrl) {
+  const connect = /* @__PURE__ */ new Set([
+    "'self'",
+    `ws://127.0.0.1:${wsPort}`,
+    `wss://127.0.0.1:${wsPort}`
+  ]);
+  if (requestHost && requestHost !== "127.0.0.1") {
+    const host = formatCspHostname(requestHost);
+    connect.add(`ws://${host}:${wsPort}`);
+    connect.add(`wss://${host}:${wsPort}`);
+  }
+  const publicWsSource = publicWsUrl ? cspSourceFromUrl(publicWsUrl) : void 0;
+  if (publicWsSource) connect.add(publicWsSource);
+  const scriptSrc = ["'self'", ...ALLOWED_INLINE_SCRIPT_HASHES].join(" ");
+  return `default-src 'self'; script-src ${scriptSrc}; style-src 'self' 'unsafe-inline'; connect-src ${Array.from(connect).join(" ")}; img-src 'self' data:; font-src 'self' data:; worker-src 'self' blob:; object-src 'none'; base-uri 'self'; frame-ancestors 'none'; form-action 'self'`;
 }
 function isInsideDist(candidate, distDir) {
   const root = path.resolve(distDir);
@@ -1282,12 +1360,15 @@ function createHttpServer(opts) {
   const port = opts.port ?? Number.parseInt(process.env["PORT"] ?? "3456", 10);
   const distDir = path.resolve(opts.distDir);
   const wsPort = opts.wsPort;
-  const requireApiToken = !isLoopbackBind(opts.host) && Boolean(opts.apiToken);
+  const requireAccessToken = Boolean(opts.requireToken) || !isLoopbackBind(opts.host);
   return http.createServer(async (req, res) => {
     try {
       const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+      const providedAccessToken = requestToken(req, url);
+      const accessTokenOk = Boolean(opts.apiToken) && tokenMatches(providedAccessToken, opts.apiToken ?? "");
+      const shouldSetAuthCookie = Boolean(opts.apiToken) && tokenMatches(url.searchParams.get("token") ?? void 0, opts.apiToken ?? "");
       if (url.pathname === "/ws-auth" && req.method === "GET" && (opts.enableWsCookie ?? true)) {
-        const provided = url.searchParams.get("token") ?? req.headers["x-ws-token"];
+        const provided = requestToken(req, url);
         if (!provided || !opts.apiToken || !tokenMatches(provided, opts.apiToken)) {
           res.writeHead(401, { "Content-Type": "text/plain" });
           res.end("Unauthorized");
@@ -1295,7 +1376,7 @@ function createHttpServer(opts) {
         }
         res.writeHead(200, {
           "Content-Type": "text/plain",
-          "Set-Cookie": `ws_token=${encodeURIComponent(opts.apiToken)}; HttpOnly; SameSite=Strict; Path=/; Max-Age=3600`,
+          "Set-Cookie": wsTokenCookie(opts.apiToken),
           // Belt-and-braces: tell any caches the cookie response itself
           // is sensitive.
           "Cache-Control": "no-store"
@@ -1303,10 +1384,20 @@ function createHttpServer(opts) {
         res.end("ok");
         return;
       }
+      if (requireAccessToken && !accessTokenOk) {
+        res.writeHead(401, {
+          "Content-Type": "text/plain",
+          "Cache-Control": "no-store"
+        });
+        res.end("Unauthorized");
+        return;
+      }
+      if (shouldSetAuthCookie && opts.apiToken) {
+        res.setHeader("Set-Cookie", wsTokenCookie(opts.apiToken));
+        res.setHeader("Cache-Control", "no-store");
+      }
       if (url.pathname === "/api/fleet/ping" && req.method === "POST") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1320,9 +1411,7 @@ function createHttpServer(opts) {
         return;
       }
       if (url.pathname === "/api/sessions" && req.method === "GET") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1332,9 +1421,7 @@ function createHttpServer(opts) {
       }
       const agentsMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/agents$/);
       if (agentsMatch && req.method === "GET") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1344,9 +1431,7 @@ function createHttpServer(opts) {
       }
       const eventsMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/events$/);
       if (eventsMatch && req.method === "GET") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1358,9 +1443,7 @@ function createHttpServer(opts) {
       }
       const msgMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/message$/);
       if (msgMatch && req.method === "POST") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1370,9 +1453,7 @@ function createHttpServer(opts) {
       }
       const mailboxMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/mailbox$/);
       if (mailboxMatch && req.method === "GET") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1382,9 +1463,7 @@ function createHttpServer(opts) {
       }
       const interruptMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/interrupt$/);
       if (interruptMatch && req.method === "POST") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1398,9 +1477,7 @@ function createHttpServer(opts) {
         return;
       }
       if (url.pathname === "/api/fleet/broadcast" && req.method === "POST") {
-        const headerToken = req.headers["x-ws-token"];
-        const provided = Array.isArray(headerToken) ? headerToken[0] : headerToken;
-        if (requireApiToken && !tokenMatches(provided, opts.apiToken ?? "")) {
+        if (requireAccessToken && !accessTokenOk) {
           res.writeHead(401, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
@@ -1447,11 +1524,14 @@ function createHttpServer(opts) {
       res.setHeader("X-Frame-Options", "DENY");
       res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
       if (ext === ".html") {
-        res.setHeader("Cache-Control", "no-cache");
-        res.setHeader("Content-Security-Policy", buildCspHeader(wsPort));
+        if (!shouldSetAuthCookie) res.setHeader("Cache-Control", "no-cache");
+        res.setHeader(
+          "Content-Security-Policy",
+          buildCspHeader(wsPort, requestHostForCsp(req.headers.host), opts.publicWsUrl)
+        );
         const html = await fs.readFile(resolvedPath, "utf8");
         res.writeHead(200);
-        res.end(injectWsPort(html, wsPort));
+        res.end(injectWsConfig(html, { wsPort, publicWsUrl: opts.publicWsUrl }));
         return;
       }
       const fileContent = await fs.readFile(resolvedPath);
@@ -1466,9 +1546,13 @@ function createHttpServer(opts) {
             "X-Content-Type-Options": "nosniff",
             "X-Frame-Options": "DENY",
             "Referrer-Policy": "strict-origin-when-cross-origin",
-            "Content-Security-Policy": buildCspHeader(wsPort)
+            "Content-Security-Policy": buildCspHeader(
+              wsPort,
+              requestHostForCsp(req.headers.host),
+              opts.publicWsUrl
+            )
           });
-          res.end(injectWsPort(html, wsPort));
+          res.end(injectWsConfig(html, { wsPort, publicWsUrl: opts.publicWsUrl }));
         } catch {
           res.writeHead(404);
           res.end("Not found");
@@ -1592,8 +1676,8 @@ function isInside(root, target) {
 }
 
 // src/server/file-handlers.ts
-import * as fs3 from "fs/promises";
-import * as path3 from "path";
+import * as fs4 from "fs/promises";
+import * as path4 from "path";
 import { atomicWrite } from "@wrongstack/core";
 
 // src/server/file-picker.ts
@@ -1644,6 +1728,34 @@ function rankFiles(paths, query, limit) {
   return scored.slice(0, limit).map((s) => s.path);
 }
 
+// src/server/path-containment.ts
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+function isPathInside(root, target) {
+  const relative3 = path3.relative(root, target);
+  return relative3 === "" || !relative3.startsWith("..") && !path3.isAbsolute(relative3);
+}
+async function resolveWorkingDirInsideProject(projectRoot, inputPath) {
+  const resolved = path3.resolve(projectRoot, inputPath);
+  let stat3;
+  try {
+    stat3 = await fs3.stat(resolved);
+  } catch {
+    throw new Error(`Directory not found or not accessible: ${resolved}`);
+  }
+  if (!stat3.isDirectory()) {
+    throw new Error(`Directory not found or not accessible: ${resolved}`);
+  }
+  const [realProjectRoot, realResolved] = await Promise.all([
+    fs3.realpath(projectRoot),
+    fs3.realpath(resolved)
+  ]);
+  if (!isPathInside(realProjectRoot, realResolved)) {
+    throw new Error(`Path must stay inside the project root: ${projectRoot}`);
+  }
+  return resolved;
+}
+
 // src/server/ws-utils.ts
 import { randomBytes } from "crypto";
 import { WebSocket } from "ws";
@@ -1672,25 +1784,106 @@ function errMessage(err) {
 function generateAuthToken() {
   return randomBytes(16).toString("hex");
 }
+function resolveAuthToken(explicit) {
+  const configured = explicit?.trim() || process.env["WEBUI_TOKEN"]?.trim() || process.env["WEBUI_AUTH_TOKEN"]?.trim();
+  return configured || generateAuthToken();
+}
+function hostForBrowserUrl(bindHost) {
+  if (bindHost === "0.0.0.0") return "127.0.0.1";
+  if (bindHost === "::" || bindHost === "[::]") return "[::1]";
+  if (bindHost.includes(":") && !bindHost.startsWith("[")) return `[${bindHost}]`;
+  return bindHost;
+}
+function buildWebUIAccessUrl(opts) {
+  const protocol = opts.protocol ?? "http";
+  const base = opts.publicUrl?.trim() || `${protocol}://${hostForBrowserUrl(opts.host)}:${opts.port}`;
+  if (!opts.token) return base;
+  try {
+    const url = new URL(base);
+    url.searchParams.set("token", opts.token);
+    const rendered = url.toString();
+    const afterOrigin = base.slice(url.origin.length);
+    if (url.pathname === "/" && !afterOrigin.startsWith("/")) {
+      return `${url.origin}${url.search}${url.hash}`;
+    }
+    return rendered;
+  } catch {
+    return `${base}${base.includes("?") ? "&" : "?"}token=${encodeURIComponent(opts.token)}`;
+  }
+}
+function envFlag(name2) {
+  const value = process.env[name2]?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
 
 // src/server/file-handlers.ts
+async function resolveFileInsideProject(projectRoot, filePath) {
+  const resolved = path4.resolve(projectRoot, filePath);
+  if (!isPathInside(projectRoot, resolved)) {
+    throw new Error("Path outside project root");
+  }
+  const { parent, base } = splitParentAndBase(resolved);
+  const realProjectRoot = await fs4.realpath(projectRoot);
+  const realParent = await realpathAllowMissing(parent);
+  const realFull = path4.join(realParent, base);
+  if (!isPathInside(realProjectRoot, realFull)) {
+    throw new Error("Path outside project root");
+  }
+  return realFull;
+}
+function splitParentAndBase(p) {
+  const base = path4.basename(p);
+  const parent = path4.dirname(p);
+  return { parent, base };
+}
+async function realpathAllowMissing(p) {
+  try {
+    return await fs4.realpath(p);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const segments = [];
+  let cursor = p;
+  while (true) {
+    const parent = path4.dirname(cursor);
+    if (parent === cursor) {
+      throw new Error("Path outside project root");
+    }
+    segments.unshift(path4.basename(cursor));
+    try {
+      const realParent = await fs4.realpath(parent);
+      return path4.join(realParent, ...segments);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      cursor = parent;
+    }
+  }
+}
 async function handleFilesTree(ws, msg, projectRoot) {
   const payload = msg.payload;
   const rawPath = payload?.path?.trim();
-  const treeRoot = rawPath && rawPath !== "." ? path3.resolve(projectRoot, rawPath) : projectRoot;
-  if (!treeRoot.startsWith(projectRoot + path3.sep) && treeRoot !== projectRoot) {
+  let treeRoot;
+  let realProjectRoot;
+  try {
+    if (rawPath && rawPath !== ".") {
+      treeRoot = await resolveWorkingDirInsideProject(projectRoot, rawPath);
+    } else {
+      treeRoot = projectRoot;
+    }
+    realProjectRoot = await fs4.realpath(projectRoot);
+  } catch {
     send(ws, {
       type: "files.tree",
       payload: { root: projectRoot, tree: [], error: "Path outside project root" }
     });
     return;
   }
-  const pathPrefix = treeRoot === projectRoot ? "" : (path3.relative(projectRoot, treeRoot) + "/").replace(/\\/g, "/");
+  const pathPrefix = treeRoot === projectRoot ? "" : (path4.relative(projectRoot, treeRoot) + "/").replace(/\\/g, "/");
   async function buildTree(dir, rel, depth) {
     if (depth > 10) return [];
     let entries = [];
     try {
-      entries = await fs3.readdir(dir, { withFileTypes: true });
+      entries = await fs4.readdir(dir, { withFileTypes: true });
     } catch {
       return [];
     }
@@ -1702,11 +1895,20 @@ async function handleFilesTree(ws, msg, projectRoot) {
     for (const e of entries) {
       if (isHiddenEntry(e.name)) continue;
       const childRel = rel ? `${rel}/${e.name}` : e.name;
-      const childAbs = path3.join(dir, e.name);
+      const childAbs = path4.join(dir, e.name);
       const childPath = pathPrefix + childRel;
       if (e.isDirectory()) {
         if (SKIP_DIRS.has(e.name)) continue;
-        const children = await buildTree(childAbs, childRel, depth + 1);
+        let realChild;
+        try {
+          realChild = await fs4.realpath(childAbs);
+        } catch {
+          continue;
+        }
+        if (!isPathInside(realProjectRoot, realChild)) {
+          continue;
+        }
+        const children = await buildTree(realChild, childRel, depth + 1);
         nodes.push({ name: e.name, path: childPath, type: "directory", children });
       } else if (e.isFile()) {
         nodes.push({ name: e.name, path: childPath, type: "file" });
@@ -1716,10 +1918,10 @@ async function handleFilesTree(ws, msg, projectRoot) {
   }
   try {
     const tree = await buildTree(treeRoot, "", 0);
-    const rootLabel = treeRoot === projectRoot ? projectRoot : path3.relative(projectRoot, treeRoot) || ".";
+    const rootLabel = treeRoot === projectRoot ? projectRoot : path4.relative(projectRoot, treeRoot) || ".";
     send(ws, { type: "files.tree", payload: { root: rootLabel, tree } });
   } catch (err) {
-    const rootLabel = treeRoot === projectRoot ? projectRoot : path3.relative(projectRoot, treeRoot) || ".";
+    const rootLabel = treeRoot === projectRoot ? projectRoot : path4.relative(projectRoot, treeRoot) || ".";
     send(ws, {
       type: "files.tree",
       payload: { root: rootLabel, tree: [], error: errMessage(err) }
@@ -1728,13 +1930,15 @@ async function handleFilesTree(ws, msg, projectRoot) {
 }
 async function handleFilesRead(ws, msg, projectRoot) {
   const { filePath } = msg.payload;
-  const resolved = path3.resolve(projectRoot, filePath);
-  if (!resolved.startsWith(projectRoot + path3.sep) && resolved !== projectRoot) {
+  let realResolved;
+  try {
+    realResolved = await resolveFileInsideProject(projectRoot, filePath);
+  } catch {
     send(ws, { type: "files.read", payload: { filePath, content: "", error: "Forbidden" } });
     return;
   }
   try {
-    const content = await fs3.readFile(resolved, "utf8");
+    const content = await fs4.readFile(realResolved, "utf8");
     send(ws, { type: "files.read", payload: { filePath, content } });
   } catch (err) {
     send(ws, {
@@ -1745,16 +1949,18 @@ async function handleFilesRead(ws, msg, projectRoot) {
 }
 async function handleFilesWrite(ws, msg, projectRoot, opts = {}) {
   const { filePath, content } = msg.payload;
-  const resolved = path3.resolve(projectRoot, filePath);
-  if (!resolved.startsWith(projectRoot + path3.sep) && resolved !== projectRoot) {
+  let realResolved;
+  try {
+    realResolved = await resolveFileInsideProject(projectRoot, filePath);
+  } catch {
     send(ws, { type: "files.written", payload: { filePath, success: false, error: "Forbidden" } });
     return;
   }
   try {
-    await atomicWrite(resolved, content);
+    await atomicWrite(realResolved, content);
     send(ws, { type: "files.written", payload: { filePath, success: true } });
     if (opts.onWritten) {
-      void Promise.resolve(opts.onWritten(resolved)).catch(() => void 0);
+      void Promise.resolve(opts.onWritten(realResolved)).catch(() => void 0);
     }
   } catch (err) {
     send(ws, {
@@ -1766,8 +1972,16 @@ async function handleFilesWrite(ws, msg, projectRoot, opts = {}) {
 async function handleFilesList(ws, msg, projectRoot) {
   const payload = msg.payload ?? {};
   const limit = payload.limit ?? 50;
-  const listRoot = payload.path ? path3.resolve(projectRoot, payload.path) : projectRoot;
-  if (!listRoot.startsWith(projectRoot + path3.sep) && listRoot !== projectRoot) {
+  let listRoot;
+  let realProjectRoot;
+  try {
+    if (payload.path) {
+      listRoot = await resolveWorkingDirInsideProject(projectRoot, payload.path);
+    } else {
+      listRoot = projectRoot;
+    }
+    realProjectRoot = await fs4.realpath(projectRoot);
+  } catch {
     send(ws, { type: "files.list", payload: { files: [] } });
     return;
   }
@@ -1776,7 +1990,7 @@ async function handleFilesList(ws, msg, projectRoot) {
     if (depth > 8 || results.length >= 600) return;
     let entries = [];
     try {
-      entries = await fs3.readdir(dir, { withFileTypes: true });
+      entries = await fs4.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -1786,7 +2000,16 @@ async function handleFilesList(ws, msg, projectRoot) {
       const childRel = rel ? `${rel}/${e.name}` : e.name;
       if (e.isDirectory()) {
         if (SKIP_DIRS.has(e.name)) continue;
-        await walk(path3.join(dir, e.name), childRel, depth + 1);
+        let realChild;
+        try {
+          realChild = await fs4.realpath(path4.join(dir, e.name));
+        } catch {
+          continue;
+        }
+        if (!isPathInside(realProjectRoot, realChild)) {
+          continue;
+        }
+        await walk(realChild, childRel, depth + 1);
       } else if (e.isFile()) {
         results.push(childRel);
       }
@@ -1800,7 +2023,7 @@ async function handleFilesList(ws, msg, projectRoot) {
 }
 
 // src/server/completion-handlers.ts
-import * as path4 from "path";
+import * as path5 from "path";
 import { searchCodebaseIndex } from "@wrongstack/tools/codebase-index/index";
 var MAX_PREFIX_CHARS = 12e3;
 var MAX_SUFFIX_CHARS = 4e3;
@@ -1875,8 +2098,8 @@ async function handleCompletionRequest(ws, msg, opts) {
     return;
   }
   const payload = parsed.payload;
-  const projectRoot = path4.resolve(opts.projectRoot);
-  const resolved = path4.resolve(projectRoot, payload.filePath);
+  const projectRoot = path5.resolve(opts.projectRoot);
+  const resolved = path5.resolve(projectRoot, payload.filePath);
   if (!isInside2(projectRoot, resolved)) {
     send(ws, {
       type: "completion.result",
@@ -2275,7 +2498,7 @@ function buildSearchQuery(linePrefix, filePath) {
   if (memberMatch?.[1]) return memberMatch[1];
   const token = linePrefix.match(/([A-Za-z_$][\w$]*)$/)?.[1];
   if (token && token.length >= 2) return token;
-  return path4.basename(filePath, path4.extname(filePath));
+  return path5.basename(filePath, path5.extname(filePath));
 }
 function currentLinePrefix(prefix) {
   const idx = Math.max(prefix.lastIndexOf("\n"), prefix.lastIndexOf("\r"));
@@ -2305,7 +2528,7 @@ function head(value, max) {
   return value.length <= max ? value : value.slice(0, max);
 }
 function isInside2(root, target) {
-  return target === root || target.startsWith(root + path4.sep);
+  return target === root || target.startsWith(root + path5.sep);
 }
 
 // src/server/memory-handlers.ts
@@ -2559,8 +2782,8 @@ async function handleMcpDiscover(ws, msg, globalConfigPath, mcpRegistry) {
 }
 
 // src/server/skills-handlers.ts
-import { promises as fs4 } from "fs";
-import path5 from "path";
+import { promises as fs5 } from "fs";
+import path6 from "path";
 import JSZip from "jszip";
 import { atomicWrite as atomicWrite2 } from "@wrongstack/core";
 import { wstackGlobalRoot } from "@wrongstack/core/utils";
@@ -2631,19 +2854,19 @@ async function handleSkillsContent(ws, ctx, msg) {
       send(ws, { type: "skills.content", payload: { name: name2, body: "", path: "", source, relatedFiles: [], references: [], error: `Skill "${name2}" not found` } });
       return;
     }
-    const body = await fs4.readFile(entry.path, "utf8");
-    const skillDir = path5.dirname(entry.path);
+    const body = await fs5.readFile(entry.path, "utf8");
+    const skillDir = path6.dirname(entry.path);
     let relatedFiles = [];
     try {
-      const files = await fs4.readdir(skillDir);
-      relatedFiles = files.filter((f) => f !== path5.basename(entry.path)).map((f) => path5.join(skillDir, f));
+      const files = await fs5.readdir(skillDir);
+      relatedFiles = files.filter((f) => f !== path6.basename(entry.path)).map((f) => path6.join(skillDir, f));
     } catch {
     }
     const nameLower = name2.toLowerCase();
     const refResults = await Promise.all(
       entries.filter((e) => e.name.toLowerCase() !== nameLower).map(async (e) => {
         try {
-          const content = await fs4.readFile(e.path, "utf8");
+          const content = await fs5.readFile(e.path, "utf8");
           return [e.name, content.toLowerCase().includes(nameLower)];
         } catch {
           return [e.name, false];
@@ -2733,14 +2956,14 @@ async function handleSkillsCreate(ws, ctx, msg) {
   }
   const createPayload = parsed.value;
   try {
-    const targetDir = createPayload.scope === "global" ? path5.join(wstackGlobalRoot(), "skills", createPayload.name.trim()) : path5.join(ctx.projectRoot, ".wrongstack", "skills", createPayload.name.trim());
+    const targetDir = createPayload.scope === "global" ? path6.join(wstackGlobalRoot(), "skills", createPayload.name.trim()) : path6.join(ctx.projectRoot, ".wrongstack", "skills", createPayload.name.trim());
     try {
-      await fs4.access(targetDir);
+      await fs5.access(targetDir);
       send(ws, { type: "skills.created", payload: { success: false, error: `Skill "${createPayload.name}" already exists` } });
       return;
     } catch {
     }
-    await fs4.mkdir(targetDir, { recursive: true });
+    await fs5.mkdir(targetDir, { recursive: true });
     const lines = createPayload.description.trim().split("\n");
     const firstLine = lines[0].trim();
     const bodyLines = lines.slice(1).map((l) => l.trim()).filter(Boolean);
@@ -2788,13 +3011,13 @@ ${trigger}
       "- `bug-hunter` \u2014 for systematic bug detection patterns",
       "- `output-standards` \u2014 for standardized `<next_steps>` formatting"
     ].join("\n");
-    await atomicWrite2(path5.join(targetDir, "SKILL.md"), skillContent);
+    await atomicWrite2(path6.join(targetDir, "SKILL.md"), skillContent);
     send(ws, {
       type: "skills.created",
       payload: {
         success: true,
         error: null,
-        skill: { name: createPayload.name.trim(), path: path5.join(targetDir, "SKILL.md"), scope: createPayload.scope }
+        skill: { name: createPayload.name.trim(), path: path6.join(targetDir, "SKILL.md"), scope: createPayload.scope }
       }
     });
   } catch (err) {
@@ -2858,23 +3081,23 @@ import {
   Agent,
   AutoCompactionMiddleware,
   Context,
-  DefaultMemoryStore as DefaultMemoryStore2,
-  DefaultModeStore as DefaultModeStore2,
+  DefaultMemoryStore,
+  DefaultModeStore,
   DefaultModelsRegistry,
   DefaultSessionReader,
-  DefaultSessionStore as DefaultSessionStore3,
-  DefaultSkillLoader as DefaultSkillLoader2,
-  DefaultSystemPromptBuilder as DefaultSystemPromptBuilder4,
-  DefaultTokenCounter as DefaultTokenCounter2,
+  DefaultSessionStore as DefaultSessionStore2,
+  DefaultSkillLoader,
+  DefaultSystemPromptBuilder as DefaultSystemPromptBuilder3,
+  DefaultTokenCounter,
   AnnotationsStore,
   CollaborationBus,
   collabPauseMiddleware,
   collabInjectMiddleware,
   estimateRequestTokensCalibrated,
   EventBus,
-  createStrategyCompactor as createStrategyCompactor2,
+  createStrategyCompactor,
   ProviderRegistry,
-  TOKENS as TOKENS2,
+  TOKENS,
   ToolRegistry,
   atomicWrite as atomicWrite6,
   createDefaultPipelines,
@@ -2893,110 +3116,10 @@ import {
 import { ToolExecutor } from "@wrongstack/core/execution";
 import { decryptConfigSecrets as decryptConfigSecrets2, encryptConfigSecrets as encryptConfigSecrets2 } from "@wrongstack/core/security";
 import { buildProviderFactoriesFromRegistry, makeProviderFromConfig } from "@wrongstack/providers";
-import { builtinToolsPack, forgetTool, rememberTool, searchMemoryTool, relatedMemoryTool } from "@wrongstack/tools";
+import { builtinToolsPack, configureExecPolicy, ensureSessionShell, forgetTool, rememberTool, searchMemoryTool, relatedMemoryTool } from "@wrongstack/tools";
 import { MCPRegistry } from "@wrongstack/mcp";
 import { WebSocket as WebSocket2, WebSocketServer } from "ws";
-
-// ../runtime/src/container.ts
-import {
-  Container,
-  DefaultConfigStore,
-  DefaultErrorHandler,
-  DefaultMemoryStore,
-  DefaultModeStore,
-  DefaultPermissionPolicy,
-  DefaultRetryPolicy,
-  DefaultSecretScrubber,
-  DefaultSessionStore,
-  DefaultSkillLoader,
-  DefaultSystemPromptBuilder,
-  DefaultTokenCounter,
-  createStrategyCompactor,
-  buildRecoveryStrategies,
-  TOKENS
-} from "@wrongstack/core";
-function createDefaultContainer(opts) {
-  const { config, wpaths, logger, modelsRegistry } = opts;
-  const container = new Container();
-  const configStore = new DefaultConfigStore(config);
-  container.bind(TOKENS.ConfigStore, () => configStore);
-  container.bind(TOKENS.Logger, () => logger);
-  container.bind(TOKENS.SecretScrubber, () => new DefaultSecretScrubber());
-  container.bind(TOKENS.RetryPolicy, () => new DefaultRetryPolicy());
-  container.bind(
-    TOKENS.ErrorHandler,
-    () => new DefaultErrorHandler(
-      buildRecoveryStrategies({
-        compactor: container.resolve(TOKENS.Compactor),
-        modelsRegistry,
-        getConfig: () => configStore.get()
-      })
-    )
-  );
-  container.bind(TOKENS.ModelsRegistry, () => modelsRegistry);
-  container.bind(
-    TOKENS.TokenCounter,
-    () => new DefaultTokenCounter({ registry: modelsRegistry, providerId: config.provider })
-  );
-  const modeStore = new DefaultModeStore({ directory: wpaths.configDir });
-  container.bind(TOKENS.ModeStore, () => modeStore);
-  container.bind(
-    TOKENS.SessionStore,
-    () => new DefaultSessionStore({
-      dir: wpaths.projectSessions,
-      // Scrub secrets out of persisted user/model turns (F-06). Tool output
-      // is already scrubbed by the executor.
-      secretScrubber: container.resolve(TOKENS.SecretScrubber)
-    })
-  );
-  const memoryStore = new DefaultMemoryStore({ paths: wpaths, events: opts.events });
-  container.bind(TOKENS.MemoryStore, () => memoryStore);
-  const skillLoader = new DefaultSkillLoader({ paths: wpaths, bundledDir: opts.bundledSkillsDir });
-  container.bind(TOKENS.SkillLoader, () => skillLoader);
-  if (opts.systemPrompt) {
-    container.bind(
-      TOKENS.SystemPromptBuilder,
-      () => new DefaultSystemPromptBuilder(opts.systemPrompt)
-    );
-  }
-  container.bind(
-    TOKENS.PermissionPolicy,
-    () => {
-      const policyOptions = {
-        trustFile: wpaths.projectTrust,
-        yolo: opts.permission?.yolo ?? false,
-        yoloDestructive: opts.permission?.yoloDestructive ?? opts.permission?.forceAllYolo ?? false,
-        confirmDestructive: opts.permission?.confirmDestructive ?? false
-      };
-      if (opts.permission?.promptDelegate !== void 0) {
-        policyOptions.promptDelegate = opts.permission.promptDelegate;
-      }
-      return new DefaultPermissionPolicy(policyOptions);
-    }
-  );
-  container.bind(
-    TOKENS.Compactor,
-    () => (
-      // Strategy comes from config.context.strategy: 'hybrid' (default, lossless
-      // rules, no LLM), 'intelligent' (LLM summarization), or 'selective'
-      // (LLM-driven selection). The LLM strategies resolve their provider from
-      // ctx at compact()-time, so binding here (before context.provider exists)
-      // is safe. preserveK / eliseThreshold are class-level fallbacks; the active
-      // ContextWindowPolicy in ctx.meta normally overrides both at runtime.
-      // eliseThreshold is a TOKEN COUNT — a previous value of 0.7 elided
-      // essentially every tool_result (anything > 1 token).
-      createStrategyCompactor({
-        strategy: config.context?.strategy,
-        preserveK: opts.compactor?.preserveK ?? 10,
-        eliseThreshold: opts.compactor?.eliseThreshold ?? 2e3,
-        smart: true,
-        summarizerModel: config.context?.summarizerModel,
-        llmSelector: config.context?.llmSelector
-      })
-    )
-  );
-  return container;
-}
+import { createDefaultContainer, makeLightSubagentFactory } from "@wrongstack/runtime";
 
 // src/server/boot.ts
 import {
@@ -3023,6 +3146,13 @@ import {
   PhaseStore,
   WorktreeManager
 } from "@wrongstack/core";
+function deriveTitle(goal) {
+  const firstLine = goal.split("\n").map((l) => l.trim()).find(Boolean);
+  if (!firstLine) return "AutoPhase";
+  const sentence = firstLine.split(/(?<=[.!?])\s/)[0] ?? firstLine;
+  const trimmed = sentence.length <= 64 ? sentence : `${sentence.slice(0, 63).trimEnd()}\u2026`;
+  return trimmed || "AutoPhase";
+}
 function isGitRepo(cwd) {
   try {
     const r = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, encoding: "utf8", windowsHide: true });
@@ -3031,6 +3161,19 @@ function isGitRepo(cwd) {
     return false;
   }
 }
+function commitsSince(cwd, baseSha, branch) {
+  try {
+    const r = spawnSync("git", ["log", "--reverse", "--format=%H", `${baseSha}..${branch}`], {
+      cwd,
+      encoding: "utf8",
+      windowsHide: true
+    });
+    if (r.status !== 0) return [];
+    return r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 var AutoPhaseWebSocketHandler = class {
   constructor(agent, context, logger, storeDir, events, projectRoot) {
     this.agent = agent;
@@ -3050,10 +3193,17 @@ var AutoPhaseWebSocketHandler = class {
   store;
   clients = /* @__PURE__ */ new Set();
   broadcastInterval = null;
-  /** Aborts in-flight task agents when the run is stopped. */
+  /** Aborts in-flight task agents AND the planning turn when the run is stopped. */
   abort = null;
+  /** Set the instant a stop/clear/revert is requested, so a planning turn that
+   *  resolves afterwards never launches the orchestrator (the abort alone can't
+   *  cover the window between the LLM call resolving and the orchestrator start). */
+  stopping = false;
   /** Optional per-phase git-worktree isolation (lazily created at start). */
   worktrees = null;
+  /** Base branch + tip SHA captured at run start so a revert can git-revert the
+   *  run's squash commits (history-preserving) instead of a destructive reset. */
+  runBase = null;
   /** Per-run worker identities so the board can show "who is on what". */
   usedNicknames = /* @__PURE__ */ new Set();
   addClient(ws) {
@@ -3077,11 +3227,13 @@ var AutoPhaseWebSocketHandler = class {
         this.broadcast({ type: "autophase.resumed", payload: {} });
         break;
       case "autophase.stop":
-        this.abort?.abort();
-        this.orchestrator?.stop();
-        this.stopBroadcast();
-        if (this.graph) void this.store.save(this.graph);
-        this.broadcast({ type: "autophase.stopped", payload: {} });
+        await this.handleStop();
+        break;
+      case "autophase.clear":
+        await this.handleClear();
+        break;
+      case "autophase.revert":
+        await this.handleRevert();
         break;
       case "autophase.status":
         this.broadcastState();
@@ -3158,17 +3310,27 @@ var AutoPhaseWebSocketHandler = class {
     }
   }
   async handleStart(payload) {
-    const title = payload?.goal || payload?.title || "Untitled Project";
+    const goal = payload?.goal || payload?.title || "Untitled Project";
+    const title = deriveTitle(goal);
     const autonomous = payload?.autonomous ?? true;
-    const phases = Array.isArray(payload?.phases) ? payload.phases : await this.planPhases(title);
+    this.abort = new AbortController();
+    this.stopping = false;
+    const phases = Array.isArray(payload?.phases) ? payload.phases : await this.planPhases(goal, this.abort.signal);
+    if (this.stopping || this.abort.signal.aborted) {
+      this.broadcast({ type: "autophase.stopped", payload: { title } });
+      return;
+    }
     this.logger.info(`[AutoPhase] Starting: ${title}`);
-    const graph = await new PhaseGraphBuilder({ title, phases, autonomous }).build();
+    const graph = await new PhaseGraphBuilder({ title, description: goal, phases, autonomous }).build();
     this.graph = graph;
-    this.abort = new AbortController();
     await this.store.save(graph);
-    if (!this.worktrees && this.events && this.projectRoot && process.env["WRONGSTACK_AUTOPHASE_WORKTREES"] !== "0" && isGitRepo(this.projectRoot)) {
+    const useWorktrees = payload?.worktrees ?? process.env["WRONGSTACK_AUTOPHASE_WORKTREES"] !== "0";
+    if (!this.worktrees && this.events && this.projectRoot && useWorktrees && isGitRepo(this.projectRoot)) {
       this.worktrees = new WorktreeManager({ projectRoot: this.projectRoot, events: this.events });
     }
+    if (this.worktrees) {
+      this.runBase = await this.worktrees.currentBase();
+    }
     this.orchestrator = new PhaseOrchestrator({
       graph,
       ctx: {
@@ -3215,6 +3377,62 @@ var AutoPhaseWebSocketHandler = class {
       this.broadcast({ type: "autophase.failed", payload: { title, error: String(err) } });
     });
   }
+  /**
+   * Halt the run NOW — at any phase. Sets `stopping` (so a planning turn that
+   * resolves afterwards bails), aborts in-flight agents, stops the orchestrator
+   * tick, and ends the live broadcast. The board is kept for review; use
+   * `autophase.clear` to reset or `autophase.revert` to undo the changes.
+   */
+  async handleStop() {
+    this.stopping = true;
+    this.abort?.abort();
+    this.orchestrator?.stop();
+    this.stopBroadcast();
+    if (this.graph) await this.store.save(this.graph).catch(() => void 0);
+    this.broadcast({ type: "autophase.stopped", payload: { title: this.graph?.title } });
+  }
+  /**
+   * Stop + wipe: tear down phase worktrees and reset to an empty board so the UI
+   * returns to the start screen ("new one"). Does NOT touch already-merged commits
+   * on the base branch — that is `autophase.revert`.
+   */
+  async handleClear() {
+    await this.handleStop();
+    if (this.worktrees) await this.worktrees.cleanupAllManaged().catch(() => void 0);
+    this.orchestrator = null;
+    this.graph = null;
+    this.runBase = null;
+    this.usedNicknames.clear();
+    this.broadcast({ type: "autophase.cleared", payload: {} });
+    this.broadcast({ type: "autophase.state", payload: this.buildState() });
+  }
+  /**
+   * Stop + undo: remove phase worktrees, then history-preservingly `git revert`
+   * every commit this run landed on the base branch (captured `runBase`..HEAD),
+   * then reset to an empty board. Refuses (reports a reason) on a dirty tree or a
+   * conflicting revert rather than leaving the tree half-reverted.
+   */
+  async handleRevert() {
+    await this.handleStop();
+    if (!this.worktrees || !this.runBase || !this.projectRoot) {
+      this.broadcast({
+        type: "autophase.reverted",
+        payload: { ok: false, reverted: 0, reason: "no git baseline was captured for this run" }
+      });
+      return;
+    }
+    await this.worktrees.cleanupAllManaged().catch(() => void 0);
+    const shas = commitsSince(this.projectRoot, this.runBase.sha, this.runBase.branch);
+    const res = await this.worktrees.revertCommits(this.runBase.branch, shas);
+    this.broadcast({ type: "autophase.reverted", payload: res });
+    if (res.ok) {
+      this.orchestrator = null;
+      this.graph = null;
+      this.runBase = null;
+      this.broadcast({ type: "autophase.cleared", payload: {} });
+      this.broadcast({ type: "autophase.state", payload: this.buildState() });
+    }
+  }
   /** Generic fallback phases when the LLM planner produces nothing usable. */
   defaultPhases() {
     return [
@@ -3225,13 +3443,18 @@ var AutoPhaseWebSocketHandler = class {
       { name: "Deployment", description: "Deploy to production", priority: "medium", estimateHours: 2, parallelizable: false }
     ];
   }
-  /** Plan phases+todos for the goal via the LLM; fall back to defaults on failure. */
-  async planPhases(goal) {
+  /** Plan phases+todos for the goal via the LLM; fall back to defaults on failure.
+   *  The caller passes the run's abort signal so a stop during planning cancels
+   *  the LLM turn (the previous fresh, never-aborted controller made planning
+   *  uninterruptible). */
+  async planPhases(goal, signal) {
     try {
       const planner = new AutoPhasePlanner({
         goal,
         runOnce: async (prompt) => {
-          const result = await this.agent.run(prompt, { signal: new AbortController().signal });
+          const result = await this.agent.run(prompt, {
+            signal: signal ?? new AbortController().signal
+          });
           return result.status === "done" ? result.finalText ?? "" : "";
         }
       });
@@ -3357,15 +3580,37 @@ Type: ${task.type}`;
     });
     const taskItems = activePhase ? Array.from(activePhase.taskGraph.nodes.values()).map(mapTask) : [];
     const completedPhases = phases.filter((p) => p.status === "completed").length;
+    const failedPhases = phases.filter((p) => p.status === "failed").length;
+    const failedTasks = phases.reduce(
+      (sum, p) => sum + Array.from(p.taskGraph.nodes.values()).filter((t) => t.status === "failed").length,
+      0
+    );
+    const lastFailed = phases.filter((p) => p.status === "failed").sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))[0];
+    const lastError = lastFailed ? `${lastFailed.name}: ${lastFailed.metadata?.integrationError ?? "phase failed"}` : null;
     return {
       title: this.graph.title,
+      // Full operator prompt, shown verbatim in a dedicated goal block (the
+      // title is only a short derived heading). Fall back to the title for
+      // legacy boards saved before the title/goal split.
+      goal: this.graph.description || this.graph.title,
       phases: phaseItems,
       tasks: taskItems,
       activePhaseId: currentActiveId,
       overallPercent: phases.length > 0 ? Math.round(completedPhases / phases.length * 100) : 0,
       autonomous: this.graph.autonomous,
       totalTasks,
-      completedTasks
+      completedTasks,
+      // Structured progress + lastError consumed by the autophase store (were
+      // defined client-side but never sent, so they stayed null on the board).
+      progress: {
+        totalPhases: phases.length,
+        completed: completedPhases,
+        failed: failedPhases,
+        totalTasks,
+        completedTasks,
+        failedTasks
+      },
+      lastError
     };
   }
   sendState(client) {
@@ -3658,6 +3903,12 @@ var SddBoardWebSocketHandler = class {
 };
 
 // src/server/sdd-wizard-ws-handler.ts
+function deriveTitle2(goal) {
+  const firstLine = goal.split("\n").map((l) => l.trim()).find(Boolean);
+  if (!firstLine) return "New SDD Project";
+  const sentence = firstLine.split(/(?<=[.!?])\s/)[0] ?? firstLine;
+  return sentence.length <= 64 ? sentence : `${sentence.slice(0, 63).trimEnd()}\u2026`;
+}
 var SddWizardWebSocketHandler = class {
   constructor(deps2) {
     this.deps = deps2;
@@ -3696,7 +3947,8 @@ var SddWizardWebSocketHandler = class {
             parallelSlots: msg.payload?.parallelSlots,
             defaultModel: msg.payload?.model,
             defaultProvider: msg.payload?.provider,
-            fallbackModels: Array.isArray(msg.payload?.fallbackModels) ? msg.payload?.fallbackModels : void 0
+            fallbackModels: Array.isArray(msg.payload?.fallbackModels) ? msg.payload?.fallbackModels : void 0,
+            worktrees: typeof msg.payload?.worktrees === "boolean" ? msg.payload.worktrees : void 0
           });
           break;
       }
@@ -3716,7 +3968,7 @@ var SddWizardWebSocketHandler = class {
     }
     if (this.busy) return;
     this.driver = this.deps.makeDriver();
-    const prompt = this.driver.start(goal);
+    const prompt = this.driver.start(deriveTitle2(goal), goal);
     await this.runTurn(prompt);
   }
   async onMessage(text) {
@@ -3787,7 +4039,7 @@ var SddWizardWebSocketHandler = class {
 };
 
 // src/server/sdd-wizard-wiring.ts
-import * as path6 from "path";
+import * as path7 from "path";
 import { spawnSync as spawnSync2 } from "child_process";
 import {
   makeCommandVerifier,
@@ -3801,6 +4053,7 @@ import {
   TaskGraphStore as TaskGraphStore2,
   WorktreeManager as WorktreeManager2
 } from "@wrongstack/core";
+var PLANNING_ONLY_GUARD = "SYSTEM: You are running a PLANNING-ONLY specification interview. Do NOT write, create, or edit any files, and do NOT run shell/terminal commands or use any code-editing tools \u2014 they are disabled here and any attempt will fail and waste the turn. Respond with TEXT ONLY: ask your question, or emit the requested spec / plan / task JSON. All code is written later, automatically, once the plan is approved and the multi-agent run starts.\n\n---\n\n";
 function buildSddWizardDeps(opts) {
   const registry = new SddRunRegistry();
   let isolatedSeq = 0;
@@ -3809,11 +4062,11 @@ function buildSddWizardDeps(opts) {
       id: `sdd-${name2.toLowerCase().replace(/\s+/g, "-")}-${isolatedSeq++}`,
       role: "executor",
       name: name2,
-      disabledTools: ["delegate"],
+      disabledTools: ["delegate", "write", "edit", "patch", "bash", "exec"],
       allowedCapabilities: ["fs.read", "net.outbound"]
     });
     try {
-      const res = await result.agent.run([{ type: "text", text: prompt }]);
+      const res = await result.agent.run([{ type: "text", text: PLANNING_ONLY_GUARD + prompt }]);
       return res.finalText ?? "";
     } finally {
       await result.dispose?.();
@@ -3823,17 +4076,18 @@ function buildSddWizardDeps(opts) {
     makeDriver: () => new SddInterviewDriver({
       specStore: new SpecStore2({ baseDir: opts.paths.projectSpecs }),
       graphStore: new TaskGraphStore2({ baseDir: opts.paths.projectTaskGraphs }),
-      sessionPath: path6.join(opts.paths.projectDir, "sdd-wizard-session.json")
+      sessionPath: path7.join(opts.paths.projectDir, "sdd-wizard-session.json")
     }),
     runInterviewTurn: (prompt) => runIsolatedTurn(prompt, "Spec Architect"),
-    startRun: async (driver, { parallelSlots, defaultModel, defaultProvider, fallbackModels }) => {
+    startRun: async (driver, { parallelSlots, defaultModel, defaultProvider, fallbackModels, worktrees: useWorktrees }) => {
       const graph = driver.getGraph();
       const tracker = driver.getTracker();
       if (!graph || !tracker) {
         throw new Error("No task graph to run \u2014 finish the interview first.");
       }
+      const worktreesEnabled = useWorktrees ?? process.env["WRONGSTACK_SDD_WORKTREES"] !== "0";
       let worktrees;
-      if (process.env["WRONGSTACK_SDD_WORKTREES"] !== "0") {
+      if (worktreesEnabled) {
         const inGit = spawnSync2("git", ["rev-parse", "--is-inside-work-tree"], {
           cwd: opts.projectRoot,
           encoding: "utf8",
@@ -3892,9 +4146,6 @@ async function handleSddWizardRoute(_ws, msg, handlers) {
   return true;
 }
 
-// src/server/index.ts
-import { makeLightSubagentFactory } from "@wrongstack/runtime";
-
 // src/server/collaboration-ws-handler.ts
 import { randomUUID } from "crypto";
 import { toErrorMessage as toErrorMessage2 } from "@wrongstack/core/utils";
@@ -4621,16 +4872,16 @@ var CollaborationWebSocketHandler = class {
 };
 
 // src/server/projects-manifest.ts
-import * as fs5 from "fs/promises";
-import * as path7 from "path";
+import * as fs6 from "fs/promises";
+import * as path8 from "path";
 import { projectSlug } from "@wrongstack/core";
 function projectsJsonPath(globalConfigPath) {
-  const base = path7.dirname(globalConfigPath);
-  return path7.join(base, "projects.json");
+  const base = path8.dirname(globalConfigPath);
+  return path8.join(base, "projects.json");
 }
 async function loadManifest(globalConfigPath) {
   try {
-    const raw = await fs5.readFile(projectsJsonPath(globalConfigPath), "utf8");
+    const raw = await fs6.readFile(projectsJsonPath(globalConfigPath), "utf8");
     const parsed = JSON.parse(raw);
     return { projects: parsed.projects ?? [] };
   } catch {
@@ -4639,16 +4890,16 @@ async function loadManifest(globalConfigPath) {
 }
 async function saveManifest(manifest, globalConfigPath) {
   const file = projectsJsonPath(globalConfigPath);
-  await fs5.mkdir(path7.dirname(file), { recursive: true });
-  await fs5.writeFile(file, JSON.stringify(manifest, null, 2), "utf8");
+  await fs6.mkdir(path8.dirname(file), { recursive: true });
+  await fs6.writeFile(file, JSON.stringify(manifest, null, 2), "utf8");
 }
 function generateProjectSlug(rootPath) {
   return projectSlug(rootPath);
 }
 async function ensureProjectDataDir(slug, globalConfigPath) {
-  const base = path7.dirname(globalConfigPath);
-  const dir = path7.join(base, "projects", slug);
-  await fs5.mkdir(dir, { recursive: true });
+  const base = path8.dirname(globalConfigPath);
+  const dir = path8.join(base, "projects", slug);
+  await fs6.mkdir(dir, { recursive: true });
   return dir;
 }
 
@@ -5074,14 +5325,14 @@ function registerShutdownHandlers(res) {
 
 // src/server/instance-registry.ts
 import * as os from "os";
-import * as path8 from "path";
-import * as fs6 from "fs/promises";
+import * as path9 from "path";
+import * as fs7 from "fs/promises";
 import { atomicWrite as atomicWrite3 } from "@wrongstack/core";
 function defaultBaseDir() {
-  return path8.join(os.homedir(), ".wrongstack");
+  return path9.join(os.homedir(), ".wrongstack");
 }
 function registryPath(baseDir = defaultBaseDir()) {
-  return path8.join(baseDir, "webui-instances.json");
+  return path9.join(baseDir, "webui-instances.json");
 }
 function isPidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -5094,7 +5345,7 @@ function isPidAlive(pid) {
 }
 async function load(file) {
   try {
-    const raw = await fs6.readFile(file, "utf8");
+    const raw = await fs7.readFile(file, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed?.version === 1 && Array.isArray(parsed.instances)) {
       return parsed;
@@ -5239,19 +5490,19 @@ function computeUsageCost(usage, rates) {
 }
 
 // src/server/provider-handlers.ts
-import { DefaultSecretScrubber as DefaultSecretScrubber2 } from "@wrongstack/core";
+import { DefaultSecretScrubber } from "@wrongstack/core";
 import { probeLocalLlm } from "@wrongstack/runtime/probe";
 
 // src/server/provider-config-io.ts
-import * as fs7 from "fs/promises";
-import * as path9 from "path";
+import * as fs8 from "fs/promises";
+import * as path10 from "path";
 import { atomicWrite as atomicWrite4 } from "@wrongstack/core";
 import { decryptConfigSecrets, encryptConfigSecrets } from "@wrongstack/core/security";
 import { DefaultSecretVault } from "@wrongstack/core";
 async function loadSavedProviders(configPath, vault) {
   let raw;
   try {
-    raw = await fs7.readFile(configPath, "utf8");
+    raw = await fs8.readFile(configPath, "utf8");
   } catch {
     return {};
   }
@@ -5268,7 +5519,7 @@ async function saveProviders(configPath, vault, providers) {
   let raw;
   let fileExists = true;
   try {
-    raw = await fs7.readFile(configPath, "utf8");
+    raw = await fs8.readFile(configPath, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") {
       throw new Error(
@@ -5417,7 +5668,7 @@ function projectSavedProviders(providers) {
     return view;
   });
 }
-var probeScrubber = new DefaultSecretScrubber2();
+var probeScrubber = new DefaultSecretScrubber();
 function createProviderHandlers(deps2) {
   const { globalConfigPath, vault, broadcast: broadcast2, clients } = deps2;
   let configWriteLock = deps2.getConfigWriteLock();
@@ -5606,7 +5857,7 @@ function createProviderHandlers(deps2) {
 
 // src/server/mode-handlers.ts
 import {
-  DefaultSystemPromptBuilder as DefaultSystemPromptBuilder2
+  DefaultSystemPromptBuilder
 } from "@wrongstack/core";
 function createModeHandlers(ctx) {
   return {
@@ -5654,7 +5905,7 @@ function createModeHandlers(ctx) {
         }
         ctx.setModeId(id);
         const modePrompt = id === "default" ? "" : (await ctx.modeStore.getMode(id))?.prompt ?? "";
-        const freshBuilder = new DefaultSystemPromptBuilder2({
+        const freshBuilder = new DefaultSystemPromptBuilder({
           memoryStore: ctx.memoryStore,
           skillLoader: ctx.skillLoader,
           modeStore: ctx.modeStore,
@@ -5685,40 +5936,10 @@ function createModeHandlers(ctx) {
 import * as fs9 from "fs/promises";
 import * as path11 from "path";
 import {
-  DefaultSessionStore as DefaultSessionStore2,
-  DefaultSystemPromptBuilder as DefaultSystemPromptBuilder3,
+  DefaultSessionStore,
+  DefaultSystemPromptBuilder as DefaultSystemPromptBuilder2,
   getSessionRegistry
 } from "@wrongstack/core";
-
-// src/server/path-containment.ts
-import * as fs8 from "fs/promises";
-import * as path10 from "path";
-function isPathInside(root, target) {
-  const relative3 = path10.relative(root, target);
-  return relative3 === "" || !relative3.startsWith("..") && !path10.isAbsolute(relative3);
-}
-async function resolveWorkingDirInsideProject(projectRoot, inputPath) {
-  const resolved = path10.resolve(projectRoot, inputPath);
-  let stat3;
-  try {
-    stat3 = await fs8.stat(resolved);
-  } catch {
-    throw new Error(`Directory not found or not accessible: ${resolved}`);
-  }
-  if (!stat3.isDirectory()) {
-    throw new Error(`Directory not found or not accessible: ${resolved}`);
-  }
-  const [realProjectRoot, realResolved] = await Promise.all([
-    fs8.realpath(projectRoot),
-    fs8.realpath(resolved)
-  ]);
-  if (!isPathInside(realProjectRoot, realResolved)) {
-    throw new Error(`Path must stay inside the project root: ${projectRoot}`);
-  }
-  return resolved;
-}
-
-// src/server/project-handlers.ts
 function createProjectHandlers(ctx) {
   return {
     listProjects: async (ws) => {
@@ -5830,7 +6051,7 @@ function createProjectHandlers(ctx) {
         try {
           const modeId = ctx.getModeId();
           const switchMode = modeId === "default" ? void 0 : await ctx.modeStore.getMode(modeId);
-          const switchBuilder = new DefaultSystemPromptBuilder3({
+          const switchBuilder = new DefaultSystemPromptBuilder2({
             memoryStore: ctx.memoryStore,
             skillLoader: ctx.skillLoader,
             modeStore: ctx.modeStore,
@@ -5854,7 +6075,7 @@ function createProjectHandlers(ctx) {
           "sessions"
         );
         await fs9.mkdir(newSessionsDir, { recursive: true });
-        const newSessionStore = new DefaultSessionStore2({ dir: newSessionsDir });
+        const newSessionStore = new DefaultSessionStore({ dir: newSessionsDir });
         const oldSession = ctx.getSession();
         const oldSessionId = oldSession.id;
         try {
@@ -6551,6 +6772,22 @@ async function handleModeRoute(ws, msg, handlers) {
   }
 }
 
+// src/server/prefs-routes.ts
+async function handlePrefsRoute(ws, msg, handlers) {
+  switch (msg.type) {
+    case "prefs.get": {
+      await handlers.getPrefs(ws);
+      return true;
+    }
+    case "prefs.update": {
+      await handlers.updatePrefs(ws, msg.payload ?? {});
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+
 // src/server/shell-git-routes.ts
 async function handleShellGitRoute(ws, msg, handlers) {
   switch (msg.type) {
@@ -6591,6 +6828,44 @@ async function handleMailboxRoute(ws, msg, handlers) {
   }
 }
 
+// src/server/mcp-routes.ts
+async function handleMcpRoute(ws, msg, handlers) {
+  switch (msg.type) {
+    case "mcp.list":
+      await handlers.list(ws, msg);
+      return true;
+    case "mcp.add":
+      await handlers.add(ws, msg);
+      return true;
+    case "mcp.update":
+      await handlers.update(ws, msg);
+      return true;
+    case "mcp.remove":
+      await handlers.remove(ws, msg);
+      return true;
+    case "mcp.enable":
+      await handlers.enable(ws, msg);
+      return true;
+    case "mcp.disable":
+      await handlers.disable(ws, msg);
+      return true;
+    case "mcp.sleep":
+      await handlers.sleep(ws, msg);
+      return true;
+    case "mcp.wake":
+      await handlers.wake(ws, msg);
+      return true;
+    case "mcp.restart":
+      await handlers.restart(ws, msg);
+      return true;
+    case "mcp.discover":
+      await handlers.discover(ws, msg);
+      return true;
+    default:
+      return false;
+  }
+}
+
 // src/server/brain-routes.ts
 async function handleBrainRoute(ws, msg, handlers) {
   switch (msg.type) {
@@ -7062,11 +7337,13 @@ function setupEvents(deps2) {
   events.on("provider.response", (e) => {
     if (e.usage?.input != null) {
       const maxCtx = context.provider.capabilities.maxContext;
-      const pct = maxCtx > 0 ? e.usage.input / maxCtx : 0;
+      const rawLoad = maxCtx > 0 ? e.usage.input / maxCtx : 0;
+      const load2 = Math.max(0, Math.min(1, rawLoad));
       const costUsd = context.tokenCounter.estimateCost().total;
       forwardSubagent("ctx_pct", {
         subagentId: "leader",
-        load: pct,
+        load: load2,
+        rawLoad,
         tokens: e.usage.input,
         maxContext: maxCtx,
         costUsd
@@ -7717,9 +7994,13 @@ async function handleGoalGet(projectRoot, broadcast2) {
 
 // src/server/index.ts
 async function startWebUI(opts = {}) {
+  ensureSessionShell();
   const requestedWsPort = opts.wsPort ?? 3457;
-  const wsHost = opts.wsHost ?? "127.0.0.1";
-  const requestedHttpPort = Number.parseInt(process.env["PORT"] ?? "3456", 10);
+  const wsHost = opts.wsHost ?? process.env["WEBUI_HOST"] ?? process.env["WS_HOST"] ?? "127.0.0.1";
+  const requestedHttpPort = opts.httpPort ?? opts.webuiPort ?? opts.port ?? Number.parseInt(process.env["WEBUI_PORT"] ?? process.env["PORT"] ?? "3456", 10);
+  const publicUrl = opts.publicUrl ?? process.env["WEBUI_PUBLIC_URL"];
+  const publicWsUrl = opts.publicWsUrl ?? process.env["WEBUI_PUBLIC_WS_URL"];
+  const requireToken = opts.requireToken ?? envFlag("WEBUI_REQUIRE_TOKEN");
   const strictPort = process.env["WEBUI_STRICT_PORT"] === "1" || process.env["WEBUI_STRICT_PORT"] === "true";
   let wsPort = requestedWsPort;
   let httpPort = requestedHttpPort;
@@ -7798,7 +8079,7 @@ async function startWebUI(opts = {}) {
     ttlSeconds: 24 * 3600
   });
   const container = createDefaultContainer({ config, wpaths, logger, modelsRegistry });
-  const configStore = opts.services?.configStore ?? container.resolve(TOKENS2.ConfigStore);
+  const configStore = opts.services?.configStore ?? container.resolve(TOKENS.ConfigStore);
   const providerRegistry = new ProviderRegistry();
   try {
     const factories = await buildProviderFactoriesFromRegistry({
@@ -7820,7 +8101,7 @@ async function startWebUI(opts = {}) {
     r.registerAllOrThrow([...builtinToolsPack.tools ?? []], builtinToolsPack.name);
     return r;
   })();
-  const memoryStore = new DefaultMemoryStore2({ paths: wpaths });
+  const memoryStore = new DefaultMemoryStore({ paths: wpaths });
   if (config.features.memory) {
     toolRegistry.register(rememberTool(memoryStore));
     toolRegistry.register(forgetTool(memoryStore));
@@ -7833,6 +8114,7 @@ async function startWebUI(opts = {}) {
   toolRegistry.register(makeMailSendTool({ projectDir: wpaths.projectDir, events }));
   toolRegistry.register(makeMailInboxTool({ projectDir: wpaths.projectDir, events }));
   applyToolDescriptionModes(toolRegistry, config.tools?.descriptionMode);
+  configureExecPolicy(config.tools?.exec ?? {});
   console.log("[WebUI] Tool registry loaded:", toolRegistry.list().length, "tools");
   const mcpRegistry = new MCPRegistry({
     toolRegistry,
@@ -7849,7 +8131,7 @@ async function startWebUI(opts = {}) {
       });
     }
   }
-  let sessionStore = opts.services?.session ?? new DefaultSessionStore3({ dir: wpaths.projectSessions });
+  let sessionStore = opts.services?.session ?? new DefaultSessionStore2({ dir: wpaths.projectSessions });
   if (!opts.services?.session) {
     sessionStore.prune(DEFAULT_SESSION_PRUNE_DAYS).then((count) => {
       if (count > 0) logger.info(`Pruned ${count} old session${count === 1 ? "" : "s"}.`);
@@ -7937,11 +8219,11 @@ async function startWebUI(opts = {}) {
     });
   } catch {
   }
-  const tokenCounter = new DefaultTokenCounter2({
+  const tokenCounter = new DefaultTokenCounter({
     registry: modelsRegistry,
     providerId: config.provider
   });
-  const modeStore = new DefaultModeStore2({ directory: wpaths.configDir });
+  const modeStore = new DefaultModeStore({ directory: wpaths.configDir });
   const activeMode = await modeStore.getActiveMode();
   let modeId = activeMode?.id ?? "default";
   const modePrompt = activeMode?.prompt ?? "";
@@ -7962,7 +8244,7 @@ async function startWebUI(opts = {}) {
   const modelCapabilitiesRef = {
     current: modelCapabilities
   };
-  const skillLoader = config.features.skills ? new DefaultSkillLoader2({ paths: wpaths }) : void 0;
+  const skillLoader = config.features.skills ? new DefaultSkillLoader({ paths: wpaths }) : void 0;
   const skillInstaller = config.features.skills ? new SkillInstaller({
     manifestPath: path16.join(wstackGlobalRoot2(), "installed-skills.json"),
     projectSkillsDir: path16.join(projectRoot, ".wrongstack", "skills"),
@@ -7970,7 +8252,7 @@ async function startWebUI(opts = {}) {
     projectHash: projectHash(projectRoot),
     skillLoader
   }) : void 0;
-  const systemPromptBuilder = new DefaultSystemPromptBuilder4({
+  const systemPromptBuilder = new DefaultSystemPromptBuilder3({
     memoryStore,
     skillLoader,
     modeStore,
@@ -8260,7 +8542,7 @@ async function startWebUI(opts = {}) {
     projectRoot,
     logger
   });
-  const compactor = createStrategyCompactor2({
+  const compactor = createStrategyCompactor({
     strategy: config.context?.strategy,
     preserveK: config.context?.preserveK ?? 10,
     eliseThreshold: config.context?.eliseThreshold ?? 2e3,
@@ -8336,9 +8618,9 @@ async function startWebUI(opts = {}) {
       maxContext: newMaxContext
     });
   }
-  const secretScrubber = container.resolve(TOKENS2.SecretScrubber);
-  const renderer = container.has(TOKENS2.Renderer) ? container.resolve(TOKENS2.Renderer) : void 0;
-  const permissionPolicy = container.resolve(TOKENS2.PermissionPolicy);
+  const secretScrubber = container.resolve(TOKENS.SecretScrubber);
+  const renderer = container.has(TOKENS.Renderer) ? container.resolve(TOKENS.Renderer) : void 0;
+  const permissionPolicy = container.resolve(TOKENS.PermissionPolicy);
   const toolExecutor = new ToolExecutor(toolRegistry, {
     permissionPolicy,
     secretScrubber,
@@ -8381,7 +8663,7 @@ async function startWebUI(opts = {}) {
     }),
     events
   );
-  container.bind(TOKENS2.BrainArbiter, () => brain);
+  container.bind(TOKENS.BrainArbiter, () => brain);
   const brainMailbox = new GlobalMailbox2(wpaths.projectDir, events);
   const brainMonitor = new BrainMonitor({
     events,
@@ -8513,8 +8795,16 @@ async function startWebUI(opts = {}) {
       contextMode: String(context.meta["contextWindowMode"] ?? DEFAULT_CONTEXT_WINDOW_MODE_ID2)
     };
   }
-  const wsToken = generateAuthToken();
-  console.log("[WebUI] WS auth token generated (redacted from logs)");
+  const wsToken = resolveAuthToken(opts.accessToken);
+  console.log("[WebUI] WS auth token ready");
+  const publicHostnames = [publicUrl, publicWsUrl].map((value) => {
+    if (!value) return void 0;
+    try {
+      return new URL(value).hostname;
+    } catch {
+      return void 0;
+    }
+  }).filter((value) => Boolean(value));
   const verifyClient2 = (info) => verifyClient({
     origin: info.origin,
     url: info.req.url ?? "",
@@ -8526,7 +8816,10 @@ async function startWebUI(opts = {}) {
     // exposure class.
     cookieHeader: info.req.headers.cookie,
     wsHost,
-    expectedToken: wsToken
+    expectedToken: wsToken,
+    requireToken,
+    allowedHostnames: publicHostnames,
+    allowBrowserUrlToken: Boolean(publicWsUrl)
   });
   const WS_MAX_PAYLOAD = 8 * 1024 * 1024;
   const wssPrimary = new WebSocketServer({
@@ -8761,8 +9054,10 @@ async function startWebUI(opts = {}) {
   let sessionRoutes;
   let projectRoutes;
   let modeRoutes;
+  let prefsRoutes;
   let shellGitRoutes;
   let mailboxRoutes;
+  let mcpRoutes;
   let brainRoutes;
   let autoPhaseRoutes;
   let specsRoutes;
@@ -8773,8 +9068,10 @@ async function startWebUI(opts = {}) {
     if (await handleSessionRoute(ws, msg, sessionRoutes)) return;
     if (await handleProjectRoute(ws, msg, projectRoutes)) return;
     if (await handleModeRoute(ws, msg, modeRoutes)) return;
+    if (await handlePrefsRoute(ws, msg, prefsRoutes)) return;
     if (await handleShellGitRoute(ws, msg, shellGitRoutes)) return;
     if (await handleMailboxRoute(ws, msg, mailboxRoutes)) return;
+    if (await handleMcpRoute(ws, msg, mcpRoutes)) return;
     if (await handleBrainRoute(ws, msg, brainRoutes)) return;
     if (await handleAutoPhaseRoute(ws, msg, autoPhaseRoutes)) return;
     if (await handleSpecsRoute(ws, msg, specsRoutes)) return;
@@ -8885,27 +9182,31 @@ async function startWebUI(opts = {}) {
       case "memory.forget":
         return handleMemoryForget(ws, msg, memoryStore);
       // ── MCP operations — delegated to shared handlers (mcp-handlers.ts),
-      // backed by the live MCPRegistry constructed above. ──
+      // backed by the live MCPRegistry constructed above. Routed via
+      // handleMcpRoute (see mcpRoutes = { ... } below). These case arms
+      // are unreachable but left as tripwires for any future regression
+      // where the route chain stops claiming 'mcp.*'. If you see one
+      // fire, fix the dispatch order in the handleMessage chain above.
       case "mcp.list":
-        return handleMcpList(ws, msg, globalConfigPath, mcpRegistry);
+        throw new Error("handleMcpRoute did not claim mcp.list \u2014 check chain order");
       case "mcp.add":
-        return handleMcpAdd(ws, msg, globalConfigPath, mcpRegistry);
-      case "mcp.remove":
-        return handleMcpRemove(ws, msg, globalConfigPath, mcpRegistry);
+        throw new Error("handleMcpRoute did not claim mcp.add \u2014 check chain order");
       case "mcp.update":
-        return handleMcpUpdate(ws, msg, globalConfigPath, mcpRegistry);
-      case "mcp.wake":
-        return handleMcpWake(ws, msg, globalConfigPath, mcpRegistry);
-      case "mcp.sleep":
-        return handleMcpSleep(ws, msg, globalConfigPath, mcpRegistry);
-      case "mcp.discover":
-        return handleMcpDiscover(ws, msg, globalConfigPath, mcpRegistry);
+        throw new Error("handleMcpRoute did not claim mcp.update \u2014 check chain order");
+      case "mcp.remove":
+        throw new Error("handleMcpRoute did not claim mcp.remove \u2014 check chain order");
       case "mcp.enable":
-        return handleMcpEnable(ws, msg, globalConfigPath, mcpRegistry);
+        throw new Error("handleMcpRoute did not claim mcp.enable \u2014 check chain order");
       case "mcp.disable":
-        return handleMcpDisable(ws, msg, globalConfigPath, mcpRegistry);
+        throw new Error("handleMcpRoute did not claim mcp.disable \u2014 check chain order");
+      case "mcp.sleep":
+        throw new Error("handleMcpRoute did not claim mcp.sleep \u2014 check chain order");
+      case "mcp.wake":
+        throw new Error("handleMcpRoute did not claim mcp.wake \u2014 check chain order");
       case "mcp.restart":
-        return handleMcpRestart(ws, msg, globalConfigPath, mcpRegistry);
+        throw new Error("handleMcpRoute did not claim mcp.restart \u2014 check chain order");
+      case "mcp.discover":
+        throw new Error("handleMcpRoute did not claim mcp.discover \u2014 check chain order");
       // Skills — full request→response cycle lives in skills-handlers.ts
       // (shared with the CLI's embedded server). skillsCtx is the closed-over
       // loader/installer/projectRoot the handlers need.
@@ -9053,53 +9354,11 @@ async function startWebUI(opts = {}) {
         break;
       }
       case "prefs.update": {
-        const parsed = validatePrefsUpdatePayload(msg.payload);
-        if (!parsed.ok) {
-          sendResult2(ws, false, parsed.message);
-          break;
-        }
-        const payload = parsed.value.prefs;
-        for (const [key, val] of Object.entries(payload)) {
-          context.meta[key] = val;
-        }
-        void persistPrefsToConfig(payload);
-        if (typeof payload["yolo"] === "boolean") {
-          permissionPolicy.setYolo?.(payload["yolo"]);
-        }
-        if (typeof payload["featureMcp"] === "boolean")
-          config.features.mcp = payload["featureMcp"];
-        if (typeof payload["featurePlugins"] === "boolean")
-          config.features.plugins = payload["featurePlugins"];
-        if (typeof payload["featureMemory"] === "boolean")
-          config.features.memory = payload["featureMemory"];
-        if (typeof payload["featureSkills"] === "boolean")
-          config.features.skills = payload["featureSkills"];
-        if (typeof payload["featureModelsRegistry"] === "boolean")
-          config.features.modelsRegistry = payload["featureModelsRegistry"];
-        if (Array.isArray(payload["fallbackModels"]))
-          config.fallbackModels = payload["fallbackModels"];
-        if (typeof payload["fallbackAuto"] === "boolean")
-          config.fallbackAuto = payload["fallbackAuto"];
-        if (typeof payload["contextAutoCompact"] === "boolean") {
-          if (payload["contextAutoCompact"] && autoCompactor) {
-            pipelines.contextWindow.remove("AutoCompaction", { optional: true });
-            pipelines.contextWindow.use({ name: "AutoCompaction", handler: autoCompactor.handler() });
-          } else {
-            pipelines.contextWindow.remove("AutoCompaction", { optional: true });
-          }
-        }
-        if (typeof payload["logLevel"] === "string") {
-          const valid = ["debug", "info", "warn", "error"];
-          if (valid.includes(payload["logLevel"])) {
-            logger.level = payload["logLevel"];
-          }
-        }
-        broadcast(clients, { type: "prefs.updated", payload: prefSnapshot() });
-        break;
+        void ws;
+        throw new Error("handlePrefsRoute did not claim prefs.update \u2014 check chain order");
       }
       case "prefs.get": {
-        send(ws, { type: "prefs.updated", payload: prefSnapshot() });
-        break;
+        throw new Error("handlePrefsRoute did not claim prefs.get \u2014 check chain order");
       }
       default:
         send(ws, {
@@ -9320,6 +9579,55 @@ async function startWebUI(opts = {}) {
     },
     sessionStartPayload
   });
+  prefsRoutes = {
+    getPrefs: async (ws) => {
+      send(ws, { type: "prefs.updated", payload: prefSnapshot() });
+    },
+    updatePrefs: async (ws, msgPayload) => {
+      const parsed = validatePrefsUpdatePayload(msgPayload);
+      if (!parsed.ok) {
+        sendResult2(ws, false, parsed.message);
+        return;
+      }
+      const payload = parsed.value.prefs;
+      for (const [key, val] of Object.entries(payload)) {
+        context.meta[key] = val;
+      }
+      void persistPrefsToConfig(payload);
+      if (typeof payload["yolo"] === "boolean") {
+        permissionPolicy.setYolo?.(payload["yolo"]);
+      }
+      if (typeof payload["featureMcp"] === "boolean")
+        config.features.mcp = payload["featureMcp"];
+      if (typeof payload["featurePlugins"] === "boolean")
+        config.features.plugins = payload["featurePlugins"];
+      if (typeof payload["featureMemory"] === "boolean")
+        config.features.memory = payload["featureMemory"];
+      if (typeof payload["featureSkills"] === "boolean")
+        config.features.skills = payload["featureSkills"];
+      if (typeof payload["featureModelsRegistry"] === "boolean")
+        config.features.modelsRegistry = payload["featureModelsRegistry"];
+      if (Array.isArray(payload["fallbackModels"]))
+        config.fallbackModels = payload["fallbackModels"];
+      if (typeof payload["fallbackAuto"] === "boolean")
+        config.fallbackAuto = payload["fallbackAuto"];
+      if (typeof payload["contextAutoCompact"] === "boolean") {
+        if (payload["contextAutoCompact"] && autoCompactor) {
+          pipelines.contextWindow.remove("AutoCompaction", { optional: true });
+          pipelines.contextWindow.use({ name: "AutoCompaction", handler: autoCompactor.handler() });
+        } else {
+          pipelines.contextWindow.remove("AutoCompaction", { optional: true });
+        }
+      }
+      if (typeof payload["logLevel"] === "string") {
+        const valid = ["debug", "info", "warn", "error"];
+        if (valid.includes(payload["logLevel"])) {
+          logger.level = payload["logLevel"];
+        }
+      }
+      broadcast(clients, { type: "prefs.updated", payload: prefSnapshot() });
+    }
+  };
   shellGitRoutes = {
     gitInfo: async (ws) => {
       await handleGitInfo(ws, projectRoot);
@@ -9372,6 +9680,18 @@ async function startWebUI(opts = {}) {
       return handleMailboxPurge(ws, { projectRoot, globalRoot: path16.dirname(globalConfigPath) }, parsed.value);
     }
   };
+  mcpRoutes = {
+    list: (ws, msg) => handleMcpList(ws, msg, globalConfigPath, mcpRegistry),
+    add: (ws, msg) => handleMcpAdd(ws, msg, globalConfigPath, mcpRegistry),
+    update: (ws, msg) => handleMcpUpdate(ws, msg, globalConfigPath, mcpRegistry),
+    remove: (ws, msg) => handleMcpRemove(ws, msg, globalConfigPath, mcpRegistry),
+    enable: (ws, msg) => handleMcpEnable(ws, msg, globalConfigPath, mcpRegistry),
+    disable: (ws, msg) => handleMcpDisable(ws, msg, globalConfigPath, mcpRegistry),
+    sleep: (ws, msg) => handleMcpSleep(ws, msg, globalConfigPath, mcpRegistry),
+    wake: (ws, msg) => handleMcpWake(ws, msg, globalConfigPath, mcpRegistry),
+    restart: (ws, msg) => handleMcpRestart(ws, msg, globalConfigPath, mcpRegistry),
+    discover: (ws, msg) => handleMcpDiscover(ws, msg, globalConfigPath, mcpRegistry)
+  };
   brainRoutes = {
     status: (ws) => {
       send(ws, {
@@ -9439,8 +9759,10 @@ async function startWebUI(opts = {}) {
     host: wsHost,
     distDir: path16.resolve(import.meta.dirname, "../../dist"),
     wsPort,
+    publicWsUrl,
     globalRoot: wpaths.globalRoot,
     apiToken: wsToken,
+    requireToken,
     watcherMetrics,
     onFleetPing: () => {
       void fleetBroadcast?.();
@@ -9448,7 +9770,12 @@ async function startWebUI(opts = {}) {
   });
   const registryBaseDir = path16.dirname(globalConfigPath);
   httpServer.listen(httpPort, wsHost, () => {
-    const openUrl = `http://${wsHost}:${httpPort}`;
+    const openUrl = buildWebUIAccessUrl({
+      host: wsHost,
+      port: httpPort,
+      token: wsToken,
+      publicUrl
+    });
     console.log(`[WebUI] HTTP server running on ${openUrl}`);
     if (opts.open) openBrowser(openUrl);
     void registerInstance(
@@ -9460,7 +9787,7 @@ async function startWebUI(opts = {}) {
         projectRoot,
         projectName: path16.basename(projectRoot) || projectRoot,
         startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        url: `http://${wsHost}:${httpPort}`
+        url: buildWebUIAccessUrl({ host: wsHost, port: httpPort, publicUrl })
       },
       registryBaseDir
     ).catch((err) => console.warn(JSON.stringify({
@@ -9502,7 +9829,55 @@ async function startWebUI(opts = {}) {
 
 // src/server/entry.ts
 var argv = process.argv.slice(2);
-if (argv.includes("--list") || argv.includes("-l") || argv[0] === "ls") {
+function readArg(names) {
+  for (let i = 0; i < argv.length; i++) {
+    const current = argv[i];
+    if (!current) continue;
+    for (const name2 of names) {
+      if (current === name2) {
+        const next = argv[i + 1];
+        if (!next || next.startsWith("-")) {
+          throw new Error(`${name2} requires a value`);
+        }
+        return next;
+      }
+      if (current.startsWith(`${name2}=`)) return current.slice(name2.length + 1);
+    }
+  }
+  return void 0;
+}
+function parsePort(value, fallback, label) {
+  if (value === void 0) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new Error(`${label} must be a port between 1 and 65535`);
+  }
+  return parsed;
+}
+function envFlag2(name2) {
+  const value = process.env[name2]?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+function printHelp() {
+  console.log(`Usage: wstackui [options]
+
+Options:
+  --host <host>             Bind host/interface (default: 127.0.0.1)
+  --port <port>             HTTP frontend port (default: 3456)
+  --ws-port <port>          WebSocket backend port (default: 3457)
+  --token <token>           Fixed access token/password (default: random per process)
+  --public-url <url>        Browser-facing HTTP URL for tunnels/proxies
+  --public-ws-url <url>     Browser-facing ws:// or wss:// URL for tunnels/proxies
+  --require-token           Require token/password even on loopback binds
+  --open, -o                Open the browser after startup
+  --list, -l, ls            List running WebUI instances
+  --help, -h                Show this help
+`);
+}
+if (argv.includes("--help") || argv.includes("-h")) {
+  printHelp();
+  process.exit(0);
+} else if (argv.includes("--list") || argv.includes("-l") || argv[0] === "ls") {
   listInstances().then((instances) => {
     console.log(formatInstances(instances));
     process.exit(0);
@@ -9516,11 +9891,40 @@ if (argv.includes("--list") || argv.includes("-l") || argv[0] === "ls") {
     process.exit(1);
   });
 } else {
-  const wsPort = Number.parseInt(process.env["WS_PORT"] ?? "3457", 10);
-  const wsHost = process.env["WS_HOST"] ?? "127.0.0.1";
+  let wsPort;
+  let httpPort;
+  let wsHost;
+  let accessToken;
+  let publicUrl;
+  let publicWsUrl;
+  try {
+    wsHost = readArg(["--host"]) ?? process.env["WEBUI_HOST"] ?? process.env["WS_HOST"] ?? "127.0.0.1";
+    httpPort = parsePort(
+      readArg(["--port", "--http-port"]) ?? process.env["WEBUI_PORT"] ?? process.env["PORT"],
+      3456,
+      "--port"
+    );
+    wsPort = parsePort(readArg(["--ws-port"]) ?? process.env["WS_PORT"], 3457, "--ws-port");
+    accessToken = readArg(["--token", "--auth-token"]) ?? process.env["WEBUI_TOKEN"] ?? process.env["WEBUI_AUTH_TOKEN"];
+    publicUrl = readArg(["--public-url"]) ?? process.env["WEBUI_PUBLIC_URL"];
+    publicWsUrl = readArg(["--public-ws-url"]) ?? process.env["WEBUI_PUBLIC_WS_URL"];
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
   const open = argv.includes("--open") || argv.includes("-o") || process.env["WEBUI_OPEN"] === "1";
-  console.log(`[WebUI] Starting standalone server on ${wsHost}:${wsPort}...`);
-  startWebUI({ wsPort, wsHost, open }).catch((err) => {
+  const requireToken = argv.includes("--require-token") || envFlag2("WEBUI_REQUIRE_TOKEN");
+  console.log(`[WebUI] Starting standalone server on ${wsHost} (http:${httpPort}, ws:${wsPort})...`);
+  startWebUI({
+    wsPort,
+    wsHost,
+    httpPort,
+    accessToken,
+    publicUrl,
+    publicWsUrl,
+    requireToken,
+    open
+  }).catch((err) => {
     console.error(JSON.stringify({
       level: "fatal",
       event: "webui.startup_failed",