@monster-orange/den 0.4.0 → 0.4.2

package/src/ui/server/index.ts

@@ -19,6 +19,7 @@ import {
 import { healthCheckFields, type HealthCheckType } from "./health-row.js";
 import { hasRuntime, repoKind } from "../../shared/repo-kind.js";
 import * as http from "http";
+import * as net from "net";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -58,6 +59,8 @@ import {
 import {
   parseScope,
   scopeKey,
+  pollView,
+  inViewMarker,
   scopePayload,
   scopeView,
   storedView,
@@ -127,6 +130,7 @@ import {
   engineVersion,
   getDistRoot,
   getEngineRoot,
+  getStateDir,
 } from "../../shared/paths.js";
 import { enginePath } from "../../shared/engine.js";
 import {
@@ -136,7 +140,10 @@ import {
   type ReleaseEvent,
 } from "./release-service.js";
 import { deploySessions } from "./release-deploy-session.js";
-import { spawnDetachedWebRestart } from "../cli/web-command.js";
+import {
+  hasDenHostsEntry,
+  spawnDetachedWebRestart,
+} from "../cli/web-command.js";
 import { recordInvocation } from "../../shared/dev-metrics/emit.js";
 import {
   validateManifest,
@@ -164,7 +171,6 @@ import {
 import { DEN_BANNER_LINES, DEN_SUBTITLE } from "../../shared/banner.js";
 import { actorLabel } from "../../shared/agent-actor.js";
 import {
-  actorFromHeaders,
   actorSuffix,
   recordAction,
   recordAgentRefusal,
@@ -173,6 +179,44 @@ import {
   setAuditSink,
 } from "./audit.js";
 import { handleReadonlyRoutes } from "./readonly-routes.js";
+import {
+  auditActorOf,
+  bindRefusal,
+  checkRequest,
+  isEdgePeer,
+  isLoopbackAddress,
+  isLoopbackBind,
+  newCsrfToken,
+  principalOf,
+  requestIsHttps,
+  sessionRequestAllowed,
+  setPrincipal,
+  signinMessage,
+  type GuardContext,
+  type GuardResult,
+} from "./request-guard.js";
+import {
+  rotateWebSecret,
+  verifyPersonToken,
+  WebSecretStore,
+} from "../../shared/web-secret.js";
+import {
+  ACTOR_TOKEN_PREFIX,
+  checkActorToken,
+  revokeAllActorTokens,
+} from "../../shared/actor-token.js";
+import {
+  checkLoginCode,
+  ignoredConfigWarning,
+  localhostOrigin,
+  readWebAuthConfig,
+  safeNext,
+  SESSION_COOKIE_MAX_AGE_S,
+  sessionCookieName,
+  sessionIdPrefix,
+  WebSessionStore,
+  type WebAuthConfig,
+} from "../../shared/web-session.js";
 import { serveUiAsset } from "./ui-assets.js";
 import { graphPrefs, patchStoredGraph } from "./graph-prefs.js";
 import { graphPageHtml } from "./graph-page.js";
@@ -239,10 +283,16 @@ interface HealthResult {
   /** From the focused workspace: the header sorts these first. */
   focused?: boolean;
   /**
-   * The workspaces in view that define this service (focus first). More
+   * The active workspaces that define this service (focus first). More
    * than one means a shared service: it is listed once, with its owners.
    */
   workspaces?: string[];
+  /**
+   * WS-6.4: whether the view scope shows it (one of its workspaces is in
+   * view). Health covers every active workspace; the header's chip and
+   * drawer count only these, while the pages see every row.
+   */
+  inView?: boolean;
 }
 
 /**
@@ -274,6 +324,19 @@ function viewerRewrite(
   });
 }
 
+/**
+ * A health row as this request sees it: its links rewritten for the
+ * viewer's host, and `inView` from the view scope now (WS-6.4: the rows
+ * are cached for every active workspace; the scope is applied per answer).
+ */
+function healthForViewer(
+  host: string | undefined,
+): (r: HealthResult) => HealthResult {
+  const rewrite = viewerRewrite(host);
+  const inView = inViewMarker(scopeView());
+  return (r) => ({ ...rewrite(r), inView: inView(r.workspaces) });
+}
+
 const HEALTH_CACHE_TTL_MS = 8_000;
 /** Consecutive timed-out health cycles per check (see TimeoutStreaks). */
 const healthTimeouts = new TimeoutStreaks();
@@ -303,10 +366,11 @@ 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, and the default one covers whatever the view scope has in view.
+ * one, and the default one covers every active workspace (WS-6.4: the view
+ * scope filters what is displayed, never what is polled).
  */
 function healthCacheKey(env: Environment, workspace: string | null): string {
-  return `${env}|${workspace ?? `*:${scopeKey(scopeView())}`}`;
+  return `${env}|${workspace ?? `*:${scopeKey(pollView())}`}`;
 }
 import {
   LOG_SWEEP_INTERVAL_MS,
@@ -435,9 +499,13 @@ function pushLog(kind: string, text: string, actor?: string): void {
  */
 function serverLog(msg: string, kind: string = "info", actor?: string): void {
   pushLog(kind, msg, actor);
-  if (!SILENT) process.stdout.write(msg + "\n");
+  if (!SILENT && !outputLost()) process.stdout.write(msg + "\n");
 }
 
+// Its output's reader gone (the terminal, runner or script that started it
+// was killed): write nothing more, and shut down (shutdown-guard.ts).
+guardStdio(() => beginShutdown("SIGPIPE"));
+
 // ── 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:
@@ -470,6 +538,17 @@ setHtmlFill((html) => {
     .join(mode)
     .split("@@DEN_DEFAULT_MODE@@")
     .join(def);
+  // 0.4.1: every page says when the config fails validation, so the shell
+  // starts none of its config polls (each would answer 422).
+  try {
+    assertDenConfigValid();
+  } catch (e) {
+    if (isConfigError(e))
+      out = out.replace(
+        '<div id="den-shell"',
+        () => '<div id="den-shell" data-config-invalid="1"',
+      );
+  }
   // MD-2: every page says when the engine on disk is not the one running.
   const engine = engineCheck();
   if (engine.stale)
@@ -522,10 +601,22 @@ function sendErrorPage(
     res.end();
     return;
   }
+  // A refusal page (421, signed out): every /api call the shell frame
+  // would make answers the same refusal, so the shell starts none of its
+  // polls and streams (data-api-off; shell.js apiOff).
+  const off = data.status === 421 || data.code === "signin_required";
   serveFile(
     res,
     path.join(PUBLIC_DIR, "error.html"),
-    (html) => fillErrorPage(html, full),
+    (html) => {
+      const page = fillErrorPage(html, full);
+      return off
+        ? page.replace(
+            '<div id="den-shell"',
+            () => '<div id="den-shell" data-api-off="1"',
+          )
+        : page;
+    },
     data.status,
   );
 }
@@ -587,6 +678,12 @@ function allWorkspaceCheckouts(): ResolvedService[] {
  */
 const CONFIG_FREE_ROUTES = new Set([
   "/api/server-info",
+  // SEC-1a: the shell's CSRF token, which the Settings fix itself needs.
+  "/api/session",
+  // SEC-1b: signing out, and the CLI's `web sessions` / `web logout`.
+  "/api/session/logout",
+  "/api/web/sessions",
+  "/api/web/logout",
   "/api/server-log",
   "/api/changelog",
   "/api/web/restart",
@@ -610,11 +707,19 @@ const CONFIG_FREE_PAGES = new Set(["/settings", "/settings.html", "/logs"]);
 import {
   setSudoPassword,
   clearSudoPassword,
+  closeLockForThisRequest,
+  inRequestLockScope,
   getSudoEnv,
   prewarmSudo,
   hasSudoPassword,
   hasPasswordlessSudo,
 } from "./sudo-store.js";
+import {
+  guardStdio,
+  isLostOutputError,
+  outputLost,
+  requestShutdown,
+} from "./shutdown-guard.js";
 
 // ── HTTP helpers ─────────────────────────────────────────────────────────────
 import { sweepLogs } from "../../shared/process/log-rotation.js";
@@ -658,9 +763,17 @@ import { parseChangelog } from "./changelog-parser.js";
 import { GitHubService } from "./github-service.js";
 import { EditorManager, SUPPORTED_LANGUAGES } from "./editor-manager.js";
 import { handleWorkspaceRoutes } from "./workspace-routes.js";
+import { handleAgentRoutes } from "./agent-routes.js";
+import {
+  handleSessionList,
+  handleSessionUpgrade,
+  isSessionIoPath,
+  sendSessionHttp,
+} from "./session-routes.js";
+import { refuseUpgrade } from "./websocket.js";
 import { isLifecycleExecCmd, streamLifecycleExec } from "./lifecycle-exec.js";
 import { readEdgeConfig, readWebPort } from "../../shared/edge/config.js";
-import { edgeHttps } from "../../shared/edge/render.js";
+import { edgeDomains, edgeHttps, routeHost } from "../../shared/edge/render.js";
 import {
   linksFor,
   openUrlFor,
@@ -776,6 +889,358 @@ function mirrorLine(runId: string, text: string): void {
   process.stdout.write(`  ${dim(`[${runId}]`)} ${stripAnsi(text)}\n`);
 }
 
+// ── Request checks (SEC-1a, SEC-1 spec §3) ─────────────────────────────────────
+
+/**
+ * The edge hostnames that route to this server: each route whose upstream
+ * is this server's port (or the configured `web.port`, which the edge's
+ * own route for Den names) on the docker host, under every edge domain.
+ * None without an edge block.
+ */
+function denEdgeHosts(): string[] {
+  let cfg: ReturnType<typeof readEdgeConfig>;
+  try {
+    cfg = readEdgeConfig();
+  } catch {
+    return [];
+  }
+  const ports = new Set([PORT, readWebPortSafe()]);
+  const names = Object.entries(cfg.routes)
+    .filter(([, upstream]) => {
+      try {
+        const u = new URL(upstream);
+        return (
+          ports.has(Number(u.port || (u.protocol === "https:" ? 443 : 80))) &&
+          ["host.docker.internal", "localhost", "127.0.0.1"].includes(
+            u.hostname,
+          )
+        );
+      } catch {
+        return false;
+      }
+    })
+    .map(([name]) => name);
+  return names.flatMap((n) =>
+    edgeDomains(cfg).map((d) => routeHost(n, d).toLowerCase()),
+  );
+}
+
+// Bind loopback only: this UI runs privileged local actions (sudo-backed
+// service commands). DEN_BIND_HOST=0.0.0.0 exposes it deliberately, and
+// (SEC-1b) only with HTTPS in front or web.allow_plain_http_remote.
+const BIND_HOST = process.env.DEN_BIND_HOST ?? "127.0.0.1";
+
+/**
+ * SEC-1b: `web.allow_plain_http_remote`, read at start. A wrong value
+ * refuses to start, naming its key. The 0.4.1-dev `web.session` lifetimes
+ * are ignored (a session never expires), with a warning at start.
+ */
+const WEB_AUTH: WebAuthConfig = (() => {
+  try {
+    return readWebAuthConfig(getDistRoot(), product().configFile);
+  } catch (e) {
+    console.error(`\n  ✗ ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+})();
+
+/**
+ * The loopback names, with the port: localhost (canonical), 127.0.0.1 and
+ * [::1]; the product's own name when /etc/hosts maps it to 127.0.0.1 (the
+ * URL `web up` opens then); and a loopback address DEN_BIND_HOST binds.
+ */
+function loopbackNames(): string[] {
+  const names = ["localhost", "127.0.0.1", "[::1]"];
+  try {
+    if (hasDenHostsEntry(fs.readFileSync("/etc/hosts", "utf-8")))
+      names.push(product().cli.toLowerCase());
+  } catch {
+    /* no hosts file */
+  }
+  const bind = BIND_HOST.trim().toLowerCase();
+  if (net.isIP(bind) && isLoopbackBind(bind))
+    names.push(net.isIPv6(bind) ? `[${bind}]` : bind);
+  return [...new Set(names)];
+}
+
+/**
+ * SEC-1b: this machine's own LAN names, with the port, for a non-loopback
+ * bind that `web.allow_plain_http_remote` allows: the bound address, or
+ * (0.0.0.0, ::) every interface's address and the host name. Beyond
+ * loopback, so every route needs a session. An IP literal or this
+ * machine's own name can't be rebound; any other name stays 421.
+ */
+function lanHosts(): string[] {
+  const bind = BIND_HOST.trim().toLowerCase();
+  if (isLoopbackBind(bind) || !WEB_AUTH.allowPlainHttpRemote) return [];
+  const br = (a: string) => (net.isIPv6(a) ? `[${a}]` : a);
+  if (bind !== "0.0.0.0" && bind !== "::")
+    return net.isIP(bind) ? [br(bind)] : [bind];
+  const out: string[] = [];
+  for (const list of Object.values(os.networkInterfaces()))
+    for (const a of list ?? [])
+      if (!a.internal)
+        out.push(br(a.address.toLowerCase().replace(/%.*$/, "")));
+  const host = os.hostname().toLowerCase();
+  if (host) out.push(host, host.endsWith(".local") ? host : `${host}.local`);
+  return [...new Set(out)];
+}
+
+/** HTTPS in front of this server: an edge with TLS that routes to it. */
+function edgeFronted(): boolean {
+  try {
+    return (
+      readEdgeConfig().tls.strategy !== "none" && denEdgeHosts().length > 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+const webSecret = new WebSecretStore();
+const webSessions = new WebSessionStore({
+  secret: () => webSecret.current(),
+});
+const SESSION_COOKIE = sessionCookieName(PORT);
+
+/** The request's `den_session_<port>` cookie value, if any. */
+function sessionCookie(req: http.IncomingMessage): string | undefined {
+  const raw = req.headers.cookie;
+  if (!raw) return undefined;
+  for (const part of raw.split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0 && part.slice(0, i).trim() === SESSION_COOKIE)
+      return part.slice(i + 1).trim();
+  }
+  return undefined;
+}
+
+const LAN_HOSTS = lanHosts();
+const GUARD: GuardContext = {
+  port: PORT,
+  loopbackNames: loopbackNames(),
+  edgeHosts: denEdgeHosts,
+  lanHosts: () => LAN_HOSTS,
+  verifyBearer: (token) => {
+    // SEC-1c: an agent's actor token, live while its session runs.
+    if (token.startsWith(ACTOR_TOKEN_PREFIX)) {
+      const rec = checkActorToken(getStateDir(), token);
+      if (rec === "revoked") return "revoked";
+      return rec
+        ? {
+            kind: "agent",
+            actor: rec.actor,
+            workspace: rec.workspace,
+            grants: rec.grants,
+            session: rec.session,
+          }
+        : null;
+    }
+    const secret = webSecret.current();
+    return secret ? verifyPersonToken(token, secret) : null;
+  },
+  csrfToken: newCsrfToken(),
+  session: (req) => webSessions.lookup(sessionCookie(req)),
+  peerIsLoopback: (req) => isLoopbackAddress(req.socket?.remoteAddress),
+  // The edge hostname only from the edge's own peers (loopback, Docker).
+  peerIsEdge: (req) => isEdgePeer(req.socket?.remoteAddress),
+};
+
+/**
+ * The Set-Cookie for a session: HttpOnly, SameSite=Strict, Path=/, Secure
+ * when the request came over HTTPS (requestIsHttps: the edge's own header
+ * only from the edge), for as long as a browser keeps a cookie: the
+ * session itself never expires.
+ */
+function sessionSetCookie(id: string, secure: boolean): string {
+  return (
+    `${SESSION_COOKIE}=${id}; Path=/; HttpOnly; SameSite=Strict; ` +
+    `Max-Age=${SESSION_COOKIE_MAX_AGE_S}${secure ? "; Secure" : ""}`
+  );
+}
+function clearSessionCookie(secure: boolean): string {
+  return (
+    `${SESSION_COOKIE}=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0` +
+    (secure ? "; Secure" : "")
+  );
+}
+
+/** The loopback names that aren't localhost: their signed-out page links there. */
+function nonCanonicalLoopback(req: http.IncomingMessage): boolean {
+  const h = String(req.headers.host ?? "")
+    .toLowerCase()
+    .replace(/:\d+$/, "");
+  return h !== "localhost" && GUARD.loopbackNames.includes(h);
+}
+
+/**
+ * The signed-out page (§2): the shell frame, "Sign in to use the terminal"
+ * (shell-grade on loopback) or "Sign in to use <title>", the command that
+ * prints a link, and on 127.0.0.1 or [::1] a link to the same path on
+ * localhost (where the cookie is). Never a form for a secret or a token.
+ */
+function sendSignedOut(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  opts: {
+    pathname: string;
+    search: string;
+    scope: "terminal" | "agents" | "den";
+    expired?: boolean;
+    requestId: string;
+    message: string;
+  },
+): void {
+  const host = String(req.headers.host ?? "").toLowerCase();
+  const toLocal = nonCanonicalLoopback(req);
+  const via = GUARD.edgeHosts().includes(host.replace(/:\d+$/, ""))
+    ? "edge"
+    : "other";
+  const origin = `${requestIsHttps(req, via === "edge" ? "edge" : null) ? "https" : "http"}://${host}`;
+  const cmd =
+    `${product().cli} web login` +
+    (toLocal || host === `localhost:${PORT}` ? "" : ` --origin ${origin}`);
+  res.setHeader("Cache-Control", "no-store");
+  sendErrorPage(req, res, {
+    status: 401,
+    code: "signin_required",
+    path: opts.pathname,
+    message: opts.message,
+    requestId: opts.requestId,
+    signin: {
+      scope: opts.scope,
+      name: product().title,
+      cmd,
+      ...(opts.expired ? { expired: true } : {}),
+      ...(toLocal && !opts.expired
+        ? {
+            localhost: `${localhostOrigin(PORT)}${opts.pathname}${opts.search}`,
+          }
+        : {}),
+    },
+  });
+}
+
+const PUBLIC_ASSET_EXTS = new Set([
+  ".js",
+  ".css",
+  ".ico",
+  ".png",
+  ".svg",
+  ".webp",
+  ".woff",
+  ".woff2",
+]);
+/** A GET of the UI's code or styling (never /api, a report or a page). */
+function isPublicAsset(req: http.IncomingMessage, pathname: string): boolean {
+  if (req.method !== "GET" && req.method !== "HEAD") return false;
+  if (/^\/(api|reports?)(\/|$)/.test(pathname)) return false;
+  return PUBLIC_ASSET_EXTS.has(path.extname(pathname).toLowerCase());
+}
+
+/** A refused request: R26 JSON for /api, the error page for a page. */
+function sendGuardRefusal(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  refusal: Extract<GuardResult, { ok: false }>,
+  requestId: string,
+  search = "",
+): void {
+  if (pathname === "/api" || pathname.startsWith("/api/"))
+    return sendJson(
+      res,
+      {
+        ok: false,
+        error: refusal.error,
+        code: refusal.code,
+        // signin_required: why, so the page words it in its own language.
+        ...(refusal.scope ? { scope: refusal.scope } : {}),
+        requestId,
+      },
+      refusal.status,
+    );
+  if (refusal.code === "signin_required" && wantsHtmlPage(req, pathname))
+    return sendSignedOut(req, res, {
+      pathname,
+      search,
+      scope: refusal.scope ?? "den",
+      requestId,
+      message: refusal.error,
+    });
+  if (wantsHtmlPage(req, pathname))
+    return sendErrorPage(req, res, {
+      status: refusal.status,
+      path: pathname,
+      message: refusal.error,
+      code: refusal.code,
+      requestId,
+    });
+  res.writeHead(refusal.status, { "Content-Type": "text/plain" });
+  res.end(`${refusal.error} (${refusal.code}, request ${requestId})`);
+}
+
+/**
+ * `GET /auth?c=<code>&next=<path>` (§2): a valid, unused login code (60 s,
+ * constant-time mac, single use) becomes a session and its cookie, then a
+ * 303 to `next` when it is a same-origin path, else `/`. Anything else gets
+ * the signed-out page, which never echoes the code.
+ */
+function handleAuth(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  url: URL,
+  requestId: string,
+  via: "loopback" | "edge" | "lan" | null,
+): void {
+  const secret = webSecret.current();
+  const check = secret
+    ? checkLoginCode(url.searchParams.get("c") ?? "", secret)
+    : null;
+  if (!check?.ok || !webSessions.consumeCode(check.nonce, check.expiresAt)) {
+    res.setHeader("Referrer-Policy", "no-referrer");
+    return sendSignedOut(req, res, {
+      pathname: "/auth",
+      search: "",
+      scope: "den",
+      expired: true,
+      requestId,
+      message: `That sign-in link expired or was used. Run \`${product().cli} web login\` for a new one.`,
+    });
+  }
+  const { id } = webSessions.create({
+    userAgent: req.headers["user-agent"],
+    host: req.headers.host,
+  });
+  res.writeHead(303, {
+    Location: safeNext(url.searchParams.get("next")),
+    "Set-Cookie": sessionSetCookie(id, requestIsHttps(req, via)),
+    "Cache-Control": "no-store",
+    "Referrer-Policy": "no-referrer",
+  });
+  res.end();
+}
+
+/**
+ * A service's declared command `cmd` for `env`, own properties only
+ * (SEC-1 §6b.2): `constructor` or `__proto__` is no command, never
+ * something from Object.prototype.
+ */
+function declaredCommand<T>(
+  commands: Record<string, Record<string, T> | undefined> | undefined,
+  env: string,
+  cmd: string,
+): T | undefined {
+  const own = (o: object | undefined, k: string) =>
+    o !== undefined && Object.prototype.hasOwnProperty.call(o, k);
+  if (!own(commands, env)) return undefined;
+  const forEnv = commands![env];
+  return own(forEnv, cmd) ? forEnv![cmd] : undefined;
+}
+
+/** A test module's name as a run takes it (SEC-1 §6b.2): never a path out. */
+const SAFE_MODULE_RE = /^[A-Za-z0-9_@][A-Za-z0-9._@/-]{0,127}$/;
+
 // ── Server ────────────────────────────────────────────────────────────────────
 
 async function handleRequest(
@@ -790,15 +1255,6 @@ async function handleRequest(
   // 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 (
-    (req.method !== "GET" && req.method !== "HEAD") ||
-    /\/(exec|sync)$/.test(pathname)
-  ) {
-    servicesCache.clear();
-    clearReadCache();
-  }
 
   // ── Request logging ────────────────────────────────────────────────────────
   // /api/health fires on the UI's 5s polling interval forever — it dominates
@@ -823,6 +1279,69 @@ async function handleRequest(
     }
   }
 
+  // ── Request checks (SEC-1a): Host, credential, Origin, CSRF ────────────────
+  // Before any route, and before a refused request can clear a cache.
+  const guard = checkRequest(req, GUARD, product().cli, product().title);
+  // The UI's own scripts and styles answer any host, and without a
+  // session, so the 421 and signed-out pages (which need shell.js and the
+  // theme) render; they hold no data. The request log above records the
+  // refusal (status, request id; never the query, where a login code is).
+  if (
+    !guard.ok &&
+    !(
+      (guard.code === "misdirected" || guard.code === "signin_required") &&
+      isPublicAsset(req, pathname)
+    )
+  )
+    return sendGuardRefusal(req, res, pathname, guard, requestId, url.search);
+  if (guard.ok) setPrincipal(req, guard.principal);
+  // SEC-1c (R8): an agent's request never passes the lock.
+  if (guard.ok && guard.principal?.kind === "agent") closeLockForThisRequest();
+
+  // ── Sign-in (SEC-1b, §2) ───────────────────────────────────────────────────
+  // Before config validation: signing in never depends on the config.
+  if (pathname === "/auth" && (req.method === "GET" || req.method === "HEAD"))
+    return handleAuth(req, res, url, requestId, guard.ok ? guard.via : null);
+  if (
+    pathname === "/signin" &&
+    (req.method === "GET" || req.method === "HEAD")
+  ) {
+    // Read-only and sign-in free (§6b.3): it checks the session itself.
+    // Signed in, or on loopback (no sign-in there), it goes on to a
+    // same-origin `next`; signed out beyond loopback, it is the signed-out
+    // page (the `web login` hint, never a form for the secret).
+    if (guard.ok && (guard.session || !guard.beyond)) {
+      res.writeHead(303, {
+        Location: safeNext(url.searchParams.get("next")),
+        "Cache-Control": "no-store",
+      });
+      res.end();
+      return;
+    }
+    return sendSignedOut(req, res, {
+      pathname,
+      search: url.search,
+      scope: "den",
+      requestId,
+      message: signinMessage("den", product().cli, product().title),
+    });
+  }
+  // AG-4a-term's session routes (`/api/sessions/<id>/io`): shell-grade, and
+  // an agent's token reaches its own session's only (request-guard). The io
+  // is a WebSocket (the server's upgrade handler): a plain GET of it is 426.
+  if (pathname.startsWith("/api/sessions/"))
+    return sendSessionHttp(req, res, pathname);
+
+  // A mutating request may change what /api/services would list (exec and
+  // sync stream over GET, for EventSource).
+  if (
+    (req.method !== "GET" && req.method !== "HEAD") ||
+    /\/(exec|sync)$/.test(pathname)
+  ) {
+    servicesCache.clear();
+    clearReadCache();
+  }
+
   // ── 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
@@ -882,6 +1401,11 @@ async function handleRequest(
     );
   }
 
+  // The Agents tab (AG-4a-term, AG spec §5d): sessions and terminal panes.
+  if (pathname === "/agents" || pathname === "/agents.html") {
+    return serveFile(res, path.join(PUBLIC_DIR, "agents.html"));
+  }
+
   if (pathname === "/tests" || pathname === "/index.html") {
     return serveFile(res, path.join(PUBLIC_DIR, "index.html"));
   }
@@ -1068,7 +1592,8 @@ async function handleRequest(
   // route; it reports them here so the activity trail shows failed attempts.
   // Agents only (the audit header), and the entry is all it can write.
   if (pathname === "/api/activity" && req.method === "POST") {
-    const actor = actorFromHeaders(req.headers);
+    // An agent's token, or (unverified) an MCP server's audit headers.
+    const actor = auditActorOf(req);
     if (!actor) return sendJson(res, { error: "agents only" }, 403);
     const raw = await readBody(req).catch(() => "");
     if (raw.length > 4096) return send400(res, "report too large");
@@ -1091,11 +1616,11 @@ async function handleRequest(
     }
     // A call into a granted workspace (AG-2a): both workspaces recorded.
     if (report.crossWorkspace !== undefined) {
-      const crossed = recordCrossWorkspace(actor, report);
+      const crossed = recordCrossWorkspace(actor, report, principalOf(req));
       if (!crossed) return send400(res, "not a cross-workspace report");
       return sendJson(res, { recorded: true, ts: crossed.ts });
     }
-    const entry = recordAgentRefusal(actor, report);
+    const entry = recordAgentRefusal(actor, report, principalOf(req));
     return sendJson(res, { recorded: true, ts: entry.ts });
   }
 
@@ -1172,11 +1697,11 @@ async function handleRequest(
 
   // ── API: health check ─────────────────────────────────────────────────────
   /**
-   * Workspaces a health run covers: one named workspace, else the view
-   * scope's (every active one by default, focus first). Health is
+   * Workspaces a health run covers: one named workspace, else every active
+   * one, focus first, whatever the view scope (WS-6.4). 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).
+   * is still up, and the Workspaces page must say so for any workspace.
+   * The scope filters what is displayed: each row's `inView` (forViewer).
    */
   function healthWorkspaces(
     workspaceName: string | null,
@@ -1185,7 +1710,7 @@ async function handleRequest(
       const named = getWorkspaceByName(workspaceName);
       return named ? [named] : [];
     }
-    return scopeView().workspaces.filter((w) => w.config);
+    return pollView().workspaces.filter((w) => w.config);
   }
 
   /**
@@ -1543,7 +2068,7 @@ async function handleRequest(
   // single-service `?address=` probe always runs live: it exists to re-check one
   // node on demand, where staleness is the whole thing being avoided.
   if (pathname === "/api/health") {
-    const forViewer = viewerRewrite(req.headers.host);
+    const forViewer = healthForViewer(req.headers.host);
     const env = (url.searchParams.get("env") ?? "local") as Environment;
     const addressFilter = url.searchParams.get("address");
     const wsParam = url.searchParams.get("workspace");
@@ -1572,7 +2097,7 @@ async function handleRequest(
   // Same checks, streamed: each result is sent the moment it lands so the fast
   // ones paint immediately instead of every dot waiting on the slowest.
   if (pathname === "/api/health/stream") {
-    const forViewer = viewerRewrite(req.headers.host);
+    const forViewer = healthForViewer(req.headers.host);
     const env = (url.searchParams.get("env") ?? "local") as Environment;
     const wsParam = url.searchParams.get("workspace");
     if (wsParam && !getWorkspaceByName(wsParam))
@@ -1657,12 +2182,16 @@ async function handleRequest(
     // Every fail here is before anything ran: a refusal or a lookup miss.
     // Recorded, so failed attempts show in the activity trail (F2).
     const fail = (msg: string): void => {
-      recordAction(actorFromHeaders(req.headers), {
-        verb: "exec",
-        detail: `${repoName}/${svcName} ${cmdName} (${env})`,
-        outcome: "refused",
-        reason: msg,
-      });
+      recordAction(
+        auditActorOf(req),
+        {
+          verb: "exec",
+          detail: `${repoName}/${svcName} ${cmdName} (${env})`,
+          outcome: "refused",
+          reason: msg,
+        },
+        principalOf(req),
+      );
       emit({ type: "error", text: msg });
       emit({ type: "done", exitCode: 1, duration: 0 });
       res.end();
@@ -1698,8 +2227,11 @@ async function handleRequest(
       );
       if (refusal) return fail(refusal);
       if (manifest) {
-        cmdDef =
-          manifest.services?.[resolved.subsystem]?.commands?.[env]?.[cmdName];
+        cmdDef = declaredCommand(
+          manifest.services?.[resolved.subsystem]?.commands,
+          env,
+          cmdName,
+        );
       }
       // Lifecycle commands run through the service runner, as the CLI's do:
       // restart without a declared restart is down + up, up on a healthy
@@ -1712,11 +2244,15 @@ async function handleRequest(
           );
         const execId = shortRunId();
         const execDesc = `${repoName}/${svcName} ${cmdName} (${env})`;
-        const execActor = actorFromHeaders(req.headers);
-        recordAction(execActor, {
-          verb: "exec",
-          detail: `${execDesc} [${execId}]`,
-        });
+        const execActor = auditActorOf(req);
+        recordAction(
+          execActor,
+          {
+            verb: "exec",
+            detail: `${execDesc} [${execId}]`,
+          },
+          principalOf(req),
+        );
         prewarmSudo();
         void streamLifecycleExec(
           {
@@ -1771,7 +2307,11 @@ async function handleRequest(
           )
         : null;
       if (refusal) return fail(refusal);
-      cmdDef = repo?.manifest.services?.[svcName]?.commands?.[env]?.[cmdName];
+      cmdDef = declaredCommand(
+        repo?.manifest.services?.[svcName]?.commands,
+        env,
+        cmdName,
+      );
     }
 
     if (!cmdDef || !repoPath) {
@@ -1817,11 +2357,15 @@ async function handleRequest(
 
     const execId = shortRunId();
     const execDesc = `${repoName}/${svcName} ${cmdName} (${env})`;
-    const execActor = actorFromHeaders(req.headers);
-    recordAction(execActor, {
-      verb: "exec",
-      detail: `${execDesc} [${execId}]`,
-    });
+    const execActor = auditActorOf(req);
+    recordAction(
+      execActor,
+      {
+        verb: "exec",
+        detail: `${execDesc} [${execId}]`,
+      },
+      principalOf(req),
+    );
 
     // For detachable commands (up/restart), the service is spawned as a daemon
     // writing to a log file so it survives den restarts.  The tail proc
@@ -2448,6 +2992,17 @@ async function handleRequest(
     }
 
     if (!pillar) return send400(res, "pillar required");
+    // SEC-1 §6b.2: a run takes the ids of declared modules, never a path. A
+    // module that climbs out (`..`), is absolute, or reads as a flag would
+    // point the runner at a script of the caller's choosing.
+    const badModule = modules.find(
+      (m) => !SAFE_MODULE_RE.test(m) || m.split("/").includes(".."),
+    );
+    if (badModule !== undefined)
+      return send400(
+        res,
+        `module ${JSON.stringify(badModule.slice(0, 80))} is not a module name`,
+      );
 
     // Resolve declarative optional fields → per-module env. Only the perf pillar
     // declares optionalFields; for every other pillar this is an empty map.
@@ -2535,8 +3090,12 @@ async function handleRequest(
     const runId = shortRunId();
     const modDesc = modules.length ? modules.join(",") : "all";
     const runDesc = `${pillar}/${env} · modules=${modDesc}`;
-    const runActor = actorFromHeaders(req.headers);
-    recordAction(runActor, { verb: "run", detail: `${runDesc} [${runId}]` });
+    const runActor = auditActorOf(req);
+    recordAction(
+      runActor,
+      { verb: "run", detail: `${runDesc} [${runId}]` },
+      principalOf(req),
+    );
     if (
       pillar === "synthetic" ||
       pillar === "smoke" ||
@@ -2709,6 +3268,110 @@ async function handleRequest(
   }
 
   // ── API: server info + staleness (drives the header "stale server" pill) ────
+  // ── API: the browser's session (SEC-1a, SEC-1b) ──────────────────────────
+  // The CSRF token the shell sends on mutating calls (X-Den-CSRF), for a
+  // same-origin caller only: the session's own when signed in
+  // (actor "person-browser"); else, on loopback, this server start's.
+  // Beyond loopback without a session there is none to hand out (every
+  // route there needs a session first).
+  if (pathname === "/api/session" && req.method === "GET") {
+    if (!sessionRequestAllowed(req, GUARD))
+      return sendJson(
+        res,
+        {
+          ok: false,
+          error: "same-origin callers only",
+          code: "origin_rejected",
+        },
+        403,
+      );
+    res.setHeader("Cache-Control", "no-store");
+    const g = guard.ok ? guard : null;
+    // An agent's token gets no browser CSRF token: it has its bearer.
+    if (g?.principal?.kind === "agent")
+      return sendJson(res, {
+        csrf: null,
+        actor: g.principal.actor,
+        signedIn: false,
+      });
+    if (g?.session)
+      return sendJson(res, {
+        csrf: g.session.csrf,
+        actor: "person-browser",
+        signedIn: true,
+      });
+    return sendJson(res, {
+      csrf: g?.beyond ? null : GUARD.csrfToken,
+      actor: null,
+      signedIn: false,
+    });
+  }
+  // Sign out: this browser's session ends and its cookie is cleared.
+  if (pathname === "/api/session/logout" && req.method === "POST") {
+    const g = guard.ok ? guard : null;
+    const ended = g?.session ? webSessions.end(g.session.key) : false;
+    res.setHeader(
+      "Set-Cookie",
+      clearSessionCookie(requestIsHttps(req, g?.via ?? null)),
+    );
+    return sendJson(res, { ok: true, ended });
+  }
+  // `<cli> web sessions` (shell-grade: the person's bearer, or a session).
+  if (pathname === "/api/web/sessions" && req.method === "GET") {
+    const mine = guard.ok ? guard.session?.key : undefined;
+    return sendJson(res, {
+      sessions: webSessions.list().map((x) => ({
+        id: sessionIdPrefix(x.key),
+        createdAt: new Date(x.createdAt).toISOString(),
+        lastSeenAt: new Date(x.lastSeenAt).toISOString(),
+        userAgent: x.userAgent,
+        host: x.host,
+        ...(x.key === mine ? { current: true } : {}),
+      })),
+    });
+  }
+  // `<cli> web logout [<id>] [--all]` (shell-grade). `rotate` (--all) also
+  // replaces web.secret: every session and person token derived from the
+  // old one stops verifying; the CLI re-reads the file, so it keeps working.
+  // And (SEC-1 §6c.2) it revokes every agent's actor token: a running
+  // agent's next call gets 401 token_revoked. One browser's or every
+  // browser's logout without --all leaves agent tokens alone.
+  if (pathname === "/api/web/logout" && req.method === "POST") {
+    let body: { id?: unknown; rotate?: unknown } = {};
+    try {
+      body = (JSON.parse((await readBody(req)) || "{}") ?? {}) as typeof body;
+    } catch {
+      return send400(res, "the body must be JSON: { id?, rotate? }");
+    }
+    if (body.id !== undefined && typeof body.id !== "string")
+      return send400(res, "id must be a session id prefix");
+    try {
+      const ended =
+        typeof body.id === "string"
+          ? [sessionIdPrefix(webSessions.endByPrefix(body.id).key)]
+          : webSessions.list().map((x) => sessionIdPrefix(x.key));
+      if (typeof body.id !== "string") webSessions.endAll();
+      const rotated = body.rotate === true;
+      let agentTokens = 0;
+      if (rotated) {
+        rotateWebSecret();
+        agentTokens = revokeAllActorTokens(getStateDir());
+      }
+      return sendJson(res, {
+        ok: true,
+        ended,
+        rotated,
+        ...(rotated ? { agentTokens } : {}),
+      });
+    } catch (e) {
+      return sendJson(
+        res,
+        { ok: false, error: (e as Error).message, code: "not_found" },
+        404,
+      );
+    }
+  }
+
   if (pathname === "/api/server-info" && req.method === "GET") {
     const { stale, scanned } = computeStale();
     const engine = engineCheck();
@@ -3034,6 +3697,20 @@ async function handleRequest(
     return;
   }
 
+  // ── Agents on the Workspaces page (AG-4a, agent-routes.ts) ───────────────
+  if (await handleAgentRoutes(req, res, pathname)) return;
+  // ── The Agents tab's list (AG-4a-term, session-routes.ts) ────────────────
+  // Beyond loopback a terminal needs a signed-in session (or a bearer).
+  if (
+    await handleSessionList(
+      req,
+      res,
+      pathname,
+      guard.ok && (!guard.beyond || !!guard.session || !!guard.principal),
+    )
+  )
+    return;
+
   // ── Workspace routes (extracted to workspace-routes.ts) ──────────────────
   await handleWorkspaceRoutes(req, res, pathname, url, editors, github);
   if (res.headersSent) return;
@@ -3630,7 +4307,8 @@ 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: unknown) => {
+  // Each request in its own lock scope (SEC-1c: an agent's stays shut).
+  inRequestLockScope(() => 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);
@@ -3712,6 +4390,49 @@ const server = http.createServer((req, res) => {
   });
 });
 
+// WebSocket upgrades pass the same checks (SEC-1 §3: Origin on every
+// upgrade; CSRF as the `den.csrf.<token>` subprotocol). One route takes
+// one: a session's io (AG-4a-term, session-routes.ts); any other passing
+// upgrade answers 404.
+server.on(
+  "upgrade",
+  (req: http.IncomingMessage, socket: net.Socket, head: Buffer) => {
+    socket.on("error", () => undefined);
+    const requestId = requestIdOf(req);
+    const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    const guard = checkRequest(req, GUARD, product().cli, product().title);
+    const refuse = (status: number, error: string, code: string) =>
+      refuseUpgrade(
+        socket,
+        status,
+        { ok: false, error, code, requestId },
+        http.STATUS_CODES[status] ?? "",
+      );
+    if (!guard.ok) {
+      serverLog(
+        `  ${logTimestamp()}  ${bold("WS  ")}  ${pathname}  →  ${logStatus(guard.status)}` +
+          dim(`  req ${requestId}`),
+        "request",
+      );
+      return refuse(guard.status, guard.error, guard.code);
+    }
+    setPrincipal(req, guard.principal);
+    if (!isSessionIoPath(pathname))
+      return refuse(404, "No WebSocket route here", "not_found");
+    handleSessionUpgrade(req, socket, head, pathname, requestId).catch(
+      (err: unknown) => {
+        serverLog(
+          `  ✗ WS ${routeTemplate(pathname)} failed (req ${requestId}): ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+          "error",
+        );
+        socket.destroy();
+      },
+    );
+  },
+);
+
 server.on("error", (err: NodeJS.ErrnoException) => {
   if (err.code === "EADDRINUSE") {
     console.error(
@@ -3801,10 +4522,14 @@ setInterval(sweepServiceLogs, LOG_SWEEP_INTERVAL_MS).unref();
 // timers — code the per-request catch can't see) would kill the whole
 // dashboard; a TDZ bug in a down-flow callback did exactly that. For a local
 // dev server, staying alive degraded beats dying — log loudly and continue.
+// Never log a lost-output error, or anything once the output is gone: that
+// write fails too, and looped (shutdown-guard.ts).
 process.on("uncaughtException", (err) => {
+  if (isLostOutputError(err) || outputLost()) return;
   console.error("[server] uncaught exception (continuing):", err);
 });
 process.on("unhandledRejection", (reason) => {
+  if (isLostOutputError(reason) || outputLost()) return;
   console.error("[server] unhandled rejection (continuing):", reason);
 });
 
@@ -3818,10 +4543,35 @@ try {
   serverLog(`  ⚠ cache warm-up failed: ${(e as Error).message}`);
 }
 
-// Bind loopback only — this UI runs privileged local actions (sudo-backed
-// service commands), so it must not be reachable from the LAN. Opt out with
-// DEN_BIND_HOST=0.0.0.0 for deliberate exposure.
-const BIND_HOST = process.env.DEN_BIND_HOST ?? "127.0.0.1";
+// Ignored config keys (a distribution's web.allow_plain_http_remote, the
+// old web.session lifetimes): the in-app log, and stderr, which is web.log
+// even when `web up` starts this --silent. Before the bind refusal, which
+// such a key often explains.
+{
+  const ignored = ignoredConfigWarning(WEB_AUTH);
+  if (ignored) {
+    pushLog("warn", `  ⚠ ${ignored}`);
+    if (!outputLost()) process.stderr.write(`  ⚠ ${ignored}\n`);
+  }
+}
+// §4: a non-loopback bind needs HTTPS in front, or the person's say-so.
+{
+  const refusal = bindRefusal(BIND_HOST, {
+    allowPlainHttpRemote: WEB_AUTH.allowPlainHttpRemote,
+    fronted: edgeFronted(),
+  });
+  if (refusal) {
+    console.error(`\n  ✗ ${refusal}\n`);
+    process.exit(1);
+  }
+}
+// SEC-1a: the secret the CLI's person token is derived from (0600 in the
+// state dir). Never printed or logged; a failure leaves bearers unverifiable.
+try {
+  webSecret.ensure();
+} catch (e) {
+  serverLog(`  ⚠ web.secret could not be created: ${(e as Error).message}`);
+}
 server.listen(PORT, BIND_HOST, () => {
   const hosts = fs.existsSync("/etc/hosts")
     ? fs.readFileSync("/etc/hosts", "utf-8")
@@ -3941,7 +4691,8 @@ async function handleShutdown(signal: string): Promise<void> {
     process.exit(0);
   }
 
-  const isTTY = process.stdin.isTTY;
+  // Lost output (SIGPIPE): nobody can answer a prompt.
+  const isTTY = process.stdin.isTTY && signal !== "SIGPIPE";
 
   if (!isTTY) {
     // Non-interactive shutdown usually means `den web` is being restarted.
@@ -3981,10 +4732,8 @@ async function handleShutdown(signal: string): Promise<void> {
 }
 
 /**
- * Run the shutdown for `signal`. A failure still ends the process: the guard
- * below ignores every later signal, so a shutdown that rejected would leave
- * the server running and deaf to SIGTERM (a service manager then waits out
- * its timeout and SIGKILLs it).
+ * Run the shutdown for `signal`. A failure still ends the process, at once
+ * rather than at the deadline.
  */
 function shutdownOn(signal: string): void {
   handleShutdown(signal).catch((e: unknown) => {
@@ -3993,16 +4742,22 @@ function shutdownOn(signal: string): void {
   });
 }
 
-let _shuttingDown = false;
+/**
+ * Start the shutdown once; a second signal exits at once, and a shutdown
+ * nobody waits on (stdin isn't a TTY) is forced to exit after a deadline
+ * (shutdown-guard.ts).
+ */
+function beginShutdown(signal: string): void {
+  requestShutdown(signal, shutdownOn, {
+    interactive: Boolean(process.stdin.isTTY) && signal !== "SIGPIPE",
+  });
+}
+
 process.on("SIGINT", () => {
-  if (_shuttingDown) return;
-  _shuttingDown = true;
-  console.log(""); // newline after ^C
-  shutdownOn("SIGINT");
+  if (!outputLost()) console.log(""); // newline after ^C
+  beginShutdown("SIGINT");
 });
 
 process.on("SIGTERM", () => {
-  if (_shuttingDown) return;
-  _shuttingDown = true;
-  shutdownOn("SIGTERM");
+  beginShutdown("SIGTERM");
 });