pmx-canvas 0.10.0 → 0.12.0

package/src/server/mutation-history.ts

@@ -14,6 +14,7 @@
 
 import type { CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { currentActor as getActor, setCurrentActor } from './attribution.js';
+import { createBoardLocal } from './board-local.js';
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -88,11 +89,25 @@ export interface SnapshotDiffResult {
   removedEdges: { id: string; from: string; to: string; toBoardId?: string; type: string }[];
 }
 
-function comparableNodeData(data: Record<string, unknown>): Record<string, unknown> {
+function comparableNodeData(data: Record<string, unknown>): string {
   const comparable = { ...data };
   delete comparable.title;
   delete comparable.content;
-  return comparable;
+  // Match content-revision semantics: fetching the same page again is not a
+  // content change. Keep authored timestamps elsewhere, including nested data.
+  delete comparable.fetchedAt;
+  if (comparable.provenance && typeof comparable.provenance === 'object') {
+    const provenance = { ...(comparable.provenance as Record<string, unknown>) };
+    delete provenance.syncedAt;
+    comparable.provenance = provenance;
+  }
+  // Canonical JSON preserves array order and the persisted JSON semantics for
+  // undefined properties, while ignoring object-key insertion order at any depth.
+  return JSON.stringify(comparable, (_key, value: unknown) =>
+    value && typeof value === 'object' && !Array.isArray(value)
+      ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+      : value,
+  );
 }
 
 // ── Ring Buffer ──────────────────────────────────────────────────────
@@ -100,11 +115,25 @@ function comparableNodeData(data: Record<string, unknown>): Record<string, unkno
 const MAX_ENTRIES = 200;
 
 class MutationHistory {
-  private entries: MutationEntry[] = [];
-  /** Index of the last applied mutation. -1 means nothing applied / all undone. */
-  private cursor = -1;
-  /** When true, mutations triggered by undo/redo are not recorded. */
-  private _replaying = false;
+  private readonly board = createBoardLocal(() => ({ entries: [] as MutationEntry[], cursor: -1, replaying: false }));
+  private get entries() {
+    return this.board.current.entries;
+  }
+  private set entries(value: MutationEntry[]) {
+    this.board.current.entries = value;
+  }
+  private get cursor() {
+    return this.board.current.cursor;
+  }
+  private set cursor(value: number) {
+    this.board.current.cursor = value;
+  }
+  private get _replaying() {
+    return this.board.current.replaying;
+  }
+  private set _replaying(value: boolean) {
+    this.board.current.replaying = value;
+  }
 
   get isReplaying(): boolean {
     return this._replaying;
@@ -315,7 +344,7 @@ export function diffLayouts(
       changes.push(`content changed (${lenDiff >= 0 ? '+' : ''}${lenDiff} chars)`);
     }
 
-    if (JSON.stringify(comparableNodeData(snapNode.data)) !== JSON.stringify(comparableNodeData(curNode.data))) {
+    if (comparableNodeData(snapNode.data) !== comparableNodeData(curNode.data)) {
       changes.push('data changed');
     }
 

package/src/server/operations/composites.ts

@@ -152,15 +152,17 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_board',
     description:
+      '"move-selection" previews or atomically relocates selected cards and group descendants to a new board, preserves identity and leaves a portal. Supply sourceBoardId, nodeIds, name, expectedRevision and requestId; preview:true reports blockers and the Undo/snapshot boundary. Retry identical input with the same requestId. It never opens the destination. ' +
       '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',
+      'list | get | create | create-from | move-selection | 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',
       create: 'board.create',
       'create-from': 'board.create-from',
+      'move-selection': 'board.move-selection',
       open: 'board.open',
       update: 'board.update',
       'knowledge-list': 'knowledge.list',
@@ -239,9 +241,9 @@ 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; "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.',
+      '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; "add-annotation" draws freehand points or text in world coordinates; "remove-annotation" erases a whole mark 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',
+      'arrange | focus | fit | clear | add-annotation | remove-annotation | get-tour | set-tour | tour-go | tour-exit | move',
     actions: {
       'get-tour': 'tour.get',
       'set-tour': 'tour.set',
@@ -252,6 +254,7 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
       focus: 'node.focus',
       fit: 'view.fit',
       clear: 'canvas.clear',
+      'add-annotation': 'annotation.add',
       'remove-annotation': 'annotation.remove',
     },
   },

package/src/server/operations/mcp-contracts.ts

@@ -11,6 +11,7 @@ import { tourSchema, tourStopSchema } from '../../shared/tour.js';
 const id = z.string().min(1);
 const count = z.number().int().nonnegative();
 const ok = z.looseObject({ ok: z.boolean() });
+const tourSuperseded = z.object({ ok: z.literal(true), superseded: z.literal(true) });
 const identified = z.looseObject({ id });
 const message = z.strictObject({ message: z.string() });
 const node = z.looseObject({
@@ -85,6 +86,20 @@ const payloads: Record<string, ZodType> = {
     board,
     z.looseObject({ ok: z.boolean(), sourceBoardId: id, cards: z.array(node), edges: z.array(edge) }),
   ]),
+  'board.move-selection': z.union([
+    z.looseObject({
+      ok: z.boolean(),
+      preview: z.looseObject({ sourceBoardId: id, nodeIds: z.array(id), blockers: z.array(z.string()) }),
+    }),
+    z.looseObject({
+      ok: z.boolean(),
+      sourceBoardId: id,
+      destinationBoardId: id,
+      portalId: id,
+      nodeIds: z.array(id),
+      replayed: z.boolean(),
+    }),
+  ]),
   'board.open': boards,
   'board.update': boards,
   'board.pin': boards,
@@ -123,13 +138,28 @@ const payloads: Record<string, ZodType> = {
   'canvas.redo': history,
   'tour.get': z.looseObject({ tour: tourSchema, derived: z.boolean(), position: count.nullable() }),
   'tour.set': ok,
-  'tour.go': z.looseObject({ ok: z.boolean(), index: count, total: count, stop: tourStopSchema }),
-  'tour.exit': ok,
+  'tour.go': z.union([
+    z.looseObject({
+      ok: z.boolean(),
+      catalogEpoch: z.string(),
+      boardGeneration: count,
+      sequence: count,
+      index: count,
+      total: count,
+      stop: tourStopSchema,
+    }),
+    tourSuperseded,
+  ]),
+  'tour.exit': z.union([
+    z.looseObject({ ok: z.boolean(), catalogEpoch: z.string(), boardGeneration: count, sequence: count }),
+    tourSuperseded,
+  ]),
   'camera.move': z.looseObject({ ok: z.boolean(), stop: tourStopSchema, viewport }),
   arrange: z.looseObject({ ok: z.boolean(), layout: z.enum(['grid', 'column', 'flow']) }),
   'node.focus': z.looseObject({ ok: z.boolean(), focused: id, panned: z.boolean() }),
   'view.fit': z.looseObject({ ok: z.boolean(), viewport }),
   'canvas.clear': z.looseObject({ ok: z.boolean(), cleared: z.literal(true) }),
+  'annotation.add': entity('annotation'),
   'annotation.remove': ok,
   'context.get': z.looseObject({ version: z.literal(1), budgetUnit: z.literal('utf16-code-units') }),
   'memory-graph.get': z.looseObject({

package/src/server/operations/mcp.ts

@@ -36,6 +36,17 @@ export interface OperationToolHost extends OperationMcpToolHost {
   recordContextRead(read: ContextReadInput): Promise<void>;
 }
 
+const routingShape = {
+  targetBoardId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Execute on this board without changing the shared workbench view. Nested operations retain this target.',
+    ),
+  agentId: z.string().min(1).optional().describe('Stable agent/thread identity for attribution and scope fences.'),
+};
+
 function executionOptions(extra: RequestHandlerExtra<ServerRequest, ServerNotification>): OperationExecutionOptions {
   const progressToken = extra._meta?.progressToken;
   return {
@@ -58,9 +69,23 @@ async function invokeMcpOperation(
   options: OperationExecutionOptions,
 ) {
   options.signal?.throwIfAborted();
-  const board = typeof opInput.board === 'string' && opInput.board.trim() ? opInput.board.trim() : undefined;
-  const readTarget = CONTEXT_READ_OPS.has(op.name) ? await host.prepareContextRead(board) : null;
-  if (readTarget?.boardId && 'board' in op.inputShape) {
+  // buildInput may project operation-specific fields; routing belongs to the
+  // invocation and must also cover formatter follow-up reads and accounting.
+  const routing = {
+    ...(formatInput.targetBoardId !== undefined ? { targetBoardId: formatInput.targetBoardId } : {}),
+    ...(formatInput.agentId !== undefined ? { agentId: formatInput.agentId } : {}),
+  };
+  opInput = { ...opInput, ...routing };
+  if (typeof routing.agentId === 'string') consumer = routing.agentId;
+  const board =
+    typeof routing.targetBoardId === 'string'
+      ? routing.targetBoardId
+      : typeof opInput.board === 'string' && opInput.board.trim()
+        ? opInput.board.trim()
+        : undefined;
+  const preparesContext = op.name === 'context.get' && opInput.contextDelivery === false;
+  const readTarget = CONTEXT_READ_OPS.has(op.name) && !preparesContext ? await host.prepareContextRead(board) : null;
+  if (readTarget?.boardId && 'board' in op.inputShape && opInput.board === undefined) {
     opInput = { ...opInput, board: readTarget.boardId };
     formatInput = { ...formatInput, board: readTarget.boardId };
   }
@@ -70,8 +95,10 @@ async function invokeMcpOperation(
   // Preserve the host receiver, and bind options to formatter follow-up reads
   // (history flags, snapshot summary, streaming node metadata).
   const formatterHost: OperationMcpToolHost = {
-    getPinnedNodeIds: (target) => host.getPinnedNodeIds(target),
-    invoker: () => ({ invoke: (name, input, followUp) => invoker.invoke(name, input, { ...options, ...followUp }) }),
+    getPinnedNodeIds: (target) => host.getPinnedNodeIds(target ?? board),
+    invoker: () => ({
+      invoke: (name, input, followUp) => invoker.invoke(name, { ...input, ...routing }, { ...options, ...followUp }),
+    }),
   };
   const formatted = structuredOperationResult(
     op.name,
@@ -151,7 +178,7 @@ export function registerOperationTools(server: McpServer, getHost: () => Promise
         // successful over MCP while the same HTTP call 400'd (0.5.1 Amp
         // finding A). Loose parsing forwards unknown keys to the op layer,
         // the single authority on dead-field rejection, HTTP and MCP alike.
-        inputSchema: z.looseObject({ ...op.inputShape, ...(tool.extraShape ?? {}) }),
+        inputSchema: z.looseObject({ ...op.inputShape, ...(tool.extraShape ?? {}), ...routingShape }),
         outputSchema: operationOutputSchema([op.name]),
         annotations: operationToolAnnotations(tool.toolName),
       },
@@ -376,8 +403,8 @@ export function registerOperationHelpTool(server: McpServer): void {
       const composite = compositeToolDefinitions.find((def) => compositeMemberOps(def).includes(name));
       const publicName = (field: string) =>
         Object.entries(composite?.fieldRemap ?? {}).find(([, original]) => original === field)?.[0] ?? field;
-      const shape = Object.fromEntries(
-        Object.entries({ ...op.inputShape, ...op.mcp?.extraShape }).map(([field, schema]) => [
+      const shape: Record<string, ZodTypeAny> = Object.fromEntries(
+        Object.entries({ ...op.inputShape, ...op.mcp?.extraShape, ...routingShape }).map(([field, schema]) => [
           publicName(field),
           schema,
         ]),
@@ -444,7 +471,7 @@ export function registerCompositeTools(
       def.toolName,
       {
         description: def.description,
-        inputSchema: z.looseObject(buildCompositeShape(def)),
+        inputSchema: z.looseObject({ ...buildCompositeShape(def), ...routingShape }),
         outputSchema: operationOutputSchema(compositeMemberOps(def)),
         annotations: operationToolAnnotations(def.toolName),
       },

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

@@ -13,6 +13,7 @@
  *
  * This module must never import server.ts or index.ts.
  */
+import { isDeepStrictEqual } from 'node:util';
 import { z } from 'zod';
 import { canvasState, type CanvasAnnotation } from '../../canvas-state.js';
 import { summarizeCanvasAnnotation } from '../../canvas-serialization.js';
@@ -35,7 +36,7 @@ const annotationRemoveOperation = defineOperation<z.infer<typeof annotationRemov
   },
   mcp: {
     toolName: 'canvas_remove_annotation',
-    description: 'Remove a human-drawn canvas annotation by ID.',
+    description: 'Erase a whole canvas mark by ID, whether drawn by a human or agent.',
     extraShape: {
       id: z.string().describe('Annotation ID to remove'),
     },
@@ -119,6 +120,19 @@ const annotationAddOperation = defineOperation<z.infer<typeof annotationAddSchem
     method: 'POST',
     path: '/api/canvas/annotation',
   },
+  mcp: {
+    toolName: 'canvas_add_annotation',
+    description: 'Draw canvas ink or write a text note in world coordinates. No session required.',
+    extraShape: {
+      type: z.enum(['freehand', 'text']).optional(),
+      points: z.array(z.object({ x: z.number(), y: z.number() })).min(1),
+      width: z.number().optional(),
+      color: z.string().optional(),
+      label: z.string().optional(),
+      text: z.string().optional(),
+      id: z.string().optional(),
+    },
+  },
   handler: (input) => {
     const body: Record<string, unknown> = input;
     const type = body.type === 'text' ? 'text' : 'freehand';
@@ -164,6 +178,13 @@ const annotationAddOperation = defineOperation<z.infer<typeof annotationAddSchem
       createdAt: new Date().toISOString(),
     };
 
+    const existing = canvasState.getAnnotations().find((entry) => entry.id === id);
+    if (existing) {
+      if (!isDeepStrictEqual(existing, { ...annotation, createdAt: existing.createdAt })) {
+        throw new OperationError(`Annotation "${id}" already exists with different content.`, 409);
+      }
+      return { ok: true, annotation: summarizeCanvasAnnotation(existing) };
+    }
     canvasState.addAnnotation(annotation);
     return { ok: true, annotation: summarizeCanvasAnnotation(annotation) };
   },

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

@@ -69,6 +69,7 @@ function clampTimeoutMs(value: unknown): number {
 /** Accept the operation's timeoutMs as well as the direct HTTP waitMs spelling. */
 function readWaitMsInput(_req: Request, params: Record<string, string>, url: URL): Record<string, unknown> {
   return {
+    ...Object.fromEntries(url.searchParams),
     ...params,
     timeoutMs: clampTimeoutMs(url.searchParams.get('timeoutMs') ?? url.searchParams.get('waitMs') ?? ''),
   };

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

@@ -289,7 +289,17 @@ const axTimelineGetOperation = defineOperation<z.infer<typeof axTimelineGetSchem
 const axDeliveryPendingShape = {
   consumer: z.unknown().optional().describe('Consumer/source label to exclude from results (e.g. copilot, mcp).'),
   limit: z.unknown().optional().describe('Max steering messages to return.'),
+  offset: z.coerce
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe('Skip this many matching pending messages. Restart at zero after an empty page.'),
   order: z.unknown().optional().describe('"oldest" (FIFO, default) or "newest" first.'),
+  addressedOnly: z
+    .boolean()
+    .optional()
+    .describe('Only messages addressed to consumer, excluding broadcasts before applying the limit.'),
   timeoutMs: z
     .unknown()
     .optional()
@@ -310,10 +320,13 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
     // consumer arrives or the timeout elapses. Custom readInput replaces the
     // default query merge, so re-read the standard params here too.
     readInput: (_req, params, url) => {
-      const raw = Number(url.searchParams.get('waitMs') ?? '');
+      const raw = Number(url.searchParams.get('timeoutMs') ?? url.searchParams.get('waitMs') ?? '');
       return {
         ...Object.fromEntries(url.searchParams),
         ...params,
+        ...(url.searchParams.has('addressedOnly')
+          ? { addressedOnly: url.searchParams.get('addressedOnly') === 'true' }
+          : {}),
         timeoutMs: Number.isFinite(raw) && raw > 0 ? raw : 0,
       };
     },
@@ -353,7 +366,13 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
     // can't bury the human's current action behind stale undelivered rows. Both
     // queries apply the same loop-safe consumer filter before the limit.
     const newest = input.order === 'newest';
-    const scope = { ...(consumer ? { consumer } : {}), ...(limit ? { limit } : {}) };
+    if (input.addressedOnly && !consumer) throw new OperationError('addressedOnly requires consumer.', 400);
+    const scope = {
+      ...(consumer ? { consumer } : {}),
+      ...(limit ? { limit } : {}),
+      addressedOnly: input.addressedOnly,
+      offset: input.offset,
+    };
     const readPending = () =>
       newest ? canvasState.getPendingSteeringForContext(scope) : canvasState.getPendingSteering(scope);
     let pending = readPending();
@@ -495,6 +514,12 @@ const axReadsListOperation = defineOperation<z.infer<typeof axReadsListSchema>,
 });
 
 const axReadsRecordShape = {
+  deliveryId: z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe('Idempotent adapter receipt ID, scoped to source, consumer and board.'),
   channel: z.enum(CONTEXT_READ_CHANNELS).describe('How the read reached the agent.'),
   resource: z.string().min(1).describe('Resource URI or operation name that was read.'),
   consumer: z.string().nullable().optional().describe('Reader identity (MCP client name, adapter host).'),
@@ -532,6 +557,7 @@ const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchem
   handler: (input) => {
     const read = canvasState.recordContextRead(
       {
+        deliveryId: input.deliveryId,
         channel: input.channel,
         resource: input.resource,
         source: input.source ?? 'api',

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

@@ -26,7 +26,8 @@ import { z } from 'zod';
 import { canvasState } from '../../canvas-state.js';
 import { serializeCanvasNode, serializeCanvasNodeCompact } from '../../canvas-serialization.js';
 import { addCanvasNode } from '../../canvas-operations.js';
-import { executeOperation, runWithSuppressedEmits } from '../registry.js';
+import { currentActor } from '../../attribution.js';
+import { executeOperation, runWithSuppressedEmits, validateOperationTarget } from '../registry.js';
 import { defineOperation, type Operation, type OperationContext } from '../types.js';
 import { readJsonValue } from '../http.js';
 import { isRecord } from './nodes.js';
@@ -57,6 +58,8 @@ const SUPPORTED_BATCH_OPS = new Set([
   'group.create',
   'group.add',
   'group.remove',
+  'annotation.add',
+  'annotation.remove',
   'pin.set',
   'pin.add',
   'pin.remove',
@@ -224,6 +227,7 @@ function shapeBatchEntry(op: string, result: unknown, creationReceipt = false):
 async function runBatch(operations: BatchEntry[], ctx: OperationContext): Promise<BatchEnvelope> {
   const refs: Record<string, unknown> = {};
   const results: Array<Record<string, unknown>> = [];
+  const actor = currentActor('api');
 
   for (let index = 0; index < operations.length; index++) {
     const operation = operations[index]!;
@@ -233,6 +237,7 @@ async function runBatch(operations: BatchEntry[], ctx: OperationContext): Promis
     }
     try {
       ctx.signal?.throwIfAborted();
+      validateOperationTarget(operation.op, args);
       if (ctx.onProgress) {
         const boardGeneration = canvasState.boardGeneration;
         await ctx.onProgress({ progress: index, total: operations.length, message: operation.op });
@@ -268,14 +273,19 @@ async function runBatch(operations: BatchEntry[], ctx: OperationContext): Promis
       // Batch churn is exempt from auto-ghosts (matches the skill's explicit
       // ghost-cursor exemption for batch operations). No `fromWorkbench`: the
       // browser never issues batches, so inner writes are agent writes and the
-      // scope fence applies to each of them.
-      const pending = executeOperation(dispatch.name, dispatch.args, {
-        suppressAutoGhost: true,
-        signal: ctx.signal,
-        onProgress: ctx.onProgress
-          ? (progress) => ctx.onProgress!({ progress: index, total: operations.length, message: progress.message })
-          : undefined,
-      });
+      // scope fence applies to each of them using the original writer identity.
+      const pending = executeOperation(
+        dispatch.name,
+        { agentId: actor.agentId, ...dispatch.args },
+        {
+          source: actor.source,
+          suppressAutoGhost: true,
+          signal: ctx.signal,
+          onProgress: ctx.onProgress
+            ? (progress) => ctx.onProgress!({ progress: index, total: operations.length, message: progress.message })
+            : undefined,
+        },
+      );
       // The first write may synchronously open a board from Home. Capture after
       // dispatch, then refuse to continue a partially completed batch elsewhere.
       const boardGeneration = canvasState.boardGeneration;
@@ -319,6 +329,7 @@ const batchShape = {
       }),
     )
     .describe('Ordered array of batch operations'),
+  agentId: z.string().optional().describe('Default writer identity for entries without their own agentId'),
   full: z
     .boolean()
     .optional()
@@ -404,13 +415,16 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
         : isRecord(body) && Array.isArray(body.operations)
           ? body.operations
           : [];
-      return { operations };
+      return {
+        operations,
+        ...(isRecord(body) ? { agentId: body.agentId, targetBoardId: body.targetBoardId } : {}),
+      };
     },
   },
   mcp: {
     toolName: 'canvas_batch',
     description:
-      'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, node.remove, graph.add, edge.add, edge.remove, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
+      'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, node.remove, graph.add, edge.add, edge.remove, group.create, group.add, group.remove, annotation.add, annotation.remove, pin.set/add/remove, snapshot.save, and arrange.',
     formatResult: (result, input) => {
       const envelope = result as BatchEnvelope;
       const payload = wantsFullBatch(input) ? envelope : compactBatchResult(envelope);

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

@@ -12,12 +12,12 @@
  *
  * This module must never import server.ts or index.ts.
  */
-import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { normalizeBoardFolder } from '../../../shared/boards.js';
 import { relationVocabularySchema } from '../../../shared/relations.js';
-import { canvasState, type CanvasLayout } from '../../canvas-state.js';
+import { boardCatalogEpoch, canvasState, type CanvasLayout } from '../../canvas-state.js';
 import { openCanvasBoard } from '../../canvas-operations.js';
+import { rewatchAllFileNodes } from '../../file-watcher.js';
 import { summarizeNodeForAgentContext } from '../../../shared/agent-context.js';
 import { BRIEF_SUMMARY_LENGTH } from '../../context-brief.js';
 import { memoryGraph, boardConnections } from '../../memory-graph.js';
@@ -25,7 +25,6 @@ import { defineOperation, OperationError, type Operation, type OperationContext
 
 /** The most cards a Home thumbnail draws (the largest first); the rest are noise at that size. */
 const PREVIEW_CARDS = 24;
-export const boardCatalogEpoch = randomUUID();
 let catalogRevision = 0;
 let reloadRevision = 0;
 
@@ -68,8 +67,8 @@ export function boardsPayload(reloaded = false): Record<string, unknown> {
     catalogEpoch: boardCatalogEpoch,
     catalogRevision: revision,
     reloadRevision,
-    boardGeneration: canvasState.boardGeneration,
-    activeBoardId: canvasState.activeBoardId,
+    boardGeneration: canvasState.visibleBoardGeneration,
+    activeBoardId: canvasState.visibleBoardId,
     boards: boards.map((board) => {
       const read = canvasState.readBoard(board.id, true);
       const readme = read?.layout.nodes.find((node) => node.id === board.readmeNodeId && node.type === 'markdown');
@@ -218,7 +217,8 @@ const boardGetOperation = defineOperation<z.infer<typeof getSchema>, Record<stri
     const id = typeof input.id === 'string' && input.id.trim() ? input.id.trim() : canvasState.activeBoardId;
     const board = id ? canvasState.listBoards().find((entry) => entry.id === id) : undefined;
     if (!board) throw new OperationError(id ? `Board "${id}" not found.` : 'No board is open.', 404);
-    return { ok: true, board, open: board.id === canvasState.activeBoardId };
+    const contentRevision = canvasState.readBoard(board.id, false)!.state.revisionState?.revision ?? 0;
+    return { ok: true, board, contentRevision, open: board.id === canvasState.activeBoardId };
   },
 });
 
@@ -406,6 +406,44 @@ const boardCreateFromOperation = defineOperation<z.infer<typeof fromSchema>, Rec
   },
 });
 
+const moveShape = {
+  sourceBoardId: z.string().min(1),
+  nodeIds: z.array(z.string().min(1)).min(1),
+  name: z.string().trim().min(1).max(120),
+  expectedRevision: z.number().int().nonnegative(),
+  requestId: z.string().trim().min(1).max(200),
+  preview: z.boolean().optional(),
+};
+const moveSchema = z.object(moveShape);
+const boardMoveOperation = defineOperation<z.infer<typeof moveSchema>, Record<string, unknown>>({
+  name: 'board.move-selection',
+  // Own validation precedes activation, and preview must never emit mutation/intent events.
+  mutates: false,
+  input: moveSchema,
+  inputShape: moveShape,
+  http: { method: 'POST', path: '/api/canvas/boards/move-selection' },
+  mcp: {
+    toolName: 'canvas_move_selection_to_board',
+    description:
+      'Preview or atomically move selected cards/group descendants to a new board, preserving identities and leaving a portal. Requires explicit sourceBoardId, expectedRevision and a durable requestId. Retry with identical input; never opens the destination. Preview lists unsafe bindings and the Undo/snapshot boundary.',
+    formatResult: jsonResult,
+  },
+  handler: (input, ctx) => {
+    const outcome = canvasState.moveSelectionToNewBoard(input);
+    if ('preview' in outcome) return { ok: true, ...outcome };
+    if (!outcome.replayed) {
+      rewatchAllFileNodes();
+      emitBoardsChanged(ctx);
+      ctx.emit('context-pins-changed', {
+        count: canvasState.contextPinnedNodeIds.size,
+        nodeIds: [...canvasState.contextPinnedNodeIds],
+      });
+      ctx.emit('ax-state-changed', {});
+    }
+    return { ok: true, ...outcome.result, replayed: outcome.replayed };
+  },
+});
+
 // ── board.pin / board.unpin ───────────────────────────────────
 // A pinned board joins the agent's working set: its README and pinned cards
 // travel in the brief whichever board is open. Pinning is context, never a
@@ -492,6 +530,7 @@ export const boardOperations: Operation[] = [
   boardGetOperation,
   boardCreateOperation,
   boardCreateFromOperation,
+  boardMoveOperation,
   boardUpdateOperation,
   boardPinOperation,
   boardUnpinOperation,