@monster-orange/den 0.2.7 → 0.3.0

package/src/ui/server/index.ts

@@ -50,10 +50,18 @@ import {
   getWorkspaceByName,
   isWorkspaceActive,
   listWorkspaceServices,
+  readWorkspacesFile,
   resolveDepAddress,
   parseAddress,
   readManifestAnyBranch,
 } from "../../shared/environment-manager/workspaces.js";
+import {
+  parseScope,
+  scopeKey,
+  scopePayload,
+  scopeView,
+  storedView,
+} from "../../shared/environment-manager/scope.js";
 import { findServiceContainer } from "../../shared/environment-manager/service-container.js";
 import {
   resolveHistorySource,
@@ -81,6 +89,8 @@ import {
   loadDaemonsFromFile,
   pruneDeadDaemonsAsync,
   daemonRootOf,
+  daemonStaleReason,
+  runningContainerBasesAsync,
   isInteractiveServiceCommand,
   rewriteLegacyOpctlKillCommandForContainer,
   shouldDetachServiceCommand,
@@ -96,6 +106,7 @@ import {
   getServiceLogPath,
 } from "../../shared/process/spawn-streaming.js";
 import {
+  assertDenConfigValid,
   readDenConfig,
   isProductionEnv,
   isLocalEnabled,
@@ -106,8 +117,17 @@ import {
   writeUserReleaseConfig,
   type ReleaseConfig,
 } from "../../shared/den-config.js";
-import { readOrg } from "../../shared/org.js";
-import { engineVersion, getDistRoot } from "../../shared/paths.js";
+import {
+  CONFIG_ERROR_STATUS,
+  configErrorBody,
+  isConfigError,
+} from "../../shared/config-error.js";
+import { readOrgView } from "../../shared/org.js";
+import {
+  engineVersion,
+  getDistRoot,
+  getEngineRoot,
+} from "../../shared/paths.js";
 import { enginePath } from "../../shared/engine.js";
 import {
   releaseService,
@@ -131,11 +151,16 @@ import {
   type Placement,
 } from "../../shared/manifest/placement.js";
 import {
-  isOpSignedIn,
-  hasSudoInVault,
   readSudoFromVault,
   saveSudoToVault,
+  sudoRef,
+  sudoVaultStatus,
+  SUDO_REF_NAME,
 } from "../../shared/auth/sudo-vault.js";
+import {
+  notConfiguredMessage,
+  secretsConfigWarnings,
+} from "../../shared/secrets/index.js";
 import { DEN_BANNER_LINES, DEN_SUBTITLE } from "../../shared/banner.js";
 import { actorLabel } from "../../shared/agent-actor.js";
 import {
@@ -143,11 +168,32 @@ import {
   actorSuffix,
   recordAction,
   recordAgentRefusal,
+  repoAtPath,
   setAuditSink,
 } from "./audit.js";
 import { handleReadonlyRoutes } from "./readonly-routes.js";
 import { serveUiAsset } from "./ui-assets.js";
-import { graphPrefs, mergeGraphPrefs } from "./graph-prefs.js";
+import { graphPrefs, patchStoredGraph } from "./graph-prefs.js";
+import { graphPageHtml } from "./graph-page.js";
+import { mergeShellPrefs, shellPrefs, storedShell } from "./shell-prefs.js";
+import { distributionSettings, userWebPort } from "./settings-distribution.js";
+import {
+  appearancePrefs,
+  mergeAppearancePrefs,
+  storedAppearance,
+} from "./appearance-prefs.js";
+import {
+  activeTheme,
+  handleThemeRoutes,
+  type ThemeRouteDeps,
+} from "./theme-routes.js";
+import { findTheme } from "./theme-runtime.js";
+import {
+  UI_LANGUAGES,
+  isUiLanguage,
+  localizePage,
+  uiLanguage,
+} from "./ui-language.js";
 import { singleFlight } from "./single-flight.js";
 import { graphOrder } from "./graph-order.js";
 import { clearReadCache, enableReadCache } from "../../shared/read-cache.js";
@@ -189,6 +235,13 @@ interface HealthResult {
   /** Where it runs for this env, and where a remote one is (R13). */
   runs: Placement["runs"];
   target: Placement["target"];
+  /** From the focused workspace: the header sorts these first. */
+  focused?: boolean;
+  /**
+   * The workspaces in view that define this service (focus first). More
+   * than one means a shared service: it is listed once, with its owners.
+   */
+  workspaces?: string[];
 }
 
 /**
@@ -247,9 +300,12 @@ const SERVICES_CACHE_TTL_MS = 2_000;
 const READ_CACHE_TTL_MS = 5_000;
 enableReadCache(READ_CACHE_TTL_MS);
 const servicesCache = singleFlight<ServicesList>(SERVICES_CACHE_TTL_MS);
-/** A workspace-scoped run covers a different service set than the default one. */
+/**
+ * A workspace-scoped run covers a different service set than the default
+ * one, and the default one covers whatever the view scope has in view.
+ */
 function healthCacheKey(env: Environment, workspace: string | null): string {
-  return `${env}|${workspace ?? "*"}`;
+  return `${env}|${workspace ?? `*:${scopeKey(scopeView())}`}`;
 }
 import {
   LOG_SWEEP_INTERVAL_MS,
@@ -381,6 +437,98 @@ function serverLog(msg: string, kind: string = "info", actor?: string): void {
   if (!SILENT) process.stdout.write(msg + "\n");
 }
 
+// ── Theme ────────────────────────────────────────────────────────────────────
+// The active theme (user's, else the org config's `theme:`, else den). A
+// theme switch is a write of user.yml `appearance:` and a new /theme.css:
+// nothing else (no edge, no services, no restart).
+const themeDeps: ThemeRouteDeps = {
+  roots: () => ({ distRoot: getDistRoot(), engineRoot: getEngineRoot() }),
+  prefs: () => appearancePrefs(readUserConfig().appearance),
+  distributionTheme: () => readBrand().theme,
+  warn: (line) => serverLog(line, "warn"),
+  denFavicon: path.join(PUBLIC_DIR, "favicon.ico"),
+};
+// The pre-paint script in each page reads the user's mode and the theme's
+// default mode from these placeholders, so the first paint is right.
+// The UI language (R19): a page in another language than English loads
+// its catalog before shell.js, so the first paint is in it.
+setHtmlFill((html) => {
+  let mode = "system";
+  let def = "dark";
+  let lang = uiLanguage(undefined);
+  try {
+    const user = readUserConfig();
+    lang = uiLanguage(user.language);
+    mode = appearancePrefs(user.appearance).mode;
+    def = activeTheme(themeDeps)?.theme.default_mode ?? "dark";
+  } catch {
+    /* defaults */
+  }
+  let out = localizePage(html, lang)
+    .split("@@DEN_MODE@@")
+    .join(mode)
+    .split("@@DEN_DEFAULT_MODE@@")
+    .join(def);
+  // MD-2: every page says when the engine on disk is not the one running.
+  const engine = engineCheck();
+  if (engine.stale)
+    out = out.replace(
+      '<div id="den-shell"',
+      () =>
+        `<div id="den-shell" data-engine-stale="${escAttr(JSON.stringify(engineBanner(engine)))}"`,
+    );
+  return out;
+});
+
+// ── MD-2: the engine this server loaded, against the one on disk ─────────────
+const ENGINE = engineWatch(getEngineRoot);
+function engineCheck(): EngineCheck {
+  return ENGINE.check();
+}
+/** What the shell's banner and the error pages say on a mismatch. */
+function engineBanner(c: EngineCheck): {
+  loaded: string | null;
+  onDisk: string | null;
+  message: string;
+} {
+  return {
+    loaded: c.loaded.version,
+    onDisk: c.onDisk.version,
+    message: engineStaleMessage(c, product().cli),
+  };
+}
+function escAttr(v: string): string {
+  return v.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+/**
+ * R26a: the shell's error page for a failed page request (404 or 500).
+ * HEAD gets the status and headers only.
+ */
+function sendErrorPage(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  data: Omit<ErrorPageData, "time" | "version" | "engine">,
+): void {
+  const engine = engineCheck();
+  const full: ErrorPageData = {
+    ...data,
+    time: new Date().toISOString(),
+    version: engine.loaded.version,
+    ...(engine.stale ? { engine: engineBanner(engine) } : {}),
+  };
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  serveFile(
+    res,
+    path.join(PUBLIC_DIR, "error.html"),
+    (html) => fillErrorPage(html, full),
+    data.status,
+  );
+}
+
 // Every audited action (exec, run, sync) lands in the log as a lifecycle
 // line; an agent's carries its label so the /logs page can mark it.
 setAuditSink((line, actor) =>
@@ -417,6 +565,46 @@ const STATIC_EXTS = new Set([
   ".woff2",
 ]);
 
+/** Every workspace's checkouts (active or not), for repoAtPath. */
+function allWorkspaceCheckouts(): ResolvedService[] {
+  const catalog = readCatalog();
+  return Object.entries(readWorkspacesFile().workspaces).flatMap(
+    ([name, config]) => listWorkspaceServices(config, catalog, name),
+  );
+}
+
+/**
+ * API routes that answer whatever the config holds: the identity probe the
+ * CLI and MCP use to find this server, its own log (where a config error is
+ * also written), the changelog, and restarting it. And (0.3.0-dev.40, R26a's
+ * 422 page) what the shell and the Settings and Logs pages need, so the
+ * rail stays usable to reach the fix: the UI prefs (theme, mode, language,
+ * the rail's pins) and editor settings (/api/settings: user.yml, and the
+ * org config's Distribution rows read without validation), the installed
+ * themes, the view scope and a workspace's editor (workspaces.yml), and
+ * whether a sudo password is held. None of them reads org data.
+ */
+const CONFIG_FREE_ROUTES = new Set([
+  "/api/server-info",
+  "/api/server-log",
+  "/api/changelog",
+  "/api/web/restart",
+  "/api/settings",
+  "/api/themes",
+  "/api/scope",
+  "/api/workspaces/settings",
+  "/api/sudo-password/status",
+  // The env picker on every page (falls back to local; a consumer's dev.40 finding).
+  "/api/environments",
+]);
+
+/**
+ * Pages that load whatever the config holds (0.3.0-dev.40): the rail's way
+ * to the fix (Settings, Logs). Any other page navigation with a config that
+ * fails validation gets the 422 "Config is invalid" page.
+ */
+const CONFIG_FREE_PAGES = new Set(["/settings", "/settings.html", "/logs"]);
+
 // ── Sudo password store ───────────────────────────────────────────────────────
 import {
   setSudoPassword,
@@ -435,8 +623,23 @@ import {
   serveFile,
   send400,
   send404,
+  setHtmlFill,
 } from "./http-helpers.js";
 import { orgOf, listOrgs } from "../../shared/manifest/service-links.js";
+import {
+  engineStaleMessage,
+  engineWatch,
+  type EngineCheck,
+} from "./engine-stamp.js";
+import {
+  fillErrorPage,
+  jsonApiErrors,
+  newRequestId,
+  pluginForPath,
+  routeTemplate,
+  wantsHtmlPage,
+  type ErrorPageData,
+} from "./http-errors.js";
 import {
   readOrgContext,
   resolveAllWorkspaceOrgs,
@@ -456,14 +659,17 @@ import { EditorManager, SUPPORTED_LANGUAGES } from "./editor-manager.js";
 import { handleWorkspaceRoutes } from "./workspace-routes.js";
 import { isLifecycleExecCmd, streamLifecycleExec } from "./lifecycle-exec.js";
 import { readEdgeConfig, readWebPort } from "../../shared/edge/config.js";
+import { edgeHttps } from "../../shared/edge/render.js";
 import {
   linksFor,
   openUrlFor,
   rehost,
+  type EdgeOrigin,
   type OpenLink,
 } from "../../shared/open-url.js";
 
 import { product } from "../../shared/product.js";
+import { readBrand } from "../../shared/brand.js";
 /** config `web.port` (user > team), falling back to the built-in default. */
 function readWebPortSafe(): number {
   try {
@@ -577,6 +783,12 @@ async function handleRequest(
 ): Promise<void> {
   const url = new URL(req.url ?? "/", `http://localhost:${PORT}`);
   const pathname = url.pathname;
+  // R26: one id per request, on every response and on its failure's log line.
+  const requestId = requestIdOf(req);
+  if (!res.headersSent) res.setHeader("X-Request-Id", requestId);
+  // R26b: every /api error answers JSON, whatever the route sends.
+  if (pathname === "/api" || pathname.startsWith("/api/"))
+    jsonApiErrors(res, requestId);
   // A mutating request may change what /api/services would list (exec and
   // sync stream over GET, for EventSource).
   if (
@@ -602,14 +814,45 @@ async function handleRequest(
       res.on("finish", () => {
         const ms = dim(`${Date.now() - start}ms`);
         serverLog(
-          `  ${logTimestamp()}  ${method}  ${pathname}  →  ${logStatus(res.statusCode)}  ${ms}`,
+          `  ${logTimestamp()}  ${method}  ${pathname}  →  ${logStatus(res.statusCode)}  ${ms}` +
+            (res.statusCode >= 400 ? dim(`  req ${requestId}`) : ""),
           "request",
         );
       });
     }
   }
 
+  // ── Config validation ──────────────────────────────────────────────────────
+  // A config that fails validation answers every API route that reads it as
+  // the ConfigError the handler below maps to 422 JSON, before any route's own
+  // catch can turn it into a 400, a 500 or an empty list. Pages still load.
+  if (pathname.startsWith("/api/") && !CONFIG_FREE_ROUTES.has(pathname))
+    assertDenConfigValid();
+  // A page navigation, likewise: the shell frame with the 422 page, not a
+  // page whose every call then fails (R26a). Static files never get here
+  // as a navigation (wantsHtmlPage needs Accept: text/html).
+  if (
+    wantsHtmlPage(req, pathname) &&
+    !CONFIG_FREE_PAGES.has(pathname) &&
+    (path.extname(pathname) === ".html" ||
+      !STATIC_EXTS.has(path.extname(pathname)))
+  )
+    assertDenConfigValid();
+
   // ── Static UI ──────────────────────────────────────────────────────────────
+  // The Settings page (R21). Local Dev's old settings panel link
+  // (/local-dev?settings=1) lands on its category there.
+  if (pathname === "/settings" || pathname === "/settings.html") {
+    return serveFile(res, path.join(PUBLIC_DIR, "settings.html"));
+  }
+  if (
+    (pathname === "/local-dev" || pathname === "/local-dev.html") &&
+    url.searchParams.has("settings")
+  ) {
+    res.writeHead(302, { Location: "/settings#editor" });
+    res.end();
+    return;
+  }
   // Local Dev is the default page when local environment is enabled.
   if (
     pathname === "/" ||
@@ -624,6 +867,20 @@ async function handleRequest(
     return serveFile(res, path.join(PUBLIC_DIR, "local-dev.html"));
   }
 
+  // The Graph page (R22): Local Dev's page in its full-width graph view.
+  if (pathname === "/graph" || pathname === "/graph.html") {
+    if (!isLocalEnabled()) {
+      res.writeHead(302, { Location: "/tests" });
+      res.end();
+      return;
+    }
+    return serveFile(
+      res,
+      path.join(PUBLIC_DIR, "local-dev.html"),
+      graphPageHtml,
+    );
+  }
+
   if (pathname === "/tests" || pathname === "/index.html") {
     return serveFile(res, path.join(PUBLIC_DIR, "index.html"));
   }
@@ -639,6 +896,11 @@ async function handleRequest(
     return serveFile(res, path.join(PUBLIC_DIR, "release.html"));
   }
 
+  // The Edge page (PL-SPEC §10): read-only, from /api/edge.
+  if (pathname === "/edge" || pathname === "/edge.html") {
+    return serveFile(res, path.join(PUBLIC_DIR, "edge.html"));
+  }
+
   if (pathname === "/logs") {
     return serveFile(res, path.join(PUBLIC_DIR, "logs.html"));
   }
@@ -647,6 +909,9 @@ async function handleRequest(
     return serveFile(res, path.join(PUBLIC_DIR, "header.js"));
   }
 
+  // The active theme as CSS, its mark and fonts, and the theme list.
+  if (handleThemeRoutes(req, res, pathname, themeDeps)) return;
+
   // The graph's modules (graph.js, panel.js, …) and vendored libraries (ELK).
   if (serveUiAsset(res, pathname, PUBLIC_DIR)) return;
 
@@ -690,6 +955,9 @@ async function handleRequest(
 
   // ── API: environments ──────────────────────────────────────────────────────
   // Orgs the catalog's repos belong to, with config/den.yml display names.
+  // ORG-1d: a repo's org is an org listing it, else one whose source claims
+  // its owner, else its GitHub owner; a claimed owner is not listed. Service
+  // rows keep `org` as the repo's GitHub owner (C3).
   // Each entry also says whether it is the default org (`github_org`) and
   // which workspaces on this machine belong to it (ORG-1a). Nothing else
   // changes: same entries, order and fields (ORG-SPEC C3).
@@ -704,7 +972,7 @@ async function handleRequest(
     );
     if (url.searchParams.get("repos") !== "1") return sendJson(res, orgs);
     const repos = Object.fromEntries(
-      Object.keys(catalog).map((r) => [r, orgOf(r, catalog)]),
+      Object.keys(catalog).map((r) => [r, orgOf(r, catalog, ctx.config.orgs)]),
     );
     return sendJson(res, { orgs, repos });
   }
@@ -809,6 +1077,17 @@ async function handleRequest(
     } catch {
       return send400(res, "invalid JSON");
     }
+    // A call that named a path (manifest_validate) is recorded under the
+    // catalog repo that path is inside, across every workspace's checkouts.
+    if (typeof report.repo !== "string" && report.path !== undefined) {
+      let repo: string | null = null;
+      try {
+        repo = repoAtPath(report.path, allWorkspaceCheckouts());
+      } catch {
+        /* unresolvable workspaces: recorded under the tool only */
+      }
+      if (repo) report = { ...report, repo };
+    }
     const entry = recordAgentRefusal(actor, report);
     return sendJson(res, { recorded: true, ts: entry.ts });
   }
@@ -886,9 +1165,11 @@ async function handleRequest(
 
   // ── API: health check ─────────────────────────────────────────────────────
   /**
-   * Workspaces a health run covers: one named workspace, else EVERY active one
-   * (focus first). Health is machine-level — a service running under a
-   * non-focused active workspace is still up, and its card must say so.
+   * Workspaces a health run covers: one named workspace, else the view
+   * scope's (every active one by default, focus first). Health is
+   * machine-level: a service running under a non-focused active workspace
+   * is still up, and its card must say so. The pages and `status` read the
+   * same scope (src/shared/environment-manager/scope.ts).
    */
   function healthWorkspaces(
     workspaceName: string | null,
@@ -897,12 +1178,7 @@ async function handleRequest(
       const named = getWorkspaceByName(workspaceName);
       return named ? [named] : [];
     }
-    const focus = getFocusedWorkspaceName();
-    const names = [
-      ...(focus ? [focus] : []),
-      ...getActiveWorkspaces().filter((n) => n !== focus),
-    ];
-    return names.flatMap((n) => getWorkspaceByName(n) ?? []);
+    return scopeView().workspaces.filter((w) => w.config);
   }
 
   /**
@@ -929,11 +1205,16 @@ async function handleRequest(
       string,
       { svc: ResolvedService; ws: { name: string; config: WorkspaceConfig } }
     >();
+    const owners = new Map<string, string[]>();
     for (const ws of workspaces)
-      for (const svc of listWorkspaceServices(ws.config, catalog, ws.name))
+      for (const svc of listWorkspaceServices(ws.config, catalog, ws.name)) {
         // Modules and libraries have no runtime, so no health dot.
-        if (!byAddress.has(svc.address) && hasRuntime(repoKind(svc.repoPath)))
+        if (!hasRuntime(repoKind(svc.repoPath))) continue;
+        if (!byAddress.has(svc.address))
           byAddress.set(svc.address, { svc, ws });
+        const o = owners.get(svc.address) ?? [];
+        if (!o.includes(ws.name)) owners.set(svc.address, [...o, ws.name]);
+      }
     let services = [...byAddress.values()];
     if (addressFilter) {
       services = services.filter((s) => s.svc.address === addressFilter);
@@ -962,11 +1243,19 @@ async function handleRequest(
       compose: ComposeHealthTarget | null;
       /** A `type: container` check: answered from the shared listing. */
       container: ContainerHealthTarget | null;
-      meta: Pick<HealthResult, "runs" | "target">;
+      meta: Pick<HealthResult, "runs" | "target" | "focused" | "workspaces">;
     }> = [];
+    const focusName = getFocusedWorkspaceName();
     let edgeDomain: string | null = null;
+    // The links follow the edge's TLS: http on its http port for `tls: none`
+    // (0.3.0-dev.40, DOC-1: the panel's Opens said https).
+    let edgeOrigin: EdgeOrigin | undefined;
     try {
-      edgeDomain = readEdgeConfig().domain;
+      const edge = readEdgeConfig();
+      edgeDomain = edge.domain;
+      edgeOrigin = edgeHttps(edge)
+        ? { https: true, port: edge.ports?.https ?? 443 }
+        : { https: false, port: edge.ports?.http ?? 80 };
     } catch {
       /* no edge configured: local links come from manifests only */
     }
@@ -996,7 +1285,12 @@ async function handleRequest(
           org: orgOf(resolved.repoName, catalog),
           compose: null,
           container: null,
-          meta: { runs: "none", target: null },
+          meta: {
+            runs: "none",
+            target: null,
+            focused: ws.name === focusName,
+            workspaces: owners.get(resolved.address) ?? [ws.name],
+          },
         });
         continue;
       }
@@ -1074,6 +1368,7 @@ async function handleRequest(
           env,
           healthUrl: healthCfg && "url" in healthCfg ? healthCfg.url : null,
           edgeDomain,
+          edgeOrigin,
         }),
         links: linksFor(manifest, resolved.subsystem, env),
         org: orgOf(resolved.repoName, catalog),
@@ -1081,7 +1376,12 @@ async function handleRequest(
         compose,
         container:
           healthCfg?.type === "container" ? containerTarget(healthCfg) : null,
-        meta: { runs: plan.placement.runs, target: plan.placement.target },
+        meta: {
+          runs: plan.placement.runs,
+          target: plan.placement.target,
+          focused: ws.name === focusName,
+          workspaces: owners.get(resolved.address) ?? [ws.name],
+        },
       });
     }
 
@@ -1318,7 +1618,8 @@ async function handleRequest(
     return sendJson(
       res,
       await servicesCache.get(
-        `${env}|${wsOverride ?? ""}`,
+        // No workspace named: what the view scope has in view.
+        `${env}|${wsOverride ?? `*:${scopeKey(scopeView())}`}`,
         () => buildServicesList(env, wsOverride),
         url.searchParams.get("refresh") === "1",
       ),
@@ -2392,10 +2693,10 @@ async function handleRequest(
     // `org` resolved (id defaults to edge.org) for the header's org label.
     const config = readDenConfig();
     // `default_org` (ORG-1a) is the default work org, `github_org`; `org`
-    // stays the instance org (readOrg).
+    // stays the instance org (readOrgView).
     return sendJson(res, {
       ...config,
-      org: readOrg(),
+      org: readOrgView(),
       default_org: config.github_org?.trim() || null,
     });
   }
@@ -2403,11 +2704,17 @@ async function handleRequest(
   // ── API: server info + staleness (drives the header "stale server" pill) ────
   if (pathname === "/api/server-info" && req.method === "GET") {
     const { stale, scanned } = computeStale();
+    const engine = engineCheck();
     return sendJson(res, {
       pid: process.pid,
       port: PORT,
-      // Den's version: the MCP server compares it with the routes it needs.
-      version: engineVersion() ?? null,
+      // The Den this server runs (its routes): the MCP server compares it
+      // with the routes it needs. loaded and onDisk (MD-2): the engine at
+      // startup and on disk now; engineStale when they differ.
+      version: ENGINE.loaded.version ?? engineVersion() ?? null,
+      loaded: engine.loaded,
+      onDisk: engine.onDisk,
+      engineStale: engine.stale,
       // Whose server this is: `<cli> web up|down`, `mcp connect` and
       // `service install` compare both with their own and never act on
       // another distribution's server (see cli/server-identity.ts).
@@ -2807,8 +3114,9 @@ async function handleRequest(
   // ── API: sudo password ────────────────────────────────────────────────────
   // POST /api/sudo-password  body: { password: string, saveToVault?: boolean }
   // GET  /api/sudo-password/status         → { set: boolean }
-  // GET  /api/sudo-password/vault-status   → { opAvailable, hasStored }
-  // POST /api/sudo-password/load-from-vault → { ok, reason? }
+  // GET  /api/sudo-password/vault-status   → { backend, label, configured,
+  //        backendAvailable, reason?, hasStored, opAvailable (deprecated) }
+  // POST /api/sudo-password/load-from-vault → { ok, reason?, message? }
   if (pathname === "/api/sudo-password") {
     if (req.method !== "POST") {
       res.writeHead(405);
@@ -2860,11 +3168,10 @@ async function handleRequest(
   }
 
   // Advertises vault capability to the UI so it knows whether to show the
-  // "Save to 1Password" checkbox and whether auto-load is worth trying.
+  // "Save to <backend>" checkbox and whether auto-load is worth trying. With
+  // no secrets.refs.sudo it says "not configured" and spawns nothing.
   if (pathname === "/api/sudo-password/vault-status") {
-    const opAvailable = await isOpSignedIn();
-    const hasStored = opAvailable ? await hasSudoInVault() : false;
-    return sendJson(res, { opAvailable, hasStored });
+    return sendJson(res, await sudoVaultStatus());
   }
 
   // Auto-unlock path: UI calls this when status.set is false. We read from
@@ -2877,6 +3184,13 @@ async function handleRequest(
       res.end();
       return;
     }
+    if (!sudoRef()) {
+      return sendJson(res, {
+        ok: false,
+        reason: "not-configured",
+        message: notConfiguredMessage(SUDO_REF_NAME),
+      });
+    }
     const password = await readSudoFromVault();
     if (!password) {
       return sendJson(res, { ok: false, reason: "not-found" });
@@ -2898,9 +3212,43 @@ async function handleRequest(
   }
 
   // ── API: user settings ────────────────────────────────────────────────────
-  // GET  /api/settings  → { editor, editors, terminal, terminals, editor_overrides, languages }
-  // POST /api/settings  body: { editor?, terminal?, editor_overrides?, graph? }
+  // GET  /api/settings  → { editor, editors, terminal, terminals, editor_overrides, languages,
+  //                         log_window_lines, graph, appearance, shell, distribution,
+  //                         user_web_port, local_dev, cli_tabs, language, ui_languages }
+  // POST /api/settings  body: { editor?, terminal?, editor_overrides?, graph?, appearance?, shell?,
+  //                             language? }
   //   graph: { direction, group, density, panelWidth } (see graph-prefs.ts)
+  //   appearance: { theme: id | null, mode: system|dark|light } (appearance-prefs.ts)
+  //   shell: { pins, collapsed, hidden, order, dock, dockHeight } (shell-prefs.ts)
+  //   language: the UI's language, en | ja | es (ui-language.ts); null or
+  //     "en" clears it (English is the default)
+  // It writes config/local/user.yml only. `distribution` is read-only: what
+  // the org config (tracked) sets, for the Settings page's Distribution rows.
+  // Every key POST accepts has a row in the Settings page's registry
+  // (settings-registry.js; settings-inventory.test.ts checks).
+  // The view scope: which active workspaces the pages, the health row and
+  // `status` show. A view preference only (user.yml `view`): it changes no
+  // edge route, container or service, and never the focus.
+  if (pathname === "/api/scope") {
+    if (req.method === "GET") return sendJson(res, scopePayload(scopeView()));
+    if (req.method === "POST") {
+      let body: { scope?: unknown };
+      try {
+        body = JSON.parse(await readBody(req)) as { scope?: unknown };
+      } catch {
+        return send400(res, "invalid JSON");
+      }
+      const parsed = parseScope(body.scope, getActiveWorkspaces());
+      if (!parsed.ok) return send400(res, parsed.error);
+      const user = readUserConfig();
+      const view = storedView(parsed.value);
+      if (view) user.view = view;
+      else delete user.view;
+      writeUserConfig(user);
+      return sendJson(res, scopePayload(scopeView(parsed.value)));
+    }
+  }
+
   if (pathname === "/api/settings") {
     if (req.method === "GET") {
       const user = readUserConfig();
@@ -2915,6 +3263,16 @@ async function handleRequest(
         languages: SUPPORTED_LANGUAGES,
         log_window_lines: user.log_window_lines ?? 20_000,
         graph: graphPrefs(user.graph),
+        appearance: appearancePrefs(user.appearance),
+        shell: shellPrefs(user.shell),
+        distribution: distributionSettings(getDistRoot()),
+        // Set from the command line (`<cli> config`), shown read-only.
+        user_web_port: userWebPort(user as Record<string, unknown>),
+        local_dev: user.local_dev !== false,
+        cli_tabs: user.cli_tabs === true,
+        // The UI's language (R19), and the ones it has catalogs for.
+        language: uiLanguage(user.language),
+        ui_languages: UI_LANGUAGES,
       });
     }
     if (req.method === "POST") {
@@ -2924,12 +3282,57 @@ async function handleRequest(
           terminal?: string | null;
           editor_overrides?: Record<string, string> | null;
           graph?: unknown;
+          appearance?: unknown;
+          shell?: unknown;
+          language?: unknown;
         };
         const user = readUserConfig();
-        if (body.graph !== undefined) {
-          const g = mergeGraphPrefs(graphPrefs(user.graph), body.graph);
+        // null clears (0.3.0-dev.32, a consumer's nit): a block or a key
+        // set to null is removed from user.yml, and a block left empty
+        // goes too, so setting a pref and clearing it again leaves the
+        // file byte-identical.
+        // The rail's pins and collapse (R14): a view preference only.
+        if (body.shell === null) delete user.shell;
+        else if (body.shell !== undefined) {
+          const sh = mergeShellPrefs(shellPrefs(user.shell), body.shell);
+          if (!sh.ok) return send400(res, sh.error);
+          const stored = storedShell(sh.value);
+          if (stored) user.shell = stored;
+          else delete user.shell;
+        }
+        if (body.graph === null) delete user.graph;
+        else if (body.graph !== undefined) {
+          const g = patchStoredGraph(user.graph, body.graph);
           if (!g.ok) return send400(res, g.error);
-          user.graph = g.value;
+          if (g.value) user.graph = g.value as UserConfig["graph"];
+          else delete user.graph;
+        }
+        // A UI preference only: the page swaps /theme.css and data-mode.
+        if (body.appearance === null) delete user.appearance;
+        else if (body.appearance !== undefined) {
+          const a = mergeAppearancePrefs(
+            appearancePrefs(user.appearance),
+            body.appearance,
+            (id) => !!findTheme(themeDeps.roots(), id)?.ok,
+          );
+          if (!a.ok) return send400(res, a.error);
+          const stored = storedAppearance(a.value);
+          if (stored) user.appearance = stored;
+          else delete user.appearance;
+        }
+        // The UI's language (R19): stored only when it isn't English.
+        if (body.language !== undefined) {
+          const clear =
+            body.language === null ||
+            body.language === "" ||
+            body.language === "en";
+          if (!clear && !isUiLanguage(body.language))
+            return send400(
+              res,
+              `language must be one of ${UI_LANGUAGES.map((l) => `"${l}"`).join(", ")}`,
+            );
+          if (clear) delete user.language;
+          else user.language = body.language as string;
         }
         if (body.editor === null || body.editor === "") {
           delete user.editor;
@@ -2975,6 +3378,9 @@ async function handleRequest(
           terminal: user.terminal ?? null,
           editor_overrides: user.editor_overrides ?? {},
           graph: graphPrefs(user.graph),
+          appearance: appearancePrefs(user.appearance),
+          shell: shellPrefs(user.shell),
+          language: uiLanguage(user.language),
         });
       } catch (e) {
         return send400(res, `Invalid request: ${(e as Error).message}`);
@@ -3142,22 +3548,157 @@ async function handleRequest(
     }
   }
 
+  // A route that throws, for the error frame's tests and screenshots only
+  // (DEN_DEBUG_ROUTES=1): a page and an API call.
+  if (
+    process.env.DEN_DEBUG_ROUTES === "1" &&
+    (pathname === "/_den/throw" || pathname === "/api/_den/throw")
+  ) {
+    throw new Error("a debug route threw (DEN_DEBUG_ROUTES)");
+  }
+
   // ── 404 ────────────────────────────────────────────────────────────────────
+  sendNotFound(req, res, pathname, requestId);
+}
+
+/**
+ * No route answered. /api: the R26b JSON (an `engine_stale` code naming
+ * both versions when the engine on disk is newer: its routes are the ones
+ * that 404 here). A page: the shell's 404 page (R26a). Anything else (an
+ * asset): plain text, as before.
+ */
+function sendNotFound(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  requestId: string,
+): void {
+  if (pathname === "/api" || pathname.startsWith("/api/")) {
+    const engine = engineCheck();
+    if (engine.stale)
+      return sendJson(
+        res,
+        {
+          ok: false,
+          error: engineStaleMessage(engine, product().cli),
+          code: "engine_stale",
+          loaded: engine.loaded.version,
+          onDisk: engine.onDisk.version,
+        },
+        404,
+      );
+    return sendJson(
+      res,
+      {
+        ok: false,
+        error: `No such API route: ${req.method ?? "GET"} ${pathname}`,
+        code: "not_found",
+      },
+      404,
+    );
+  }
+  if (wantsHtmlPage(req, pathname))
+    return sendErrorPage(req, res, {
+      status: 404,
+      path: pathname,
+      requestId,
+      plugin: pluginForPath(pathname, ROOT),
+    });
   res.writeHead(404, { "Content-Type": "text/plain" });
   res.end("Not found");
 }
 
+/** The request's id: assigned once (the handler and its catch share it). */
+const REQUEST_IDS = new WeakMap<http.IncomingMessage, string>();
+function requestIdOf(req: http.IncomingMessage): string {
+  let id = REQUEST_IDS.get(req);
+  if (!id) {
+    id = newRequestId();
+    REQUEST_IDS.set(req, id);
+  }
+  return id;
+}
+
 const server = http.createServer((req, res) => {
   // An async handler with no catch turns any route throw into an unhandled
   // rejection — which CRASHES the whole server on modern Node (freezing every
   // health dot) and leaves the request hanging. Fail the one request instead.
-  handleRequest(req, res).catch((err) => {
-    console.error(`[server] ${req.method} ${req.url} failed:`, err);
+  handleRequest(req, res).catch((err: unknown) => {
+    // R26: the log has the stack under the request id; the browser gets the
+    // id, never the stack. The route is its template: no query values.
+    const requestId = requestIdOf(req);
+    const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    const route = routeTemplate(pathname);
+    const method = req.method ?? "GET";
+    // A config that fails validation is the user's to fix, not a crash: the
+    // /api frame answers 422 config_invalid (jsonApiErrors adds requestId), a
+    // page gets the error page saying so, anything else the message as text.
+    if (isConfigError(err)) {
+      serverLog(
+        `  ⚠ ${method} ${route} (req ${requestId}): ${err.message}`,
+        "error",
+      );
+      try {
+        if (res.headersSent) {
+          res.end();
+          return;
+        }
+        if (pathname === "/api" || pathname.startsWith("/api/")) {
+          sendJson(res, configErrorBody(err), CONFIG_ERROR_STATUS);
+          return;
+        }
+        if (wantsHtmlPage(req, pathname)) {
+          sendErrorPage(req, res, {
+            status: CONFIG_ERROR_STATUS,
+            path: pathname,
+            message: err.message,
+            issues: configErrorBody(err).issues,
+            cli: product().cli,
+            requestId,
+          });
+          return;
+        }
+        res.writeHead(CONFIG_ERROR_STATUS, { "Content-Type": "text/plain" });
+        res.end(`${err.message} (request ${requestId})`);
+      } catch {
+        /* socket already gone */
+      }
+      return;
+    }
+    const stack =
+      err instanceof Error ? (err.stack ?? err.message) : String(err);
+    serverLog(
+      `  ✗ ${method} ${route} failed (req ${requestId}): ${stack}`,
+      "error",
+    );
+    if (SILENT)
+      console.error(
+        `[server] ${method} ${route} failed (req ${requestId}):`,
+        err,
+      );
     try {
-      if (!res.headersSent) {
-        res.writeHead(500, { "Content-Type": "text/plain" });
+      if (res.headersSent) {
+        res.end();
+        return;
+      }
+      if (pathname === "/api" || pathname.startsWith("/api/")) {
+        sendJson(
+          res,
+          {
+            ok: false,
+            error: `${method} ${route} failed on the server`,
+            code: "internal",
+          },
+          500,
+        );
+        return;
+      }
+      if (wantsHtmlPage(req, pathname)) {
+        sendErrorPage(req, res, { status: 500, method, route, requestId });
+        return;
       }
-      res.end("internal server error");
+      res.writeHead(500, { "Content-Type": "text/plain" });
+      res.end(`internal server error (request ${requestId})`);
     } catch {
       /* socket already gone */
     }
@@ -3215,6 +3756,8 @@ void (async () => {
     delay: (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
     retryDelayMs: DAEMON_RETRY_DELAY_MS,
     rootOf: daemonRootOf,
+    staleReason: daemonStaleReason,
+    runningContainers: runningContainerBasesAsync,
   });
   if (reaped.removed.length > 0)
     console.error(
@@ -3292,6 +3835,8 @@ server.listen(PORT, BIND_HOST, () => {
   console.log();
   console.log(`  Web UI  →  http://${host}:${PORT}`);
   console.log();
+  // Once per start: a secrets config that leaves Den's own features off.
+  for (const w of secretsConfigWarnings()) serverLog(`  ⚠ ${w}`);
 });
 
 // ── Graceful shutdown ─────────────────────────────────────────────────────────