pmx-canvas 0.8.2 → 0.9.1

package/src/server/memory-graph.ts

@@ -0,0 +1,166 @@
+import { canvasState } from './canvas-state.js';
+import { summarizeNodeForAgentContext } from '../shared/agent-context.js';
+import {
+  memoryKey,
+  wikiLinksFromData,
+  type MemoryGraph,
+  type MemoryGraphEdge,
+  type MemoryGraphNode,
+  type MemoryTarget,
+} from '../shared/memory-graph.js';
+
+/** One library projection for Home, backlinks, brief discovery and agent exploration. No writes. */
+export function memoryGraph(projection: 'full' | 'boards' = 'full'): MemoryGraph {
+  const boards = canvasState.listBoards();
+  const reads = boards.map((board) => ({ board, read: canvasState.readBoard(board.id, false) }));
+  const keys = new Set<string>();
+  const nodes: MemoryGraphNode[] = [];
+  const edges: MemoryGraphEdge[] = [];
+  const unresolvedLinks: MemoryGraph['unresolvedLinks'] = [];
+  const add = (
+    kind: MemoryGraphEdge['kind'],
+    id: string,
+    source: MemoryTarget,
+    target: MemoryTarget,
+    label?: string,
+    type?: string,
+    relationKind?: string,
+    reason?: string,
+  ) => {
+    edges.push({
+      id,
+      kind,
+      from: memoryKey(source),
+      to: memoryKey(target),
+      source,
+      target,
+      missing: false,
+      ...(label ? { label } : {}),
+      ...(type ? { type } : {}),
+      ...(relationKind ? { relationKind } : {}),
+      ...(reason ? { reason } : {}),
+    });
+  };
+  for (const { board, read } of reads) {
+    const readme = read?.layout.nodes.find((node) => node.id === board.readmeNodeId);
+    const summary = (node: NonNullable<typeof read>['layout']['nodes'][number]) =>
+      summarizeNodeForAgentContext(node, { defaultTextLength: 280, webpageTextLength: 280 }).slice(0, 280);
+    nodes.push({
+      key: memoryKey({ boardId: board.id }),
+      boardId: board.id,
+      kind: 'board',
+      title: board.name,
+      summary: readme ? summary(readme) : '',
+      folder: board.folder,
+      inContext: !!board.pin,
+      summaryOnly: true,
+      nodeCount: board.nodeCount,
+      ...(board.mapPosition ? { position: board.mapPosition } : {}),
+    });
+    keys.add(memoryKey({ boardId: board.id }));
+    if (board.previousBoardId)
+      add(
+        'previous',
+        `previous:${board.id}`,
+        { boardId: board.id },
+        { boardId: board.previousBoardId },
+        'previous board',
+      );
+    for (const node of read?.layout.nodes ?? []) {
+      const source = { boardId: board.id, cardId: node.id };
+      keys.add(memoryKey(source));
+      if (projection === 'full')
+        nodes.push({
+          ...source,
+          key: memoryKey(source),
+          kind: 'card',
+          title: typeof node.data.title === 'string' ? node.data.title : node.id,
+          summary: summary(node),
+          folder: board.folder,
+          type: node.type,
+          summaryOnly: true,
+          linksRevision: node.linksRevision ?? 0,
+          inContext: !!board.pin || !!read?.state.contextPins.includes(node.id),
+        });
+      if (projection === 'full') add('member', `member:${memoryKey(source)}`, { boardId: board.id }, source);
+      if (node.type === 'board' && typeof node.data.boardId === 'string') {
+        add('portal', `portal:${memoryKey(source)}`, source, { boardId: node.data.boardId });
+      }
+      for (const link of node.type === 'markdown' ? wikiLinksFromData(node.data) : []) {
+        if (link.target) add('wiki', `wiki:${memoryKey(source)}:${link.ref}`, source, link.target, link.ref);
+        else unresolvedLinks.push({ source, ref: link.ref });
+      }
+    }
+    for (const edge of read?.layout.edges ?? []) {
+      add(
+        'card',
+        `card:${board.id}:${edge.id}`,
+        { boardId: board.id, cardId: edge.from },
+        { boardId: edge.toBoardId ?? board.id, cardId: edge.to },
+        edge.label,
+        edge.type,
+        edge.kind,
+        edge.reason,
+      );
+    }
+  }
+  for (const edge of edges) edge.missing = !keys.has(edge.from) || !keys.has(edge.to);
+  const graph = { nodes, edges, unresolvedLinks, focus: null, depth: 2 };
+  return projection === 'boards' ? boardMemoryGraph(graph) : graph;
+}
+
+/** Keep original qualified endpoints and missing evidence, without card summaries or membership. */
+export function boardMemoryGraph(graph: MemoryGraph): MemoryGraph {
+  return {
+    ...graph,
+    nodes: graph.nodes.filter((node) => node.kind === 'board'),
+    edges: graph.edges.filter(
+      (edge) => edge.kind !== 'member' && (edge.missing || edge.source.boardId !== edge.target.boardId),
+    ),
+  };
+}
+
+/** Board-level connections are a collapse of the SAME edges, not another link scanner. */
+export function boardConnections(graph: MemoryGraph): MemoryGraphEdge[] {
+  return graph.edges.filter((edge) => edge.kind !== 'member' && edge.source.boardId !== edge.target.boardId);
+}
+
+/** Undirected exploration. Membership is a hop too; focus accepts a board ID, qualified key, or pins. */
+export function localMemoryGraph(graph: MemoryGraph, focus: string | null, depth: number): MemoryGraph {
+  if (!focus) return { ...graph, depth };
+  const seed =
+    focus === 'pins'
+      ? graph.nodes.filter((node) => node.inContext).map((node) => node.key)
+      : graph.nodes
+          .filter((node) => node.key === focus || (node.kind === 'board' && node.boardId === focus))
+          .map((node) => node.key);
+  const selected = new Set(seed);
+  let frontier = new Set(seed);
+  for (let level = 0; level < depth; level++) {
+    const next = new Set<string>();
+    for (const edge of graph.edges) {
+      if (edge.missing) continue;
+      if (frontier.has(edge.from) && !selected.has(edge.to)) next.add(edge.to);
+      if (frontier.has(edge.to) && !selected.has(edge.from)) next.add(edge.from);
+    }
+    for (const key of next) selected.add(key);
+    frontier = next;
+  }
+  const edges = graph.edges.filter((edge) => selected.has(edge.from) && (selected.has(edge.to) || edge.missing));
+  const deliveredEdges = new Set(edges.map((edge) => edge.id));
+  return {
+    nodes: graph.nodes
+      .filter((node) => selected.has(node.key))
+      .map((node) => ({
+        ...node,
+        linksComplete: graph.edges.every(
+          (edge) =>
+            edge.kind === 'member' || (edge.from !== node.key && edge.to !== node.key) || deliveredEdges.has(edge.id),
+        ),
+      })),
+    edges,
+    unresolvedLinks: graph.unresolvedLinks.filter((link) => selected.has(memoryKey(link.source))),
+    focus,
+    depth,
+  };
+}

package/src/server/mutation-history.ts

@@ -84,8 +84,8 @@ export interface SnapshotDiffResult {
     title: string | null;
     changes: string[];
   }[];
-  addedEdges: { id: string; from: string; to: string; type: string }[];
-  removedEdges: { id: string; from: string; to: string; type: string }[];
+  addedEdges: { id: string; from: string; to: string; toBoardId?: string; type: string }[];
+  removedEdges: { id: string; from: string; to: string; toBoardId?: string; type: string }[];
 }
 
 function comparableNodeData(data: Record<string, unknown>): Record<string, unknown> {
@@ -335,12 +335,24 @@ export function diffLayouts(
 
   for (const [id, edge] of curEdges) {
     if (!snapEdges.has(id)) {
-      addedEdges.push({ id, from: edge.from, to: edge.to, type: edge.type });
+      addedEdges.push({
+        id,
+        from: edge.from,
+        to: edge.to,
+        ...(edge.toBoardId !== undefined ? { toBoardId: edge.toBoardId } : {}),
+        type: edge.type,
+      });
     }
   }
   for (const [id, edge] of snapEdges) {
     if (!curEdges.has(id)) {
-      removedEdges.push({ id, from: edge.from, to: edge.to, type: edge.type });
+      removedEdges.push({
+        id,
+        from: edge.from,
+        to: edge.to,
+        ...(edge.toBoardId !== undefined ? { toBoardId: edge.toBoardId } : {}),
+        type: edge.type,
+      });
     }
   }
 
@@ -395,7 +407,7 @@ export function formatDiff(diff: SnapshotDiffResult): string {
   if (diff.addedEdges.length > 0) {
     lines.push(`Added edges (${diff.addedEdges.length}):`);
     for (const e of diff.addedEdges) {
-      lines.push(`  + ${e.type}: ${e.from} → ${e.to}`);
+      lines.push(`  + ${e.type}: ${e.from} → ${e.toBoardId ? `${e.toBoardId}/` : ''}${e.to}`);
     }
     lines.push('');
   }
@@ -403,7 +415,7 @@ export function formatDiff(diff: SnapshotDiffResult): string {
   if (diff.removedEdges.length > 0) {
     lines.push(`Removed edges (${diff.removedEdges.length}):`);
     for (const e of diff.removedEdges) {
-      lines.push(`  - ${e.type}: ${e.from} → ${e.to}`);
+      lines.push(`  - ${e.type}: ${e.from} → ${e.toBoardId ? `${e.toBoardId}/` : ''}${e.to}`);
     }
     lines.push('');
   }

package/src/server/operations/composites.ts

@@ -137,12 +137,13 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
     // compositeFoldedOpNames and frees the name in the same change.
     toolName: 'canvas_snapshot',
     description:
-      'Canvas snapshots: save the current state, list saved snapshots, restore one, delete one, garbage-collect old ones, or diff the live canvas against one. Action "save" stores a named snapshot; "list" returns saved snapshots (newest first); "restore" replaces the live canvas with a snapshot; "delete" removes one; "gc" keeps the newest N and deletes the rest (dryRun to preview); "diff" shows added/removed/modified nodes and edges versus a snapshot (by name or id).',
-    actionSummary: 'save | list | restore | delete | gc | diff',
+      'Canvas snapshots: save the current state, list saved snapshots, restore one, delete one, garbage-collect old ones, or diff the live canvas against one. Action "save" stores a named snapshot; "list" returns saved snapshots (newest first); "restore" replaces the live canvas with a snapshot; "delete" removes one; "gc" keeps the newest N and deletes the rest (dryRun to preview); "diff" shows added/removed/modified nodes and edges versus a snapshot (by name or id); "restore-node" puts one card (nodeId) back to its content in a snapshot, leaving the rest of the board as it is.',
+    actionSummary: 'save | list | restore | restore-node | delete | gc | diff',
     actions: {
       save: 'snapshot.save',
       list: 'snapshot.list',
       restore: 'snapshot.restore',
+      'restore-node': 'snapshot.restore-node',
       delete: 'snapshot.delete',
       gc: 'snapshot.gc',
       diff: 'snapshot.diff',
@@ -151,8 +152,10 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_board',
     description:
-      'Boards in this workspace — the library of the human\'s and your working memory, filed in categories on Home. Your writes always go to the open board (activeBoardId); on Home (no board open) your first write opens the most recent board, or a new one when there are none. Action "list" returns every board (with its category), most recently opened first; "get" reads one (default: the open board); "create" makes a new empty board WITHOUT opening it (optional category); "open" explicitly switches the shared workbench to id (null or omitted opens Home), changing the visible board and subsequent write target. After creating a board, open its returned id and verify activeBoardId before writing; another participant can switch the board later. "update" renames a board, files it under a category (category "" removes it), or designates its README via readmeNodeId. As part of normal board authoring, read the board metadata; if readmeNodeId is null, choose or create a concise markdown introduction explaining its purpose and key context, then designate that node with "update". Preserve an existing README unless the human asks to change it; humans can override the designation manually. Only the human deletes boards.',
-    actionSummary: 'list | get | create | create-from | open | update',
+      'Knowledge data: knowledge-list reads categories/folders/shared relation presets; category-set replaces category (id/name/glyph/decayType/rate/triggers/revalidationMethod); category-remove deletes an unused category by id (explicit folder assignments, including empty folders, refuse deletion); relation-preset-set saves preset (id/name/vocabulary); relation-preset-remove deletes a template without changing existing board vocabularies; folder-set replaces path/categoryId/lifecycleOverride (null inherits). These workspace actions never open a board and are refused under agent scope fences. ' +
+      'Boards in this workspace — the library of the human\'s and your working memory, filed in folders on Home. Your writes always go to the open board (activeBoardId); on Home (no board open) your first write opens the most recent board, or a new one when there are none. Action "list" returns every board (with its folder), most recently opened first; "get" reads one (default: the open board); "create" makes a new empty board WITHOUT opening it (optional folder); "open" explicitly switches the server active board to id (null or omitted opens Home), changing the subsequent write target. Humans browsing Map/Graph stay in the library until they explicitly open a board/card; do not infer activeBoardId from their visible library. After creating a board, open its returned id and verify activeBoardId before writing; another participant can switch the board later. "update" renames a board, files it under a folder (folder "" removes it), or designates its README via readmeNodeId. As part of normal board authoring, read the board metadata; if readmeNodeId is null, choose or create a concise markdown introduction explaining its purpose and key context, then designate that node with "update". Preserve an existing README unless the human asks to change it; humans can override the designation manually. "pin" adds a board to the working set (its README and pinned cards reach your brief whichever board is open; optional reason), "unpin" removes it; a pinned board is read-only context, never a write target. Only the human deletes boards.',
+    actionSummary:
+      'list | get | create | create-from | open | update | pin | unpin | knowledge-list | category-set | category-remove | relation-preset-set | relation-preset-remove | folder-set',
     actions: {
       list: 'board.list',
       get: 'board.get',
@@ -160,18 +163,31 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
       'create-from': 'board.create-from',
       open: 'board.open',
       update: 'board.update',
+      'knowledge-list': 'knowledge.list',
+      'category-set': 'knowledge.category-set',
+      'category-remove': 'knowledge.category-remove',
+      'relation-preset-set': 'knowledge.relation-preset-set',
+      'relation-preset-remove': 'knowledge.relation-preset-remove',
+      'folder-set': 'knowledge.folder-set',
+      pin: 'board.pin',
+      unpin: 'board.unpin',
     },
   },
   {
     toolName: 'canvas_node',
     description:
-      'Create, read, update, or remove a canvas node. One tool for node CRUD: action "add" creates a node (requires type — markdown, status, context, ledger, trace, file, image, webpage, html, group, etc.); "get" reads one node by id; "update" patches an existing node (title, content, position, size, data); "remove" deletes a node by id. For spec-driven content (json-render, graph) use canvas_render; for external/built apps use canvas_app (actions: open-mcp-app, diagram, build-artifact).',
-    actionSummary: 'add | get | update | remove',
+      'Lifecycle data: lifecycle-get reads effective inheritance, due/source qualification and review history (optional board); lifecycle-set sets full lifecycleOverride or null; review requires outcome retain/revise/externalize/retire/unresolved, evidence and applied. Applied retain/revise/externalize with nonempty evidence also requires expectedContentRevision and expectedSources from the content and sources actually checked; stale reviews fail. Records keep those observations and persist content before evidence. lifecycle-restore requires evidence and explicitly restores retirement, never validation. Retired cards are excluded from active briefs by default. Writes accept expectedBoardId and obey edit locks/scope. ' +
+      'Create, read, update, or remove a canvas node. One tool for node CRUD: action "add" creates a node (requires type — markdown, board with data.boardId for a portal, status, context, ledger, trace, file, image, webpage, html, group, etc.); "get" reads one node by id; "update" patches an existing node (title, content, position, size, data); "remove" deletes a node by id. For spec-driven content (json-render, graph) use canvas_render; for external/built apps use canvas_app (actions: open-mcp-app, diagram, build-artifact).',
+    actionSummary: 'add | get | update | remove | lifecycle-get | lifecycle-set | review | lifecycle-restore',
     actions: {
       add: 'node.add',
       get: 'node.get',
       update: 'node.update',
       remove: 'node.remove',
+      'lifecycle-get': 'node.lifecycle-get',
+      'lifecycle-set': 'node.lifecycle-set',
+      review: 'node.review',
+      'lifecycle-restore': 'node.lifecycle-restore',
     },
   },
   {
@@ -223,11 +239,15 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_view',
     description:
-      'Canvas viewport and layout control. Action "arrange" auto-lays-out nodes (grid/columns/etc.); "focus" pans/zooms the viewport to a node; "fit" zooms to fit all nodes in view; "clear" removes every node and edge from the canvas; "remove-annotation" deletes a human-drawn annotation by id.',
-    actionSummary: 'arrange | focus | fit | clear | remove-annotation | get-tour | set-tour',
+      'Canvas viewport and layout control. Action "arrange" auto-lays-out nodes (grid/columns/etc.); "focus" pans/zooms the viewport to a node; "fit" zooms to fit all nodes in view; "clear" removes every node and edge from the canvas; "remove-annotation" deletes a human-drawn annotation by id; "get-tour"/"set-tour" read or persist the presentation tour; "tour-go" presents a stop (stop index or step next/previous); "tour-exit" leaves presentation; "move" eases the camera to a nodeId, world rect or viewport over a duration. Camera actions never enter undo history.',
+    actionSummary:
+      'arrange | focus | fit | clear | remove-annotation | get-tour | set-tour | tour-go | tour-exit | move',
     actions: {
       'get-tour': 'tour.get',
       'set-tour': 'tour.set',
+      'tour-go': 'tour.go',
+      'tour-exit': 'tour.exit',
+      move: 'camera.move',
       arrange: 'arrange',
       focus: 'node.focus',
       fit: 'view.fit',
@@ -238,10 +258,11 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_query',
     description:
-      'Read the board cheapest-first. Action "context" returns a budgeted cross-board brief with a durable consumer cursor (budget is UTF-16 characters); "search" finds nodes by title/content keywords; "layout" returns the full layout; "validate" checks geometry and endpoints.',
-    actionSummary: 'context | search | layout | validate',
+      'Read the board cheapest-first. Action "context" returns a budgeted cross-board brief with a durable consumer cursor (budget is UTF-16 characters); "graph" explores the library relation graph (focus: board ID, qualified node key, or pins; depth: 0–4), summaries only; "search" finds nodes by title/content keywords; "layout" returns the full layout; "validate" checks geometry and endpoints.',
+    actionSummary: 'context | graph | search | layout | validate',
     actions: {
       context: 'context.get',
+      graph: 'memory-graph.get',
       search: 'search',
       layout: 'layout.get',
       validate: 'validate.get',
@@ -275,7 +296,7 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_ax_state',
     description:
-      'Read or set host-agnostic PMX AX state. Action "get" reads the AX state + agent-ready context (pinned/focused context, focus field); "set-focus" places node IDs in the AX focus field (nodeIds); "set-policy" patches the tool/prompt policy (tools.allowed|excluded|approvalRequired, prompt.systemAppend|mode — merges with existing); "report-capability" records a host/session capability for diagnostics; "presence" reads agent presence (who is writing, phase, attached session, context budget); "set-presence" updates this caller\'s presence (phase idle|thinking|tooling|waiting-approval, detail, focusNodeId, cursor, attached — attached:true starts a session, false ends it; contextUsage {used,total} reports the agent\'s real token window so the board\'s meter shows it instead of the pinned-context estimate). Adapters may pass a source label (e.g. codex).',
+      'Read or set host-agnostic PMX AX state. Action "get" reads the AX state + agent-ready context (pinned/focused context, focus field); "set-focus" places node IDs in the AX focus field (nodeIds); "set-policy" patches the tool/prompt policy (tools.allowed|excluded|approvalRequired, prompt.systemAppend|mode — merges with existing); "report-capability" records a host/session capability for diagnostics; "presence" reads agent presence (who is writing, phase, attached session); "set-presence" updates this caller\'s presence (phase idle|thinking|tooling|waiting-approval, detail, focusNodeId, cursor, attached — attached:true starts a session, false ends it; contextUsage {used,total} reports the agent\'s real token usage, which the board\'s context panel names). Adapters may pass a source label (e.g. codex).',
     actionSummary: 'get | set-focus | set-policy | report-capability | presence | set-presence',
     actions: {
       get: 'ax.get',

package/src/server/operations/http.ts

@@ -9,7 +9,7 @@
 import { executeOperation, listOperations } from './registry.js';
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
 import { OperationError } from './types.js';
-import { isWorkbenchToken } from '../workbench-auth.js';
+import { isWorkbenchToken, refuseStaleWorkbenchWrite } from '../workbench-auth.js';
 
 function responseJson(data: unknown, status = 200): Response {
   return Response.json(data, {
@@ -90,7 +90,12 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       // the browser is not agent activity, so it never synthesizes an
       // auto-ghost. Everything else (CLI, scripts, adapters) counts as agent.
       const workbenchMarked = req.headers.get('x-pmx-workbench') === '1';
-      const humanAuthor = isWorkbenchToken(req.headers.get('x-pmx-workbench-token'));
+      const token = req.headers.get('x-pmx-workbench-token');
+      const humanAuthor = isWorkbenchToken(token);
+      // Before reconnect delivers the rotated capability, do not silently
+      // downgrade an old tab's human save to an agent edit.
+      const staleWrite = refuseStaleWorkbenchWrite(req);
+      if (staleWrite) return staleWrite;
       // Presence writer label: adapters/CLI may identify themselves; plain
       // HTTP callers read as 'api'.
       const sourceHeader = req.headers.get('x-pmx-source');

package/src/server/operations/index.ts

@@ -12,6 +12,7 @@ import { validateOperations } from './ops/validate.js';
 import { annotationOperations } from './ops/annotation.js';
 import { snapshotOperations } from './ops/snapshots.js';
 import { boardOperations } from './ops/boards.js';
+import { memoryGraphOperations } from './ops/memory-graph.js';
 import { backupOperations } from './ops/backup.js';
 import { exportOperations } from './ops/export.js';
 import { jsonRenderOperations } from './ops/json-render.js';
@@ -29,8 +30,10 @@ import { axPresenceOperations } from './ops/ax-presence.js';
 import { humanPresenceOperations } from './ops/human-presence.js';
 import { canvasWireOperations } from './ops/canvas-wire.js';
 import { importOperations } from './ops/imports.js';
+import { lifecycleOperations } from './ops/lifecycle.js';
 
 for (const op of [
+  ...lifecycleOperations,
   ...nodeOperations,
   ...edgeOperations,
   ...viewportOperations,
@@ -40,6 +43,7 @@ for (const op of [
   ...annotationOperations,
   ...snapshotOperations,
   ...boardOperations,
+  ...memoryGraphOperations,
   ...backupOperations,
   ...exportOperations,
   ...jsonRenderOperations,

package/src/server/operations/mcp.ts

@@ -12,7 +12,14 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { getOperation, listOperations } from './registry.js';
 import { agentSourceLabel, type OperationInvoker } from './invoker.js';
 import { OperationError, type Operation, type OperationMcpToolHost } from './types.js';
-import { CONTEXT_READ_OPS, contextReadFromPayload, type ContextReadInput } from '../context-reads.js';
+import {
+  CONTEXT_READ_OPS,
+  contextReadFromPayload,
+  pinnedBoardReads,
+  graphReads,
+  type ContextReadInput,
+} from '../context-reads.js';
+import type { MemoryGraph } from '../../shared/memory-graph.js';
 import { compositeFoldedOpNames, compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
 
 export interface OperationToolHost extends OperationMcpToolHost {
@@ -50,6 +57,14 @@ async function invokeMcpOperation(
       if (node.data === undefined && !node.content) return formatted;
     }
     try {
+      if (op.name === 'memory-graph.get') {
+        for (const read of graphReads(
+          { channel: 'operation', resource: op.name, source: agentSourceLabel('mcp'), consumer, agentId: null },
+          JSON.parse(text) as MemoryGraph,
+        ))
+          await host.recordContextRead(read);
+        return formatted;
+      }
       await host.recordContextRead(
         contextReadFromPayload(
           {
@@ -64,6 +79,16 @@ async function invokeMcpOperation(
           text,
         ),
       );
+      if (op.name === 'context.get') {
+        const base = {
+          channel: 'operation' as const,
+          resource: op.name,
+          source: agentSourceLabel('mcp'),
+          consumer,
+          agentId: null,
+        };
+        for (const read of pinnedBoardReads(base, text)) await host.recordContextRead(read);
+      }
     } catch (error) {
       console.error('[pmx-canvas mcp] recording a context read failed:', error);
     }

package/src/server/operations/ops/ax-presence.ts

@@ -39,7 +39,7 @@ const presenceSetShape = {
     'true attaches a session; false detaches it. Read presence first and reuse your host adapter session instead of attaching another. Only detach sessions you own.',
   ),
   contextUsage: PRESENCE_SET_SHAPE.contextUsage.describe(
-    "The agent's real token window as {used,total} — shown on the board's context meter instead of the pinned-context estimate (null clears it)",
+    "The agent's real token usage as {used,total} — the board's context panel names how many tokens its whole context holds (null clears it)",
   ),
 };
 const presenceSetSchema = z.looseObject(presenceSetShape);

package/src/server/operations/ops/ax-read.ts

@@ -13,7 +13,11 @@
  */
 import { agentPresence } from '../../agent-presence.js';
 import { z } from 'zod';
-import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../../../shared/agent-context.js';
+import {
+  buildAgentContextPreamble,
+  serializeNodeForAgentContext,
+  summarizeNodeForAgentContext,
+} from '../../../shared/agent-context.js';
 import { buildCanvasAxContext, buildCanvasAxSurfaceSnapshot } from '../../ax-context.js';
 import { applyAxInteraction } from '../../ax-interaction.js';
 import {
@@ -31,6 +35,9 @@ import { defineOperation, OperationError, type Operation, type OperationContext
 import { readTargetBoard } from './boards.js';
 import { normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
 import { isRecord } from './nodes.js';
+import { lifecycleQualifications } from '../../lifecycle-status.js';
+import { memoryKey } from '../../../shared/memory-graph.js';
+import { findNeighborhoods } from '../../spatial-analysis.js';
 
 // ── Activity-reaction validation (moved from server.ts) ───────
 
@@ -167,20 +174,64 @@ const pinnedContextOperation = defineOperation<z.infer<typeof pinnedContextSchem
   },
   handler: ({ board }) => {
     const target = readTargetBoard(board);
-    const pinnedIds = Array.from(target.pinnedNodeIds);
+    const qualifications = lifecycleQualifications(Date.now(), target.boardId ? [{ boardId: target.boardId }] : []);
+    const qualification = (id: string, boardId = target.boardId) =>
+      boardId ? qualifications[memoryKey({ boardId, cardId: id })] : undefined;
+    const pinnedIds = Array.from(target.pinnedNodeIds).filter((id) => !qualification(id)?.retired);
     const nodes = pinnedIds
       .map((id) => target.layout.nodes.find((node) => node.id === id))
       .filter((node): node is CanvasNodeState => node !== undefined);
     const preamble =
       pinnedIds.length > 0 ? buildAgentContextPreamble(nodes, { defaultTextLength: 700, webpageTextLength: 1600 }) : '';
-    const serialized = nodes.map((node) =>
-      serializeNodeForAgentContext(node, {
+    const serialized = nodes.map((node) => ({
+      ...serializeNodeForAgentContext(node, {
         defaultTextLength: 700,
         webpageTextLength: 1600,
         includePosition: true,
       }),
-    );
-    return { preamble, nodeIds: pinnedIds, count: pinnedIds.length, nodes: serialized };
+      qualification: qualification(node.id),
+    }));
+    const activeNodes = target.layout.nodes.filter((node) => !qualification(node.id)?.retired);
+    return {
+      preamble,
+      nodeIds: pinnedIds,
+      count: pinnedIds.length,
+      pinnedCount: pinnedIds.length,
+      nodes: serialized,
+      edges: target.layout.edges.filter(
+        (edge) =>
+          pinnedIds.includes(edge.from) &&
+          (!edge.toBoardId || edge.toBoardId === target.boardId) &&
+          pinnedIds.includes(edge.to),
+      ),
+      neighborhoods: findNeighborhoods(activeNodes, new Set(pinnedIds)).map((neighborhood) => ({
+        pinnedNodeId: neighborhood.pinnedNodeId,
+        pinnedNodeTitle: neighborhood.pinnedNodeTitle,
+        nearbyNodes: neighborhood.neighbors.map((node) => ({ ...node, qualification: qualification(node.id) })),
+      })),
+      pinnedBoards: canvasState
+        .listBoards()
+        .filter((board) => board.pin)
+        .map((board) => {
+          const read = canvasState.readBoard(board.id, true);
+          const cards = (read?.layout.nodes ?? []).filter((node) => !qualification(node.id, board.id)?.retired);
+          const readme = cards.find((node) => node.id === board.readmeNodeId && node.type === 'markdown');
+          return {
+            boardId: board.id,
+            name: board.name,
+            pin: board.pin,
+            summary: readme ? summarizeNodeForAgentContext(readme, { defaultTextLength: 1000 }) : null,
+            readmeQualification: readme ? qualification(readme.id, board.id) : null,
+            pinnedTitles: cards
+              .filter((node) => read?.state.contextPins.includes(node.id))
+              .map((node) => ({
+                nodeId: node.id,
+                title: String(node.data.title ?? node.id),
+                qualification: qualification(node.id, board.id),
+              })),
+          };
+        }),
+    };
   },
 });
 

package/src/server/operations/ops/ax-timeline.ts

@@ -506,6 +506,14 @@ const axReadsRecordShape = {
     .array(z.string())
     .optional()
     .describe('Ids of every serialized node in what the agent received; defaults to deliveredNodeIds.'),
+  seenNodeIds: z
+    .array(z.string())
+    .optional()
+    .describe('Ids of every node that arrived with its relations, summaries included; defaults to readNodeIds.'),
+  seenLinkRevisions: z
+    .record(z.string(), z.number().int().nonnegative())
+    .optional()
+    .describe('Exact link revisions captured in the delivered graph or brief before transport work.'),
   bytes: z.number().int().nonnegative().describe('Size of what the agent received.'),
   boardId: z.string().nullable().optional().describe('Board that was read, captured before delivery.'),
 };
@@ -532,6 +540,8 @@ const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchem
         pinnedNodeIds: input.pinnedNodeIds ?? [...canvasState.contextPinnedNodeIds],
         deliveredNodeIds: input.deliveredNodeIds,
         ...(input.readNodeIds ? { readNodeIds: input.readNodeIds } : {}),
+        ...(input.seenNodeIds ? { seenNodeIds: input.seenNodeIds } : {}),
+        ...(input.seenLinkRevisions ? { seenLinkRevisions: input.seenLinkRevisions } : {}),
         bytes: input.bytes,
       },
       input.boardId === undefined ? canvasState.activeBoardId : input.boardId,
@@ -542,12 +552,17 @@ const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchem
 
 const axReadsStatusShape = {
   board: z.string().optional().describe('Board id; defaults to the open board.'),
+  boards: z
+    .string()
+    .optional()
+    .describe("Comma-separated board ids: also return each one's latest agent read (pinned boards, in one request)."),
 };
 const axReadsStatusSchema = z.looseObject(axReadsStatusShape);
 
 /**
  * Per node: when an agent last read its content, who, and at which revision
- * (vs the node's revision now); and per pin: who pinned it, when and why.
+ * (vs the node's revision now); per node, the newest links revision a read
+ * carried (connection marks); and per pin: who pinned it, when and why.
  */
 const axReadsStatusOperation = defineOperation<z.infer<typeof axReadsStatusSchema>, Record<string, unknown>>({
   name: 'ax.reads.status',
@@ -567,7 +582,18 @@ const axReadsStatusOperation = defineOperation<z.infer<typeof axReadsStatusSchem
         : boardId
           ? (canvasState.readBoard(boardId, false)?.state.contextPinMeta ?? {})
           : {};
-    return { ok: true, boardId, nodes: canvasState.getNodeReadStatus(boardId), pins };
+    const others = typeof input.boards === 'string' ? input.boards.split(',').map((id) => id.trim()) : [];
+    return {
+      ok: true,
+      boardId,
+      board: canvasState.getBoardLastRead(boardId),
+      ...(others.length > 0
+        ? { boards: Object.fromEntries(others.filter(Boolean).map((id) => [id, canvasState.getBoardLastRead(id)])) }
+        : {}),
+      nodes: canvasState.getNodeReadStatus(boardId),
+      links: canvasState.getSeenLinks(boardId),
+      pins,
+    };
   },
 });
 

package/src/server/operations/ops/backup.ts

@@ -120,9 +120,11 @@ const backupRestoreOperation = defineOperation<z.infer<typeof restoreSchema>, Re
     }
     const previous = `${canvasState.databasePath}.before-restore`;
     restoreCanvasLibrary(file);
-    // `reloaded` tells open tabs to take the board fresh even when its id is unchanged.
-    ctx.emit('boards-changed', { ...boardsPayload(), reloaded: true });
-    return { ok: true, restored: file, previous, ...boardsPayload() };
+    // Keep the reload marker in later catalogs too, if a GET overtakes this event.
+    const catalog = boardsPayload(true);
+    ctx.emit('boards-changed', catalog);
+    ctx.emit('settings-changed', { workspaceSettings: canvasState.getWorkspaceSettings() });
+    return { ok: true, restored: file, previous, ...catalog };
   },
 });