@abstractframework/observer 0.1.11 → 0.1.13

package/README.md

@@ -10,6 +10,16 @@ What it does (implemented in `src/ui/app.tsx` + `src/lib/gateway_client.ts`):
 - **Control** runs via durable commands (`pause`, `resume`, `cancel`)
 - (Optional) **Voice** in run chat: gateway-based TTS + push-to-talk transcription (`src/ui/use_gateway_voice.ts`)
 
+## Watching entities (the entity app)
+
+The **entity app** (memory graph + visits UI) is its own package,
+[AbstractEntity](https://github.com/lpalbou/AbstractEntity)
+(`npx @abstractframework/entity`, default port `3007`). The observer still
+*watches* entities — the Board's entities strip reads
+`GET /api/gateway/entities` + `/entities/{name}/card` — and its
+"Entities ↗" links point at the entity app deployment
+(`ABSTRACTOBSERVER_ENTITY_APP_URL`, default `http://127.0.0.1:3007`).
+
 ## Where it fits (AbstractFramework ecosystem)
 AbstractObserver is one of the browser UIs in the **AbstractFramework** ecosystem:
 - AbstractFramework (ecosystem entrypoint): https://github.com/lpalbou/AbstractFramework
@@ -36,11 +46,12 @@ npx --yes --package @abstractframework/observer -- abstractobserver
 
 Note: the npm package is `@abstractframework/observer`, and the CLI binary is `abstractobserver`.
 
-Open `http://localhost:3001`, then go to **Settings** and configure:
-- **Gateway URL** (usually your gateway base URL, e.g. `http://localhost:8081`)
-  - Leave it blank only for same-origin deployments (reverse proxy routes `/api`) or when using `npm run dev` (Vite `/api` proxy).
-- **Gateway user** and that user's **Gateway token** in hosted user-auth mode,
-  then click **Connect**
+Open `http://localhost:3001`. Sign-in is the shared AbstractFramework
+connection dialog (the same one AbstractFlow and the gateway console use):
+it opens automatically when this browser has no gateway session — enter the
+gateway URL (pre-filled from the server), a Gateway user id, and that
+user's token. The dialog is always one click away on the header connection
+badge.
 
 In hosted mode, Observer exchanges the user token for an app-scoped Gateway
 browser session and does not persist the token in browser settings. Direct
@@ -61,23 +72,30 @@ abstractobserver
 
 ### Pin a version (recommended for deployments)
 ```bash
-npx --yes --package @abstractframework/observer@0.1.6 -- abstractobserver
+npx --yes --package @abstractframework/observer@0.1.13 -- abstractobserver
 ```
 
 ### CLI configuration
-The CLI is a static file server implemented in `bin/cli.js`.
+The CLI (`bin/cli.js`) serves the built UI and mounts the app-origin Gateway
+session proxy from `@abstractframework/app-server` (a runtime dependency of
+this package, installed automatically).
 - `PORT` (default `3001`)
 - `HOST` (default `0.0.0.0`)
+- `ABSTRACTOBSERVER_GATEWAY_URL` (or `ABSTRACTGATEWAY_URL`) — the Gateway this server signs in to and proxies `/api` to (default `http://127.0.0.1:8080`)
 - `--monitor-gpu` or `ABSTRACTOBSERVER_MONITOR_GPU=on` (enables the optional GPU widget)
 
+See `docs/configuration.md` for the full list.
+
 ## Features (UI pages)
 All pages share the same gateway connection settings.
 
+- **Board** (Mission Control, the landing page): kanban columns Pending / Working / Review / Done across every run — cards move themselves by state; the Review column carries inline Approve/Deny/Answer; an entities strip shows each entity's phase and links into the entity app; run lists poll live (5s visible / 30s hidden)
 - **Observe**: workflow/subworkflow navigator, overview, human timeline, raw ledger, provider calls, graph, digest, attachments, chat (optional voice: PTT + TTS)
-- **Runtime**: Activity, Artifacts, and Logs modes for platform-level monitoring. The Artifact Explorer uses Gateway artifact envelopes and exact stats, separates Voice/Music/Sound/unclassified audio from render kinds such as Markdown/HTML/JSON, previews media inline, and links artifacts back to producing runs, ledgers, and trace/audit actions when metadata is available
+- **Runtime**: Activity, Artifacts, Memory, and Logs modes for platform-level monitoring. The Artifact Explorer uses Gateway artifact envelopes and exact stats, separates Voice/Music/Sound/unclassified audio from render kinds such as Markdown/HTML/JSON, previews media inline, and links artifacts back to producing runs, ledgers, and trace/audit actions when metadata is available
 - **Launch**: start runs, schedule runs, bundle upload/reload
-- **Mindmap**: knowledge-graph query UI (requires `POST /api/gateway/kg/query`)
-- **Backlog / Inbox (reports + email) / Processes**: maintainer tooling (high trust; requires additional gateway endpoints)
+- **Runtime → Memory**: knowledge-graph (active memory) query UI (requires `POST /api/gateway/kg/query`)
+- **Settings**: connection status, theme and display preferences, optional remote tool worker
+- **About** (the info button in the top bar): the AbstractObserver version, links to its website, source, documentation and issue tracker, and the versions the connected gateway reports
 
 ## Documentation
 - Start here: `docs/getting-started.md`
@@ -94,6 +112,7 @@ All pages share the same gateway connection settings.
 - Contributing: `CONTRIBUTING.md`
 - Security policy (vulnerability reporting): `SECURITY.md`
 - Acknowledgments: `ACKNOWLEDGMENTS.md`
+- Code of conduct: `CODE_OF_CONDUCT.md`
 
 ## Development (from source)
 ```bash

package/bin/cli.js

@@ -6,36 +6,38 @@
  */
 
 import * as http from 'http';
-import * as https from 'https';
 import { readFileSync, existsSync, statSync } from 'fs';
-import { join, extname, dirname } from 'path';
+import { join, extname, dirname, resolve, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+import { createGatewaySessionProxy } from '@abstractframework/app-server';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = join(__dirname, '..', 'dist');
 const PORT = process.env.PORT || 3001;
 const HOST = process.env.HOST || '0.0.0.0';
+// ONE app since the 2026-07-12 split: the entity view moved to its own
+// package (abstractentity, :3007). The ABSTRACTOBSERVER_LANDING knob died
+// with it — this server always lands on index.html.
 const DEFAULT_GATEWAY_URL = String(process.env.ABSTRACTOBSERVER_GATEWAY_URL || process.env.ABSTRACTGATEWAY_URL || 'http://127.0.0.1:8080').trim().replace(/\/+$/, '') || 'http://127.0.0.1:8080';
-const GATEWAY_SESSION_URL_COOKIE = 'abstractobserver_gateway_url';
-const GATEWAY_SESSION_ID_COOKIE = 'abstractobserver_gateway_session';
-const GATEWAY_SESSION_CSRF_COOKIE = 'abstractobserver_gateway_csrf';
-const TRUE_VALUES = new Set(['1', 'true', 'yes', 'y', 'on']);
+// Where the ENTITY app lives — drives the "Entities ↗" links in the UI.
+// Normalized to origin+path (query/hash dropped): both consumers append
+// their own query (`/entity.html` redirect here, deep links in the UI),
+// so a configured value carrying `?` would produce malformed URLs.
+const ENTITY_APP_URL = (() => {
+  const raw = String(process.env.ABSTRACTOBSERVER_ENTITY_APP_URL || '').trim();
+  if (!raw) return '';
+  try {
+    const u = new URL(raw);
+    return `${u.origin}${u.pathname}`.replace(/\/+$/, '');
+  } catch {
+    return raw.split(/[?#]/)[0].replace(/\/+$/, '');
+  }
+})();
 const ARGV = process.argv.slice(2);
-function parse_bool_env(name) {
-  const raw = process.env[name];
-  if (raw === undefined || raw === null || String(raw).trim() === "") return undefined;
-  const normalized = String(raw).trim().toLowerCase();
-  if (["1", "true", "yes", "on"].includes(normalized)) return true;
-  if (["0", "false", "no", "off"].includes(normalized)) return false;
-  console.warn(`#FALLBACK: ${name}="${raw}" is not a boolean; defaulting to false.`);
-  return false;
-}
-
 const MONITOR_GPU =
   ARGV.includes("--monitor-gpu") ||
   ["1", "true", "yes", "on"].includes(String(process.env.ABSTRACTOBSERVER_MONITOR_GPU || "").trim().toLowerCase());
-const ENABLE_BACKLOG = parse_bool_env("ABSTRACTOBSERVER_ENABLE_BACKLOG");
-const ENABLE_INBOX_TRIAGE = parse_bool_env("ABSTRACTOBSERVER_ENABLE_INBOX_TRIAGE");
 
 // MIME types for common file extensions
 const MIME_TYPES = {
@@ -60,8 +62,11 @@ function getMimeType(filePath) {
 function inject_config_html(html) {
   const ui_config = {};
   if (MONITOR_GPU) ui_config.monitor_gpu = true;
-  if (ENABLE_BACKLOG !== undefined) ui_config.enable_backlog = ENABLE_BACKLOG;
-  if (ENABLE_INBOX_TRIAGE !== undefined) ui_config.enable_inbox_triage = ENABLE_INBOX_TRIAGE;
+  // THIS deployment's gateway (maintainer incident 2026-07-09: the sign-in
+  // card showed a retired gateway's URL) — the UI's connect/sign-in surfaces
+  // default to it instead of any hardcoded historical port.
+  if (DEFAULT_GATEWAY_URL) ui_config.gateway_url = DEFAULT_GATEWAY_URL;
+  if (ENTITY_APP_URL) ui_config.entity_app_url = ENTITY_APP_URL;
   if (!Object.keys(ui_config).length) return html;
   const marker = "window.__ABSTRACT_UI_CONFIG__";
   if (html.includes(marker)) return html;
@@ -101,312 +106,69 @@ function serveFile(res, filePath) {
   }
 }
 
-function sendJson(res, status, payload) {
-  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
-  res.end(JSON.stringify(payload));
-}
-
-function envBool(name) {
-  const raw = process.env[name];
-  if (typeof raw !== 'string' || !raw.trim()) return false;
-  return TRUE_VALUES.has(raw.trim().toLowerCase());
-}
-
-function requestHostname(req) {
-  const trustProxyHeaders = envBool('ABSTRACTOBSERVER_TRUST_PROXY_HEADERS') || envBool('ABSTRACTGATEWAY_TRUST_PROXY_HEADERS');
-  const headerValue = trustProxyHeaders ? (req?.headers?.['x-forwarded-host'] || req?.headers?.host) : req?.headers?.host;
-  const raw = String(headerValue || '').split(',', 1)[0].trim();
-  if (!raw) return '';
-  if (raw.startsWith('[')) return raw.slice(1).split(']', 1)[0].trim().toLowerCase();
-  if ((raw.match(/:/g) || []).length === 1) return raw.split(':')[0].trim().toLowerCase();
-  return raw.toLowerCase();
-}
-
-function isLoopbackHostname(hostname) {
-  const h = String(hostname || '').trim().toLowerCase();
-  return h === 'localhost' || h === 'localhost.localdomain' || h === '::1' || h.startsWith('127.');
-}
-
-function browserGatewayConnectionConfigAllowed(req) {
-  if (envBool('ABSTRACTOBSERVER_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG')) return true;
-  if (envBool('ABSTRACTGATEWAY_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG')) return true;
-  return isLoopbackHostname(requestHostname(req));
-}
-
-function browserGatewayConnectionConfigDenial(req) {
-  const host = requestHostname(req) || 'unknown host';
-  return (
-    `Browser-supplied Gateway URL changes are disabled for this non-local Observer host (${host}). ` +
-    'Use the server-configured Gateway URL, or set ABSTRACTOBSERVER_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG=1 behind your own access control.'
-  );
-}
-
-function parseCookies(req) {
-  const out = {};
-  for (const part of String(req?.headers?.cookie || '').split(';')) {
-    const idx = part.indexOf('=');
-    if (idx < 0) continue;
-    const key = part.slice(0, idx).trim();
-    const value = part.slice(idx + 1).trim();
-    if (!key) continue;
-    try {
-      out[key] = decodeURIComponent(value);
-    } catch {
-      out[key] = value;
-    }
-  }
-  return out;
-}
-
-function cookieSecure(req) {
-  return String(req?.headers?.['x-forwarded-proto'] || '').trim().toLowerCase() === 'https' ? '; Secure' : '';
-}
-
-function setSessionCookies(res, req, gatewayUrl, sessionId, csrfToken, persist) {
-  const secure = cookieSecure(req);
-  const maxAge = persist ? '; Max-Age=2592000' : '';
-  const attrs = `; Path=/; HttpOnly; SameSite=Lax${secure}${maxAge}`;
-  const csrfAttrs = `; Path=/; SameSite=Lax${secure}${maxAge}`;
-  res.setHeader('Set-Cookie', [
-    `${GATEWAY_SESSION_URL_COOKIE}=${encodeURIComponent(gatewayUrl)}${attrs}`,
-    `${GATEWAY_SESSION_ID_COOKIE}=${encodeURIComponent(sessionId)}${attrs}`,
-    `${GATEWAY_SESSION_CSRF_COOKIE}=${encodeURIComponent(csrfToken)}${csrfAttrs}`,
-  ]);
-}
-
-function clearSessionCookies(res, req) {
-  const secure = cookieSecure(req);
-  res.setHeader('Set-Cookie', [
-    `${GATEWAY_SESSION_URL_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0${secure}`,
-    `${GATEWAY_SESSION_ID_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0${secure}`,
-    `${GATEWAY_SESSION_CSRF_COOKIE}=; Path=/; SameSite=Lax; Max-Age=0${secure}`,
-  ]);
-}
-
-function browserSession(req) {
-  const cookies = parseCookies(req);
-  const cookieUrl = String(cookies[GATEWAY_SESSION_URL_COOKIE] || '').trim().replace(/\/+$/, '');
-  const allowCookieUrl =
-    envBool('ABSTRACTOBSERVER_ALLOW_BROWSER_GATEWAY_URL_COOKIE') ||
-    envBool('ABSTRACTOBSERVER_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG') ||
-    envBool('ABSTRACTGATEWAY_ALLOW_REMOTE_BROWSER_GATEWAY_CONFIG') ||
-    browserGatewayConnectionConfigAllowed(req);
-  return {
-    gatewayUrl: cookieUrl && (allowCookieUrl || cookieUrl === DEFAULT_GATEWAY_URL) ? cookieUrl : DEFAULT_GATEWAY_URL,
-    sessionId: String(cookies[GATEWAY_SESSION_ID_COOKIE] || '').trim(),
-    csrfToken: String(cookies[GATEWAY_SESSION_CSRF_COOKIE] || '').trim(),
-  };
-}
-
-function resolveBackend(gatewayUrl) {
-  const backend = new URL(String(gatewayUrl || DEFAULT_GATEWAY_URL).trim());
-  if (!backend.port) backend.port = backend.protocol === 'https:' ? '443' : '80';
-  return {
-    url: backend,
-    origin: `${backend.protocol}//${backend.host}`,
-    client: backend.protocol === 'https:' ? https : http,
-  };
-}
-
-function mutatingMethod(method) {
-  return ['POST', 'PUT', 'PATCH', 'DELETE'].includes(String(method || 'GET').toUpperCase());
-}
-
-function readRequestJson(req) {
-  return new Promise((resolve) => {
-    const chunks = [];
-    req.on('data', (chunk) => chunks.push(chunk));
-    req.on('end', () => {
-      try {
-        const raw = Buffer.concat(chunks).toString('utf8');
-        resolve(raw ? JSON.parse(raw) : {});
-      } catch {
-        resolve({});
-      }
-    });
-    req.on('error', () => resolve({}));
-  });
-}
-
-function gatewayRequest(gatewayUrl, options, body) {
-  return new Promise((resolve) => {
-    let backend;
-    try {
-      backend = resolveBackend(gatewayUrl);
-    } catch (err) {
-      resolve({ ok: false, status: 0, payload: { detail: `Invalid gateway URL: ${String(err?.message || err)}` } });
-      return;
-    }
-    const req = backend.client.request(
-      {
-        protocol: backend.url.protocol,
-        hostname: backend.url.hostname,
-        port: backend.url.port,
-        timeout: options.timeout || 4000,
-        ...options,
-      },
-      (resp) => {
-        const chunks = [];
-        resp.on('data', (chunk) => chunks.push(chunk));
-        resp.on('end', () => {
-          const text = Buffer.concat(chunks).toString('utf8');
-          let payload = {};
-          try {
-            payload = text ? JSON.parse(text) : {};
-          } catch {
-            payload = { detail: text };
-          }
-          const status = resp.statusCode || 0;
-          resolve({ ok: status >= 200 && status < 300, status, payload, headers: resp.headers, origin: backend.origin });
-        });
-      }
-    );
-    req.on('timeout', () => {
-      req.destroy();
-      resolve({ ok: false, status: 0, payload: { detail: 'Gateway request timed out' }, origin: backend?.origin });
-    });
-    req.on('error', (err) => resolve({ ok: false, status: 0, payload: { detail: String(err?.message || err) }, origin: backend?.origin }));
-    if (body) req.write(body);
-    req.end();
-  });
-}
-
-function cookieValueFromSetCookie(rawHeaders, name) {
-  const headers = Array.isArray(rawHeaders) ? rawHeaders : rawHeaders ? [rawHeaders] : [];
-  for (const header of headers) {
-    for (const candidate of String(header || '').split(/,(?=\s*[^;,=]+=)/)) {
-      const first = candidate.split(';', 1)[0];
-      const idx = first.indexOf('=');
-      if (idx < 0) continue;
-      if (first.slice(0, idx).trim() !== name) continue;
-      const raw = first.slice(idx + 1).trim();
-      try {
-        return decodeURIComponent(raw);
-      } catch {
-        return raw;
-      }
-    }
-  }
-  return '';
-}
-
-async function handleConnectionApi(req, res) {
-  if (req.method === 'GET') {
-    const session = browserSession(req);
-    if (!session.sessionId) {
-      sendJson(res, 200, { ok: false, gateway_url: session.gatewayUrl, has_session: false, gateway: { ok: false, error: 'Gateway sign-in required' } });
-      return;
-    }
-    const checked = await gatewayRequest(session.gatewayUrl, {
-      method: 'GET',
-      path: '/api/gateway/me',
-      headers: { Accept: 'application/json', 'X-AbstractGateway-Session': session.sessionId },
-    });
-    sendJson(res, 200, { ok: checked.ok, gateway_url: session.gatewayUrl, has_session: Boolean(session.sessionId), gateway: checked.payload });
-    return;
-  }
-  if (req.method === 'POST') {
-    const payload = await readRequestJson(req);
-    const gatewayUrl = String(payload.gateway_url || DEFAULT_GATEWAY_URL).trim().replace(/\/+$/, '') || DEFAULT_GATEWAY_URL;
-    if (!browserGatewayConnectionConfigAllowed(req) && gatewayUrl !== DEFAULT_GATEWAY_URL) {
-      sendJson(res, 403, { detail: browserGatewayConnectionConfigDenial(req) });
-      return;
-    }
-    const body = Buffer.from(JSON.stringify({
-      user_id: String(payload.gateway_user_id || '').trim(),
-      token: String(payload.gateway_token || '').trim(),
-      remember: payload.persist === true,
-    }));
-    const login = await gatewayRequest(gatewayUrl, {
-      method: 'POST',
-      path: '/api/gateway/session/login',
-      headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'Content-Length': String(body.length) },
-    }, body);
-    const session = login.payload && typeof login.payload.session === 'object' ? login.payload.session : {};
-    const setCookie = login.headers?.['set-cookie'];
-    const sessionId = cookieValueFromSetCookie(setCookie, 'abstractgateway_session') || String(session.session_id || '').trim();
-    const csrfToken = cookieValueFromSetCookie(setCookie, 'abstractgateway_csrf') || String(session.csrf_token || '').trim();
-    if (!login.ok || !sessionId || !csrfToken) {
-      sendJson(res, login.status || 401, { ok: false, detail: login.payload?.detail || 'Gateway browser session failed', gateway: login.payload });
-      return;
-    }
-    setSessionCookies(res, req, gatewayUrl, sessionId, csrfToken, payload.persist === true);
-    sendJson(res, 200, { ok: true, gateway_url: gatewayUrl, has_session: true, gateway: login.payload });
-    return;
-  }
-  if (req.method === 'DELETE') {
-    const session = browserSession(req);
-    if (session.sessionId) {
-      const body = Buffer.from('{}');
-      await gatewayRequest(session.gatewayUrl, {
-        method: 'POST',
-        path: '/api/gateway/session/logout',
-        headers: {
-          Accept: 'application/json',
-          'Content-Type': 'application/json',
-          'Content-Length': String(body.length),
-          'X-AbstractGateway-Session': session.sessionId,
-          'X-AbstractGateway-CSRF': session.csrfToken,
-        },
-        timeout: 2000,
-      }, body);
-    }
-    clearSessionCookies(res, req);
-    sendJson(res, 200, { ok: true });
-    return;
-  }
-  sendJson(res, 405, { detail: 'Method not allowed' });
-}
-
-const HOP_BY_HOP_HEADERS = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'trailers', 'transfer-encoding', 'upgrade']);
+// APP-ORIGIN GATEWAY SESSION PROXY - the shared @abstractframework/app-server
+// module (extracted from this file's hardened copy; one source across
+// observer/flow/abstractcode per the 2026-07-12 consolidation). Cookie names
+// (abstractobserver_gateway_*), the x-abstractobserver-csrf header, and the
+// ABSTRACTOBSERVER_* / ABSTRACTGATEWAY_* env gates are all derived from appId,
+// so existing sessions and deployment security posture survive the swap.
+const gatewaySessionProxy = createGatewaySessionProxy({
+  appId: 'abstractobserver',
+  defaultGatewayUrl: DEFAULT_GATEWAY_URL,
+});
 
-function proxyHeaders(headers) {
-  const out = {};
-  for (const [key, value] of Object.entries(headers || {})) {
-    const k = String(key).toLowerCase();
-    if (HOP_BY_HOP_HEADERS.has(k) || k === 'content-length') continue;
-    out[key] = value;
-  }
-  return out;
+// ── LOCAL FOLDER REVEAL (operator 2026-07-15: a folder button on the run
+// opens its workspace). Only meaningful when this server runs on the SAME
+// machine as the gateway (the local-first posture). Gateway workspace roots
+// are often RELATIVE to the gateway process cwd — resolve against
+// ABSTRACTOBSERVER_GATEWAY_DIR (default: the workspace parent this repo
+// lives in, matching the launcher layout).
+const GATEWAY_DIR = String(process.env.ABSTRACTOBSERVER_GATEWAY_DIR || join(__dirname, '..', '..')).trim();
+
+function resolveWorkspacePath(raw) {
+  const p = String(raw || '').trim();
+  if (!p || p.includes('\0')) return null;
+  const abs = isAbsolute(p) ? p : resolve(GATEWAY_DIR, p);
+  try {
+    if (existsSync(abs) && statSync(abs).isDirectory()) return abs;
+  } catch {}
+  return null;
 }
 
-function proxyApiRequest(req, res) {
-  const session = browserSession(req);
-  if (!session.sessionId) {
-    sendJson(res, 401, { detail: 'Gateway sign-in required' });
-    return;
+function handleRevealRequest(req, res, pathname) {
+  if (pathname !== '/api/local/reveal' || req.method !== 'POST') return false;
+  // Loopback only: revealing Finder windows on a remotely-served observer
+  // is someone else's desktop. The socket peer is the truth (Host spoofable).
+  const peer = String(req.socket?.remoteAddress || '');
+  const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1';
+  if (!loopback) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: false, error: 'Folder reveal is only available on the machine running the observer.' }));
+    return true;
   }
-  if (mutatingMethod(req.method)) {
-    const presented = String(req.headers['x-abstractobserver-csrf'] || '').trim();
-    if (!session.csrfToken || presented !== session.csrfToken) {
-      sendJson(res, 403, { detail: 'Gateway browser session CSRF token missing or invalid', reason_code: 'csrf_required' });
+  let body = '';
+  req.on('data', (c) => { body += c; if (body.length > 8192) req.destroy(); });
+  req.on('end', () => {
+    let path = '';
+    try { path = String(JSON.parse(body || '{}').path || ''); } catch {}
+    const abs = resolveWorkspacePath(path);
+    if (!abs) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: `Workspace folder not found on this machine: ${path || '(empty)'}` }));
       return;
     }
-  }
-  let backend;
-  try {
-    backend = resolveBackend(session.gatewayUrl);
-  } catch (err) {
-    sendJson(res, 500, { detail: `Invalid gateway URL: ${String(err?.message || err)}` });
-    return;
-  }
-  const headers = { ...req.headers, host: backend.url.host };
-  delete headers.cookie;
-  delete headers.authorization;
-  delete headers['x-forwarded-for'];
-  delete headers['x-forwarded-host'];
-  delete headers['x-forwarded-proto'];
-  headers['x-abstractgateway-session'] = session.sessionId;
-  if (mutatingMethod(req.method)) headers['x-abstractgateway-csrf'] = session.csrfToken;
-  const proxyReq = backend.client.request(
-    { protocol: backend.url.protocol, hostname: backend.url.hostname, port: backend.url.port, method: req.method, path: req.url, headers },
-    (proxyRes) => {
-      res.writeHead(proxyRes.statusCode || 502, proxyHeaders(proxyRes.headers));
-      proxyRes.pipe(res);
+    const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+    try {
+      // `open <dir>` reveals a folder; never a shell, never arbitrary exec.
+      spawn(cmd, [abs], { stdio: 'ignore', detached: true }).unref();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, path: abs }));
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: String(e && e.message || e) }));
     }
-  );
-  proxyReq.on('error', (err) => sendJson(res, 502, { detail: `Backend not reachable at ${backend.origin} (${String(err?.message || err)})` }));
-  req.pipe(proxyReq);
+  });
+  return true;
 }
 
 const server = http.createServer((req, res) => {
@@ -414,13 +176,15 @@ const server = http.createServer((req, res) => {
   const url = new URL(req.url, `http://${req.headers.host}`);
   let pathname = url.pathname;
 
-  if (pathname === '/api/connection/gateway') {
-    void handleConnectionApi(req, res);
+  // Local-machine folder reveal (before the proxy: /api/local/* is OURS,
+  // never forwarded to the gateway).
+  if (handleRevealRequest(req, res, pathname)) {
     return;
   }
 
-  if (pathname.startsWith('/api/')) {
-    proxyApiRequest(req, res);
+  // Connection endpoint + everything under /api/ (proxied to the gateway
+  // with session cookies swapped for gateway headers).
+  if (gatewaySessionProxy.handle(req, res, pathname)) {
     return;
   }
   
@@ -431,6 +195,10 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  if (pathname === '/' || pathname === '') {
+    pathname = '/index.html';
+  }
+
   // Try to serve the requested file
   let filePath = join(DIST_DIR, pathname);
   
@@ -438,6 +206,27 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  // An EXPLICIT .html request that misses must fail loudly, never fall
+  // through to the SPA fallback (maintainer incident 2026-07-09: the wrong
+  // app wearing the right URL is worse than a 404). /entity.html was real
+  // here before the 2026-07-12 split — send old bookmarks to the entity
+  // app's own deployment when we know it, otherwise say where it went.
+  if (pathname.endsWith('.html')) {
+    if (pathname === '/entity.html' && ENTITY_APP_URL) {
+      res.writeHead(302, { Location: `${ENTITY_APP_URL}/${url.search || ''}` });
+      res.end();
+      return;
+    }
+    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end(
+      pathname === '/entity.html'
+        ? 'The entity app moved to its own package (abstractentity, default http://127.0.0.1:3007). '
+          + 'Set ABSTRACTOBSERVER_ENTITY_APP_URL to make this a redirect.'
+        : `${pathname} is not in this build (dist/). This server hosts the AbstractObserver app only.`
+    );
+    return;
+  }
+
   // Try with .html extension
   if (serveFile(res, filePath + '.html')) {
     return;
@@ -448,7 +237,7 @@ const server = http.createServer((req, res) => {
     return;
   }
 
-  // SPA fallback: serve index.html for all other routes
+  // SPA fallback
   const indexPath = join(DIST_DIR, 'index.html');
   if (serveFile(res, indexPath)) {
     return;