@wrongstack/webui 0.273.1 → 0.275.0

package/dist/server/entry.js

@@ -171,9 +171,12 @@ var BOOLEAN_PREF_KEYS = /* @__PURE__ */ new Set([
   "reasoningPreserve",
   "hqEnabled",
   "hqRawContent",
-  "fallbackAuto"
+  "fallbackAuto",
+  "favoriteModelsOnly"
 ]);
-var STRING_ARRAY_PREF_KEYS = /* @__PURE__ */ new Set(["fallbackModels"]);
+var STRING_ARRAY_PREF_KEYS = /* @__PURE__ */ new Set(["fallbackModels", "favoriteModels"]);
+var STRING_ARRAY_RECORD_PREF_KEYS = /* @__PURE__ */ new Set(["fallbackProfiles"]);
+var MODEL_MATRIX_PREF_KEYS = /* @__PURE__ */ new Set(["modelMatrix"]);
 var NUMBER_PREF_KEYS = /* @__PURE__ */ new Set([
   "autonomyDelayMs",
   "autoProceedMaxIterations",
@@ -208,6 +211,33 @@ function validatePreferenceValue(key, value) {
   if (STRING_ARRAY_PREF_KEYS.has(key)) {
     return Array.isArray(value) && value.every((v) => typeof v === "string") ? null : `prefs.update payload.${key} must be an array of strings`;
   }
+  if (STRING_ARRAY_RECORD_PREF_KEYS.has(key)) {
+    return isRecord(value) && Object.values(value).every(
+      (v) => Array.isArray(v) && v.every((item) => typeof item === "string")
+    ) ? null : `prefs.update payload.${key} must be an object of string arrays`;
+  }
+  if (MODEL_MATRIX_PREF_KEYS.has(key)) {
+    if (!isRecord(value)) return `prefs.update payload.${key} must be an object`;
+    for (const entry of Object.values(value)) {
+      if (!isRecord(entry)) return `prefs.update payload.${key} entries must be objects`;
+      const provider = entry["provider"];
+      const model = entry["model"];
+      const fallbackProfile = entry["fallbackProfile"];
+      if (provider !== void 0 && typeof provider !== "string") {
+        return `prefs.update payload.${key}.provider must be a string when provided`;
+      }
+      if (model !== void 0 && typeof model !== "string") {
+        return `prefs.update payload.${key}.model must be a string when provided`;
+      }
+      if (fallbackProfile !== void 0 && typeof fallbackProfile !== "string") {
+        return `prefs.update payload.${key}.fallbackProfile must be a string when provided`;
+      }
+      if (model === void 0 && fallbackProfile === void 0) {
+        return `prefs.update payload.${key} entries require model or fallbackProfile`;
+      }
+    }
+    return null;
+  }
   const allowed = ENUM_PREF_KEYS[key];
   if (allowed) {
     return typeof value === "string" && allowed.has(value) ? null : `prefs.update payload.${key} must be one of: ${Array.from(allowed).join(", ")}`;
@@ -436,8 +466,8 @@ function validateShellOpenPayload(payload) {
   if (!isRecord(payload)) {
     return { ok: false, message: "shell.open payload must be an object with string path" };
   }
-  const path17 = payload["path"];
-  if (typeof path17 !== "string" || path17.trim().length === 0) {
+  const path18 = payload["path"];
+  if (typeof path18 !== "string" || path18.trim().length === 0) {
     return { ok: false, message: "shell.open payload.path must be a non-empty string" };
   }
   const target = payload["target"];
@@ -447,20 +477,20 @@ function validateShellOpenPayload(payload) {
       message: 'shell.open payload.target must be "file" or "terminal" when provided'
     };
   }
-  return { ok: true, value: { path: path17, target } };
+  return { ok: true, value: { path: path18, target } };
 }
 function validateGitDiffPayload(payload) {
   if (!isRecord(payload)) {
     return { ok: false, message: "git.diff payload must be an object" };
   }
-  const path17 = payload["path"];
-  if (path17 === void 0 || path17 === null) {
+  const path18 = payload["path"];
+  if (path18 === void 0 || path18 === null) {
     return { ok: true, value: { path: "" } };
   }
-  if (typeof path17 !== "string") {
+  if (typeof path18 !== "string") {
     return { ok: false, message: "git.diff payload.path must be a string when provided" };
   }
-  return { ok: true, value: { path: path17 } };
+  return { ok: true, value: { path: path18 } };
 }
 function validateProjectsAddPayload(payload) {
   if (!isRecord(payload)) {
@@ -710,8 +740,57 @@ async function handleWorklistMessage(ctx, ws, msg) {
 
 // src/server/index.ts
 import { makeMailboxTool, makeMailSendTool, makeMailInboxTool, mailboxSessionTag } from "@wrongstack/core";
-import { toErrorMessage as toErrorMessage6, wstackGlobalRoot as wstackGlobalRoot2, projectHash } from "@wrongstack/core/utils";
+import { toErrorMessage as toErrorMessage6, wstackGlobalRoot as wstackGlobalRoot3, projectHash } from "@wrongstack/core/utils";
 import { SkillInstaller } from "@wrongstack/core/skills";
+
+// src/server/discover-mailbox-bridge.ts
+import { resolveProjectDir, wstackGlobalRoot } from "@wrongstack/core";
+import { readLiveLock } from "@wrongstack/core/coordination";
+async function discoverMailboxBridgeForWebui(params) {
+  const mode = params.config?.features?.mailboxBridge ?? "auto";
+  if (mode === "off") return;
+  const projectDir = resolveProjectDir(params.projectRoot, wstackGlobalRoot());
+  const result = await readLiveLock(projectDir);
+  switch (result.kind) {
+    case "live": {
+      params.logger.debug("webui joined existing mailbox bridge", {
+        url: result.lock.url,
+        lockPath: projectDir
+      });
+      params.ctx.meta["mailboxBridge"] = {
+        url: result.lock.url,
+        token: result.lock.token,
+        lockPath: projectDir,
+        childPid: null,
+        source: "joined"
+      };
+      break;
+    }
+    case "probe-failed": {
+      params.logger.warn(
+        "mailbox bridge present but /healthz unreachable; webui will start without external-agent connectivity",
+        { url: result.lock.url, lockPath: projectDir }
+      );
+      params.ctx.meta["mailboxBridge"] = {
+        url: result.lock.url,
+        token: result.lock.token,
+        lockPath: projectDir,
+        childPid: null,
+        source: "unhealthy"
+      };
+      break;
+    }
+    case "absent": {
+      params.logger.info(
+        "no mailbox bridge running; webui will start without external-agent connectivity. Run `wstack mailbox serve` or a CLI surface to bring one up.",
+        { projectDir }
+      );
+      break;
+    }
+  }
+}
+
+// src/server/index.ts
 import {
   BrainMonitor,
   DefaultBrainArbiter,
@@ -719,8 +798,9 @@ import {
   createAutonomyBrain,
   createTieredBrainArbiter
 } from "@wrongstack/core";
-import * as fs13 from "fs/promises";
-import * as path16 from "path";
+import * as fs14 from "fs/promises";
+import * as path17 from "path";
+import { createRequire as createRequire2 } from "module";
 
 // src/server/http-server.ts
 import * as fs from "fs/promises";
@@ -897,7 +977,7 @@ async function handleApiSessionEvents(res, globalRoot, sessionId, limit) {
     return;
   }
   try {
-    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths2, DefaultSessionStore: DefaultSessionStore3, DefaultSessionReader: DefaultSessionReader2 } = await import("@wrongstack/core");
+    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths4, DefaultSessionStore: DefaultSessionStore3, DefaultSessionReader: DefaultSessionReader2 } = await import("@wrongstack/core");
     const registry = new SessionRegistry(globalRoot);
     const entry = await registry.get(sessionId);
     if (!entry) {
@@ -905,7 +985,7 @@ async function handleApiSessionEvents(res, globalRoot, sessionId, limit) {
       res.end(JSON.stringify({ error: "Session not found" }));
       return;
     }
-    const paths = resolveWstackPaths2({ projectRoot: entry.projectRoot, globalRoot });
+    const paths = resolveWstackPaths4({ projectRoot: entry.projectRoot, globalRoot });
     const store = new DefaultSessionStore3({ dir: paths.projectSessions });
     const reader = new DefaultSessionReader2({ store });
     const rawEntries = [];
@@ -932,7 +1012,7 @@ async function handleApiSessionEvents(res, globalRoot, sessionId, limit) {
   }
 }
 function readJsonBody(req) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     let data = "";
     req.on("data", (chunk) => {
       data += chunk;
@@ -943,7 +1023,7 @@ function readJsonBody(req) {
     });
     req.on("end", () => {
       try {
-        resolve9(data ? JSON.parse(data) : {});
+        resolve10(data ? JSON.parse(data) : {});
       } catch (err) {
         reject(err instanceof Error ? err : new Error(String(err)));
       }
@@ -979,7 +1059,7 @@ async function handleApiSessionMessage(res, req, globalRoot, sessionId) {
   const priority = ["low", "normal", "high"].includes(rawPriority) ? rawPriority : "high";
   const subject = typeof body["subject"] === "string" && body["subject"].trim() ? body["subject"].trim() : "Message from Fleet HQ";
   try {
-    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths2, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
+    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths4, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
     const registry = new SessionRegistry(globalRoot);
     const entry = await registry.get(sessionId);
     if (!entry) {
@@ -987,7 +1067,7 @@ async function handleApiSessionMessage(res, req, globalRoot, sessionId) {
       res.end(JSON.stringify({ error: "Session not found" }));
       return;
     }
-    const paths = resolveWstackPaths2({ projectRoot: entry.projectRoot, globalRoot });
+    const paths = resolveWstackPaths4({ projectRoot: entry.projectRoot, globalRoot });
     const mailbox = new GlobalMailbox3(paths.projectDir);
     const to = `leader@${mailboxSessionTag2(sessionId)}`;
     const sent = await mailbox.send({ from, to, type, subject, body: text, priority });
@@ -1005,7 +1085,7 @@ async function handleApiSessionMailbox(res, globalRoot, sessionId) {
     return;
   }
   try {
-    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths2, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
+    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths4, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
     const registry = new SessionRegistry(globalRoot);
     const entry = await registry.get(sessionId);
     if (!entry) {
@@ -1013,7 +1093,7 @@ async function handleApiSessionMailbox(res, globalRoot, sessionId) {
       res.end(JSON.stringify({ error: "Session not found" }));
       return;
     }
-    const paths = resolveWstackPaths2({ projectRoot: entry.projectRoot, globalRoot });
+    const paths = resolveWstackPaths4({ projectRoot: entry.projectRoot, globalRoot });
     const mailbox = new GlobalMailbox3(paths.projectDir);
     const leaderAddr = `leader@${mailboxSessionTag2(sessionId)}`;
     const [inbound, outbound] = await Promise.all([
@@ -1063,7 +1143,7 @@ async function handleApiSessionInterrupt(res, req, globalRoot, sessionId) {
   const reason = typeof body["reason"] === "string" && body["reason"].trim() ? body["reason"].trim() : "Operator requested stop from Fleet HQ";
   const from = typeof body["from"] === "string" && body["from"].trim() ? body["from"].trim() : "human@webui";
   try {
-    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths2, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
+    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths4, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
     const registry = new SessionRegistry(globalRoot);
     const entry = await registry.get(sessionId);
     if (!entry) {
@@ -1071,7 +1151,7 @@ async function handleApiSessionInterrupt(res, req, globalRoot, sessionId) {
       res.end(JSON.stringify({ error: "Session not found" }));
       return;
     }
-    const paths = resolveWstackPaths2({ projectRoot: entry.projectRoot, globalRoot });
+    const paths = resolveWstackPaths4({ projectRoot: entry.projectRoot, globalRoot });
     const mailbox = new GlobalMailbox3(paths.projectDir);
     const to = `leader@${mailboxSessionTag2(sessionId)}`;
     const sent = await mailbox.send({
@@ -1111,7 +1191,7 @@ async function handleApiFleetBroadcast(res, req, globalRoot) {
   }
   const from = typeof body["from"] === "string" && body["from"].trim() ? body["from"].trim() : "human@webui";
   try {
-    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths2, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
+    const { SessionRegistry, resolveWstackPaths: resolveWstackPaths4, GlobalMailbox: GlobalMailbox3, mailboxSessionTag: mailboxSessionTag2 } = await import("@wrongstack/core");
     const registry = new SessionRegistry(globalRoot);
     const all = await registry.list();
     const mySlug = all.find((s) => s.pid === process.pid)?.projectSlug;
@@ -1123,7 +1203,7 @@ async function handleApiFleetBroadcast(res, req, globalRoot) {
     }
     const mbByDir = /* @__PURE__ */ new Map();
     const mailboxFor = (projectRoot) => {
-      const dir = resolveWstackPaths2({ projectRoot, globalRoot }).projectDir;
+      const dir = resolveWstackPaths4({ projectRoot, globalRoot }).projectDir;
       let mb = mbByDir.get(dir);
       if (!mb) {
         mb = new GlobalMailbox3(dir);
@@ -1167,7 +1247,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 +1258,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 +1304,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 +1360,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" && requestHost !== "::1" && requestHost !== "[::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 +1440,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 +1456,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 +1464,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 +1491,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 +1501,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 +1511,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 +1523,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 +1533,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 +1543,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 +1557,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 +1604,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 +1626,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");
@@ -1700,6 +1864,37 @@ 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) {
@@ -1744,6 +1939,16 @@ async function realpathAllowMissing(p) {
     }
   }
 }
+function validatedPayload(msg, label) {
+  if (msg == null || typeof msg !== "object") {
+    throw new TypeError(`Expected object for ${label}, got ${msg}`);
+  }
+  const payload = msg.payload;
+  if (payload == null || typeof payload !== "object") {
+    throw new TypeError(`Expected payload object for ${label}, got ${payload}`);
+  }
+  return payload;
+}
 async function handleFilesTree(ws, msg, projectRoot) {
   const payload = msg.payload;
   const rawPath = payload?.path?.trim();
@@ -1814,7 +2019,13 @@ async function handleFilesTree(ws, msg, projectRoot) {
   }
 }
 async function handleFilesRead(ws, msg, projectRoot) {
-  const { filePath } = msg.payload;
+  let filePath;
+  try {
+    ({ filePath } = validatedPayload(msg, "files.read"));
+  } catch {
+    send(ws, { type: "files.read", payload: { filePath: "", content: "", error: "Malformed request" } });
+    return;
+  }
   let realResolved;
   try {
     realResolved = await resolveFileInsideProject(projectRoot, filePath);
@@ -1833,7 +2044,14 @@ async function handleFilesRead(ws, msg, projectRoot) {
   }
 }
 async function handleFilesWrite(ws, msg, projectRoot, opts = {}) {
-  const { filePath, content } = msg.payload;
+  let filePath;
+  let content;
+  try {
+    ({ filePath, content } = validatedPayload(msg, "files.write"));
+  } catch {
+    send(ws, { type: "files.written", payload: { filePath: "", success: false, error: "Malformed request" } });
+    return;
+  }
   let realResolved;
   try {
     realResolved = await resolveFileInsideProject(projectRoot, filePath);
@@ -2671,7 +2889,7 @@ 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";
+import { wstackGlobalRoot as wstackGlobalRoot2 } from "@wrongstack/core/utils";
 async function handleSkillsList(ws, ctx) {
   if (!ctx.skillLoader) {
     send(ws, { type: "skills.list", payload: { skills: [], enabled: false } });
@@ -2841,7 +3059,7 @@ async function handleSkillsCreate(ws, ctx, msg) {
   }
   const createPayload = parsed.value;
   try {
-    const targetDir = createPayload.scope === "global" ? path6.join(wstackGlobalRoot(), "skills", createPayload.name.trim()) : path6.join(ctx.projectRoot, ".wrongstack", "skills", createPayload.name.trim());
+    const targetDir = createPayload.scope === "global" ? path6.join(wstackGlobalRoot2(), "skills", createPayload.name.trim()) : path6.join(ctx.projectRoot, ".wrongstack", "skills", createPayload.name.trim());
     try {
       await fs5.access(targetDir);
       send(ws, { type: "skills.created", payload: { success: false, error: `Skill "${createPayload.name}" already exists` } });
@@ -2961,6 +3179,416 @@ async function handleSkillsExport(ws, ctx) {
   }
 }
 
+// src/server/prompts-handlers.ts
+function parseVariablesPayload(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const o = item;
+    if (typeof o["name"] !== "string" || !o["name"].trim()) continue;
+    const enumVals = Array.isArray(o["enum"]) && o["enum"].every((x) => typeof x === "string") ? o["enum"].map((s) => s.trim()).filter(Boolean) : void 0;
+    const v = { name: o["name"].trim() };
+    if (typeof o["description"] === "string" && o["description"].trim()) {
+      v.description = o["description"].trim();
+    }
+    if (o["required"] === true) v.required = true;
+    if (o["multiline"] === true) v.multiline = true;
+    if (enumVals && enumVals.length > 0) v.enum = enumVals;
+    out.push(v);
+  }
+  return out.length > 0 ? out : void 0;
+}
+function toMeta(e) {
+  return {
+    id: e.id,
+    slug: e.slug,
+    title: e.title,
+    description: e.description,
+    category: e.category,
+    tags: e.tags,
+    source: e.source,
+    favorite: e.favorite,
+    variables: e.variables ?? []
+  };
+}
+async function handlePromptsList(ws, ctx) {
+  if (!ctx.promptLoader) {
+    send(ws, { type: "prompts.list", payload: { enabled: false, prompts: [], categories: [] } });
+    return;
+  }
+  try {
+    const [all, categories] = await Promise.all([
+      ctx.promptLoader.list(),
+      ctx.promptLoader.categories()
+    ]);
+    send(ws, {
+      type: "prompts.list",
+      payload: { enabled: true, prompts: all.map(toMeta), categories }
+    });
+  } catch (err) {
+    send(ws, {
+      type: "prompts.list",
+      payload: { enabled: true, prompts: [], categories: [], error: errMessage(err) }
+    });
+  }
+}
+async function handlePromptsSearch(ws, ctx, msg) {
+  if (!ctx.promptLoader) {
+    send(ws, { type: "prompts.search", payload: { enabled: false, prompts: [] } });
+    return;
+  }
+  const payload = msg.payload ?? {};
+  try {
+    const results = await ctx.promptLoader.search(payload.query ?? "", {
+      ...payload.category ? { category: payload.category } : {},
+      limit: 50
+    });
+    send(ws, { type: "prompts.search", payload: { enabled: true, prompts: results.map(toMeta) } });
+  } catch (err) {
+    send(ws, {
+      type: "prompts.search",
+      payload: { enabled: true, prompts: [], error: errMessage(err) }
+    });
+  }
+}
+async function handlePromptsContent(ws, ctx, msg) {
+  const slug = msg.payload?.slug;
+  if (!ctx.promptLoader || !slug) {
+    send(ws, {
+      type: "prompts.content",
+      payload: { slug: slug ?? "", found: false, content: "", variables: [] }
+    });
+    return;
+  }
+  try {
+    const entry = await ctx.promptLoader.find(slug);
+    if (!entry) {
+      send(ws, {
+        type: "prompts.content",
+        payload: { slug, found: false, content: "", variables: [] }
+      });
+      return;
+    }
+    send(ws, {
+      type: "prompts.content",
+      payload: {
+        slug: entry.slug,
+        found: true,
+        title: entry.title,
+        content: entry.content,
+        variables: entry.variables ?? [],
+        category: entry.category,
+        source: entry.source
+      }
+    });
+  } catch (err) {
+    send(ws, {
+      type: "prompts.content",
+      payload: { slug, found: false, content: "", variables: [], error: errMessage(err) }
+    });
+  }
+}
+async function handlePromptsFavorite(ws, ctx, msg) {
+  const payload = msg.payload;
+  if (!ctx.promptLoader || !payload?.slug) {
+    send(ws, {
+      type: "prompts.favorite",
+      payload: { success: false, error: "Prompt library unavailable" }
+    });
+    return;
+  }
+  try {
+    const updated = await ctx.promptLoader.setFavorite(payload.slug, payload.favorite !== false);
+    if (!updated) {
+      send(ws, {
+        type: "prompts.favorite",
+        payload: { success: false, error: "Prompt not found" }
+      });
+      return;
+    }
+    send(ws, {
+      type: "prompts.favorite",
+      payload: { success: true, slug: updated.slug, favorite: updated.favorite }
+    });
+  } catch (err) {
+    send(ws, { type: "prompts.favorite", payload: { success: false, error: errMessage(err) } });
+  }
+}
+async function handlePromptsCreate(ws, ctx, msg) {
+  const p = msg.payload;
+  if (!ctx.promptLoader || !p) {
+    send(ws, {
+      type: "prompts.created",
+      payload: { success: false, error: "Prompt library unavailable" }
+    });
+    return;
+  }
+  const title = typeof p["title"] === "string" ? p["title"].trim() : "";
+  const content = typeof p["content"] === "string" ? p["content"] : "";
+  if (!title || !content) {
+    send(ws, {
+      type: "prompts.created",
+      payload: { success: false, error: "Title and content are required" }
+    });
+    return;
+  }
+  try {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const tags = Array.isArray(p["tags"]) ? p["tags"].filter((t) => typeof t === "string") : [];
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "prompt";
+    const variables = parseVariablesPayload(p["variables"]);
+    const entry = {
+      id: slug,
+      slug,
+      title,
+      description: typeof p["description"] === "string" ? p["description"] : "",
+      content,
+      category: typeof p["category"] === "string" && p["category"] ? p["category"] : "uncategorized",
+      tags,
+      source: "user",
+      favorite: false,
+      ...variables ? { variables } : {},
+      createdAt: now,
+      updatedAt: now
+    };
+    await ctx.promptLoader.save(entry);
+    send(ws, { type: "prompts.created", payload: { success: true, slug } });
+  } catch (err) {
+    send(ws, { type: "prompts.created", payload: { success: false, error: errMessage(err) } });
+  }
+}
+async function handlePromptsUsed(ws, ctx, msg) {
+  const slug = msg.payload?.slug;
+  if (!ctx.promptUsage || !slug) {
+    send(ws, { type: "prompts.used", payload: { success: false } });
+    return;
+  }
+  try {
+    await ctx.promptUsage.record(slug);
+    send(ws, { type: "prompts.used", payload: { success: true, slug } });
+  } catch {
+    send(ws, { type: "prompts.used", payload: { success: false } });
+  }
+}
+async function handlePromptsRecent(ws, ctx) {
+  if (!ctx.promptUsage) {
+    send(ws, { type: "prompts.recent", payload: { slugs: [] } });
+    return;
+  }
+  try {
+    const recent = await ctx.promptUsage.recent(50);
+    send(ws, { type: "prompts.recent", payload: { slugs: recent.map((r) => r.slug) } });
+  } catch (err) {
+    send(ws, { type: "prompts.recent", payload: { slugs: [], error: errMessage(err) } });
+  }
+}
+
+// src/server/design-handlers.ts
+import * as fs6 from "fs/promises";
+import * as path7 from "path";
+import {
+  applyTokenOverrides,
+  getDesignKitLoader,
+  getDesignState,
+  isDesignStack,
+  loadActiveKit,
+  materializeTokens,
+  recordKitChoice,
+  recordOverrides,
+  runDesignVerify,
+  setActiveKit,
+  setDesignOverrides
+} from "@wrongstack/core";
+function readOverrides(value) {
+  const out = {};
+  if (value && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) {
+      if (typeof v === "string") out[k] = v;
+    }
+  }
+  return out;
+}
+var FOUNDATIONS_ID = "_foundations";
+async function buildListPayload(ctx) {
+  const loader = getDesignKitLoader(ctx.projectRoot);
+  const manifests = (await loader.list()).filter((k) => k.id !== FOUNDATIONS_ID);
+  const kits = [];
+  for (const m of manifests) {
+    const tokens = await loader.readTokens(m.id);
+    kits.push({
+      id: m.id,
+      name: m.name,
+      aesthetic: m.aesthetic,
+      bestFor: m.bestFor,
+      stacks: m.stacks,
+      tags: m.tags,
+      light: tokens?.light ?? {},
+      dark: tokens?.dark ?? {}
+    });
+  }
+  const state = ctx.agentMeta ? getDesignState(ctx.agentMeta) : void 0;
+  const persisted = await loadActiveKit(ctx.projectRoot).catch(() => void 0);
+  return {
+    kits,
+    activeKit: state?.activeKit ?? persisted?.kit ?? null,
+    stack: state?.stack ?? persisted?.stack ?? null,
+    overrides: state?.overrides ?? persisted?.overrides ?? {}
+  };
+}
+async function handleDesignList(ws, ctx) {
+  try {
+    send(ws, { type: "design.list", payload: await buildListPayload(ctx) });
+  } catch (err) {
+    send(ws, {
+      type: "design.list",
+      payload: { kits: [], activeKit: null, stack: null, error: String(err) }
+    });
+  }
+}
+async function handleDesignState(ws, ctx) {
+  const state = ctx.agentMeta ? getDesignState(ctx.agentMeta) : void 0;
+  send(ws, {
+    type: "design.state",
+    payload: {
+      activeKit: state?.activeKit ?? null,
+      stack: state?.stack ?? null,
+      overrides: state?.overrides ?? {}
+    }
+  });
+}
+async function handleDesignUse(ws, ctx, msg) {
+  const payload = msg.payload ?? {};
+  const kitId = typeof payload.kit === "string" ? payload.kit.trim() : "";
+  if (!kitId) {
+    send(ws, { type: "design.use", payload: { ok: false, error: "No kit id provided" } });
+    return;
+  }
+  try {
+    const loader = getDesignKitLoader(ctx.projectRoot);
+    const kit = await loader.find(kitId);
+    if (!kit) {
+      send(ws, { type: "design.use", payload: { ok: false, kit: kitId, error: "Kit not found" } });
+      return;
+    }
+    const stackArg = typeof payload.stack === "string" ? payload.stack : void 0;
+    const stack = stackArg && isDesignStack(stackArg) ? stackArg : kit.stacks[0] ?? "web";
+    const persisted = await loadActiveKit(ctx.projectRoot).catch(() => void 0);
+    const keep = persisted?.kit === kit.id ? persisted.overrides ?? {} : {};
+    const overrides = { ...keep, ...readOverrides(payload.overrides) };
+    if (ctx.agentMeta) setActiveKit(ctx.agentMeta, kit.id, stack, overrides);
+    await recordKitChoice(
+      ctx.projectRoot,
+      kit.id,
+      stack,
+      "webui",
+      (/* @__PURE__ */ new Date()).toISOString(),
+      Object.keys(overrides).length ? overrides : void 0
+    );
+    const body = await loader.readBody(kit.id, stack);
+    const rawTokens = await loader.readTokens(kit.id);
+    const tokens = rawTokens ? applyTokenOverrides(rawTokens, overrides) : rawTokens;
+    send(ws, {
+      type: "design.use",
+      payload: {
+        ok: true,
+        kit: kit.id,
+        name: kit.name,
+        aesthetic: kit.aesthetic,
+        stack,
+        body,
+        overrides,
+        light: tokens?.light ?? {},
+        dark: tokens?.dark ?? {}
+      }
+    });
+  } catch (err) {
+    send(ws, { type: "design.use", payload: { ok: false, kit: kitId, error: String(err) } });
+  }
+}
+async function handleDesignSet(ws, ctx, msg) {
+  const patch = readOverrides(msg.payload?.overrides);
+  if (Object.keys(patch).length === 0) {
+    send(ws, { type: "design.set", payload: { ok: false, error: "No overrides provided" } });
+    return;
+  }
+  try {
+    const merged = await recordOverrides(ctx.projectRoot, patch, (/* @__PURE__ */ new Date()).toISOString());
+    if (!merged) {
+      send(ws, { type: "design.set", payload: { ok: false, error: "No active kit" } });
+      return;
+    }
+    if (ctx.agentMeta) setDesignOverrides(ctx.agentMeta, merged);
+    send(ws, { type: "design.set", payload: { ok: true, overrides: merged } });
+  } catch (err) {
+    send(ws, { type: "design.set", payload: { ok: false, error: String(err) } });
+  }
+}
+async function handleDesignMaterialize(ws, ctx, msg) {
+  const payload = msg.payload ?? {};
+  try {
+    const active = await loadActiveKit(ctx.projectRoot);
+    if (!active) {
+      send(ws, { type: "design.materialize", payload: { ok: false, error: "No active kit" } });
+      return;
+    }
+    const loader = getDesignKitLoader(ctx.projectRoot);
+    const stackArg = typeof payload.stack === "string" ? payload.stack : void 0;
+    const stack = stackArg && isDesignStack(stackArg) ? stackArg : active.stack && isDesignStack(active.stack) ? active.stack : "web";
+    const raw = await loader.readTokens(active.kit);
+    if (!raw) {
+      send(ws, { type: "design.materialize", payload: { ok: false, error: "Kit has no tokens" } });
+      return;
+    }
+    const tokens = applyTokenOverrides(raw, active.overrides);
+    const result = materializeTokens({
+      tokens,
+      stack,
+      kitId: active.kit,
+      outPath: typeof payload.out === "string" ? payload.out : void 0
+    });
+    const abs = path7.join(ctx.projectRoot, result.path);
+    await fs6.mkdir(path7.dirname(abs), { recursive: true });
+    await fs6.writeFile(abs, result.content);
+    send(ws, {
+      type: "design.materialize",
+      payload: { ok: true, path: result.path, format: result.format, stack }
+    });
+  } catch (err) {
+    send(ws, { type: "design.materialize", payload: { ok: false, error: String(err) } });
+  }
+}
+async function handleDesignVerify(ws, ctx) {
+  try {
+    const active = await loadActiveKit(ctx.projectRoot);
+    if (!active) {
+      send(ws, { type: "design.verify", payload: { ok: false, error: "No active kit" } });
+      return;
+    }
+    const loader = getDesignKitLoader(ctx.projectRoot);
+    const raw = await loader.readTokens(active.kit);
+    if (!raw) {
+      send(ws, { type: "design.verify", payload: { ok: false, error: "Kit has no tokens" } });
+      return;
+    }
+    const tokens = applyTokenOverrides(raw, active.overrides);
+    const report = await runDesignVerify(ctx.projectRoot, tokens);
+    send(ws, {
+      type: "design.verify",
+      payload: {
+        ok: true,
+        kit: active.kit,
+        filesScanned: report.filesScanned,
+        score: report.score,
+        violations: report.violations.slice(0, 50),
+        violationCount: report.violations.length
+      }
+    });
+  } catch (err) {
+    send(ws, { type: "design.verify", payload: { ok: false, error: String(err) } });
+  }
+}
+
 // src/server/index.ts
 import {
   Agent,
@@ -2972,6 +3600,8 @@ import {
   DefaultSessionReader,
   DefaultSessionStore as DefaultSessionStore2,
   DefaultSkillLoader,
+  DefaultPromptLoader,
+  PromptUsageStore,
   DefaultSystemPromptBuilder as DefaultSystemPromptBuilder3,
   DefaultTokenCounter,
   AnnotationsStore,
@@ -2986,17 +3616,20 @@ import {
   ToolRegistry,
   atomicWrite as atomicWrite6,
   createDefaultPipelines,
+  installDesignStudioMiddleware,
   createSessionEventBridge,
   resolveSessionLoggingConfig,
   DEFAULT_CONTEXT_WINDOW_MODE_ID as DEFAULT_CONTEXT_WINDOW_MODE_ID2,
   DEFAULT_SESSION_PRUNE_DAYS,
   DEFAULT_TOOLS_CONFIG,
   applyToolDescriptionModes,
+  applyToolResultRenderModes,
   resolveContextWindowPolicy as resolveContextWindowPolicy2,
   enhanceUserPrompt,
   gatedEnhancerReasoning,
   recentTextTurns,
-  resolveProviderModelList
+  resolveProviderModelList,
+  cleanupStaleSddWorktrees as cleanupStaleSddWorktrees3
 } from "@wrongstack/core";
 import { ToolExecutor } from "@wrongstack/core/execution";
 import { decryptConfigSecrets as decryptConfigSecrets2, encryptConfigSecrets as encryptConfigSecrets2 } from "@wrongstack/core/security";
@@ -3031,6 +3664,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 });
@@ -3039,6 +3679,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;
@@ -3058,10 +3711,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) {
@@ -3085,11 +3745,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();
@@ -3166,17 +3828,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: {
@@ -3223,6 +3895,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 [
@@ -3233,13 +3961,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 ?? "" : "";
         }
       });
@@ -3374,6 +4107,10 @@ Type: ${task.type}`;
     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,
@@ -3575,7 +4312,7 @@ var SpecsWebSocketHandler = class {
 };
 
 // src/server/sdd-board-ws-handler.ts
-import { SddBoardStore } from "@wrongstack/core";
+import { applySddLifecycle, SddBoardStore } from "@wrongstack/core";
 var CONTROL_TYPES = /* @__PURE__ */ new Set([
   "pause",
   "resume",
@@ -3589,19 +4326,19 @@ var CONTROL_TYPES = /* @__PURE__ */ new Set([
   "set_task_verification",
   "cancel_task",
   "delete_task",
-  "split_task",
-  // Lifecycle (pair with a prior `stop`): sweep worktrees / revert merged commits.
-  "cleanup_worktrees",
-  "rollback"
+  "split_task"
 ]);
+var LIFECYCLE_TYPES = /* @__PURE__ */ new Set(["cleanup_worktrees", "rollback", "destroy"]);
 var SddBoardWebSocketHandler = class {
   store;
   clients = /* @__PURE__ */ new Set();
+  lifecycle;
   latest = null;
   poll = null;
   unsub = null;
-  constructor(boardsDir, events) {
+  constructor(boardsDir, events, lifecycle) {
     this.store = new SddBoardStore({ baseDir: boardsDir });
+    this.lifecycle = lifecycle;
     if (events) {
       const handler = (e) => {
         this.latest = e.snapshot;
@@ -3630,6 +4367,10 @@ var SddBoardWebSocketHandler = class {
       return;
     }
     const action = msg.type.replace(/^sdd\.board\./, "");
+    if (LIFECYCLE_TYPES.has(action)) {
+      await this.applyLifecycle(action, msg.payload);
+      return;
+    }
     if (CONTROL_TYPES.has(action)) {
       const runId = msg.payload?.runId ?? this.latest?.runId ?? (await this.store.list())[0]?.runId;
       if (runId) {
@@ -3641,6 +4382,40 @@ var SddBoardWebSocketHandler = class {
       }
     }
   }
+  /**
+   * Apply a cleanup/rollback/destroy from disk and broadcast a structured
+   * `sdd.board.lifecycle_result`. Refuses (no-op) while a run is still active —
+   * the user must stop it first; the UI gates the buttons on `!active` and the
+   * Destroy flow auto-stops then waits before sending `destroy`.
+   */
+  async applyLifecycle(op, payload) {
+    if (!this.lifecycle) {
+      this.broadcast({
+        type: "sdd.board.lifecycle_result",
+        payload: { op, ok: false, reason: "Lifecycle operations are not available in this session." }
+      });
+      return;
+    }
+    if (this.latest && (this.latest.status === "running" || this.latest.status === "paused")) {
+      this.broadcast({
+        type: "sdd.board.lifecycle_result",
+        payload: { op, ok: false, reason: "Stop the run first, then retry." }
+      });
+      return;
+    }
+    const runId = payload?.runId ?? this.latest?.runId;
+    const result = await applySddLifecycle(op, {
+      projectRoot: this.lifecycle.projectRoot,
+      paths: this.lifecycle.paths,
+      runId,
+      revertMerged: payload?.revertMerged === true
+    });
+    this.broadcast({ type: "sdd.board.lifecycle_result", payload: result });
+    if (op === "destroy" && result.ok) {
+      this.latest = null;
+      this.broadcast({ type: "sdd.board.snapshot", payload: null });
+    }
+  }
   dispose() {
     if (this.poll) clearInterval(this.poll);
     this.unsub?.();
@@ -3684,6 +4459,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;
@@ -3722,7 +4503,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;
       }
@@ -3742,7 +4524,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) {
@@ -3813,9 +4595,10 @@ var SddWizardWebSocketHandler = class {
 };
 
 // src/server/sdd-wizard-wiring.ts
-import * as path7 from "path";
+import * as path8 from "path";
 import { spawnSync as spawnSync2 } from "child_process";
 import {
+  cleanupStaleSddWorktrees,
   makeCommandVerifier,
   makeLlmSubtaskGenerator,
   SddBoardStore as SddBoardStore2,
@@ -3827,6 +4610,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;
@@ -3835,11 +4619,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?.();
@@ -3849,23 +4633,30 @@ function buildSddWizardDeps(opts) {
     makeDriver: () => new SddInterviewDriver({
       specStore: new SpecStore2({ baseDir: opts.paths.projectSpecs }),
       graphStore: new TaskGraphStore2({ baseDir: opts.paths.projectTaskGraphs }),
-      sessionPath: path7.join(opts.paths.projectDir, "sdd-wizard-session.json")
+      sessionPath: path8.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",
           windowsHide: true
         }).stdout?.trim() === "true";
-        if (inGit) worktrees = new WorktreeManager2({ projectRoot: opts.projectRoot, events: opts.events });
+        if (inGit) {
+          await cleanupStaleSddWorktrees({
+            projectRoot: opts.projectRoot,
+            boardsDir: opts.paths.projectSddBoards
+          }).catch(() => void 0);
+          worktrees = new WorktreeManager2({ projectRoot: opts.projectRoot, events: opts.events });
+        }
       }
       const boardStore = new SddBoardStore2({ baseDir: opts.paths.projectSddBoards });
       const verifyTask = makeCommandVerifier();
@@ -4644,16 +5435,16 @@ var CollaborationWebSocketHandler = class {
 };
 
 // src/server/projects-manifest.ts
-import * as fs6 from "fs/promises";
-import * as path8 from "path";
+import * as fs7 from "fs/promises";
+import * as path9 from "path";
 import { projectSlug } from "@wrongstack/core";
 function projectsJsonPath(globalConfigPath) {
-  const base = path8.dirname(globalConfigPath);
-  return path8.join(base, "projects.json");
+  const base = path9.dirname(globalConfigPath);
+  return path9.join(base, "projects.json");
 }
 async function loadManifest(globalConfigPath) {
   try {
-    const raw = await fs6.readFile(projectsJsonPath(globalConfigPath), "utf8");
+    const raw = await fs7.readFile(projectsJsonPath(globalConfigPath), "utf8");
     const parsed = JSON.parse(raw);
     return { projects: parsed.projects ?? [] };
   } catch {
@@ -4662,16 +5453,16 @@ async function loadManifest(globalConfigPath) {
 }
 async function saveManifest(manifest, globalConfigPath) {
   const file = projectsJsonPath(globalConfigPath);
-  await fs6.mkdir(path8.dirname(file), { recursive: true });
-  await fs6.writeFile(file, JSON.stringify(manifest, null, 2), "utf8");
+  await fs7.mkdir(path9.dirname(file), { recursive: true });
+  await fs7.writeFile(file, JSON.stringify(manifest, null, 2), "utf8");
 }
 function generateProjectSlug(rootPath) {
   return projectSlug(rootPath);
 }
 async function ensureProjectDataDir(slug, globalConfigPath) {
-  const base = path8.dirname(globalConfigPath);
-  const dir = path8.join(base, "projects", slug);
-  await fs6.mkdir(dir, { recursive: true });
+  const base = path9.dirname(globalConfigPath);
+  const dir = path9.join(base, "projects", slug);
+  await fs7.mkdir(dir, { recursive: true });
   return dir;
 }
 
@@ -4833,16 +5624,22 @@ function clampDim(value, fallback) {
 }
 
 // src/server/worktree-ws-handler.ts
+import { join as join6, resolve as resolve6, sep as sep4 } from "path";
+import { cleanupStaleSddWorktrees as cleanupStaleSddWorktrees2, WorktreeManager as WorktreeManager3 } from "@wrongstack/core";
 import { toErrorMessage as toErrorMessage4 } from "@wrongstack/core/utils";
 var MAX_ACTIVITY = 6;
+var ACTIVE_STATUSES = /* @__PURE__ */ new Set(["allocating", "active", "committing", "merging"]);
+var MANAGED_BRANCH_RE = /^wstack\/ap\/[A-Za-z0-9._/-]+$/;
 var WorktreeWebSocketHandler = class {
-  constructor(events, logger) {
+  constructor(events, logger, management) {
     this.events = events;
     this.logger = logger;
+    this.management = management;
     this.subscribe();
   }
   events;
   logger;
+  management;
   clients = /* @__PURE__ */ new Set();
   handles = /* @__PURE__ */ new Map();
   baseBranch = "";
@@ -4853,12 +5650,197 @@ var WorktreeWebSocketHandler = class {
     ws.on("close", () => this.clients.delete(ws));
     ws.on("error", () => this.clients.delete(ws));
     this.send(ws, this.stateMessage());
+    void this.scanAndBroadcast();
+  }
+  /** Handle worktree-panel control messages (scan / clean / per-row ops). */
+  async handleMessage(msg) {
+    if (msg.type === "worktree.scan") {
+      await this.scanAndBroadcast();
+      return true;
+    }
+    if (msg.type === "worktree.cleanup") {
+      await this.cleanupOrphans();
+      return true;
+    }
+    if (msg.type === "worktree.remove") {
+      await this.removeOne(msg.payload?.["dir"], msg.payload?.["branch"]);
+      return true;
+    }
+    if (msg.type === "worktree.merge") {
+      await this.mergeBranch(msg.payload?.["branch"]);
+      return true;
+    }
+    if (msg.type === "worktree.diff") {
+      await this.diffOne(msg.payload?.["dir"], msg.payload?.["baseBranch"]);
+      return true;
+    }
+    return false;
   }
   dispose() {
     for (const off of this.offs) off();
     this.offs.length = 0;
     this.stopBroadcast();
   }
+  // ── orphan management ─────────────────────────────────────────────────────
+  /** Absolute managed-worktrees root for this project. */
+  worktreesRoot() {
+    return resolve6(join6(this.management.projectRoot, ".wrongstack", "worktrees"));
+  }
+  /** True iff `dir` resolves strictly inside the managed worktrees root. */
+  underRoot(dir) {
+    const abs = resolve6(dir);
+    const root = this.worktreesRoot();
+    return abs !== root && abs.startsWith(root + sep4);
+  }
+  /** Branches of worktrees a live in-session run currently owns. */
+  liveActiveBranches() {
+    const live = /* @__PURE__ */ new Set();
+    for (const h of this.handles.values()) {
+      if (ACTIVE_STATUSES.has(h.status) && h.branch) live.add(h.branch);
+    }
+    return live;
+  }
+  /**
+   * Scan the disk for managed worktrees/branches NOT owned by a live in-session
+   * run and broadcast them as orphans, with whether it is safe to clean now.
+   * No-op (empty inventory) when management deps were not wired.
+   */
+  async scanAndBroadcast() {
+    if (!this.management) {
+      this.broadcast({ type: "worktree.orphans", payload: { orphans: [], canClean: false } });
+      return;
+    }
+    try {
+      const wt = new WorktreeManager3({ projectRoot: this.management.projectRoot });
+      const { worktrees, branches } = await wt.listManaged();
+      const live = this.liveActiveBranches();
+      const orphans = [];
+      const seenBranches = /* @__PURE__ */ new Set();
+      for (const w of worktrees) {
+        if (w.branch && live.has(w.branch)) continue;
+        if (w.branch) seenBranches.add(w.branch);
+        orphans.push({ kind: "worktree", dir: w.dir, branch: w.branch });
+      }
+      for (const b of branches) {
+        if (live.has(b) || seenBranches.has(b)) continue;
+        orphans.push({ kind: "branch", branch: b });
+      }
+      const canClean = this.liveActiveBranches().size === 0;
+      this.broadcast({
+        type: "worktree.orphans",
+        payload: {
+          orphans,
+          canClean,
+          reason: canClean ? void 0 : "a run is live in this session"
+        }
+      });
+    } catch (err) {
+      this.logger.debug?.(`worktree orphan scan failed: ${toErrorMessage4(err)}`);
+      this.broadcast({ type: "worktree.orphans", payload: { orphans: [], canClean: false } });
+    }
+  }
+  /**
+   * Force-remove every orphaned worktree + branch. Refused while a run is live —
+   * in this session (active handles) OR another process (the SDD board liveness
+   * guard inside cleanupStaleSddWorktrees). Best-effort; reports the outcome.
+   */
+  async cleanupOrphans() {
+    if (!this.management) {
+      this.broadcast({
+        type: "worktree.cleanup_result",
+        payload: { ok: false, removed: 0, reason: "cleanup is not available in this session" }
+      });
+      return;
+    }
+    if (this.liveActiveBranches().size > 0) {
+      this.broadcast({
+        type: "worktree.cleanup_result",
+        payload: { ok: false, removed: 0, reason: "a run is live in this session \u2014 stop it first" }
+      });
+      return;
+    }
+    const res = await cleanupStaleSddWorktrees2({
+      projectRoot: this.management.projectRoot,
+      boardsDir: this.management.boardsDir
+    });
+    if (res.skippedReason) {
+      this.broadcast({
+        type: "worktree.cleanup_result",
+        payload: { ok: false, removed: 0, reason: res.skippedReason }
+      });
+      await this.scanAndBroadcast();
+      return;
+    }
+    for (const [id, h] of [...this.handles]) {
+      if (!ACTIVE_STATUSES.has(h.status)) this.handles.delete(id);
+    }
+    this.broadcast({ type: "worktree.cleanup_result", payload: { ok: true, removed: res.removed } });
+    this.broadcastState();
+    await this.scanAndBroadcast();
+  }
+  /** Remove/discard ONE worktree + branch. Refused while a live run owns it. */
+  async removeOne(dir, branch) {
+    if (!this.management || !dir && !branch) {
+      this.broadcast({ type: "worktree.cleanup_result", payload: { ok: false, removed: 0, reason: "nothing to remove" } });
+      return;
+    }
+    if (branch && !MANAGED_BRANCH_RE.test(branch)) {
+      this.broadcast({ type: "worktree.cleanup_result", payload: { ok: false, removed: 0, reason: "not a managed worktree branch" } });
+      return;
+    }
+    if (dir && !this.underRoot(dir)) {
+      this.broadcast({ type: "worktree.cleanup_result", payload: { ok: false, removed: 0, reason: "path is outside the managed worktrees root" } });
+      return;
+    }
+    if (branch && this.liveActiveBranches().has(branch)) {
+      this.broadcast({ type: "worktree.cleanup_result", payload: { ok: false, removed: 0, reason: "a run is live on this worktree \u2014 stop it first" } });
+      return;
+    }
+    let removed = false;
+    if (dir) {
+      const wt = new WorktreeManager3({ projectRoot: this.management.projectRoot });
+      ({ removed } = await wt.removeOne(dir, branch));
+    }
+    for (const [id, h] of [...this.handles]) {
+      if (branch && h.branch === branch || dir && h.handleId && dir.endsWith(h.handleId)) this.handles.delete(id);
+    }
+    this.broadcast({ type: "worktree.cleanup_result", payload: { ok: removed, removed: removed ? 1 : 0, reason: removed ? void 0 : "remove failed (not a managed worktree?)" } });
+    this.broadcastState();
+    await this.scanAndBroadcast();
+  }
+  /** Squash-merge ONE branch into base. Refused while a live run owns it. */
+  async mergeBranch(branch) {
+    if (!this.management || !branch) {
+      this.broadcast({ type: "worktree.merge_result", payload: { ok: false, branch: branch ?? "", reason: "no branch" } });
+      return;
+    }
+    if (!MANAGED_BRANCH_RE.test(branch)) {
+      this.broadcast({ type: "worktree.merge_result", payload: { ok: false, branch, reason: "not a managed worktree branch" } });
+      return;
+    }
+    if (this.liveActiveBranches().has(branch)) {
+      this.broadcast({ type: "worktree.merge_result", payload: { ok: false, branch, reason: "a run is live on this worktree \u2014 stop it first" } });
+      return;
+    }
+    const wt = new WorktreeManager3({ projectRoot: this.management.projectRoot });
+    const res = await wt.mergeBranch(branch);
+    this.broadcast({
+      type: "worktree.merge_result",
+      payload: { ok: res.ok, branch, conflict: res.conflict, conflictFiles: res.conflictFiles, reason: res.reason }
+    });
+    await this.scanAndBroadcast();
+  }
+  /** Compact change summary for one worktree checkout. */
+  async diffOne(dir, baseBranch) {
+    if (!this.management || !dir || !this.underRoot(dir)) {
+      this.broadcast({ type: "worktree.diff_result", payload: { dir: dir ?? "", summary: null } });
+      return;
+    }
+    const base = baseBranch && MANAGED_BRANCH_RE.test(baseBranch) ? baseBranch : void 0;
+    const wt = new WorktreeManager3({ projectRoot: this.management.projectRoot });
+    const summary = await wt.diffSummary(resolve6(dir), base);
+    this.broadcast({ type: "worktree.diff_result", payload: { dir, summary } });
+  }
   // ── internals ───────────────────────────────────────────────────────────
   subscribe() {
     const on = this.events.on.bind(this.events);
@@ -4870,6 +5852,7 @@ var WorktreeWebSocketHandler = class {
           handleId: e.handleId,
           ownerId: e.ownerId,
           ownerLabel: e.ownerLabel,
+          dir: e.dir,
           branch: e.branch,
           baseBranch: e.baseBranch,
           status: "active",
@@ -4972,10 +5955,10 @@ var WorktreeWebSocketHandler = class {
 };
 
 // src/server/mailbox-handlers.ts
-import { GlobalMailbox, resolveProjectDir } from "@wrongstack/core";
+import { GlobalMailbox, resolveProjectDir as resolveProjectDir2 } from "@wrongstack/core";
 async function handleMailboxMessages(ws, deps2, payload) {
   try {
-    const dir = resolveProjectDir(deps2.projectRoot, deps2.globalRoot);
+    const dir = resolveProjectDir2(deps2.projectRoot, deps2.globalRoot);
     const mb = new GlobalMailbox(dir);
     const messages = await mb.query({
       limit: payload?.limit ?? 30,
@@ -5011,7 +5994,7 @@ async function handleMailboxMessages(ws, deps2, payload) {
 }
 async function handleMailboxAgents(ws, deps2, payload) {
   try {
-    const dir = resolveProjectDir(deps2.projectRoot, deps2.globalRoot);
+    const dir = resolveProjectDir2(deps2.projectRoot, deps2.globalRoot);
     const mb = new GlobalMailbox(dir);
     const agents = payload?.onlineOnly ? await mb.getOnlineAgents() : await mb.getAgentStatuses();
     send(ws, {
@@ -5040,7 +6023,7 @@ async function handleMailboxAgents(ws, deps2, payload) {
 }
 async function handleMailboxClear(ws, deps2) {
   try {
-    const dir = resolveProjectDir(deps2.projectRoot, deps2.globalRoot);
+    const dir = resolveProjectDir2(deps2.projectRoot, deps2.globalRoot);
     const mb = new GlobalMailbox(dir);
     await mb.clearAll();
     send(ws, { type: "mailbox.cleared", payload: {} });
@@ -5050,7 +6033,7 @@ async function handleMailboxClear(ws, deps2) {
 }
 async function handleMailboxPurge(ws, deps2, opts) {
   try {
-    const dir = resolveProjectDir(deps2.projectRoot, deps2.globalRoot);
+    const dir = resolveProjectDir2(deps2.projectRoot, deps2.globalRoot);
     const mb = new GlobalMailbox(dir);
     const result = await mb.purgeStale(opts);
     send(ws, { type: "mailbox.purged", payload: result });
@@ -5097,14 +6080,14 @@ function registerShutdownHandlers(res) {
 
 // src/server/instance-registry.ts
 import * as os from "os";
-import * as path9 from "path";
-import * as fs7 from "fs/promises";
+import * as path10 from "path";
+import * as fs8 from "fs/promises";
 import { atomicWrite as atomicWrite3 } from "@wrongstack/core";
 function defaultBaseDir() {
-  return path9.join(os.homedir(), ".wrongstack");
+  return path10.join(os.homedir(), ".wrongstack");
 }
 function registryPath(baseDir = defaultBaseDir()) {
-  return path9.join(baseDir, "webui-instances.json");
+  return path10.join(baseDir, "webui-instances.json");
 }
 function isPidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -5117,7 +6100,7 @@ function isPidAlive(pid) {
 }
 async function load(file) {
   try {
-    const raw = await fs7.readFile(file, "utf8");
+    const raw = await fs8.readFile(file, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed?.version === 1 && Array.isArray(parsed.instances)) {
       return parsed;
@@ -5176,16 +6159,16 @@ function formatInstances(instances) {
 // src/server/port-utils.ts
 import * as net from "net";
 function isPortFree(host, port) {
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     const srv = net.createServer();
-    srv.once("error", () => resolve9(false));
+    srv.once("error", () => resolve10(false));
     srv.once("listening", () => {
-      srv.close(() => resolve9(true));
+      srv.close(() => resolve10(true));
     });
     try {
       srv.listen(port, host);
     } catch {
-      resolve9(false);
+      resolve10(false);
     }
   });
 }
@@ -5266,15 +6249,15 @@ import { DefaultSecretScrubber } from "@wrongstack/core";
 import { probeLocalLlm } from "@wrongstack/runtime/probe";
 
 // src/server/provider-config-io.ts
-import * as fs8 from "fs/promises";
-import * as path10 from "path";
+import * as fs9 from "fs/promises";
+import * as path11 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 fs8.readFile(configPath, "utf8");
+    raw = await fs9.readFile(configPath, "utf8");
   } catch {
     return {};
   }
@@ -5291,7 +6274,7 @@ async function saveProviders(configPath, vault, providers) {
   let raw;
   let fileExists = true;
   try {
-    raw = await fs8.readFile(configPath, "utf8");
+    raw = await fs9.readFile(configPath, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") {
       throw new Error(
@@ -5629,7 +6612,8 @@ function createProviderHandlers(deps2) {
 
 // src/server/mode-handlers.ts
 import {
-  DefaultSystemPromptBuilder
+  DefaultSystemPromptBuilder,
+  resolveWstackPaths
 } from "@wrongstack/core";
 function createModeHandlers(ctx) {
   return {
@@ -5677,13 +6661,18 @@ function createModeHandlers(ctx) {
         }
         ctx.setModeId(id);
         const modePrompt = id === "default" ? "" : (await ctx.modeStore.getMode(id))?.prompt ?? "";
+        const paths = resolveWstackPaths({ projectRoot: ctx.projectRoot, globalRoot: ctx.globalRoot });
         const freshBuilder = new DefaultSystemPromptBuilder({
           memoryStore: ctx.memoryStore,
           skillLoader: ctx.skillLoader,
           modeStore: ctx.modeStore,
           modeId: id,
           modePrompt,
-          modelCapabilities: ctx.modelCapabilities
+          modelCapabilities: ctx.modelCapabilities,
+          instructionPaths: {
+            globalDir: paths.globalInstructions,
+            projectDir: paths.inProjectInstructions
+          }
         });
         ctx.context.systemPrompt = await freshBuilder.build({
           cwd: ctx.projectRoot,
@@ -5705,12 +6694,13 @@ function createModeHandlers(ctx) {
 }
 
 // src/server/project-handlers.ts
-import * as fs9 from "fs/promises";
-import * as path11 from "path";
+import * as fs10 from "fs/promises";
+import * as path12 from "path";
 import {
   DefaultSessionStore,
   DefaultSystemPromptBuilder as DefaultSystemPromptBuilder2,
-  getSessionRegistry
+  getSessionRegistry,
+  resolveWstackPaths as resolveWstackPaths2
 } from "@wrongstack/core";
 function createProjectHandlers(ctx) {
   return {
@@ -5733,9 +6723,9 @@ function createProjectHandlers(ctx) {
       }
       const { root: addRoot, name: displayName } = parsed.value;
       try {
-        const resolved = path11.resolve(addRoot);
-        await fs9.access(resolved);
-        const stat3 = await fs9.stat(resolved);
+        const resolved = path12.resolve(addRoot);
+        await fs10.access(resolved);
+        const stat3 = await fs10.stat(resolved);
         if (!stat3.isDirectory()) throw new Error(`Not a directory: ${resolved}`);
         const manifest = await loadManifest(ctx.globalConfigPath);
         const existing = manifest.projects.find((p) => p.root === resolved);
@@ -5751,7 +6741,7 @@ function createProjectHandlers(ctx) {
           });
           return;
         }
-        const name2 = displayName?.trim() || path11.basename(resolved);
+        const name2 = displayName?.trim() || path12.basename(resolved);
         const slug = generateProjectSlug(resolved);
         await ensureProjectDataDir(slug, ctx.globalConfigPath);
         const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -5764,7 +6754,7 @@ function createProjectHandlers(ctx) {
       } catch (err) {
         send(ws, {
           type: "projects.added",
-          payload: { name: path11.basename(addRoot), root: addRoot, slug: "", message: errMessage(err) }
+          payload: { name: path12.basename(addRoot), root: addRoot, slug: "", message: errMessage(err) }
         });
       }
     },
@@ -5779,17 +6769,17 @@ function createProjectHandlers(ctx) {
       }
       const { root: selRoot, name: selName } = parsed.value;
       try {
-        const resolved = path11.resolve(selRoot);
+        const resolved = path12.resolve(selRoot);
         try {
-          await fs9.access(resolved);
-          const stat3 = await fs9.stat(resolved);
+          await fs10.access(resolved);
+          const stat3 = await fs10.stat(resolved);
           if (!stat3.isDirectory()) throw new Error(`Not a directory: ${resolved}`);
         } catch (err) {
           send(ws, {
             type: "projects.selected",
             payload: {
               root: selRoot,
-              name: selName || path11.basename(selRoot),
+              name: selName || path12.basename(selRoot),
               message: `Cannot switch: ${errMessage(err)}`
             }
           });
@@ -5801,7 +6791,7 @@ function createProjectHandlers(ctx) {
           entry.lastSeen = (/* @__PURE__ */ new Date()).toISOString();
           entry.lastWorkingDir = resolved;
         } else {
-          const name2 = selName?.trim() || path11.basename(resolved);
+          const name2 = selName?.trim() || path12.basename(resolved);
           const slug = generateProjectSlug(resolved);
           manifest.projects.push({
             name: name2,
@@ -5823,13 +6813,21 @@ function createProjectHandlers(ctx) {
         try {
           const modeId = ctx.getModeId();
           const switchMode = modeId === "default" ? void 0 : await ctx.modeStore.getMode(modeId);
+          const switchPaths = resolveWstackPaths2({
+            projectRoot: resolved,
+            globalRoot: ctx.wpaths.globalRoot
+          });
           const switchBuilder = new DefaultSystemPromptBuilder2({
             memoryStore: ctx.memoryStore,
             skillLoader: ctx.skillLoader,
             modeStore: ctx.modeStore,
             modeId,
             modePrompt: switchMode?.prompt ?? "",
-            modelCapabilities: ctx.modelCapabilities
+            modelCapabilities: ctx.modelCapabilities,
+            instructionPaths: {
+              globalDir: switchPaths.globalInstructions,
+              projectDir: switchPaths.inProjectInstructions
+            }
           });
           ctx.context.systemPrompt = await switchBuilder.build({
             cwd: resolved,
@@ -5840,13 +6838,13 @@ function createProjectHandlers(ctx) {
           });
         } catch {
         }
-        const newSessionsDir = path11.join(
-          path11.dirname(ctx.globalConfigPath),
+        const newSessionsDir = path12.join(
+          path12.dirname(ctx.globalConfigPath),
           "projects",
           switchSlug,
           "sessions"
         );
-        await fs9.mkdir(newSessionsDir, { recursive: true });
+        await fs10.mkdir(newSessionsDir, { recursive: true });
         const newSessionStore = new DefaultSessionStore({ dir: newSessionsDir });
         const oldSession = ctx.getSession();
         const oldSessionId = oldSession.id;
@@ -5880,7 +6878,7 @@ function createProjectHandlers(ctx) {
             sessionId: newSession.id,
             projectSlug: switchSlug,
             projectRoot: resolved,
-            projectName: path11.basename(resolved),
+            projectName: path12.basename(resolved),
             workingDir: resolved,
             clientType: "webui",
             pid: process.pid,
@@ -5892,8 +6890,8 @@ function createProjectHandlers(ctx) {
           type: "projects.selected",
           payload: {
             root: resolved,
-            name: selName || path11.basename(resolved),
-            message: `Switched to ${selName || path11.basename(resolved)}`
+            name: selName || path12.basename(resolved),
+            message: `Switched to ${selName || path12.basename(resolved)}`
           }
         });
         broadcast(ctx.clients, {
@@ -5913,7 +6911,7 @@ function createProjectHandlers(ctx) {
           type: "projects.selected",
           payload: {
             root: selRoot,
-            name: selName || path11.basename(selRoot),
+            name: selName || path12.basename(selRoot),
             message: errMessage(err)
           }
         });
@@ -5944,7 +6942,7 @@ function createProjectHandlers(ctx) {
 }
 
 // src/server/session-handlers.ts
-import * as path12 from "path";
+import * as path13 from "path";
 import {
   DEFAULT_CONTEXT_WINDOW_MODE_ID,
   repairToolUseAdjacency,
@@ -6286,7 +7284,7 @@ function createSessionHandlers(ctx) {
         const { DefaultSessionRewinder } = await import("@wrongstack/core");
         const projectRoot = ctx.getProjectRoot();
         const rewinder = new DefaultSessionRewinder(
-          path12.join(projectRoot, ".wrongstack", "sessions"),
+          path13.join(projectRoot, ".wrongstack", "sessions"),
           projectRoot
         );
         const checkpoints = await rewinder.listCheckpoints(ctx.getSession().id);
@@ -6301,7 +7299,7 @@ function createSessionHandlers(ctx) {
         const { DefaultSessionRewinder } = await import("@wrongstack/core");
         const projectRoot = ctx.getProjectRoot();
         const rewinder = new DefaultSessionRewinder(
-          path12.join(projectRoot, ".wrongstack", "sessions"),
+          path13.join(projectRoot, ".wrongstack", "sessions"),
           projectRoot
         );
         await rewinder.rewindToCheckpoint(ctx.getSession().id, checkpointIndex);
@@ -6677,9 +7675,9 @@ async function handleSddBoardRoute(_ws, msg, handlers) {
 }
 
 // src/server/setup-events.ts
-import * as fs10 from "fs/promises";
+import * as fs11 from "fs/promises";
 import { watch as fsWatch } from "fs";
-import * as path13 from "path";
+import * as path14 from "path";
 function setupEvents(deps2) {
   const { events, broadcast: broadcast2, clients, config, context, pendingConfirms, globalConfigPath, sessionBridge, wpaths, watcherMetrics, onFleetBroadcaster } = deps2;
   const disposers = [];
@@ -6768,6 +7766,22 @@ function setupEvents(deps2) {
     }).catch(() => {
     });
     broadcast2(clients, { type: "todos.updated", payload: { todos: [...context.todos] } });
+    const sideEffects = context.sideEffects ?? [];
+    if (sideEffects.length > 0) {
+      broadcast2(clients, {
+        type: "side_effects",
+        payload: {
+          sideEffects: sideEffects.slice(-50).map((se) => ({
+            toolUseId: se.toolUseId,
+            toolName: se.toolName,
+            ts: se.ts,
+            input: se.input,
+            outcome: se.outcome,
+            risk: se.risk
+          }))
+        }
+      });
+    }
     if (e.name === "task" || e.name === "plan" || e.name === "todo") {
       void (async () => {
         try {
@@ -7146,16 +8160,16 @@ function setupEvents(deps2) {
     if (wpaths?.projectStatus) {
       try {
         const statusFile = wpaths.projectStatus(e.projectHash);
-        const dir = path13.dirname(statusFile);
-        await fs10.mkdir(dir, { recursive: true });
-        await fs10.writeFile(statusFile, JSON.stringify(e, null, 2), "utf-8");
+        const dir = path14.dirname(statusFile);
+        await fs11.mkdir(dir, { recursive: true });
+        await fs11.writeFile(statusFile, JSON.stringify(e, null, 2), "utf-8");
       } catch (err) {
         console.error("[setup-events] Failed to write status.json:", err);
       }
     }
   });
   if (wpaths?.projectStatus && wpaths.configDir) {
-    const projectsDir = path13.join(wpaths.configDir, "projects");
+    const projectsDir = path14.join(wpaths.configDir, "projects");
     const knownProjectHashes = /* @__PURE__ */ new Set();
     const debounceTimers = /* @__PURE__ */ new Map();
     const DEBOUNCE_MS = 150;
@@ -7218,20 +8232,20 @@ function setupEvents(deps2) {
     let watcher;
     const startWatcher = async () => {
       try {
-        await fs10.mkdir(projectsDir, { recursive: true });
+        await fs11.mkdir(projectsDir, { recursive: true });
         watcher = fsWatch(projectsDir, { persistent: true, recursive: true }, async (eventType, filename) => {
           if (eventType === "change") {
             if (filename == null) return;
             if (watcherMetrics) watcherMetrics.fileChangesDetected++;
-            const targetFile = path13.join(projectsDir, String(filename));
+            const targetFile = path14.join(projectsDir, String(filename));
             if (targetFile.endsWith("status.json")) {
-              const projectHash2 = path13.basename(path13.dirname(targetFile));
+              const projectHash2 = path14.basename(path14.dirname(targetFile));
               if (knownProjectHashes.size > 0 && !knownProjectHashes.has(projectHash2)) {
                 return;
               }
               if (watcherMetrics) watcherMetrics.filesProcessed++;
               try {
-                const content = await fs10.readFile(targetFile, "utf-8");
+                const content = await fs11.readFile(targetFile, "utf-8");
                 const statusData = JSON.parse(content);
                 if (statusData.projectHash) {
                   const hash = String(statusData.projectHash);
@@ -7283,7 +8297,7 @@ function setupEvents(deps2) {
       }
     });
   }
-  const globalRoot = globalConfigPath ? path13.dirname(globalConfigPath) : void 0;
+  const globalRoot = globalConfigPath ? path14.dirname(globalConfigPath) : void 0;
   if (globalRoot) {
     const broadcastSessions = async () => {
       try {
@@ -7356,11 +8370,11 @@ function setupEvents(deps2) {
 
 // src/server/custom-context-modes.ts
 import { listContextWindowModes, atomicWrite as atomicWrite5 } from "@wrongstack/core";
-import * as fs11 from "fs/promises";
-import * as path14 from "path";
+import * as fs12 from "fs/promises";
+import * as path15 from "path";
 var STORE_FILENAME = "custom-context-modes.json";
 function storePath(wrongstackDir) {
-  return path14.join(wrongstackDir, STORE_FILENAME);
+  return path15.join(wrongstackDir, STORE_FILENAME);
 }
 var BUILTIN_IDS = /* @__PURE__ */ new Set(["balanced", "frugal", "deep", "archival"]);
 function createCustomModeStore(wrongstackDir) {
@@ -7368,7 +8382,7 @@ function createCustomModeStore(wrongstackDir) {
   const load2 = async () => {
     modes.clear();
     try {
-      const raw = await fs11.readFile(storePath(wrongstackDir), "utf8");
+      const raw = await fs12.readFile(storePath(wrongstackDir), "utf8");
       const parsed = JSON.parse(raw);
       if (Array.isArray(parsed.modes)) {
         for (const m of parsed.modes) {
@@ -7414,7 +8428,8 @@ function createCustomModeStore(wrongstackDir) {
       custom: true
     };
     modes.set(mode.id, entry);
-    void save2();
+    void save2().catch(() => {
+    });
     return { ok: true };
   };
   const update = (id, patch) => {
@@ -7440,7 +8455,8 @@ function createCustomModeStore(wrongstackDir) {
     if (patch.targetLoad !== void 0) next.targetLoad = patch.targetLoad;
     if (patch.aggressiveOn !== void 0) next.aggressiveOn = patch.aggressiveOn;
     modes.set(id, next);
-    void save2();
+    void save2().catch(() => {
+    });
     return { ok: true };
   };
   const remove = (id) => {
@@ -7450,7 +8466,8 @@ function createCustomModeStore(wrongstackDir) {
     if (!modes.delete(id)) {
       return { ok: false, error: `Mode "${id}" not found` };
     }
-    void save2();
+    void save2().catch(() => {
+    });
     return { ok: true };
   };
   const list = () => {
@@ -7491,14 +8508,17 @@ function createEternalSubscription(subscribe, broadcast2, clientsRef) {
 }
 
 // src/server/shell-open.ts
-import * as fs12 from "fs/promises";
-import * as path15 from "path";
+import * as fs13 from "fs/promises";
+import * as path16 from "path";
 import { spawn as spawn2 } from "child_process";
-var METACHAR_REGEX = /[&|<>^"'`\n\r]/;
+var METACHAR_REGEX = /[&|<>^"'`'\n\r]/;
+function shellQuote(s) {
+  return s.replaceAll("'", `'"'"'`);
+}
 async function handleShellOpen(req, logger) {
   try {
-    const resolved = path15.resolve(req.path);
-    await fs12.access(resolved);
+    const resolved = path16.resolve(req.path);
+    await fs13.access(resolved);
     if (METACHAR_REGEX.test(resolved)) {
       return { success: false, message: "Path contains unsupported characters." };
     }
@@ -7531,7 +8551,11 @@ async function handleShellOpen(req, logger) {
           () => launch(
             "gnome-terminal",
             [`--working-directory=${resolved}`],
-            () => launch("xterm", ["-e", `cd '${resolved}' && ${process.env["SHELL"] ?? "sh"}`])
+            () => (
+              // Pass argv array so sh -c sees a literal string, not an interpolated one.
+              // shellQuote() guards against paths that somehow slipped the METACHAR_REGEX.
+              launch("xterm", ["-e", "sh", "-c", `cd ${shellQuote(resolved)} && ${process.env["SHELL"] ?? "sh"}`])
+            )
           )
         );
       }
@@ -7550,9 +8574,9 @@ async function handleGitInfo(ws, projectRoot) {
   const cwd = projectRoot || void 0;
   try {
     const { execFile: ef } = await import("child_process");
-    const git = (args) => new Promise((resolve9) => {
+    const git = (args) => new Promise((resolve10) => {
       ef("git", args, { cwd, timeout: 3e3 }, (err, stdout) => {
-        resolve9(err ? "" : stdout.trim());
+        resolve10(err ? "" : stdout.trim());
       });
     });
     const [branchRaw, diffRaw, statusRaw, upstreamRaw] = await Promise.all([
@@ -7578,12 +8602,12 @@ async function handleGitInfo(ws, projectRoot) {
 function makeGit(cwd) {
   return async (args) => {
     const { execFile: ef } = await import("child_process");
-    return new Promise((resolve9) => {
+    return new Promise((resolve10) => {
       ef(
         "git",
         args,
         { cwd, timeout: 5e3, maxBuffer: 1024 * 1024 * 16 },
-        (err, stdout) => resolve9(err ? "" : stdout)
+        (err, stdout) => resolve10(err ? "" : stdout)
       );
     });
   };
@@ -7607,15 +8631,15 @@ async function handleGitChanges(ws, projectRoot) {
         if (!m) continue;
         const added = m[1] === "-" ? 0 : Number(m[1]);
         const deleted = m[2] === "-" ? 0 : Number(m[2]);
-        let path17 = m[3] ?? "";
-        if (path17 === "") {
+        let path18 = m[3] ?? "";
+        if (path18 === "") {
           i += 1;
-          path17 = parts[i + 1] ?? parts[i] ?? "";
+          path18 = parts[i + 1] ?? parts[i] ?? "";
           i += 1;
         }
-        if (!path17) continue;
-        const prev = counts.get(path17) ?? { added: 0, deleted: 0 };
-        counts.set(path17, { added: prev.added + added, deleted: prev.deleted + deleted });
+        if (!path18) continue;
+        const prev = counts.get(path18) ?? { added: 0, deleted: 0 };
+        counts.set(path18, { added: prev.added + added, deleted: prev.deleted + deleted });
       }
     };
     parseNumstat(unstagedNumstat);
@@ -7627,7 +8651,7 @@ async function handleGitChanges(ws, projectRoot) {
       if (!rec || rec.length < 3) continue;
       const x = rec[0] ?? " ";
       const y = rec[1] ?? " ";
-      const path17 = rec.slice(3);
+      const path18 = rec.slice(3);
       const isRename = x === "R" || x === "C" || y === "R" || y === "C";
       if (isRename) i += 1;
       let status;
@@ -7639,13 +8663,13 @@ async function handleGitChanges(ws, projectRoot) {
       else if (x === "D" || y === "D") status = "D";
       else status = "M";
       const staged = x !== " " && x !== "?";
-      let added = counts.get(path17)?.added ?? 0;
-      let deleted = counts.get(path17)?.deleted ?? 0;
+      let added = counts.get(path18)?.added ?? 0;
+      let deleted = counts.get(path18)?.deleted ?? 0;
       if (status === "?") {
         added = 0;
         deleted = 0;
       }
-      files.push({ path: path17, status, added, deleted, staged });
+      files.push({ path: path18, status, added, deleted, staged });
     }
     send(ws, { type: "git.changes", payload: { files } });
   } catch (err) {
@@ -7656,21 +8680,21 @@ async function handleGitChanges(ws, projectRoot) {
   }
 }
 var MAX_DIFF_BYTES = 2 * 1024 * 1024;
-async function handleGitDiff(ws, projectRoot, path17) {
+async function handleGitDiff(ws, projectRoot, path18) {
   const cwd = projectRoot || void 0;
-  const reply = (extra) => send(ws, { type: "git.diff", payload: { path: path17, ...extra } });
-  if (!path17 || path17.includes("\0") || path17.includes("..") || nodePath.isAbsolute(path17)) {
+  const reply = (extra) => send(ws, { type: "git.diff", payload: { path: path18, ...extra } });
+  if (!path18 || path18.includes("\0") || path18.includes("..") || nodePath.isAbsolute(path18)) {
     reply({ oldText: "", newText: "", error: "invalid path" });
     return;
   }
   try {
     const git = makeGit(cwd);
     const { readFile: readFile9 } = await import("fs/promises");
-    const { join: join12 } = await import("path");
-    const oldText = await git(["show", `HEAD:${path17}`]);
+    const { join: join14 } = await import("path");
+    const oldText = await git(["show", `HEAD:${path18}`]);
     let newText = "";
     try {
-      const abs = cwd ? join12(cwd, path17) : path17;
+      const abs = cwd ? join14(cwd, path18) : path18;
       const buf = await readFile9(abs);
       if (buf.includes(0)) {
         reply({ oldText: "", newText: "", binary: true });
@@ -7751,10 +8775,10 @@ async function handleProcessKillAll(ws) {
 }
 
 // src/server/goal-handlers.ts
-import { resolveWstackPaths } from "@wrongstack/core/utils";
+import { resolveWstackPaths as resolveWstackPaths3 } from "@wrongstack/core/utils";
 async function handleGoalGet(projectRoot, broadcast2) {
   try {
-    const goalPath = resolveWstackPaths({ projectRoot }).projectGoal;
+    const goalPath = resolveWstackPaths3({ projectRoot }).projectGoal;
     const { readFile: readFile9 } = await import("fs/promises");
     const raw = await readFile9(goalPath, "utf8");
     const goal = JSON.parse(raw);
@@ -7768,8 +8792,11 @@ async function handleGoalGet(projectRoot, broadcast2) {
 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;
@@ -7809,7 +8836,7 @@ async function startWebUI(opts = {}) {
     const write = async () => {
       let raw;
       try {
-        raw = await fs13.readFile(globalConfigPath, "utf8");
+        raw = await fs14.readFile(globalConfigPath, "utf8");
       } catch {
         raw = "{}";
       }
@@ -7883,6 +8910,7 @@ async function startWebUI(opts = {}) {
   toolRegistry.register(makeMailSendTool({ projectDir: wpaths.projectDir, events }));
   toolRegistry.register(makeMailInboxTool({ projectDir: wpaths.projectDir, events }));
   applyToolDescriptionModes(toolRegistry, config.tools?.descriptionMode);
+  applyToolResultRenderModes(toolRegistry, config.tools?.resultRenderMode);
   configureExecPolicy(config.tools?.exec ?? {});
   console.log("[WebUI] Tool registry loaded:", toolRegistry.list().length, "tools");
   const mcpRegistry = new MCPRegistry({
@@ -7927,7 +8955,7 @@ async function startWebUI(opts = {}) {
       sessionId: session.id,
       projectSlug: wpaths.projectSlug,
       projectRoot,
-      projectName: path16.basename(projectRoot),
+      projectName: path17.basename(projectRoot),
       workingDir,
       clientType: "webui",
       pid: process.pid,
@@ -7947,7 +8975,7 @@ async function startWebUI(opts = {}) {
       const hqTelemetry = createHqPublisherFromEnv({
         clientKind: "webui",
         projectRoot,
-        projectName: path16.basename(projectRoot),
+        projectName: path17.basename(projectRoot),
         appConfig: config,
         socketFactory: (url) => new WebSocket2(url)
       });
@@ -7959,7 +8987,7 @@ async function startWebUI(opts = {}) {
           events,
           sessionId: session.id,
           projectRoot,
-          projectName: path16.basename(projectRoot),
+          projectName: path17.basename(projectRoot),
           globalRoot: wpaths.globalRoot,
           initialAgents: statusTracker?.getAgents(),
           startedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -8015,19 +9043,39 @@ async function startWebUI(opts = {}) {
   };
   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"),
-    globalSkillsDir: path16.join(wstackGlobalRoot2(), "skills"),
+    manifestPath: path17.join(wstackGlobalRoot3(), "installed-skills.json"),
+    projectSkillsDir: path17.join(projectRoot, ".wrongstack", "skills"),
+    globalSkillsDir: path17.join(wstackGlobalRoot3(), "skills"),
     projectHash: projectHash(projectRoot),
     skillLoader
   }) : void 0;
+  const promptsEnabled = config.features.prompts !== false;
+  const bundledPromptsDir = promptsEnabled ? (() => {
+    try {
+      const req = createRequire2(import.meta.url);
+      return path17.join(
+        path17.dirname(req.resolve("@wrongstack/core/package.json")),
+        "data",
+        "prompts"
+      );
+    } catch {
+      return void 0;
+    }
+  })() : void 0;
+  const promptLoader = promptsEnabled ? new DefaultPromptLoader({ paths: wpaths, bundledDir: bundledPromptsDir }) : void 0;
+  const promptUsage = new PromptUsageStore(wpaths.promptUsage);
+  const promptsCtx = { promptLoader, promptUsage };
   const systemPromptBuilder = new DefaultSystemPromptBuilder3({
     memoryStore,
     skillLoader,
     modeStore,
     modeId,
     modePrompt,
-    modelCapabilities: () => modelCapabilitiesRef.current
+    modelCapabilities: () => modelCapabilitiesRef.current,
+    instructionPaths: {
+      globalDir: wpaths.globalInstructions,
+      projectDir: wpaths.inProjectInstructions
+    }
   });
   let onlineAgents = [];
   try {
@@ -8122,6 +9170,10 @@ async function startWebUI(opts = {}) {
     context.meta["enhanceLanguage"] = autonomyCfg["enhanceLanguage"] ?? "original";
     context.meta["nextPrediction"] = config.nextPrediction ?? false;
     context.meta["fallbackModels"] = config.fallbackModels ?? [];
+    context.meta["fallbackProfiles"] = config.fallbackProfiles ?? {};
+    context.meta["favoriteModels"] = config.favoriteModels ?? [];
+    context.meta["favoriteModelsOnly"] = config.favoriteModelsOnly === true;
+    context.meta["modelMatrix"] = config.modelMatrix ?? {};
     context.meta["fallbackAuto"] = config.fallbackAuto !== false;
     context.meta["featureMcp"] = config.features.mcp !== false;
     context.meta["featurePlugins"] = config.features.plugins !== false;
@@ -8134,6 +9186,20 @@ async function startWebUI(opts = {}) {
     context.meta["logLevel"] = config.log?.level ?? "info";
     context.meta["auditLevel"] = config.session?.auditLevel ?? "standard";
     context.meta["maxIterations"] = config.tools?.maxIterations ?? 500;
+    context.meta["contextMode"] = config.context?.mode ?? "balanced";
+    {
+      const tsm = config.features?.tokenSavingMode;
+      context.meta["tokenSavingTier"] = typeof tsm === "string" ? tsm : tsm ? "medium" : "off";
+    }
+    context.meta["maxConcurrent"] = typeof config.maxConcurrent === "number" ? config.maxConcurrent : 10;
+    context.meta["titleAnimation"] = autonomyCfg["terminalTitleAnimation"] !== false;
+    {
+      const mr = config.modelRuntime ?? {};
+      context.meta["reasoningMode"] = mr.reasoning?.mode ?? "auto";
+      context.meta["reasoningEffort"] = mr.reasoning?.effort ?? "high";
+      context.meta["reasoningPreserve"] = mr.reasoning?.preserve === true;
+      context.meta["cacheTtl"] = mr.cache?.ttl ?? "default";
+    }
     const hqConfig = config.hq;
     context.meta["hqEnabled"] = hqConfig?.enabled === true;
     context.meta["hqUrl"] = hqConfig?.url ?? "";
@@ -8167,6 +9233,10 @@ async function startWebUI(opts = {}) {
     "indexOnStart",
     "contextAutoCompact",
     "contextStrategy",
+    "contextMode",
+    "tokenSavingTier",
+    "maxConcurrent",
+    "titleAnimation",
     "logLevel",
     "auditLevel",
     "hqEnabled",
@@ -8182,6 +9252,10 @@ async function startWebUI(opts = {}) {
     "reasoningPreserve",
     "cacheTtl",
     "fallbackModels",
+    "fallbackProfiles",
+    "favoriteModels",
+    "favoriteModelsOnly",
+    "modelMatrix",
     "fallbackAuto"
   ];
   const prefSnapshot = () => {
@@ -8214,6 +9288,15 @@ async function startWebUI(opts = {}) {
       if (autonomyTouched) decrypted.autonomy = autonomyCfg;
       if (typeof payload["nextPrediction"] === "boolean") decrypted.nextPrediction = payload["nextPrediction"];
       if (Array.isArray(payload["fallbackModels"])) decrypted.fallbackModels = payload["fallbackModels"];
+      if (payload["fallbackProfiles"] && typeof payload["fallbackProfiles"] === "object" && !Array.isArray(payload["fallbackProfiles"])) {
+        decrypted.fallbackProfiles = payload["fallbackProfiles"];
+      }
+      if (Array.isArray(payload["favoriteModels"])) decrypted.favoriteModels = payload["favoriteModels"];
+      if (typeof payload["favoriteModelsOnly"] === "boolean")
+        decrypted.favoriteModelsOnly = payload["favoriteModelsOnly"];
+      if (payload["modelMatrix"] && typeof payload["modelMatrix"] === "object" && !Array.isArray(payload["modelMatrix"])) {
+        decrypted.modelMatrix = payload["modelMatrix"];
+      }
       if (typeof payload["fallbackAuto"] === "boolean") decrypted.fallbackAuto = payload["fallbackAuto"];
       const FEATURE_MAP = {
         featureMcp: "mcp",
@@ -8229,12 +9312,26 @@ async function startWebUI(opts = {}) {
           decrypted.features = feats;
         }
       }
-      if (typeof payload["contextAutoCompact"] === "boolean" || typeof payload["contextStrategy"] === "string") {
+      if (typeof payload["contextAutoCompact"] === "boolean" || typeof payload["contextStrategy"] === "string" || typeof payload["contextMode"] === "string") {
         const ctxCfg = decrypted.context ?? {};
         if (typeof payload["contextAutoCompact"] === "boolean") ctxCfg.autoCompact = payload["contextAutoCompact"];
         if (typeof payload["contextStrategy"] === "string") ctxCfg.strategy = payload["contextStrategy"];
+        if (typeof payload["contextMode"] === "string") ctxCfg.mode = payload["contextMode"];
         decrypted.context = ctxCfg;
       }
+      if (typeof payload["tokenSavingTier"] === "string") {
+        const featsCfg = decrypted.features ?? {};
+        featsCfg.tokenSavingMode = payload["tokenSavingTier"];
+        decrypted.features = featsCfg;
+      }
+      if (typeof payload["maxConcurrent"] === "number") {
+        decrypted.maxConcurrent = payload["maxConcurrent"];
+      }
+      if (typeof payload["titleAnimation"] === "boolean") {
+        const autoCfg = decrypted.autonomy ?? {};
+        autoCfg.terminalTitleAnimation = payload["titleAnimation"];
+        decrypted.autonomy = autoCfg;
+      }
       if (typeof payload["logLevel"] === "string") {
         const logCfg = decrypted.log ?? {};
         logCfg.level = payload["logLevel"];
@@ -8305,6 +9402,7 @@ async function startWebUI(opts = {}) {
   const collabInject = collabInjectMiddleware(collabBus, { logger });
   Object.defineProperty(collabInject, "name", { value: "collab-inject" });
   pipelines.toolCall.prepend(collabInject);
+  installDesignStudioMiddleware({ pipelines, ctx: context });
   const codebaseIndexing = setupWebUICodebaseIndexing({
     config,
     context,
@@ -8400,6 +9498,17 @@ async function startWebUI(opts = {}) {
     perIterationOutputCapBytes: config.tools?.perIterationOutputCapBytes ?? DEFAULT_TOOLS_CONFIG.perIterationOutputCapBytes,
     tracer: void 0
   });
+  const webuiLogger = container.resolve(TOKENS.Logger);
+  void discoverMailboxBridgeForWebui({
+    projectRoot,
+    config,
+    logger: webuiLogger,
+    ctx: context
+  }).catch((err) => {
+    webuiLogger.warn("mailbox bridge discovery threw on webui boot", {
+      err: err instanceof Error ? err.message : String(err)
+    });
+  });
   const agent = new Agent({
     container,
     tools: toolRegistry,
@@ -8496,7 +9605,18 @@ async function startWebUI(opts = {}) {
     projectRoot
   );
   const specsHandler = new SpecsWebSocketHandler(wpaths.projectSpecs, wpaths.projectTaskGraphs);
-  const sddBoardHandler = new SddBoardWebSocketHandler(wpaths.projectSddBoards);
+  const sddBoardHandler = new SddBoardWebSocketHandler(wpaths.projectSddBoards, void 0, {
+    projectRoot,
+    paths: {
+      projectSpecs: wpaths.projectSpecs,
+      projectTaskGraphs: wpaths.projectTaskGraphs,
+      projectSddSession: wpaths.projectSddSession,
+      projectSddBoards: wpaths.projectSddBoards
+    }
+  });
+  void cleanupStaleSddWorktrees3({ projectRoot, boardsDir: wpaths.projectSddBoards }).catch(
+    () => void 0
+  );
   const sddWizardHandler = new SddWizardWebSocketHandler(
     buildSddWizardDeps({
       agent,
@@ -8518,7 +9638,10 @@ async function startWebUI(opts = {}) {
       }
     })
   );
-  const worktreeHandler = new WorktreeWebSocketHandler(events, logger);
+  const worktreeHandler = new WorktreeWebSocketHandler(events, logger, {
+    projectRoot,
+    boardsDir: wpaths.projectSddBoards
+  });
   const terminalHandler = new TerminalWebSocketHandler(() => workingDir, logger);
   const collabHandler = new CollaborationWebSocketHandler(
     events,
@@ -8557,15 +9680,23 @@ async function startWebUI(opts = {}) {
       inputCost,
       outputCost,
       cacheReadCost,
-      projectName: path16.basename(projectRoot) || projectRoot,
+      projectName: path17.basename(projectRoot) || projectRoot,
       projectRoot,
       cwd: workingDir,
       mode: modeId,
       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 ?? "",
@@ -8577,7 +9708,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({
@@ -8695,8 +9829,8 @@ async function startWebUI(opts = {}) {
       clients.delete(ws);
       if (closing) rateLimits.delete(closing.connId);
       if (pendingConfirms.size > 0) {
-        for (const [id, resolve9] of pendingConfirms) {
-          resolve9("no");
+        for (const [id, resolve10] of pendingConfirms) {
+          resolve10("no");
           pendingConfirms.delete(id);
         }
       }
@@ -8776,21 +9910,21 @@ async function startWebUI(opts = {}) {
     });
   }
   async function touchProjectEntry(root, workDir) {
-    const resolved = path16.resolve(root);
+    const resolved = path17.resolve(root);
     const manifest = await loadManifest(globalConfigPath);
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const existing = manifest.projects.find((p) => path16.resolve(p.root) === resolved);
+    const existing = manifest.projects.find((p) => path17.resolve(p.root) === resolved);
     if (existing) {
       existing.lastSeen = now;
-      if (workDir) existing.lastWorkingDir = path16.resolve(workDir);
+      if (workDir) existing.lastWorkingDir = path17.resolve(workDir);
     } else {
       manifest.projects.push({
-        name: path16.basename(resolved),
+        name: path17.basename(resolved),
         root: resolved,
         slug: generateProjectSlug(resolved),
         createdAt: now,
         lastSeen: now,
-        lastWorkingDir: workDir ? path16.resolve(workDir) : void 0
+        lastWorkingDir: workDir ? path17.resolve(workDir) : void 0
       });
     }
     await saveManifest(manifest, globalConfigPath);
@@ -8835,6 +9969,8 @@ async function startWebUI(opts = {}) {
     if (await handleSpecsRoute(ws, msg, specsRoutes)) return;
     if (await handleSddBoardRoute(ws, msg, sddBoardRoutes)) return;
     if (await handleSddWizardRoute(ws, msg, sddWizardRoutes)) return;
+    if (msg.type.startsWith("worktree.") && await worktreeHandler.handleMessage(msg))
+      return;
     switch (msg.type) {
       // Collaboration messages short-circuit the user/agent flow.
       // They don't touch runLock, the agent loop, or the message queue —
@@ -8905,10 +10041,10 @@ async function startWebUI(opts = {}) {
       }
       case "tool.confirm_result": {
         const { id, decision } = msg.payload;
-        const resolve9 = pendingConfirms.get(id);
-        if (resolve9) {
+        const resolve10 = pendingConfirms.get(id);
+        if (resolve10) {
           pendingConfirms.delete(id);
-          resolve9(decision);
+          resolve10(decision);
         }
         break;
       }
@@ -8992,6 +10128,48 @@ async function startWebUI(opts = {}) {
       case "skills.export":
         await handleSkillsExport(ws, { skillLoader, skillInstaller, projectRoot });
         break;
+      // Prompt library — shared handlers (prompts-handlers.ts).
+      case "prompts.list":
+        await handlePromptsList(ws, promptsCtx);
+        break;
+      case "prompts.search":
+        await handlePromptsSearch(ws, promptsCtx, msg);
+        break;
+      case "prompts.content":
+        await handlePromptsContent(ws, promptsCtx, msg);
+        break;
+      case "prompts.favorite":
+        await handlePromptsFavorite(ws, promptsCtx, msg);
+        break;
+      case "prompts.create":
+        await handlePromptsCreate(ws, promptsCtx, msg);
+        break;
+      case "prompts.used":
+        await handlePromptsUsed(ws, promptsCtx, msg);
+        break;
+      case "prompts.recent":
+        await handlePromptsRecent(ws, promptsCtx);
+        break;
+      // Design Studio — shared handlers (design-handlers.ts). agentMeta is the
+      // live context so design.use pins the active kit for the next turn.
+      case "design.list":
+        await handleDesignList(ws, { projectRoot, agentMeta: context });
+        break;
+      case "design.use":
+        await handleDesignUse(ws, { projectRoot, agentMeta: context }, msg);
+        break;
+      case "design.state":
+        await handleDesignState(ws, { projectRoot, agentMeta: context });
+        break;
+      case "design.set":
+        await handleDesignSet(ws, { projectRoot, agentMeta: context }, msg);
+        break;
+      case "design.materialize":
+        await handleDesignMaterialize(ws, { projectRoot, agentMeta: context }, msg);
+        break;
+      case "design.verify":
+        await handleDesignVerify(ws, { projectRoot, agentMeta: context });
+        break;
       case "diag.get": {
         const usage = tokenCounter.total();
         send(ws, {
@@ -9072,11 +10250,29 @@ async function startWebUI(opts = {}) {
             messages: context.messages.length,
             readFiles: context.readFiles.size,
             tools: toolRegistry.list().length,
+            sideEffectCount: context.sideEffects?.length ?? 0,
             elapsedMs: Date.now() - sessionStartedAt
           }
         });
         break;
       }
+      case "side_effects.list": {
+        const sideEffects = context.sideEffects ?? [];
+        send(ws, {
+          type: "side_effects",
+          payload: {
+            sideEffects: sideEffects.slice(-50).map((se) => ({
+              toolUseId: se.toolUseId,
+              toolName: se.toolName,
+              ts: se.ts,
+              input: se.input,
+              outcome: se.outcome,
+              risk: se.risk
+            }))
+          }
+        });
+        break;
+      }
       case "process.list": {
         await handleProcessList(ws);
         break;
@@ -9331,6 +10527,7 @@ async function startWebUI(opts = {}) {
     toolRegistry,
     config,
     projectRoot,
+    globalRoot: wpaths.globalRoot,
     clients,
     setModeId: (id) => {
       modeId = id;
@@ -9367,6 +10564,16 @@ async function startWebUI(opts = {}) {
         config.features.modelsRegistry = payload["featureModelsRegistry"];
       if (Array.isArray(payload["fallbackModels"]))
         config.fallbackModels = payload["fallbackModels"];
+      if (payload["fallbackProfiles"] && typeof payload["fallbackProfiles"] === "object" && !Array.isArray(payload["fallbackProfiles"])) {
+        config.fallbackProfiles = payload["fallbackProfiles"];
+      }
+      if (Array.isArray(payload["favoriteModels"]))
+        config.favoriteModels = payload["favoriteModels"];
+      if (typeof payload["favoriteModelsOnly"] === "boolean")
+        config.favoriteModelsOnly = payload["favoriteModelsOnly"];
+      if (payload["modelMatrix"] && typeof payload["modelMatrix"] === "object" && !Array.isArray(payload["modelMatrix"])) {
+        config.modelMatrix = payload["modelMatrix"];
+      }
       if (typeof payload["fallbackAuto"] === "boolean")
         config.fallbackAuto = payload["fallbackAuto"];
       if (typeof payload["contextAutoCompact"] === "boolean") {
@@ -9418,7 +10625,7 @@ async function startWebUI(opts = {}) {
         sendResult2(ws, false, parsed.message);
         return;
       }
-      return handleMailboxMessages(ws, { projectRoot, globalRoot: path16.dirname(globalConfigPath) }, parsed.value);
+      return handleMailboxMessages(ws, { projectRoot, globalRoot: path17.dirname(globalConfigPath) }, parsed.value);
     },
     agents: (ws, msg) => {
       const parsed = validateMailboxAgentsPayload(msg.payload);
@@ -9426,16 +10633,16 @@ async function startWebUI(opts = {}) {
         sendResult2(ws, false, parsed.message);
         return;
       }
-      return handleMailboxAgents(ws, { projectRoot, globalRoot: path16.dirname(globalConfigPath) }, parsed.value);
+      return handleMailboxAgents(ws, { projectRoot, globalRoot: path17.dirname(globalConfigPath) }, parsed.value);
     },
-    clear: (ws) => handleMailboxClear(ws, { projectRoot, globalRoot: path16.dirname(globalConfigPath) }),
+    clear: (ws) => handleMailboxClear(ws, { projectRoot, globalRoot: path17.dirname(globalConfigPath) }),
     purge: (ws, msg) => {
       const parsed = validateMailboxPurgePayload(msg.payload);
       if (!parsed.ok) {
         sendResult2(ws, false, parsed.message);
         return;
       }
-      return handleMailboxPurge(ws, { projectRoot, globalRoot: path16.dirname(globalConfigPath) }, parsed.value);
+      return handleMailboxPurge(ws, { projectRoot, globalRoot: path17.dirname(globalConfigPath) }, parsed.value);
     }
   };
   mcpRoutes = {
@@ -9515,18 +10722,25 @@ async function startWebUI(opts = {}) {
   };
   const httpServer = createHttpServer({
     host: wsHost,
-    distDir: path16.resolve(import.meta.dirname, "../../dist"),
+    distDir: path17.resolve(import.meta.dirname, "../../dist"),
     wsPort,
+    publicWsUrl,
     globalRoot: wpaths.globalRoot,
     apiToken: wsToken,
+    requireToken,
     watcherMetrics,
     onFleetPing: () => {
       void fleetBroadcast?.();
     }
   });
-  const registryBaseDir = path16.dirname(globalConfigPath);
+  const registryBaseDir = path17.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(
@@ -9536,9 +10750,9 @@ async function startWebUI(opts = {}) {
         wsPort,
         host: wsHost,
         projectRoot,
-        projectName: path16.basename(projectRoot) || projectRoot,
+        projectName: path17.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({
@@ -9580,7 +10794,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);
@@ -9594,11 +10856,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",