pmx-canvas 0.6.5 → 0.7.0

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

@@ -52,6 +52,7 @@ import {
 } from '../../canvas-serialization.js';
 import { WEBPAGE_NODE_DEFAULT_SIZE, normalizeWebpageUrl } from '../../webpage-node.js';
 import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
+import { readTargetBoard } from './boards.js';
 
 // ── Node types ────────────────────────────────────────────────
 // Single definition site for the basic node-type list: drives the HTTP type
@@ -59,6 +60,7 @@ import { defineOperation, OperationError, type Operation, type OperationContext
 // and the MCP type enum.
 export const NODE_TYPES = [
   'markdown',
+  'board',
   'status',
   'context',
   'ledger',
@@ -91,6 +93,8 @@ export function defaultNodeSize(type: string): { width: number; height: number }
       return { width: 640, height: 460 };
     case 'markdown':
       return MARKDOWN_NODE_DEFAULT_SIZE;
+    case 'board':
+      return { width: 360, height: 160 };
     case 'mcp-app':
       return MCP_APP_NODE_DEFAULT_SIZE;
     case 'image':
@@ -400,6 +404,12 @@ export function createBasicCanvasNode(
 ): { node: CanvasNodeState; needsCodeGraphRecompute: boolean; sizeAdjustment?: CanvasSizeAdjustment } {
   const type = typeof body.type === 'string' ? body.type : '';
   const extraData = isRecord(body.data) ? body.data : undefined;
+  if (
+    extraData &&
+    ('attachmentId' in extraData || (isRecord(extraData.source) && 'attachmentId' in extraData.source))
+  ) {
+    throw new OperationError('Attachment identity and import provenance are server-managed.');
+  }
   if (type === 'html') {
     if ('html' in body && typeof body.html !== 'string') {
       throw new OperationError('HTML node field "html" must be a string.');
@@ -500,6 +510,25 @@ export function buildNodePatch(
   existing: CanvasNodeState,
   body: Record<string, unknown>,
 ): { patch: Partial<CanvasNodeState>; groupChildIds?: string[] } {
+  if (body.type !== undefined && body.type !== existing.type) throw new OperationError('Node type is immutable.');
+  if (
+    existing.type === 'file' &&
+    typeof existing.data.attachmentId === 'string' &&
+    (body.path !== undefined || body.content !== undefined)
+  ) {
+    throw new OperationError('Attached file nodes cannot be repointed or changed into disk-backed files.');
+  }
+  if (body.data && typeof body.data === 'object' && !Array.isArray(body.data)) {
+    const data = body.data as Record<string, unknown>;
+    const source = data.source;
+    const importedSource = source && typeof source === 'object' && 'attachmentId' in source;
+    const attachedFileContent =
+      existing.type === 'file' &&
+      typeof existing.data.attachmentId === 'string' &&
+      ('path' in data || 'content' in data || 'fileContent' in data);
+    if ('attachmentId' in data || importedSource || attachedFileContent)
+      throw new OperationError('Attachment identity and import provenance are immutable.');
+  }
   // Same dead-field traps as create (gauntlet, 2026-08-27): reject loudly
   // instead of dropping — and note that patching `content` on a file node
   // updates the FILE CONTENT snapshot, it does not re-point the node.
@@ -657,7 +686,11 @@ async function createWebpageNode(body: Record<string, unknown>, ctx: OperationCo
   // The node should appear before the (slow) page fetch completes; the
   // registry emits the final layout update after the handler returns.
   ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+  const boardGeneration = canvasState.boardGeneration;
   const refreshed = await refreshCanvasWebpageNode(id);
+  if (canvasState.boardGeneration !== boardGeneration) {
+    throw new OperationError('The board changed while the webpage was loading.', 409);
+  }
   const created = canvasState.getNode(id) ?? node;
   return {
     node: created,
@@ -974,6 +1007,7 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
 
 const nodeGetShape = {
   id: z.string().describe('The node ID to retrieve'),
+  board: z.unknown().optional().describe('Board id to read without opening it.'),
   includeBlobs: z.unknown().optional().describe('Include full blob payloads instead of blob summaries.'),
 };
 
@@ -993,18 +1027,25 @@ const nodeGetOperation = defineOperation<z.infer<typeof nodeGetSchema>, Serializ
     description:
       'Get a single node by ID. Defaults to compact metadata; pass full:true to include full data/tool results.',
     extraShape: {
+      board: z.string().optional().describe('Board id to read without opening it.'),
       full: z.boolean().optional().describe('Include full node data, including mcp-app tool results. Default false.'),
       verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
-    buildInput: (input) => ({ id: input.id, includeBlobs: true }),
+    buildInput: (input) => ({ id: input.id, board: input.board, includeBlobs: true }),
     formatResult: (result, input) => {
       const node = result as CanvasNodeState;
       const payload = wantsFullPayload(input) ? serializeCanvasNodeForAgent(node) : compactNodePayload(node);
       return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
     },
   },
-  handler: ({ id, includeBlobs }) => {
+  handler: ({ id, includeBlobs, board }) => {
     const full = includeBlobs === true || includeBlobs === 'true';
+    if (typeof board === 'string' && board.trim()) {
+      const target = readTargetBoard(board, full);
+      const node = target.layout.nodes.find((candidate) => candidate.id === id);
+      if (!node) throw new OperationError(`Node "${id}" not found on board "${board}".`, 404);
+      return full ? serializeCanvasNode(node) : serializeCanvasNodeWithBlobSummaries(node);
+    }
     const node = full ? canvasState.getNode(id) : canvasState.getNodeForPersistence(id);
     if (!node) throw new OperationError(`Node "${id}" not found.`, 404);
     const responseNode = withContextPinReadState(node);
@@ -1297,6 +1338,7 @@ const nodeRemoveOperation = defineOperation<z.infer<typeof nodeRemoveSchema>, Re
 // ── layout.get ────────────────────────────────────────────────
 
 const layoutGetShape = {
+  board: z.unknown().optional().describe('Board id to read without opening it.'),
   includeBlobs: z.unknown().optional().describe('Include full blob payloads instead of blob summaries.'),
 };
 
@@ -1316,23 +1358,33 @@ const layoutGetOperation = defineOperation<z.infer<typeof layoutGetSchema>, Reco
     description:
       'Get the canvas layout. Defaults to a compact agent-safe projection; pass full:true for full node data.',
     extraShape: {
+      board: z.string().optional().describe('Board id to read without opening it.'),
       full: z
         .boolean()
         .optional()
         .describe('Return the full layout including node data. Default false keeps responses compact.'),
       verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
-    buildInput: () => ({ includeBlobs: true }),
+    buildInput: (input) => ({ board: input.board, includeBlobs: true }),
     formatResult: async (result, input, host) => {
       const layout = result as CanvasLayout;
       const payload = wantsFullPayload(input)
         ? agentSafeFullLayoutPayload(layout)
-        : compactLayoutPayload(layout, await host.getPinnedNodeIds());
+        : compactLayoutPayload(
+            layout,
+            await host.getPinnedNodeIds(typeof input.board === 'string' ? input.board : undefined),
+          );
       return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
     },
   },
-  handler: ({ includeBlobs }) => {
+  handler: ({ includeBlobs, board }) => {
     const full = includeBlobs === true || includeBlobs === 'true';
+    if (typeof board === 'string' && board.trim()) {
+      const target = readTargetBoard(board, full);
+      return (full
+        ? serializeCanvasLayout(target.layout)
+        : serializeCanvasLayoutWithBlobSummaries(target.layout)) as unknown as Record<string, unknown>;
+    }
     return (full
       ? serializeCanvasLayout(canvasState.getLayout())
       : serializeCanvasLayoutWithBlobSummaries(

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

@@ -23,13 +23,22 @@ import { setCanvasContextPins, syncCanvasRuntimeBackends } from '../../canvas-op
 import { buildCanvasSummary } from '../../canvas-serialization.js';
 import { mutationHistory } from '../../mutation-history.js';
 import { buildSpatialContext, searchNodes } from '../../spatial-analysis.js';
-import { defineOperation, type Operation, type OperationMcpToolHost } from '../types.js';
-import { isRecord } from './nodes.js';
+import {
+  compileContextBrief,
+  type ContextBriefLibraryBoard,
+  type ContextBriefSourceEntry,
+} from '../../context-brief.js';
+import { summarizeNodeForAgentContext } from '../../agent-context.js';
+import { defineOperation, OperationError, type Operation, type OperationMcpToolHost } from '../types.js';
+import { buildSummaryFromLayout, isRecord } from './nodes.js';
+import { readTargetBoard } from './boards.js';
 
 // ── pin.set ───────────────────────────────────────────────────
 
 /** Legacy server.ts handleContextPinsUpdate capped the requested list at 20. */
 const MAX_PINS = 20;
+export const DEFAULT_CONTEXT_BRIEF_BUDGET = 16_000;
+export const MAX_CONTEXT_BRIEF_BUDGET = 100_000;
 
 const pinShape = {
   nodeIds: z.unknown().optional().describe('Array of node IDs to pin'),
@@ -92,6 +101,7 @@ const pinOperation = defineOperation<z.infer<typeof pinSchema>, Record<string, u
 
 const searchShape = {
   q: z.unknown().optional().describe('Search query — matches against node titles, content, and file paths'),
+  scope: z.unknown().optional().describe('active (default) or library (all boards)'),
   limit: z.unknown().optional().describe('Max results to return (default: all over HTTP, 10 via the MCP tool).'),
 };
 
@@ -113,12 +123,14 @@ const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<str
     extraShape: {
       query: z.string().describe('Search query — matches against node titles, content, and file paths'),
       limit: z.number().optional().describe('Max results to return (default: 10)'),
+      scope: z.enum(['active', 'library']).optional().describe('Search the active board or the full board library'),
     },
     // Map the MCP-facing `query` arg onto the wire's `q`. The handler caps by
     // `limit` on every transport; the MCP tool additionally defaults it to 10.
     buildInput: (input) => ({
       q: typeof input.query === 'string' ? input.query : '',
       ...(typeof input.limit === 'number' ? { limit: input.limit } : {}),
+      ...(input.scope === 'library' ? { scope: 'library' } : {}),
     }),
     formatResult: (result, input) => {
       const body = isRecord(result) ? result : {};
@@ -154,7 +166,40 @@ const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<str
         : typeof rawLimit === 'string' && rawLimit.trim() !== ''
           ? Number(rawLimit)
           : Number.NaN;
-    const results = searchNodes(canvasState.getLayout().nodes, q);
+    const library = input.scope === 'library';
+    const results = library
+      ? canvasState.listBoards().flatMap((board) => {
+          const read = canvasState.readBoard(board.id, true);
+          if (!read) return [];
+          const cards = searchNodes(read.layout.nodes, q).map((result) => ({
+            ...result,
+            boardId: board.id,
+            boardTitle: board.name,
+            cardId: result.id,
+          }));
+          const metadata = `${board.name} ${board.category ?? ''}`.toLocaleLowerCase();
+          const readme = read.layout.nodes.find((node) => node.id === board.readmeNodeId);
+          const readmeText = typeof readme?.data.content === 'string' ? readme.data.content : '';
+          if (`${metadata} ${readmeText.toLocaleLowerCase()}`.includes(q.toLocaleLowerCase())) {
+            cards.unshift({
+              id: board.id,
+              type: 'board',
+              title: board.name,
+              snippet: readmeText.slice(0, 160) || board.category || board.name,
+              score: metadata.includes(q.toLocaleLowerCase()) ? 4 : 2,
+              boardId: board.id,
+              boardTitle: board.name,
+              cardId: readme?.id ?? board.id,
+            });
+          }
+          return cards;
+        })
+      : searchNodes(canvasState.getLayout().nodes, q).map((result) => ({
+          ...result,
+          boardId: canvasState.activeBoardId,
+          cardId: result.id,
+        }));
+    results.sort((a, b) => b.score - a.score);
     return {
       results: Number.isFinite(limit) && limit > 0 ? results.slice(0, Math.floor(limit)) : results,
       query: q,
@@ -162,6 +207,152 @@ const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<str
   },
 });
 
+// ── context.get ───────────────────────────────────────────────
+
+const contextShape = {
+  consumer: z.unknown().optional().describe('Stable consumer id used for the durable board-scoped cursor'),
+  since: z.unknown().optional().describe('Explicit content revision; bypasses the durable consumer cursor'),
+  budget: z.unknown().optional().describe('Maximum response size in UTF-16 code units'),
+};
+const contextSchema = z.looseObject(contextShape);
+
+const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<string, unknown>>({
+  name: 'context.get',
+  mutates: false,
+  input: contextSchema,
+  inputShape: contextShape,
+  http: { method: 'GET', path: '/api/canvas/context' },
+  handler: (input) => {
+    const active = canvasState.getActiveBoard();
+    if (!active) throw new OperationError('Open a board before requesting its context.', 409);
+    const consumer =
+      typeof input.consumer === 'string' && input.consumer.trim() ? input.consumer.trim().slice(0, 200) : null;
+    const explicitSince = input.since !== undefined;
+    const sinceValue = explicitSince
+      ? Number(input.since)
+      : consumer
+        ? canvasState.getContextBriefCursor(active.id, consumer)
+        : null;
+    const budgetValue = input.budget === undefined ? DEFAULT_CONTEXT_BRIEF_BUDGET : Number(input.budget);
+    const budget = Number.isFinite(budgetValue)
+      ? Math.min(MAX_CONTEXT_BRIEF_BUDGET, Math.max(0, Math.floor(budgetValue)))
+      : DEFAULT_CONTEXT_BRIEF_BUDGET;
+
+    // Capture the active target and revision synchronously. Library boards are
+    // read from SQLite and are never opened or made writable by this operation.
+    const layout = canvasState.getLayout();
+    const revision = canvasState.getContentRevision();
+    const pinnedNodeIds = [...canvasState.contextPinnedNodeIds];
+    const linkedIds = new Map<string, string[]>();
+    for (const node of layout.nodes) {
+      if (node.type !== 'board' || typeof node.data.boardId !== 'string') continue;
+      const ids = linkedIds.get(node.data.boardId) ?? [];
+      ids.push(node.id);
+      linkedIds.set(node.data.boardId, ids);
+    }
+    const libraryBoards: ContextBriefLibraryBoard[] = [];
+    for (const board of canvasState.listBoards()) {
+      if (board.id === active.id) continue;
+      if (!linkedIds.has(board.id) && (!active.category || active.category !== board.category)) continue;
+      const read = canvasState.readBoard(board.id, true);
+      if (!read) continue;
+      const readme = read.layout.nodes.find((node) => node.id === board.readmeNodeId);
+      const pins = new Set(read.state.contextPins);
+      libraryBoards.push({
+        boardId: board.id,
+        name: board.name,
+        category: board.category,
+        ...(readme
+          ? {
+              readme: {
+                nodeId: readme.id,
+                title: typeof readme.data.title === 'string' ? readme.data.title : readme.id,
+                summary: summarizeNodeForAgentContext(readme, { defaultTextLength: 1_000, webpageTextLength: 1_000 }),
+              },
+            }
+          : {}),
+        pinnedTitles: read.layout.nodes
+          .filter((node) => pins.has(node.id))
+          .map((node) => ({
+            nodeId: node.id,
+            title: typeof node.data.title === 'string' ? node.data.title : node.id,
+          })),
+        linkIds: linkedIds.get(board.id) ?? [],
+      });
+    }
+    const entries: ContextBriefSourceEntry[] = layout.nodes
+      .filter((node) => node.createdBy?.actor === 'human')
+      .map((node) => ({
+        sourceBoardId: active.id,
+        nodeId: node.id,
+        reason: 'human' as const,
+        title: typeof node.data.title === 'string' ? node.data.title : node.id,
+        text: summarizeNodeForAgentContext(node, { defaultTextLength: budget, webpageTextLength: budget }),
+      }));
+    entries.push(
+      ...canvasState
+        .getApprovalGates()
+        .filter((item) => item.status === 'pending')
+        .map((item) => ({
+          sourceBoardId: active.id,
+          nodeId: `approval:${item.id}`,
+          reason: 'ask' as const,
+          title: item.title,
+          text: item.detail || item.action || 'Approval requested.',
+        })),
+      ...canvasState
+        .getModeRequests()
+        .filter((item) => item.status === 'pending')
+        .map((item) => ({
+          sourceBoardId: active.id,
+          nodeId: `mode:${item.id}`,
+          reason: 'ask' as const,
+          title: `Mode request: ${item.mode}`,
+          text: item.reason || 'Mode change requested.',
+        })),
+      ...canvasState
+        .getElicitations()
+        .filter((item) => item.status === 'pending')
+        .map((item) => ({
+          sourceBoardId: active.id,
+          nodeId: `elicitation:${item.id}`,
+          reason: 'ask' as const,
+          title: 'Open question',
+          text: item.prompt,
+        })),
+    );
+    entries.push(
+      ...canvasState.getPendingSteering({ consumer: consumer ?? undefined, limit: 50 }).map((item) => ({
+        sourceBoardId: active.id,
+        nodeId: `steering:${item.id}`,
+        reason: 'steer' as const,
+        title: 'Human steering',
+        text: item.message,
+      })),
+    );
+    const result = compileContextBrief({
+      activeBoard: { boardId: active.id, name: active.name, category: active.category },
+      nodes: layout.nodes,
+      pinnedNodeIds,
+      contentRevision: revision.revision,
+      retentionFloor: revision.retentionFloor,
+      tombstones: canvasState.readContentDelta(sinceValue ?? 0).deleted,
+      since: explicitSince ? (Number.isSafeInteger(sinceValue) ? sinceValue : Number.NaN) : sinceValue,
+      libraryBoards,
+      entries,
+      budget,
+    });
+    if (consumer && !explicitSince && result.document && result.nextCursor !== null && !result.invalidCursor) {
+      canvasState.advanceContextBriefCursor(active.id, consumer, result.nextCursor);
+    }
+    return (result.document ?? {
+      version: 1,
+      budgetUnit: 'utf16-code-units',
+      error: 'Budget is too small for the context envelope.',
+    }) as unknown as Record<string, unknown>;
+  },
+});
+
 // ── history.get (HTTP/CLI only — canvas://history stays a resource) ──
 
 const historyGetShape = {};
@@ -258,7 +449,7 @@ const redoOperation = defineOperation<z.infer<typeof undoRedoSchema>, Record<str
 
 // ── spatial.get (HTTP only — canvas://spatial-context stays a resource) ──
 
-const spatialGetShape = {};
+const spatialGetShape = { board: z.unknown().optional().describe('Board id to read without opening it.') };
 
 const spatialGetSchema = z.looseObject(spatialGetShape);
 
@@ -271,12 +462,13 @@ const spatialGetOperation = defineOperation<z.infer<typeof spatialGetSchema>, Re
     method: 'GET',
     path: '/api/canvas/spatial-context',
   },
-  handler: () => {
-    const layout = canvasState.getLayout();
+  handler: ({ board }) => {
+    const target = readTargetBoard(board);
+    const layout = target.layout;
     return buildSpatialContext(
       layout.nodes,
       layout.edges,
-      canvasState.contextPinnedNodeIds,
+      target.pinnedNodeIds,
       layout.annotations,
     ) as unknown as Record<string, unknown>;
   },
@@ -284,7 +476,7 @@ const spatialGetOperation = defineOperation<z.infer<typeof spatialGetSchema>, Re
 
 // ── summary.get (HTTP only — canvas://summary stays a resource) ──
 
-const summaryGetShape = {};
+const summaryGetShape = { board: z.unknown().optional().describe('Board id to read without opening it.') };
 
 const summaryGetSchema = z.looseObject(summaryGetShape);
 
@@ -297,12 +489,17 @@ const summaryGetOperation = defineOperation<z.infer<typeof summaryGetSchema>, Re
     method: 'GET',
     path: '/api/canvas/summary',
   },
-  handler: () => buildCanvasSummary() as unknown as Record<string, unknown>,
+  handler: ({ board }) => {
+    if (typeof board !== 'string' || !board.trim()) return buildCanvasSummary() as unknown as Record<string, unknown>;
+    const target = readTargetBoard(board);
+    return buildSummaryFromLayout(target.layout, [...target.pinnedNodeIds]);
+  },
 });
 
 export const queryOperations: Operation[] = [
   pinOperation,
   searchOperation,
+  contextOperation,
   historyGetOperation,
   undoOperation,
   redoOperation,

package/src/server/operations/registry.ts

@@ -7,12 +7,16 @@
  * Handlers never emit `canvas-layout-update` themselves for the final state —
  * `mutates: true` is the single source; extra events go through `ctx.emit`.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { canvasState } from '../canvas-state.js';
 import { intentRegistry } from '../intent-registry.js';
 import { humanPresence } from '../human-presence.js';
-import { setMutationActor } from '../mutation-history.js';
+import { withCurrentActor } from '../attribution.js';
 import { agentPresence, describeWrite } from '../agent-presence.js';
 import { checkScopeFence, checkScopeOwnership } from '../scope-fence.js';
+import { CONTEXT_READ_OPS, contextReadFromPayload } from '../context-reads.js';
+import { openBoardForWrite } from '../canvas-operations.js';
+import { boardsPayload } from './ops/boards.js';
 import type { PmxAxIntent, PmxAxIntentKind } from '../../shared/ax-intent.js';
 import { OperationError, type Operation, type OperationContext } from './types.js';
 
@@ -43,18 +47,12 @@ export function setOperationEventEmitter(emitter: OperationEventEmitter | null):
   operationEventEmitter = emitter;
 }
 
-// Depth-counted EMIT suppression (same pattern as, but deliberately distinct
-// state from, canvasState's recording suppression: batch suppresses SSE emits
-// while sub-ops still record history; undo/redo suppresses recording while
-// still emitting SSE — merging the two counters would break one or the other).
-// While > 0, emitOperationEvent is a no-op so a meta-op (canvas.batch) can run
-// many sub-ops without producing per-entry SSE frames, then emit ONE final
-// layout frame itself. Both the `mutates` auto-emit and `ctx.emit` route through
-// emitOperationEvent, so this covers both. Re-entrant-safe via the depth counter.
-let suppressEmitDepth = 0;
+// Batch suppression belongs to its async call chain, never concurrent human
+// operations (especially board switches while a batch waits on the network).
+const suppressedEmits = new AsyncLocalStorage<boolean>();
 
 function emitOperationEvent(event: string, payload: Record<string, unknown> = {}): void {
-  if (suppressEmitDepth > 0) return;
+  if (isEmitSuppressed()) return;
   operationEventEmitter?.(event, payload);
 }
 
@@ -63,17 +61,12 @@ function emitOperationEvent(event: string, payload: Record<string, unknown> = {}
  * mcpapp.open, whose canvas node is created as a side-effect of `ext-app-open` —
  * use this to reject loudly instead of silently no-op'ing in a suppressed run. */
 export function isEmitSuppressed(): boolean {
-  return suppressEmitDepth > 0;
+  return suppressedEmits.getStore() === true;
 }
 
-/** Run `fn` with all operation SSE emits suppressed; restores depth on finally. */
+/** Suppress this call chain's per-entry frames; the batch emits its final frame afterward. */
 export async function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T> {
-  suppressEmitDepth++;
-  try {
-    return await fn();
-  } finally {
-    suppressEmitDepth--;
-  }
+  return suppressedEmits.run(true, fn);
 }
 
 const operationContext: OperationContext = { emit: emitOperationEvent };
@@ -208,6 +201,14 @@ export interface ExecuteOperationMeta {
    * to agents only, and batch inner writes are always agent-originated.
    */
   fromWorkbench?: boolean;
+  /** Authorship only: true when the per-boot workbench token matched. */
+  humanAuthor?: boolean;
+  /**
+   * An MCP server attached to this daemon, or a host adapter, fetching on an
+   * agent's behalf. It records the read the agent actually made itself
+   * (POST /api/canvas/ax/context-reads), so this fetch is not recorded.
+   */
+  proxiedRead?: boolean;
 }
 
 /**
@@ -296,6 +297,14 @@ const PRESENCE_EXEMPT_OPS = new Set([
   'ax.activity.ingest',
   'human.presence.set',
   'human.presence.get',
+  // Recording a context read is instrumentation of a read, not a write.
+  'ax.reads.record',
+  // Backup and restore are maintenance of the library file, not edits.
+  'backup.run',
+  'backup.schedule',
+  'backup.restore',
+  // Writing an export file shares nothing by itself and edits nothing.
+  'export.run',
   // Camera and attention controls are observation/navigation, not edits.
   // They must not create a writer, bump opCount, or refresh an existing one.
   'viewport.set',
@@ -353,22 +362,105 @@ export async function executeOperation(
   rawInput: unknown,
   meta: ExecuteOperationMeta = {},
 ): Promise<unknown> {
-  // History entries recorded while this op runs carry who made them (item
-  // 10: the session panel offers undo on the agent's latest edit).
-  const historyWriter =
-    typeof asRecord(rawInput).agentId === 'string' && String(asRecord(rawInput).agentId).trim()
-      ? String(asRecord(rawInput).agentId).trim()
-      : (meta.source ?? 'api');
-  setMutationActor(meta.fromWorkbench ? 'human' : 'agent', historyWriter);
-  try {
-    return await executeOperationInner(name, rawInput, meta);
-  } finally {
-    setMutationActor(null);
-  }
+  // Attribution follows this call chain across awaits and nested operations.
+  const inputAgentId = asRecord(rawInput).agentId;
+  return withCurrentActor(
+    {
+      actor: meta.humanAuthor ? 'human' : 'agent',
+      source: meta.humanAuthor ? 'browser' : (meta.source ?? 'api'),
+      ...(typeof inputAgentId === 'string' && inputAgentId.trim() ? { agentId: inputAgentId.trim() } : {}),
+    },
+    async () => {
+      const recordRead = CONTEXT_READ_OPS.has(name) && !meta.fromWorkbench && !meta.proxiedRead;
+      const input = asRecord(rawInput);
+      const requestedBoard =
+        recordRead && 'board' in getOperation(name).inputShape && isString(input.board) && input.board.trim()
+          ? input.board.trim()
+          : null;
+      const readBoardId = requestedBoard ?? canvasState.activeBoardId;
+      const readPins = recordRead
+        ? requestedBoard
+          ? (canvasState.readBoard(requestedBoard, false)?.state.contextPins ?? [])
+          : [...canvasState.contextPinnedNodeIds]
+        : [];
+      const result = await executeOperationInner(name, rawInput, meta);
+      if (recordRead) {
+        canvasState.recordContextRead(
+          contextReadFromPayload(
+            {
+              channel: 'operation',
+              resource: name,
+              source: meta.source ?? 'api',
+              consumer: isString(input.consumer) && input.consumer.trim() ? input.consumer.trim() : null,
+              agentId: isString(input.agentId) && input.agentId.trim() ? input.agentId.trim() : null,
+              pinnedNodeIds: readPins,
+            },
+            result,
+          ),
+          readBoardId,
+        );
+      }
+      return result;
+    },
+  );
+}
+
+/** Opening, switching and deleting boards is the human's; an agent asks for another board. */
+const HUMAN_ONLY_OPS = new Set(['board.open', 'board.delete', 'import.request', 'import.cancel', 'import.commit']);
+const TRUSTED_HUMAN_ONLY_OPS = new Set([
+  'board.open',
+  'board.delete',
+  'import.request',
+  'import.cancel',
+  'import.commit',
+]);
+
+/**
+ * Writes that need a board beyond the layout mutations: canvas-bound AX items,
+ * pins, snapshots and app nodes. `canvas.clear` on Home clears nothing, so it
+ * never opens a board it would then wipe.
+ */
+const BOARD_WRITE_OPS = new Set(['pin.set', 'snapshot.save', 'mcpapp.open', 'diagram.open', 'webartifact.build']);
+
+const CANVAS_BOUND_AX_WRITE_PREFIXES = [
+  'ax.work.',
+  'ax.review.',
+  'ax.approval.',
+  'ax.elicitation.',
+  'ax.mode.',
+] as const;
+
+function isCanvasBoundAxWrite(name: string): boolean {
+  if (name === 'ax.focus.set' || name === 'ax.policy.set') return true;
+  return CANVAS_BOUND_AX_WRITE_PREFIXES.some((prefix) => name.startsWith(prefix)) && !name.endsWith('.await');
+}
+
+function needsOpenBoard(op: Operation): boolean {
+  if (op.name === 'canvas.clear' || PRESENCE_EXEMPT_OPS.has(op.name)) return false;
+  return op.mutates || BOARD_WRITE_OPS.has(op.name) || isCanvasBoundAxWrite(op.name);
 }
 
 async function executeOperationInner(name: string, rawInput: unknown, meta: ExecuteOperationMeta): Promise<unknown> {
   const op = getOperation(name);
+  if (HUMAN_ONLY_OPS.has(name) && !meta.fromWorkbench) {
+    throw new OperationError(
+      'Only the human opens or deletes boards. Ask them in the chat to open the board you need.',
+      403,
+    );
+  }
+  if (TRUSTED_HUMAN_ONLY_OPS.has(name) && !meta.humanAuthor) {
+    throw new OperationError('This action requires trusted human authority.', 403);
+  }
+  // File drops carry their captured board through the HTTP round trip. Check
+  // before opening a recent board from Home, not just before reading the file.
+  const capturedBoard = asRecord(rawInput).boardId;
+  if (name === 'node.add' && typeof capturedBoard === 'string' && capturedBoard !== canvasState.activeBoardId) {
+    throw new OperationError('The board changed while the file was loading.', 409);
+  }
+  if (!canvasState.activeBoardId && needsOpenBoard(op)) {
+    openBoardForWrite();
+    if (canvasState.activeBoardId) emitOperationEvent('boards-changed', boardsPayload());
+  }
   // Scope fence (design item 4): an attached agent's writes must stay inside
   // the fence the human granted. Reads and the human's own writes pass, and
   // the fence itself is the human's to set — an agent cannot clear or widen it.

package/src/server/operations/types.ts

@@ -60,7 +60,7 @@ export interface OperationHttpRoute {
 
 /** Host capabilities available to MCP result formatters. */
 export interface OperationMcpToolHost {
-  getPinnedNodeIds(): Promise<string[]>;
+  getPinnedNodeIds(board?: string): Promise<string[]>;
   /**
    * Invoke another registered operation over the host's transport (local or
    * HTTP) — structural subset of OperationInvoker to avoid an import cycle.