pmx-canvas 0.8.2 → 0.9.0

package/src/server/server.ts

@@ -39,13 +39,16 @@
 
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { isWorkbenchToken, workbenchToken } from './workbench-auth.js';
+import { isWorkbenchToken, refuseStaleWorkbenchWrite, 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, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import * as marked from 'marked';
+import { renderWikiMarkdown, resolveWikiLinks, wikiReferences } from './wiki-links.js';
+import { wikiLinksFromData } from '../shared/memory-graph.js';
 import { type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
+import { boardCatalogEpoch, boardsPayload } from './operations/ops/boards.js';
 import {
   buildAxBridge,
   buildAxStateBridge,
@@ -83,6 +86,7 @@ import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENT_NAME_LENGTH } from './document-imp
 import { dispatchOperationRoute, setOperationEventEmitter } from './operations/index.js';
 import { intentRegistry } from './intent-registry.js';
 import { agentPresence } from './agent-presence.js';
+import { cardText, changeExcerpts, describeEdit } from './edit-summary.js';
 import { HUMAN_STARTED_SESSION_LABEL } from '../shared/agent-presence.js';
 import { diffLayouts } from './mutation-history.js';
 import { humanPresence } from './human-presence.js';
@@ -159,6 +163,7 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy, started
   // or every node when the board was empty at attach (no snapshot was taken).
   let addedIds = startSnapshotId ? new Set<string>() : new Set(layout.nodes.map((node) => node.id));
   let modifiedIds = new Set<string>();
+  let beforeNodes = new Map<string, CanvasNodeState>();
   // 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.
@@ -168,6 +173,7 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy, started
       const diff = diffLayouts(snapData.name, snapData, layout);
       addedIds = new Set(diff.addedNodes.map((node) => node.id));
       modifiedIds = new Set(diff.modifiedNodes.map((node) => node.id));
+      beforeNodes = new Map(snapData.nodes.map((node) => [node.id, node]));
       if (
         diff.addedNodes.length === 0 &&
         diff.removedNodes.length === 0 &&
@@ -197,7 +203,7 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy, started
     rejected: ax.approvalGates.filter((gate) => gate.status === 'rejected').length,
     held: ax.approvalGates.filter((gate) => gate.status === 'held').length,
   };
-  const context = sessionContextActivity(layout.nodes, startedAt, addedIds, modifiedIds);
+  const context = sessionContextActivity(layout.nodes, startedAt, addedIds, modifiedIds, beforeNodes);
   // Reading or pinning is something the human wants to see even when the
   // board itself did not change ("did the agent read what I pinned?").
   if (context.read.length > 0 || context.pinned.length > 0) unchanged = false;
@@ -205,12 +211,15 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy, started
   // workbench session and would overwrite it. The label is what the receipt shows.
   emitPrimaryWorkbenchEvent('agent-session-ended', {
     label: presence.label,
+    // The writer key (the envelope reserves `sessionId`): the client's live lens matches on it.
+    writer: presence.sessionId,
     parentAgentId: presence.parentAgentId ?? null,
+    startedAt,
     endedAt,
     endedBy,
     counts,
     unchanged,
-    snapshot: snapshot ? { id: snapshot.id, name: snapshot.name } : null,
+    snapshot: snapshot ? { id: snapshot.id, name: snapshot.name, boardId: canvasState.activeBoardId } : null,
     context,
   });
 });
@@ -218,7 +227,13 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy, started
 interface ReceiptNode {
   id: string;
   title: string;
+  boardId: string | null;
   reason?: string;
+  /** Edited cards: what the edit did ("rewrote the second paragraph"). */
+  change?: string;
+  /** Edited cards: the text before and after, cut around the first difference, for "See change". */
+  before?: string;
+  after?: string;
 }
 
 /**
@@ -231,6 +246,7 @@ function sessionContextActivity(
   startedAt: string | null,
   addedIds: Set<string>,
   modifiedIds: Set<string>,
+  beforeNodes: Map<string, CanvasNodeState>,
 ): {
   read: ReceiptNode[];
   pinned: ReceiptNode[];
@@ -239,11 +255,12 @@ function sessionContextActivity(
   changedSinceRead: ReceiptNode[];
 } {
   const byId = new Map(nodes.map((node) => [node.id, node]));
+  const boardId = canvasState.activeBoardId;
   const entry = (node: CanvasNodeState): ReceiptNode => ({
     id: node.id,
+    boardId,
     title: typeof node.data.title === 'string' && node.data.title.trim() ? node.data.title : node.id,
   });
-  const boardId = canvasState.activeBoardId;
   const read = startedAt
     ? canvasState.getReadNodeIdsSince(boardId, startedAt).flatMap((id) => {
         const node = byId.get(id);
@@ -256,7 +273,14 @@ function sessionContextActivity(
     return [{ ...entry(node), ...(meta.reason ? { reason: meta.reason } : {}) }];
   });
   const created = nodes.filter((node) => addedIds.has(node.id) && node.createdBy?.actor === 'agent').map(entry);
-  const edited = nodes.filter((node) => modifiedIds.has(node.id) && node.lastEditedBy?.actor === 'agent').map(entry);
+  const edited = nodes
+    .filter((node) => modifiedIds.has(node.id) && node.lastEditedBy?.actor === 'agent')
+    .map((node) => {
+      const before = beforeNodes.get(node.id);
+      return before
+        ? { ...entry(node), change: describeEdit(before, node), ...changeExcerpts(cardText(before), cardText(node)) }
+        : entry(node);
+    });
   const readStatus = new Map(canvasState.getNodeReadStatus(boardId).map((status) => [status.nodeId, status]));
   const changedSinceRead = [...canvasState.contextPinnedNodeIds].flatMap((id) => {
     const node = byId.get(id);
@@ -898,19 +922,45 @@ function toSseFrame(event: string, payload: PrimaryWorkbenchEventPayload): Uint8
 // open and never flush it to the browser, so an EventSource client behind one
 // receives nothing and the canvas never boots. Every broadcast event is also
 // recorded here with a monotonic seq; GET /api/workbench/poll replays them as
-// a normal, immediately-closed JSON response that any proxy delivers. Bounded:
+// a normal, completed JSON response that any proxy delivers. Bounded:
 // a client whose `since` fell off the ring gets a fresh connect snapshot,
 // which fully rebuilds client state (same events an SSE connect sends).
 const WORKBENCH_EVENT_RING_MAX = 500;
 let workbenchEventSeq = 0;
 const workbenchEventRing: Array<{ seq: number; event: string; payload: PrimaryWorkbenchEventPayload }> = [];
+const workbenchPollWaiters = new Set<() => void>();
+let remoteEdgesSignature = '';
 
 function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPayload): void {
+  let remoteEdgesChanged = false;
+  if (event === 'canvas-layout-update') {
+    // Remote footer titles come from the catalog. Refresh it on endpoint changes
+    // (including SDK writes and Undo), never on ordinary geometry broadcasts.
+    const signature = JSON.stringify([
+      canvasState.activeBoardId,
+      canvasState.boardGeneration,
+      canvasState
+        .getEdges()
+        .filter((edge) => edge.toBoardId)
+        .map((edge) => [edge.id, edge.from, edge.toBoardId, edge.to]),
+    ]);
+    remoteEdgesChanged = signature !== remoteEdgesSignature;
+    remoteEdgesSignature = signature;
+  }
+  if (event === 'canvas-layout-update' || event === 'context-pins-changed') {
+    payload = {
+      ...payload,
+      catalogEpoch: boardCatalogEpoch,
+      boardGeneration: canvasState.boardGeneration,
+      boardId: canvasState.activeBoardId,
+    };
+  }
   workbenchEventSeq += 1;
   workbenchEventRing.push({ seq: workbenchEventSeq, event, payload });
   if (workbenchEventRing.length > WORKBENCH_EVENT_RING_MAX) {
     workbenchEventRing.splice(0, workbenchEventRing.length - WORKBENCH_EVENT_RING_MAX);
   }
+  for (const wake of workbenchPollWaiters) wake();
   const frame = toSseFrame(event, payload);
   for (const [subscriberId, controller] of workbenchSubscribers.entries()) {
     try {
@@ -925,6 +975,7 @@ function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPa
       syncCanvasBrowserOpenedFromSubscribers();
     }
   }
+  if (remoteEdgesChanged) emitPrimaryWorkbenchEvent('boards-changed', boardsPayload());
 }
 
 function setPrimaryWorkbenchPath(safePath: string, source: string): void {
@@ -2201,6 +2252,9 @@ function buildWorkbenchConnectSnapshot(
       continuity,
       path: primaryWorkbenchPath,
       theme: canvasState.theme,
+      workspaceSettings: canvasState.getWorkspaceSettings(),
+      workbenchToken,
+      catalogEpoch: boardCatalogEpoch,
       // Lets a long-lived client detect that the server was upgraded under it
       // (stale in-memory SPA — 0.4.5 report Finding W) and reload once. The
       // bundle stamp catches DEV rolls too: a rebuild+restart never bumps the
@@ -2243,6 +2297,9 @@ function buildWorkbenchConnectSnapshot(
   events.push({
     event: 'canvas-layout-update',
     payload: {
+      catalogEpoch: boardCatalogEpoch,
+      boardGeneration: canvasState.boardGeneration,
+      boardId: canvasState.activeBoardId,
       layout: canvasState.getLayout(),
       sessionId: primaryWorkbenchSessionId,
       timestamp: new Date().toISOString(),
@@ -2251,6 +2308,7 @@ function buildWorkbenchConnectSnapshot(
   events.push({
     event: 'context-pins-changed',
     payload: {
+      boardId: canvasState.activeBoardId,
       count: canvasState.contextPinnedNodeIds.size,
       nodeIds: Array.from(canvasState.contextPinnedNodeIds),
       sessionId: primaryWorkbenchSessionId,
@@ -2294,15 +2352,32 @@ function buildWorkbenchConnectSnapshot(
  * Proxy-safe transport (Amp orb portals and any proxy that buffers streaming
  * responses): returns the buffered events after `since` — or the full connect
  * snapshot when `since` is absent, from a previous server run, or already
- * evicted from the ring — as a normal JSON response that closes immediately.
- * The client polls every couple of seconds; each response flushes through any
- * proxy. `seq` is the cursor for the next poll.
+ * evicted from the ring — as a normal JSON response. A caught-up client may
+ * wait up to one second for an event instead of leaving a gap between reads.
+ * Each response closes so buffering proxies flush it. `seq` is the next cursor.
  */
-function handleWorkbenchPoll(url: URL): Response {
+async function handleWorkbenchPoll(req: Request, url: URL): Promise<Response> {
   rotatePrimaryWorkbenchSessionIfNeeded();
   const requestedSessionId = url.searchParams.get('session')?.trim() ?? '';
   const sinceRaw = url.searchParams.get('since');
   const since = sinceRaw === null ? Number.NaN : Number(sinceRaw);
+  const waitMs = Math.min(1000, Math.max(0, Number(url.searchParams.get('waitMs')) || 0));
+  if (waitMs > 0 && since === workbenchEventSeq && !req.signal.aborted) {
+    await new Promise<void>((resolve) => {
+      const finish = (): void => {
+        if (!workbenchPollWaiters.delete(finish)) return;
+        clearTimeout(timer);
+        req.signal.removeEventListener('abort', finish);
+        resolve();
+      };
+      const timer = setTimeout(finish, waitMs);
+      workbenchPollWaiters.add(finish);
+      req.signal.addEventListener('abort', finish, { once: true });
+      if (req.signal.aborted) finish();
+    });
+  }
+  if (req.signal.aborted || !server) return new Response(null, { status: 204 });
+  // Recheck retention after waiting: an event burst can evict this cursor.
   const ringHeadSeq =
     workbenchEventRing.length > 0 ? (workbenchEventRing[0] as { seq: number }).seq : workbenchEventSeq + 1;
   const usableSince = Number.isInteger(since) && since >= 0 && since <= workbenchEventSeq && since + 1 >= ringHeadSeq;
@@ -2378,6 +2453,8 @@ function handleWorkbenchEvents(req: Request): Response {
 }
 
 async function handleSave(req: Request): Promise<Response> {
+  const staleWrite = refuseStaleWorkbenchWrite(req);
+  if (staleWrite) return staleWrite;
   const body = await readJson(req);
   if (body === null) return malformedJsonResponse();
   const pathLike = typeof body.path === 'string' ? body.path : '';
@@ -2397,12 +2474,31 @@ async function handleSave(req: Request): Promise<Response> {
 async function handleRender(req: Request): Promise<Response> {
   const body = await readJson(req);
   if (body === null) return malformedJsonResponse();
+  if (body.expectedBoardId !== undefined && body.expectedBoardId !== canvasState.activeBoardId) {
+    return responseJson({ ok: false, error: 'The active board changed. Refresh before retrying this action.' }, 409);
+  }
   const markdown = typeof body.markdown === 'string' ? body.markdown : '';
-  const html =
-    (marked.parse(normalizeMarkdownExternalUrls(markdown), {
-      gfm: true,
-      breaks: true,
-    }) as string) || '';
+  const node = typeof body.nodeId === 'string' ? canvasState.getNode(body.nodeId) : undefined;
+  const previous = node?.type === 'markdown' ? wikiLinksFromData(node.data) : [];
+  // The editor sends its draft through this same endpoint. Only changed/unsaved
+  // text may resolve titles; persisted text must replay even unresolved bindings.
+  const persisted = node?.type === 'markdown' && node.data.content === markdown;
+  const initializedRefs =
+    node?.type === 'markdown' && node.data.wikiLinks !== undefined && typeof node.data.content === 'string'
+      ? wikiReferences(node.data.content)
+      : [];
+  const refs = wikiReferences(markdown).filter(
+    (ref) => !initializedRefs.includes(ref) || previous.some((link) => link.ref === ref),
+  );
+  const needsResolution = !persisted && refs.some((ref) => !previous.some((link) => link.ref === ref && link.target));
+  const catalog = needsResolution ? canvasState.wikiCatalog() : [];
+  const links = persisted ? previous : refs.map((ref) => resolveWikiLinks(`[[${ref}]]`, previous, catalog)[0]);
+  const targets = new Map<string, ReturnType<typeof canvasState.readBoard>>();
+  const html = renderWikiMarkdown(normalizeMarkdownExternalUrls(markdown), links, (target) => {
+    if (!targets.has(target.boardId)) targets.set(target.boardId, canvasState.readBoard(target.boardId, false));
+    const board = targets.get(target.boardId);
+    return !!board && (!target.cardId || board.layout.nodes.some((card) => card.id === target.cardId));
+  });
   return responseJson({ html });
 }
 
@@ -3354,6 +3450,8 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   // browser only (an MCP notification would make a read cause more reads).
   canvasState.setContextReadListener((boardId) => {
     emitPrimaryWorkbenchEvent('context-status-changed', { boardId });
+    // The live session lens counts reads (AgentContext.dc.html).
+    agentPresence.noteRead();
   });
 
   // Ensure direct HTTP server usage records undo/redo history, not just PmxCanvas.start().
@@ -3517,7 +3615,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           }
 
           if (url.pathname === '/api/workbench/poll' && req.method === 'GET') {
-            return handleWorkbenchPoll(url);
+            return handleWorkbenchPoll(req, url);
           }
 
           if (url.pathname === '/api/workbench/intent' && req.method === 'POST') {
@@ -3677,6 +3775,7 @@ export function stopCanvasServer(): void {
     server.stop(true);
     server = null;
   }
+  for (const wake of workbenchPollWaiters) wake();
 }
 
 export function getCanvasServerPort(): number | null {

package/src/server/spatial-analysis.ts

@@ -72,17 +72,8 @@ export interface SpatialContext {
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
-/** Euclidean distance between two node centers */
-export function centerDistance(a: CanvasNodeState, b: CanvasNodeState): number {
-  const ax = a.position.x + a.size.width / 2;
-  const ay = a.position.y + a.size.height / 2;
-  const bx = b.position.x + b.size.width / 2;
-  const by = b.position.y + b.size.height / 2;
-  return Math.sqrt((ax - bx) ** 2 + (ay - by) ** 2);
-}
-
 /** Gap distance — how far apart two nodes are edge-to-edge (0 if overlapping) */
-function gapDistance(a: CanvasNodeState, b: CanvasNodeState): number {
+export function gapDistance(a: CanvasNodeState, b: CanvasNodeState): number {
   const aRight = a.position.x + a.size.width;
   const aBottom = a.position.y + a.size.height;
   const bRight = b.position.x + b.size.width;
@@ -259,7 +250,8 @@ export function detectClusters(nodes: CanvasNodeState[], proximityThreshold = 20
 }
 
 /**
- * Find the nearest unpinned nodes to each pinned node.
+ * Find the nearest unpinned nodes by their edge-to-edge gap from each pin.
+ * The inclusive distance limit is in world pixels, independent of card size.
  */
 export function findNeighborhoods(
   nodes: CanvasNodeState[],
@@ -272,7 +264,7 @@ export function findNeighborhoods(
 
   return pinned.map((pin) => {
     const withDist = unpinned
-      .map((n) => ({ node: n, distance: centerDistance(pin, n) }))
+      .map((n) => ({ node: n, distance: gapDistance(pin, n) }))
       .filter((d) => d.distance <= maxDistance)
       .sort((a, b) => a.distance - b.distance)
       .slice(0, maxNeighbors);
@@ -290,6 +282,38 @@ export function findNeighborhoods(
   });
 }
 
+/** Shared lexical relevance for cards and library metadata. Scores are ranking details. */
+export function searchRelevance(title: string, fields: Array<[string, number]>, query: string): number {
+  const normalize = (text: string) => text.toLowerCase().trim().replace(/\s+/g, ' ');
+  const q = normalize(query);
+  if (!q) return 0;
+  const terms = [...new Set(q.split(' '))];
+  const texts = [[normalize(title), 3] as const, ...fields.map(([text, weight]) => [normalize(text), weight] as const)];
+  const whole = terms.map((term) => {
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // JS \b is ASCII-only; letters, marks and numbers in any script remain part of a word.
+    return new RegExp(`(?<![\\p{L}\\p{M}\\p{N}_])${escaped}(?![\\p{L}\\p{M}\\p{N}_])`, 'u');
+  });
+  let weight = 0;
+  for (const [text, importance] of texts) {
+    for (const term of terms) if (text.includes(term)) weight += importance;
+  }
+  if (!weight) return 0;
+  const wholeTerms = whole.filter((pattern) => texts.some(([text]) => pattern.test(text))).length;
+  const tier =
+    texts[0][0] === q
+      ? 5
+      : texts.some(([text]) => text === q)
+        ? 4
+        : wholeTerms === terms.length
+          ? 3
+          : wholeTerms > 0
+            ? 2
+            : 1;
+  // Field evidence breaks ties but can never overwhelm a better match tier.
+  return tier + weight / (weight + 1);
+}
+
 /**
  * Full-text search across node titles and content.
  * Returns matching nodes with relevance score.
@@ -322,16 +346,17 @@ export function searchNodes(
     ).toLowerCase();
     const url = ((node.data.url as string) ?? '').toLowerCase();
 
-    let score = 0;
-    for (const term of terms) {
-      // Title matches are worth more
-      if (title.includes(term)) score += 3;
-      if (path.includes(term)) score += 2;
-      if (url.includes(term)) score += 2;
-      if (description.includes(term)) score += 1;
-      if (summary.includes(term)) score += 1;
-      if (content.includes(term)) score += 1;
-    }
+    const score = searchRelevance(
+      title,
+      [
+        [path, 2],
+        [url, 2],
+        [description, 1],
+        [summary, 1],
+        [content, 1],
+      ],
+      q,
+    );
 
     if (score === 0) continue;
 
@@ -359,7 +384,7 @@ export function searchNodes(
     });
   }
 
-  results.sort((a, b) => b.score - a.score);
+  results.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   return results;
 }
 

package/src/server/tour-control.ts

@@ -0,0 +1,82 @@
+/**
+ * Driving a board tour: the shared stop cursor and eased camera moves.
+ *
+ * Navigation, not editing: nothing here records undo history, and the cursor
+ * is in-memory (like presence) — a restart or board switch starts over at the
+ * first stop. The browser animates; the server only decides WHERE to go and
+ * broadcasts it, so an agent and every presenting viewer agree on the stop.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { derivedTour, resolveStop, tourStopSchema, type Camera, type Tour, type TourStop } from '../shared/tour.js';
+import { canvasState } from './canvas-state.js';
+import { getClientViewportSize } from './canvas-operations.js';
+import { OperationError } from './operations/types.js';
+
+export type TourStep = number | 'next' | 'previous';
+
+export interface TourStepResult {
+  index: number;
+  total: number;
+  stop: TourStop;
+}
+
+let cursor: { boardGeneration: number; tour: string; index: number } | null = null;
+
+export function currentTour(): Tour {
+  return canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes);
+}
+
+/** The stop the tour is on for the active board, or null when not touring. */
+export function tourPosition(tour: Tour = currentTour()): number | null {
+  if (cursor && (cursor.boardGeneration !== canvasState.boardGeneration || cursor.tour !== JSON.stringify(tour))) {
+    cursor = null;
+  }
+  return cursor?.index ?? null;
+}
+
+/** Move the shared cursor. `next`/`previous` clamp at the ends; an explicit index must exist. */
+export function goToTourStop(step: TourStep): TourStepResult {
+  const tour = currentTour();
+  const { stops } = tour;
+  const at = tourPosition(tour);
+  if (stops.length === 0) {
+    throw new OperationError('This board has no tour stops. Save a tour or add groups.', 400);
+  }
+  let index: number;
+  if (step === 'next') index = at === null ? 0 : Math.min(stops.length - 1, at + 1);
+  else if (step === 'previous') index = at === null ? 0 : Math.max(0, Math.min(stops.length - 1, at - 1));
+  else if (Number.isInteger(step) && step >= 0 && step < stops.length) index = step;
+  else throw new OperationError(`Tour stop ${step} does not exist (stops 0–${stops.length - 1}).`, 400);
+  cursor = { boardGeneration: canvasState.boardGeneration, tour: JSON.stringify(tour), index };
+  return { index, total: stops.length, stop: stops[index] as TourStop };
+}
+
+export function exitTour(): void {
+  cursor = null;
+}
+
+/**
+ * Resolve an eased camera move and store its end camera as the board viewport
+ * (unrecorded). The size is the last window a browser reported, so this is the
+ * server's best estimate; the browser re-resolves against its real canvas area.
+ */
+export function moveCamera(input: unknown): { stop: TourStop; viewport: Camera } {
+  const parsed = tourStopSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new OperationError('Give exactly one of nodeId, rect {x,y,width,height} or viewport {x,y,scale}.', 400);
+  }
+  const stop = parsed.data;
+  if ('nodeId' in stop.target && !canvasState.getNode(stop.target.nodeId)) {
+    throw new OperationError(`Node "${stop.target.nodeId}" not found.`, 404);
+  }
+  const size = getClientViewportSize() ?? { width: 1440, height: 900 };
+  let viewport: Camera;
+  try {
+    viewport = resolveStop(stop, canvasState.getLayout().nodes, size.width, size.height);
+  } catch (error) {
+    throw new OperationError(error instanceof Error ? error.message : String(error), 400);
+  }
+  canvasState.withSuppressedRecording(() => canvasState.setViewport(viewport));
+  return { stop, viewport };
+}

package/src/server/wiki-links.ts

@@ -0,0 +1,137 @@
+import { Marked, type Token, type Tokens } from 'marked';
+import type { MemoryTarget, WikiLink } from '../shared/memory-graph.js';
+
+interface WikiToken extends Tokens.Generic {
+  type: 'wiki';
+  ref: string;
+  label: string;
+}
+
+function wiki(token: Token): token is WikiToken {
+  return token.type === 'wiki';
+}
+
+const escapeHtml = (text: string) =>
+  text.replace(
+    /[&<>"']/g,
+    (c) =>
+      ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+      })[c]!,
+  );
+
+// Same language as Marked 15's blockSkip, with ordinary destination characters
+// consumed in runs instead of one regex iteration per byte of an inline image.
+const blockSkip = /\[[^[\]]*?\]\([^\\()]*(?:\\.[^\\()]*|\([^\\()]*(?:\\.[^\\()]*)*\)[^\\()]*)*\)|`[^`]*?`|<[^<>]*?>/g;
+
+/** Marked's inline tokenizer keeps wiki syntax out of code spans/fences and HTML attributes. */
+function parser(render: (token: WikiToken) => string): Marked {
+  let taskIndex = 0;
+  return new Marked(
+    { gfm: true, breaks: true },
+    {
+      renderer: {
+        checkbox({ checked }) {
+          return `<input data-pmx-task="${taskIndex++}" type="checkbox" disabled${checked ? ' checked' : ''}>`;
+        },
+        html({ text }) {
+          // This attribute belongs to generated tasks, never author-supplied HTML.
+          return text.replace(/\bdata-pmx-task\b/gi, 'data-pmx-raw-task');
+        },
+      },
+      tokenizer: {
+        space() {
+          // Lexer installs rules after constructing the tokenizer. Copy rather
+          // than mutating shared rules, before it queues inline parsing.
+          this.rules.inline = { ...this.rules.inline, blockSkip };
+          return false;
+        },
+        lheading(src) {
+          // Setext headings cannot cross a blank line. Avoid Marked 15's costly
+          // unmatched long-line regex unless a possible underline is present.
+          const blank = /\n\s*?\n/.exec(src);
+          const paragraph = blank ? src.slice(0, blank.index + 1) : src;
+          if (!/\n {0,3}(?:=+|-+) *(?:\n|$)/.test(paragraph)) return undefined;
+          return false;
+        },
+      },
+      extensions: [
+        {
+          name: 'wiki',
+          level: 'inline',
+          start: (src) => src.indexOf('[['),
+          tokenizer(src) {
+            const match = /^\[\[([^\]\n]+)\]\]/.exec(src);
+            if (!match) return undefined;
+            const [ref, ...alias] = match[1].split('|');
+            if (!ref.trim()) return undefined;
+            return { type: 'wiki', raw: match[0], ref: ref.trim(), label: alias.join('|').trim() || ref.trim() };
+          },
+          renderer: (token) => (wiki(token) ? render(token) : false),
+        },
+      ],
+    },
+  );
+}
+
+export function wikiReferences(content: string): string[] {
+  const marked = parser(() => '');
+  const refs = new Set<string>();
+  marked.walkTokens(marked.lexer(content), (token) => {
+    if (wiki(token)) refs.add(token.ref);
+  });
+  return [...refs];
+}
+
+export interface WikiBoard {
+  id: string;
+  name: string;
+  cards: Array<{ id: string; title: string }>;
+}
+
+/** IDs win over names; title matches must be unique. Never retarget an already bound link. */
+export function resolveWikiLinks(content: string, previous: WikiLink[], boards: WikiBoard[]): WikiLink[] {
+  const resolve = (ref: string): MemoryTarget | undefined => {
+    const separator = ref.indexOf('#');
+    const boardName = (separator < 0 ? ref : ref.slice(0, separator)).trim();
+    const cardName = separator < 0 ? null : ref.slice(separator + 1).trim();
+    const exact = boards.find((board) => board.id === boardName);
+    const matches = exact
+      ? [exact]
+      : boards.filter((board) => board.name.toLocaleLowerCase() === boardName.toLocaleLowerCase());
+    if (matches.length !== 1) return undefined;
+    const board = matches[0];
+    if (cardName === null) return { boardId: board.id };
+    const exactCard = board.cards.find((card) => card.id === cardName);
+    const cards = exactCard
+      ? [exactCard]
+      : board.cards.filter((card) => card.title.toLocaleLowerCase() === cardName.toLocaleLowerCase());
+    return cards.length === 1 ? { boardId: board.id, cardId: cards[0].id } : undefined;
+  };
+  return wikiReferences(content).map((ref) => {
+    const target = previous.find((link) => link.ref === ref)?.target ?? resolve(ref);
+    return { ref, ...(target ? { target } : {}) };
+  });
+}
+
+/** Only server-owned bindings may navigate; the client still sanitizes rendered HTML. */
+export function renderWikiMarkdown(
+  content: string,
+  links: WikiLink[],
+  exists: (target: MemoryTarget) => boolean,
+): string {
+  return parser((token) => {
+    const target = links.find((link) => link.ref === token.ref)?.target;
+    const attributes =
+      target && exists(target)
+        ? `data-wiki-board="${escapeHtml(target.boardId)}"${target.cardId ? ` data-wiki-card="${escapeHtml(target.cardId)}"` : ''}`
+        : target
+          ? 'data-wiki-missing="true"'
+          : '';
+    return `<a href="#" class="wiki-link${target && exists(target) ? '' : ' is-unresolved'}" ${attributes} data-wiki-ref="${escapeHtml(token.ref)}" data-wiki-markdown="${escapeHtml(token.raw)}" data-wiki-label="${escapeHtml(token.label)}">${escapeHtml(token.label)}</a>`;
+  }).parse(content) as string;
+}

package/src/server/workbench-auth.ts

@@ -9,3 +9,14 @@ export function isWorkbenchToken(value: string | null): boolean {
   const expected = Buffer.from(workbenchToken);
   return actual.length === expected.length && timingSafeEqual(actual, expected);
 }
+
+/** Refuse an old tab's writes after a daemon restart, without downgrading its actor. */
+export function refuseStaleWorkbenchWrite(req: Request): Response | null {
+  const token = req.headers.get('x-pmx-workbench-token');
+  if (req.method === 'GET' || req.headers.get('x-pmx-workbench') !== '1' || token === null || isWorkbenchToken(token))
+    return null;
+  return Response.json(
+    { ok: false, error: 'Workbench connection changed. Reconnect before saving.' },
+    { status: 409, headers: { 'Cache-Control': 'no-store' } },
+  );
+}

package/src/shared/agent-context.ts

@@ -10,6 +10,8 @@ export interface AgentContextNode {
   kind: string;
   title: string | null;
   content: string | null;
+  /** Context excerpts do not serialize the card's complete incident relations. */
+  linksComplete?: false;
   metadata?: Record<string, unknown>;
   position?: { x: number; y: number };
 }
@@ -421,6 +423,7 @@ export function serializeNodeForAgentContext(
     kind: getCanvasNodeKind(node),
     title: typeof node.data.title === 'string' ? node.data.title : null,
     content: summarizeNodeForAgentContext(node, options) || null,
+    linksComplete: false,
     ...(metadata ? { metadata } : {}),
     ...(options.includePosition ? { position: node.position } : {}),
   };