pmx-canvas 0.6.4 → 0.7.0

package/src/server/server.ts

@@ -23,6 +23,7 @@
  * - POST /api/canvas/graph        -> create a native graph node
  * - GET  /api/canvas/json-render/view?nodeId=... -> local json-render viewer
  * - GET  /api/canvas/file-bytes?nodeId=... -> raw bytes for a file node
+ * - GET  /api/canvas/exports/<file>        -> a written static board export (sandboxed)
  * - POST /api/canvas/web-artifact -> build bundled HTML artifact + optional canvas node
  * - GET  /api/workbench/events   -> SSE event stream
  * - GET  /api/workbench/poll     -> proxy-safe polling transport (same events, JSON)
@@ -38,9 +39,11 @@
 
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import { isWorkbenchToken, workbenchToken } from './workbench-auth.js';
+import { withCurrentActor } from './attribution.js';
 import { existsSync, readFileSync, realpathSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { basename, extname, join, relative, resolve } from 'node:path';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import * as marked from 'marked';
 import { type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
 import {
@@ -67,11 +70,13 @@ import { canvasThemeScheme, isCanvasTheme } from '../shared/themes.js';
 import { canOpenNodeAsSurface } from '../shared/surface.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
+  addCanvasNode,
   cancelCodeGraphRecompute,
   primeCanvasRuntimeBackends,
   setCanvasLayoutUpdateEmitter,
   syncCanvasRuntimeBackends,
 } from './canvas-operations.js';
+import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENT_NAME_LENGTH } from './document-import.js';
 import { dispatchOperationRoute, setOperationEventEmitter } from './operations/index.js';
 import { intentRegistry } from './intent-registry.js';
 import { agentPresence } from './agent-presence.js';
@@ -79,6 +84,8 @@ import { HUMAN_STARTED_SESSION_LABEL } from '../shared/agent-presence.js';
 import { diffLayouts } from './mutation-history.js';
 import { humanPresence } from './human-presence.js';
 import { startGateTtlSweeper, stopGateTtlSweeper } from './ax-gate-ttl.js';
+import { startBackupScheduler, stopBackupScheduler } from './backup.js';
+import { exportsFolder } from './board-export.js';
 import { setWebviewRunner } from './operations/webview-runner.js';
 import { closeNodeAppSession, nodeAppSessionId } from './operations/ops/nodes.js';
 import { traceManager } from './trace-manager.js';
@@ -143,7 +150,7 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy) => {
   let snapshot = startSnapshotId
     ? (canvasState.listSnapshots({ all: true }).find((entry) => entry.id === startSnapshotId) ?? null)
     : null;
-  let unchanged = false;
+  let unchanged = !startSnapshotId && canvasState.getLayout().nodes.length === 0;
   // A session that changed NOTHING on the board leaves no snapshot behind —
   // session churn (idle timeouts, receipt tests, attach/detach cycles) was
   // flooding the History drawer with identical boards.
@@ -184,6 +191,7 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy) => {
   // workbench session and would overwrite it. The label is what the receipt shows.
   emitPrimaryWorkbenchEvent('agent-session-ended', {
     label: presence.label,
+    parentAgentId: presence.parentAgentId ?? null,
     endedAt,
     endedBy,
     counts,
@@ -970,6 +978,39 @@ function normalizeMarkdownExternalUrls(markdown: string): string {
 const CANVAS_ASSET_VERSION = Date.now().toString(36);
 const MAX_FRAME_DOCUMENTS = 128;
 const MAX_FRAME_DOCUMENT_BYTES = 5 * 1024 * 1024;
+
+async function readBoundedBody(req: Request, limit: number): Promise<Uint8Array | null> {
+  if (!req.body) return new Uint8Array();
+  const reader = req.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > limit) {
+        await reader.cancel();
+        return null;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+function attachmentDisposition(name: string): string {
+  const fallback = name.replace(/[^\x20-\x7e]|["\\]/g, '_');
+  return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
 const DEFAULT_FRAME_DOCUMENT_SANDBOX = 'allow-scripts';
 const SAFE_FRAME_DOCUMENT_SANDBOX_TOKENS = new Set([
   'allow-downloads',
@@ -1111,6 +1152,7 @@ function canvasSpaHtml(): string {
   }
   <script>window.__PMX_BOOT_SERVER_VERSION = ${JSON.stringify(serverPackageVersion())};</script>
   <script>window.__PMX_BOOT_BUNDLE_STAMP = ${JSON.stringify(canvasBundleStamp())};</script>
+  <script>window.__PMX_WORKBENCH_TOKEN = ${JSON.stringify(workbenchToken)};</script>
   <script type="module" src="/canvas/index.js?v=${CANVAS_ASSET_VERSION}"></script>
 </body>
 </html>`;
@@ -1431,15 +1473,17 @@ function handleNodeSurface(pathname: string, url: URL): Response {
     // escaped diagram source, rendered by /canvas/mermaid-entry.js.
     const inlineAssets = url.searchParams.get('inline-assets') === '1';
     const doc = buildHtmlSurfaceDocument(
-      buildMermaidSurfaceHtml(source, inlineAssets ? mermaidEntryJsInline() : null),
+      buildMermaidSurfaceHtml(
+        source,
+        inlineAssets ? mermaidEntryJsInline() : null,
+        node.data.fit === 'none' ? 'none' : 'contain',
+        url.searchParams.get('frameToken') ?? '',
+      ),
       {
         theme,
         title: surfaceTitle,
         themeToken: url.searchParams.get('themeToken') ?? undefined,
-        // Content-height reporter nonce (lets the node grow to fit the diagram).
-        ...(url.searchParams.get('frameToken')
-          ? { contentHeightToken: url.searchParams.get('frameToken') as string }
-          : {}),
+        // Mermaid reports its natural height itself, before contain scaling.
         // Inline the theme tokens so srcdoc-rendered surfaces (Amp orb portals)
         // are styled without depending on the <link> subresource.
         ...(surfaceThemeCssInline() ? { inlineThemeCss: surfaceThemeCssInline() as string } : {}),
@@ -1555,6 +1599,39 @@ async function handleCanvasImage(pathname: string): Promise<Response> {
   });
 }
 
+// ── Serve a written board export (plan 013) ─────────────────
+// Only names the exporter writes, only from the exports folder. The page runs
+// its own viewer script, so it is served with an opaque-origin sandbox: it can
+// never reach this server's API as the workbench.
+const EXPORT_FILE_NAME = /^[a-z0-9-]+-\d{8}T\d{9}Z(?:-\d+)?\.html$/;
+
+function handleBoardExportFile(url: URL): Response {
+  const name = decodeURIComponent(url.pathname.slice('/api/canvas/exports/'.length));
+  const folder = exportsFolder();
+  if (!folder || !EXPORT_FILE_NAME.test(name)) return responseText('Export not found', 404);
+  let path: string;
+  try {
+    const realFolder = realpathSync(folder);
+    path = realpathSync(join(folder, name));
+    const rel = relative(realFolder, path);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) || !statSync(path).isFile()) {
+      return responseText('Export not found', 404);
+    }
+  } catch {
+    return responseText('Export not found', 404);
+  }
+  const download = url.searchParams.get('download') === '1';
+  return new Response(Bun.file(path), {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Content-Security-Policy': 'sandbox allow-scripts allow-popups allow-popups-to-escape-sandbox',
+      'Content-Disposition': `${download ? 'attachment' : 'inline'}; filename="${name}"`,
+      'X-Content-Type-Options': 'nosniff',
+      'Cache-Control': 'no-store',
+    },
+  });
+}
+
 // ── Serve raw bytes for file nodes (PDF viewer, downloads) ───
 /**
  * Ceiling for the raw byte route. The route streams via Bun.file, so this is a
@@ -3217,6 +3294,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   const loaded = canvasState.loadFromDisk({ clearExisting: true });
   // Unattended-approval policy: hold pending gates whose TTL elapsed.
   startGateTtlSweeper((event, payload) => emitPrimaryWorkbenchEvent(event, payload));
+  startBackupScheduler();
   setCanvasLayoutUpdateEmitter(() => {
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   });
@@ -3370,6 +3448,69 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           // theme/update/viewport/annotation/refresh (plan-009 C1 slices 1-3). A
           // null return falls through to the remaining hand-written routes
           // (SSE, binary, HTML/static serving, and the server-coupled handlers).
+          if (url.pathname === '/api/canvas/attachments' && req.method === 'POST') {
+            const boardId = url.searchParams.get('boardId')?.trim() ?? '';
+            const name = url.searchParams.get('name')?.trim() ?? '';
+            const mime = url.searchParams.get('mime')?.trim() || 'application/octet-stream';
+            const x = Number(url.searchParams.get('x') ?? 40);
+            const y = Number(url.searchParams.get('y') ?? 40);
+            if (!boardId || !name || !Number.isFinite(x) || !Number.isFinite(y))
+              return responseJson({ ok: false, error: 'boardId, name, and finite x/y are required.' }, 400);
+            if (name.length > MAX_ATTACHMENT_NAME_LENGTH)
+              return responseJson(
+                { ok: false, error: `Attachment name exceeds ${MAX_ATTACHMENT_NAME_LENGTH} characters.` },
+                400,
+              );
+            if (Number(req.headers.get('content-length') ?? 0) > MAX_ATTACHMENT_BYTES)
+              return responseJson({ ok: false, error: 'Attachment exceeds the 20 MiB limit.' }, 413);
+            const bytes = await readBoundedBody(req, MAX_ATTACHMENT_BYTES);
+            if (!bytes) return responseJson({ ok: false, error: 'Attachment exceeds the 20 MiB limit.' }, 413);
+            if (bytes.byteLength === 0) return responseJson({ ok: false, error: 'Attachment is empty.' }, 400);
+            if (canvasState.activeBoardId !== boardId)
+              return responseJson({ ok: false, error: 'The captured target board is no longer active.' }, 409);
+            if (!isWorkbenchToken(req.headers.get('x-pmx-workbench-token')))
+              return responseJson({ ok: false, error: 'A trusted human upload is required.' }, 403);
+            const attachment = withCurrentActor({ actor: 'human', source: 'browser' }, () =>
+              canvasState.storeAttachment({ boardId, name, mime, bytes }),
+            );
+            if (!attachment) return responseJson({ ok: false, error: 'Board not found.' }, 404);
+            const { node } = withCurrentActor({ actor: 'human', source: 'browser' }, () =>
+              addCanvasNode({
+                type: 'file',
+                title: name,
+                data: { attachmentId: attachment.id, mime, size: attachment.size },
+                x,
+                y,
+                defaultWidth: 440,
+                defaultHeight: 360,
+                fileMode: 'auto',
+              }),
+            );
+            const created = canvasState.createDocumentImport(attachment.id, { x, y: y + 400 });
+            const documentImport = created;
+            emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+            return responseJson({ ok: true, attachment, nodeId: node.id, import: documentImport }, 201);
+          }
+
+          const attachmentBytesMatch = url.pathname.match(/^\/api\/canvas\/attachments\/([^/]+)\/bytes$/);
+          if (attachmentBytesMatch && (req.method === 'GET' || req.method === 'HEAD')) {
+            const id = decodeURIComponent(attachmentBytesMatch[1]!);
+            const attachment = canvasState.getAttachment(id);
+            if (!attachment || !canvasState.listBoards().some((board) => board.id === attachment.boardId))
+              return responseJson({ ok: false, error: 'Attachment not found.' }, 404);
+            const bytes = canvasState.readAttachmentBytes(id);
+            if (!bytes) return responseJson({ ok: false, error: 'Attachment bytes are missing.' }, 404);
+            return new Response(req.method === 'HEAD' ? null : new Blob([Uint8Array.from(bytes)]), {
+              headers: {
+                'Content-Type': 'application/octet-stream',
+                'Content-Length': String(bytes.byteLength),
+                'Content-Disposition': attachmentDisposition(attachment.name),
+                'X-Content-Type-Options': 'nosniff',
+                'Cache-Control': 'no-store',
+              },
+            });
+          }
+
           if (url.pathname.startsWith('/api/')) {
             const operationResponse = await dispatchOperationRoute(req, url);
             if (operationResponse) return operationResponse;
@@ -3393,6 +3534,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 
           // HEAD answers like GET (see the standalone-surface note above): a PDF
           // viewer probes this URL for type/length before fetching the bytes.
+          if (url.pathname.startsWith('/api/canvas/exports/') && (req.method === 'GET' || req.method === 'HEAD')) {
+            return handleBoardExportFile(url);
+          }
+
           if (url.pathname === '/api/canvas/file-bytes' && (req.method === 'GET' || req.method === 'HEAD')) {
             return await handleCanvasFileBytes(url);
           }
@@ -3428,11 +3573,13 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 }
 
 export function stopCanvasServer(): void {
+  // A failed flush must leave the live server and its runtime state available for recovery.
+  canvasState.close();
   stopGateTtlSweeper();
+  stopBackupScheduler();
   agentPresence.reset();
   humanPresence.reset();
   intentRegistry.reset();
-  canvasState.close();
   closeAllMcpAppSessions();
   cancelCodeGraphRecompute();
   setCanvasLayoutUpdateEmitter(null);

package/src/server/spatial-analysis.ts

@@ -306,14 +306,12 @@ export function searchNodes(
 
   for (const node of nodes) {
     const title = ((node.data.title as string) ?? '').toLowerCase();
-    const content = (
-      (node.data.content as string) ??
-      (node.data.agentSummary as string) ??
-      (node.data.contentSummary as string) ??
-      (node.data.description as string) ??
-      (node.data.fileContent as string) ??
-      ''
-    ).toLowerCase();
+    // Search the same meaning delivered to agents, without a brief's truncation.
+    const fullContent = summarizeNodeForAgentContext(node, {
+      defaultTextLength: Number.POSITIVE_INFINITY,
+      webpageTextLength: Number.POSITIVE_INFINITY,
+    });
+    const content = fullContent.toLowerCase();
     const path = ((node.data.path as string) ?? '').toLowerCase();
     const description = ((node.data.description as string) ?? '').toLowerCase();
     const summary = (
@@ -337,16 +335,10 @@ export function searchNodes(
 
     if (score === 0) continue;
 
-    // Extract a snippet around the first match in content
+    // Any query term may have matched, not necessarily the first one.
     let snippet = '';
-    const fullContent =
-      (node.data.content as string) ??
-      (node.data.agentSummary as string) ??
-      (node.data.contentSummary as string) ??
-      (node.data.description as string) ??
-      (node.data.fileContent as string) ??
-      '';
-    const matchIdx = fullContent.toLowerCase().indexOf(terms[0]);
+    const matches = terms.map((term) => content.indexOf(term)).filter((index) => index >= 0);
+    const matchIdx = matches.length ? Math.min(...matches) : -1;
     if (matchIdx >= 0) {
       const start = Math.max(0, matchIdx - 40);
       const end = Math.min(fullContent.length, matchIdx + 80);

package/src/server/trace-manager.ts

@@ -88,6 +88,7 @@ class TraceManager {
     mcpToolName?: string | null;
   }): void {
     if (!this._enabled) return;
+    this.dropStaleChain();
 
     const id = nextTraceNodeId();
     const category = categorize(payload.name, payload.mcpServerName);
@@ -178,6 +179,7 @@ class TraceManager {
 
   onSubagentStarted(payload: { agentName: string; agentDisplayName?: string }): void {
     if (!this._enabled) return;
+    this.dropStaleChain();
 
     const id = nextTraceNodeId();
     const origin = this.getOrigin();
@@ -264,6 +266,23 @@ class TraceManager {
     this.broadcastUpdate();
   }
 
+  /**
+   * The chain's last node is gone (another board was opened, or it was
+   * deleted): start a new chain instead of wiring edges to a missing node.
+   */
+  private dropStaleChain(): void {
+    if (this.lastTraceNodeId && !canvasState.getNode(this.lastTraceNodeId)) this.resetChain();
+  }
+
+  /** Forget the trace chain without touching nodes. */
+  resetChain(): void {
+    this.traceNodeIds = [];
+    this.lastTraceNodeId = null;
+    this.toolCallToNodeId.clear();
+    this.traceOrigin = null;
+    this.chainIndex = 0;
+  }
+
   clearTrace(): void {
     const traceNodeIds = new Set(this.traceNodeIds);
     for (const node of canvasState.getLayout().nodes) {

package/src/server/web-artifacts.ts

@@ -13,7 +13,7 @@ import {
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { ensureArtifactsDir, getWorkspaceRoot } from './artifact-paths.js';
 import { canvasState, type CanvasNodeState } from './canvas-state.js';
-import { emitCanvasLayoutUpdate } from './canvas-operations.js';
+import { emitCanvasLayoutUpdate, type CanvasSizeAdjustment } from './canvas-operations.js';
 import { findOpenCanvasPosition } from './placement.js';
 
 const BUNDLED_WEB_ARTIFACT_SCRIPTS_DIR = join(import.meta.dir, 'web-artifacts', 'scripts');
@@ -95,12 +95,14 @@ export interface WebArtifactSourceContext {
 export interface WebArtifactCanvasOpenResult {
   nodeId: string;
   url: string;
+  sizeAdjustment: CanvasSizeAdjustment;
 }
 
 export interface WebArtifactCanvasBuildResult extends WebArtifactBuildOutput {
   openedInCanvas: boolean;
   nodeId?: string;
   url?: string;
+  sizeAdjustment?: CanvasSizeAdjustment;
   startedAt: string;
   completedAt: string;
   durationMs: number;
@@ -740,7 +742,11 @@ export function openWebArtifactInCanvas(input: {
   // This keeps web-artifacts.ts server-independent so the registry op
   // (operations/ops/app.ts) can import it without pulling in server.ts.
   emitCanvasLayoutUpdate();
-  return { nodeId: id, url };
+  return {
+    nodeId: id,
+    url,
+    sizeAdjustment: { requested: { width: null, height: null }, applied: node.size, reason: 'defaulted' },
+  };
 }
 
 export async function buildWebArtifactOnCanvas(
@@ -748,6 +754,7 @@ export async function buildWebArtifactOnCanvas(
     openInCanvas?: boolean;
   },
 ): Promise<WebArtifactCanvasBuildResult> {
+  const boardGeneration = canvasState.boardGeneration;
   const startedMs = Date.now();
   const startedAt = new Date(startedMs).toISOString();
   const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -759,7 +766,7 @@ export async function buildWebArtifactOnCanvas(
     durationMs: completedMs - startedMs,
     timeoutMs,
   };
-  if (input.openInCanvas === false) {
+  if (input.openInCanvas === false || canvasState.boardGeneration !== boardGeneration) {
     return { ...build, openedInCanvas: false, ...timing };
   }
   const opened = openWebArtifactInCanvas({
@@ -778,6 +785,7 @@ export async function buildWebArtifactOnCanvas(
     openedInCanvas: true,
     nodeId: opened.nodeId,
     url: opened.url,
+    sizeAdjustment: opened.sizeAdjustment,
     ...timing,
   };
 }

package/src/server/webpage-node.ts

@@ -1,7 +1,14 @@
+import { lookup } from 'node:dns/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { isIP } from 'node:net';
+import { Readable } from 'node:stream';
+
 const FETCH_TIMEOUT_MS = 10000;
 const MAX_HTML_LENGTH = 1_000_000;
 const MAX_TEXT_LENGTH = 50_000;
 const EXCERPT_LENGTH = 420;
+const MAX_REDIRECTS = 5;
 
 export const WEBPAGE_NODE_DEFAULT_SIZE = {
   width: 520,
@@ -236,24 +243,177 @@ export function summarizeWebpageContent(data: Record<string, unknown>, maxLength
   return parts.join('\n').trim();
 }
 
-export async function fetchWebpageSnapshot(inputUrl: string): Promise<WebpageSnapshot> {
+export type AddressScope = 'public' | 'private' | 'link-local';
+
+/**
+ * Where an IP literal points. `private` covers loopback, RFC 1918, CGNAT and
+ * IPv6 ULA; `link-local` is kept apart because it holds cloud metadata
+ * (169.254.169.254) and is refused on every hop.
+ */
+export function classifyAddress(address: string): AddressScope {
+  let ip = address.toLowerCase().replace(/^\[|\]$/g, '');
+  // URL canonicalization also covers expanded IPv6 and dotted mapped IPv4.
+  // Checking only ::ffff:a.b.c.d misses the hex form used by URL.hostname.
+  if (isIP(ip) === 6) ip = new URL(`http://[${ip}]/`).hostname.slice(1, -1);
+  const mapped = ip.match(/^::ffff:([\da-f]+):([\da-f]+)$/);
+  if (mapped) {
+    const high = Number.parseInt(mapped[1], 16);
+    const low = Number.parseInt(mapped[2], 16);
+    return classifyAddress(`${high >>> 8}.${high & 255}.${low >>> 8}.${low & 255}`);
+  }
+  if (isIP(ip) === 4) {
+    const [a, b] = ip.split('.').map(Number);
+    if (a === 169 && b === 254) return 'link-local';
+    if (a === 127 || a === 10 || a === 0) return 'private';
+    if (a === 172 && b >= 16 && b <= 31) return 'private';
+    if (a === 192 && b === 168) return 'private';
+    if (a === 100 && b >= 64 && b <= 127) return 'private';
+    return 'public';
+  }
+  if (/^fe[89ab]/.test(ip)) return 'link-local';
+  if (ip === '::1' || ip === '::' || /^f[cd]/.test(ip)) return 'private';
+  return 'public';
+}
+
+interface ResolvedHop {
+  addresses: string[];
+  scope: AddressScope;
+}
+
+type ResolveHost = (hostname: string) => Promise<Array<{ address: string; family: number }>>;
+
+function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new DOMException('The operation was aborted.', 'AbortError'));
+    if (signal.aborted) return abort();
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+  });
+}
+
+/** Resolves a hop once, retaining the narrowest scope any returned address reaches. */
+async function resolveHop(url: URL, resolveHost: ResolveHost): Promise<ResolvedHop> {
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  const addresses = isIP(host) ? [{ address: host, family: isIP(host) }] : await resolveHost(host);
+  const selected = addresses[0];
+  if (!selected || (selected.family !== 4 && selected.family !== 6)) {
+    throw new WebpageFetchError(`Could not resolve ${host}.`);
+  }
+  const scopes = addresses.map((entry) => classifyAddress(entry.address));
+  const scope = scopes.includes('link-local') ? 'link-local' : scopes.includes('private') ? 'private' : 'public';
+  return { addresses: addresses.map((entry) => entry.address), scope };
+}
+
+async function requestHop(url: URL, resolved: ResolvedHop, signal: AbortSignal): Promise<Response> {
+  let failure: unknown;
+  for (const address of resolved.addresses) {
+    try {
+      return await requestAddress(url, address, signal);
+    } catch (error) {
+      if (signal.aborted) throw error;
+      failure = error;
+    }
+  }
+  throw failure;
+}
+
+function requestAddress(url: URL, address: string, signal: AbortSignal): Promise<Response> {
+  return new Promise((resolve, reject) => {
+    const request = (url.protocol === 'https:' ? httpsRequest : httpRequest)(
+      url,
+      {
+        method: 'GET',
+        hostname: address,
+        servername: isIP(url.hostname.replace(/^\[|\]$/g, '')) ? undefined : url.hostname,
+        signal,
+        headers: {
+          Accept: 'text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.1',
+          Host: url.host,
+          'User-Agent': 'pmx-canvas webpage node',
+        },
+      },
+      (incoming) => {
+        const headers = new Headers();
+        for (let index = 0; index < incoming.rawHeaders.length; index += 2) {
+          headers.append(incoming.rawHeaders[index], incoming.rawHeaders[index + 1]);
+        }
+        const status = incoming.statusCode ?? 500;
+        const empty = status === 204 || status === 205 || status === 304;
+        // Node and DOM declare separate types for the same web-stream API.
+        const body = empty ? null : (Readable.toWeb(incoming) as unknown as ReadableStream<Uint8Array>);
+        if (empty) incoming.resume();
+        resolve(new Response(body, { status, statusText: incoming.statusMessage, headers }));
+      },
+    );
+    request.on('error', reject);
+    request.end();
+  });
+}
+
+async function readBoundedBody(response: Response): Promise<string> {
+  const reader = response.body?.getReader();
+  if (!reader) return '';
+  const decoder = new TextDecoder();
+  let body = '';
+  let bytes = 0;
+  while (bytes < MAX_HTML_LENGTH) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const remaining = MAX_HTML_LENGTH - bytes;
+    body += decoder.decode(value.subarray(0, remaining), { stream: value.byteLength <= remaining });
+    bytes += Math.min(value.byteLength, remaining);
+    if (value.byteLength > remaining || bytes === MAX_HTML_LENGTH) {
+      await reader.cancel();
+      break;
+    }
+  }
+  return body + decoder.decode();
+}
+
+/**
+ * Refuses link-local on every hop, and a redirect that moves a public fetch
+ * onto a loopback or private address. A URL the caller points at a local dev
+ * server on purpose still loads, and may redirect within the local network.
+ */
+export function checkWebpageHop(originScope: AddressScope, hopScope: AddressScope, hopUrl: string): void {
+  if (hopScope === 'link-local') {
+    throw new WebpageFetchError(`Refused to fetch ${hopUrl}: link-local addresses are not allowed.`);
+  }
+  if (originScope === 'public' && hopScope === 'private') {
+    throw new WebpageFetchError(`Refused redirect to ${hopUrl}: a public page may not redirect to a private address.`);
+  }
+}
+
+export async function fetchWebpageSnapshot(
+  inputUrl: string,
+  options: { resolveHost?: ResolveHost; timeoutMs?: number } = {},
+): Promise<WebpageSnapshot> {
   const url = normalizeWebpageUrl(inputUrl);
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  const timeoutMs = options.timeoutMs ?? FETCH_TIMEOUT_MS;
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const resolveHost = options.resolveHost ?? ((host) => lookup(host, { all: true }));
 
   try {
-    const response = await fetch(url, {
-      redirect: 'follow',
-      signal: controller.signal,
-      headers: {
-        Accept: 'text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.1',
-        'User-Agent': 'pmx-canvas webpage node',
-      },
-    });
+    // Redirects are followed by hand so every hop's host is checked before it is fetched.
+    let resolved = await abortable(resolveHop(new URL(url), resolveHost), controller.signal);
+    const originScope = resolved.scope;
+    let hopUrl = url;
+    let response: Response;
+    for (let hop = 0; ; hop++) {
+      checkWebpageHop(originScope, resolved.scope, hopUrl);
+      response = await requestHop(new URL(hopUrl), resolved, controller.signal);
+      const location = response.headers.get('location');
+      if (response.status < 300 || response.status >= 400 || !location) break;
+      await response.body?.cancel();
+      if (hop === MAX_REDIRECTS) throw new WebpageFetchError(`Too many redirects while fetching ${url}.`);
+      hopUrl = normalizeWebpageUrl(new URL(location, hopUrl).toString());
+      resolved = await abortable(resolveHop(new URL(hopUrl), resolveHost), controller.signal);
+    }
 
     const contentType = response.headers.get('content-type');
-    const responseUrl = normalizeWebpageUrl(response.url || url);
-    const body = (await response.text()).slice(0, MAX_HTML_LENGTH);
+    const responseUrl = hopUrl;
+    const body = await readBoundedBody(response);
 
     if (!response.ok) {
       throw new WebpageFetchError(`Request failed with ${response.status} ${response.statusText}`.trim(), {
@@ -292,7 +452,7 @@ export async function fetchWebpageSnapshot(inputUrl: string): Promise<WebpageSna
   } catch (error) {
     if (error instanceof WebpageFetchError) throw error;
     if (error instanceof Error && error.name === 'AbortError') {
-      throw new WebpageFetchError(`Timed out after ${FETCH_TIMEOUT_MS}ms while fetching ${url}.`);
+      throw new WebpageFetchError(`Timed out after ${timeoutMs}ms while fetching ${url}.`);
     }
     throw new WebpageFetchError(error instanceof Error ? error.message : `Failed to fetch ${url}.`);
   } finally {

package/src/server/workbench-auth.ts

@@ -0,0 +1,11 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+/** Per-process capability used only to distinguish workbench clicks from HTTP agents. */
+export const workbenchToken = randomBytes(32).toString('base64url');
+
+export function isWorkbenchToken(value: string | null): boolean {
+  if (!value) return false;
+  const actual = Buffer.from(value);
+  const expected = Buffer.from(workbenchToken);
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}

package/src/server/workboard.ts

@@ -82,14 +82,14 @@ export function buildWorkboardSpec(workItems: PmxAxWorkItem[]): JsonRenderSpec {
     }
     elements[columnId] = {
       type: 'Stack',
-      props: { direction: 'vertical', gap: 'sm' },
+      props: { direction: 'vertical', gap: 'sm', align: 'stretch' },
       children: columnChildren,
     };
     columnIds.push(columnId);
   }
   elements.board = {
-    type: 'Stack',
-    props: { direction: 'horizontal', gap: 'md', align: 'start' },
+    type: 'Grid',
+    props: { columns: columnIds.length, gap: 'md' },
     children: columnIds,
   };
   return { root: 'board', elements };