pmx-canvas 0.4.5 → 0.4.6

package/src/client/theme/global.css

@@ -1895,6 +1895,74 @@ html.is-node-resizing .ext-app-preview-catcher {
   }
 }
 
+/* Diff nodes — unified diff viewer with per-file sections */
+.diff-node {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  height: 100%;
+  overflow: auto;
+  font-family: var(--mono);
+  font-size: 12px;
+  color: var(--c-text);
+}
+
+.diff-node.diff-node-empty {
+  align-items: center;
+  justify-content: center;
+  color: var(--c-muted);
+}
+
+.diff-node .diff-file {
+  border: 1px solid var(--c-line);
+  border-radius: 6px;
+  overflow: hidden;
+  flex-shrink: 0;
+}
+
+.diff-node .diff-file-header {
+  padding: 4px 8px;
+  background: var(--c-panel-overlay);
+  border-bottom: 1px solid var(--c-line);
+  color: var(--c-text-soft);
+  font-weight: 600;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.diff-node .diff-lines {
+  margin: 0;
+  padding: 4px 0;
+  overflow-x: auto;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: 1.5;
+}
+
+.diff-node .diff-lines > div {
+  padding: 0 8px;
+  white-space: pre;
+}
+
+.diff-node .diff-hunk {
+  color: var(--c-muted);
+}
+
+.diff-node .diff-line-add {
+  color: var(--c-ok);
+  background: var(--c-ok-10);
+}
+
+.diff-node .diff-line-remove {
+  color: var(--c-danger);
+  background: var(--c-danger-12);
+}
+
+.diff-node .diff-line-context {
+  color: var(--c-text-soft);
+}
+
 /* Docked node — compact toolbar-flanking panel */
 .docked-node {
   min-width: 200px;

package/src/client/types.ts

@@ -21,6 +21,8 @@ export interface CanvasNodeState {
     | 'ledger'
     | 'trace'
     | 'file'
+    | 'diff'
+    | 'mermaid'
     | 'image'
     | 'html'
     | 'group';
@@ -77,6 +79,8 @@ export const TYPE_LABELS: Record<CanvasNodeState['type'], string> = {
   ledger: 'LOG',
   trace: 'TRACE',
   file: 'FILE',
+  diff: 'DIFF',
+  mermaid: 'MERMAID',
   image: 'IMG',
   html: 'HTML',
   group: 'GROUP',
@@ -92,6 +96,8 @@ export const EXPANDABLE_TYPES = new Set<CanvasNodeState['type']>([
   'context',
   'ledger',
   'file',
+  'diff',
+  'mermaid',
   'image',
   'html',
 ]);

package/src/mcp/server.ts

@@ -27,7 +27,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { AX_SOURCES } from '../server/operations/ops/ax-shared.js';
-import { canvasState, describeCanvasSchema } from '../server/index.js';
+import { canvasState, describeCanvasSchema, stopCanvasServer } from '../server/index.js';
 import { AX_INTERACTION_TYPES } from '../server/ax-interaction.js';
 import { buildPendingAxActivity } from '../server/ax-state.js';
 import { registerOperationTools, registerCompositeTools } from '../server/operations/index.js';
@@ -884,6 +884,24 @@ export async function startMcpServer(): Promise<void> {
   // Connect via stdio
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  // Exit when the stdio channel closes (0.4.5 report Finding Y): without this,
+  // a client that completes the official close sequence leaves this process
+  // orphaned — the auto-started canvas server and its timers keep the event
+  // loop alive forever. stopCanvasServer() checkpoints the SQLite DB before
+  // exit and is a no-op when this process only attached to a remote daemon.
+  const shutdown = (): void => {
+    try {
+      stopCanvasServer();
+    } catch {
+      // Exit regardless — a failed cleanup must not resurrect the orphan.
+    }
+    process.exit(0);
+  };
+  server.server.onclose = shutdown;
+  process.stdin.on('end', shutdown);
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
 }
 
 // Allow direct execution: bun run src/mcp/server.ts

package/src/server/ax-interaction.ts

@@ -102,6 +102,12 @@ export const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabili
     'notify-agent',
   ),
   file: caps(true, ['ax.evidence.add', 'ax.review.add', 'ax.focus.set', 'ax.event.record']),
+  diff: caps(true, ['ax.evidence.add', 'ax.review.add', 'ax.focus.set', 'ax.event.record']),
+  mermaid: caps(
+    true,
+    ['ax.steer', 'ax.work.create', 'ax.evidence.add', 'ax.command.invoke', 'ax.event.record'],
+    'notify-agent',
+  ),
   'json-render': caps(true, [
     'ax.work.create',
     'ax.work.update',

package/src/server/canvas-operations.ts

@@ -17,6 +17,7 @@ import {
   type ExternalMcpTransportConfig,
 } from './mcp-app-runtime.js';
 import { mutationHistory } from './mutation-history.js';
+import { clampCreateNodeSize } from './canvas-validation.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
@@ -114,6 +115,10 @@ export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
 export const IMAGE_NODE_DEFAULT_SIZE = { width: 480, height: 360 };
 export const LEDGER_NODE_DEFAULT_SIZE = { width: 420, height: 280 };
 
+// Per-type minimum creation sizes + clamp live in canvas-validation.ts
+// (NODE_MIN_CREATE_SIZES / clampCreateNodeSize) — shared with the validate
+// surface's sizeWarnings.
+
 interface CanvasCreateGroupInput {
   title?: string;
   childIds?: string[];
@@ -360,11 +365,20 @@ export function buildJsonRenderNodeUpdate(
   if (node.type !== 'json-render') throw new Error(`Node "${node.id}" is not a json-render node.`);
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
   const title = input.title?.trim() || inferJsonRenderNodeTitle(spec);
+  // Bump specVersion so the viewer URL changes: the iframe src is keyed on
+  // nodeId + ?v=specVersion, and the viewer only reads the spec at document
+  // load. Without the bump the src is byte-identical after a content update,
+  // the iframe never reloads, and the node renders stale forever (the live
+  // workboard's refresh depends on this).
+  const prevVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : 0;
   return {
     spec,
     data: {
       ...node.data,
-      ...createJsonRenderNodeData(node.id, title, spec, { viewerType: 'json-render' }),
+      ...createJsonRenderNodeData(node.id, title, spec, {
+        viewerType: 'json-render',
+        specVersion: prevVersion + 1,
+      }),
     },
   };
 }
@@ -906,8 +920,12 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
     throw new Error(`Use the dedicated ${input.type} node APIs for structured viewer nodes.`);
   }
 
-  const width = input.width ?? input.defaultWidth ?? 720;
-  const height = input.height ?? input.defaultHeight ?? 600;
+  const { width, height } = clampCreateNodeSize(
+    input.type,
+    input.width ?? input.defaultWidth ?? 720,
+    input.height ?? input.defaultHeight ?? 600,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1540,8 +1558,12 @@ export function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
   node: CanvasNodeState;
 } {
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
-  const width = input.width ?? JSON_RENDER_NODE_SIZE.width;
-  const height = input.height ?? JSON_RENDER_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'json-render',
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1580,8 +1602,12 @@ export function createCanvasStreamingJsonRenderNode(input: {
   strictSize?: boolean;
 }): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState } {
   const spec = emptyStreamingSpec();
-  const width = input.width ?? JSON_RENDER_NODE_SIZE.width;
-  const height = input.height ?? JSON_RENDER_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'json-render',
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1652,8 +1678,12 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
 } {
   const title = input.title?.trim() || 'Graph';
   const spec = buildGraphSpec(input);
-  const width = input.width ?? GRAPH_NODE_SIZE.width;
-  const height = input.heightPx ?? GRAPH_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'graph',
+    input.width ?? GRAPH_NODE_SIZE.width,
+    input.heightPx ?? GRAPH_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }

package/src/server/canvas-provenance.ts

@@ -14,6 +14,8 @@ export type CanvasNodeType =
   | 'ledger'
   | 'trace'
   | 'file'
+  | 'diff'
+  | 'mermaid'
   | 'image'
   | 'html'
   | 'group';

package/src/server/canvas-schema.ts

@@ -209,6 +209,39 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       'Path-backed file nodes automatically persist `data.provenance` with a file URI and file-watch refresh strategy.',
     ],
   },
+  {
+    type: 'diff',
+    kind: 'node',
+    description: 'Unified diff viewer with per-file sections and colored add/remove lines.',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_node (action:"add")',
+    fields: [
+      { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
+      { name: 'content', type: 'string', required: false, description: 'Unified diff text (git or raw hunks).' },
+    ],
+    example: {
+      type: 'diff',
+      title: 'Fix null check',
+      content: '--- a/src/app.ts\n+++ b/src/app.ts\n@@ -1,3 +1,3 @@\n-const a = b.c;\n+const a = b?.c;\n context',
+    },
+  },
+  {
+    type: 'mermaid',
+    kind: 'node',
+    description:
+      'Text-to-diagram node rendered client-side with Mermaid (flowcharts, sequence, state, class diagrams, …).',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_node (action:"add")',
+    fields: [
+      { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
+      { name: 'content', type: 'string', required: false, description: 'Mermaid diagram source text.' },
+    ],
+    example: {
+      type: 'mermaid',
+      title: 'Request flow',
+      content: 'graph TD; A[Client] --> B[Server]; B --> C[(DB)];',
+    },
+  },
   {
     type: 'image',
     kind: 'node',

package/src/server/canvas-state.ts

@@ -175,6 +175,8 @@ export interface CanvasNodeState {
     | 'ledger'
     | 'trace'
     | 'file'
+    | 'diff'
+    | 'mermaid'
     | 'image'
     | 'html'
     | 'group';
@@ -368,6 +370,28 @@ class CanvasStateManager {
     };
   }
 
+  // ── Work-item change listener (single slot, for live workboard refresh) ──
+  private _workItemsChangedListener: (() => void) | null = null;
+
+  /**
+   * Register THE work-item change listener (single slot, last-write-wins).
+   * Fired after addWorkItem/updateWorkItem completes (including the node
+   * status mirror), so live views like the workboard can rebuild from the
+   * fresh work-item list.
+   */
+  setWorkItemsChangedListener(listener: (() => void) | null): void {
+    this._workItemsChangedListener = listener;
+  }
+
+  private notifyWorkItemsChanged(): void {
+    if (!this._workItemsChangedListener) return;
+    try {
+      this._workItemsChangedListener();
+    } catch (error) {
+      logCanvasStateWarning('work-items-changed listener failed', error);
+    }
+  }
+
   private notifyChange(type: CanvasChangeType): void {
     // Iterate a snapshot: a listener (e.g. a blocking-wait via onChange) may dispose
     // itself synchronously here, and splicing the live array mid-iteration would skip
@@ -1727,6 +1751,7 @@ class CanvasStateManager {
   ): PmxAxWorkItem {
     const item = this.ax.addWorkItem(input, options);
     this.mirrorAxWorkStatusToNodes(item.nodeIds, [], item.status);
+    this.notifyWorkItemsChanged();
     return item;
   }
 
@@ -1745,6 +1770,7 @@ class CanvasStateManager {
     const item = this.ax.updateWorkItem(id, patch, options);
     if (!item) return null;
     this.mirrorAxWorkStatusToNodes(item.nodeIds, previousNodeIds, item.status);
+    this.notifyWorkItemsChanged();
     return item;
   }
 

package/src/server/canvas-validation.ts

@@ -1,6 +1,47 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
 
+/**
+ * Per-type minimum node size (0.4.5 report follow-up): agents frequently
+ * create nodes with explicit frames far too small for their content — clipped
+ * markdown, charts squeezed behind inner scrollbars. Explicit sizes below the
+ * floor are clamped UP at creation (canvas-operations.ts creators);
+ * `strictSize: true` is the escape hatch for a genuinely small fixed frame.
+ * Floors sit below every type default and above the point of unreadability.
+ * Creation-only: later updates are untouched (the browser's drag-resize
+ * enforces its own 200×100 floor client-side), but `validate` reports any
+ * node below its floor as an advisory sizeWarning. Absent types (trace,
+ * group, prompt/response) are intentionally unclamped — trace is small by
+ * design, groups size to their children.
+ */
+export const NODE_MIN_CREATE_SIZES: Partial<Record<CanvasNodeState['type'], { width: number; height: number }>> = {
+  markdown: { width: 360, height: 180 },
+  context: { width: 360, height: 180 },
+  file: { width: 360, height: 200 },
+  diff: { width: 420, height: 240 },
+  mermaid: { width: 360, height: 240 },
+  status: { width: 280, height: 120 },
+  ledger: { width: 320, height: 200 },
+  image: { width: 240, height: 180 },
+  html: { width: 420, height: 280 },
+  webpage: { width: 420, height: 280 },
+  'json-render': { width: 420, height: 280 },
+  graph: { width: 420, height: 280 },
+  'mcp-app': { width: 480, height: 320 },
+};
+
+export function clampCreateNodeSize(
+  type: CanvasNodeState['type'],
+  width: number,
+  height: number,
+  strictSize?: boolean,
+): { width: number; height: number } {
+  if (strictSize === true) return { width, height };
+  const min = NODE_MIN_CREATE_SIZES[type];
+  if (!min) return { width, height };
+  return { width: Math.max(width, min.width), height: Math.max(height, min.height) };
+}
+
 export interface CanvasValidationPair {
   aId: string;
   aTitle: string | null;
@@ -15,12 +56,24 @@ export interface CanvasContainmentIssue {
   childTitle: string | null;
 }
 
+export interface CanvasSizeWarning {
+  id: string;
+  title: string | null;
+  type: CanvasNodeState['type'];
+  width: number;
+  height: number;
+  minWidth: number;
+  minHeight: number;
+}
+
 export interface CanvasValidationResult {
   ok: boolean;
   collisions: CanvasValidationPair[];
   containments: CanvasContainmentIssue[];
   containmentViolations: CanvasContainmentIssue[];
   missingEdgeEndpoints: Array<{ edgeId: string; from: string; to: string }>;
+  /** Nodes below their type's readable minimum (advisory — does not fail `ok`). */
+  sizeWarnings: CanvasSizeWarning[];
   summary: {
     nodes: number;
     edges: number;
@@ -28,6 +81,7 @@ export interface CanvasValidationResult {
     containments: number;
     containmentViolations: number;
     missingEdgeEndpoints: number;
+    sizeWarnings: number;
   };
 }
 
@@ -109,12 +163,36 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
     .filter((edge) => !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
     .map((edge) => ({ edgeId: edge.id, from: edge.from, to: edge.to }));
 
+  // Advisory: nodes below their type's readable floor (clipped/unreadable
+  // content — 0.4.5 report follow-up). Creation clamps these, but resized or
+  // strictSize-created nodes can still be undersized; surface them so an
+  // agent's validate pass sees the problem. Collapsed/docked nodes render as
+  // bars, and strictSize is the deliberate opt-out — all skipped.
+  const sizeWarnings: CanvasSizeWarning[] = layout.nodes
+    .filter((node) => !node.collapsed && node.dockPosition == null && node.data?.strictSize !== true)
+    .flatMap((node) => {
+      const min = NODE_MIN_CREATE_SIZES[node.type];
+      if (!min || (node.size.width >= min.width && node.size.height >= min.height)) return [];
+      return [
+        {
+          id: node.id,
+          title: getCanvasNodeTitle(node),
+          type: node.type,
+          width: node.size.width,
+          height: node.size.height,
+          minWidth: min.width,
+          minHeight: min.height,
+        },
+      ];
+    });
+
   return {
     ok: collisions.length === 0 && containmentViolations.length === 0 && missingEdgeEndpoints.length === 0,
     collisions,
     containments,
     containmentViolations,
     missingEdgeEndpoints,
+    sizeWarnings,
     summary: {
       nodes: layout.nodes.length,
       edges: layout.edges.length,
@@ -122,6 +200,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
       containments: containments.length,
       containmentViolations: containmentViolations.length,
       missingEdgeEndpoints: missingEdgeEndpoints.length,
+      sizeWarnings: sizeWarnings.length,
     },
   };
 }

package/src/server/html-surface.ts

@@ -211,6 +211,17 @@ function escapeSurfaceHtml(value: string): string {
   return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
+/**
+ * Author-HTML fragment for a `mermaid` node surface: the HTML-escaped diagram
+ * source in a hidden `<pre>` the entry script reads back via textContent, plus
+ * the separately-built renderer bundle (dist/canvas/mermaid-entry.js — kept out
+ * of the main SPA bundle). Escaping is mandatory: the source is arbitrary node
+ * data and must not be parsed as markup.
+ */
+export function buildMermaidSurfaceHtml(source: string): string {
+  return `<pre class="mermaid-source" style="display:none">${escapeSurfaceHtml(source)}</pre><script src="/canvas/mermaid-entry.js"></script>`;
+}
+
 export interface HtmlSurfaceOptions {
   theme: SurfaceTheme;
   /**

package/src/server/index.ts

@@ -542,15 +542,22 @@ export class PmxCanvas extends EventEmitter {
       nodeIds?: string[];
       data?: Record<string, unknown> | null;
     },
-    options?: { source?: PmxAxSource },
+    options?: { source?: PmxAxSource; agentId?: string | null },
   ): PmxAxEvent {
-    const event = canvasState.recordAxEvent(input, { source: options?.source ?? 'sdk' });
+    const event = canvasState.recordAxEvent(input, { source: options?.source ?? 'sdk', agentId: options?.agentId });
     emitPrimaryWorkbenchEvent('ax-event-created', { event });
     return event;
   }
 
-  sendSteering(message: string, options?: { source?: PmxAxSource }): PmxAxSteeringMessage {
-    const steering = canvasState.recordSteeringMessage(message, { source: options?.source ?? 'sdk' });
+  sendSteering(
+    message: string,
+    options?: { source?: PmxAxSource; agentId?: string | null; target?: string | null },
+  ): PmxAxSteeringMessage {
+    const steering = canvasState.recordSteeringMessage(message, {
+      source: options?.source ?? 'sdk',
+      agentId: options?.agentId,
+      target: options?.target,
+    });
     emitPrimaryWorkbenchEvent('ax-event-created', { steering });
     return steering;
   }
@@ -604,7 +611,13 @@ export class PmxCanvas extends EventEmitter {
   }
 
   addWorkItem(
-    input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    input: {
+      title: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options?: { source?: PmxAxSource },
   ): PmxAxWorkItem {
     const workItem = canvasState.addWorkItem(input, { source: options?.source ?? 'sdk' });
@@ -614,7 +627,13 @@ export class PmxCanvas extends EventEmitter {
 
   updateWorkItem(
     id: string,
-    patch: { title?: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    patch: {
+      title?: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options?: { source?: PmxAxSource },
   ): PmxAxWorkItem | null {
     const workItem = canvasState.updateWorkItem(id, patch, { source: options?.source ?? 'sdk' });

package/src/server/operations/composites.ts

@@ -156,14 +156,15 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_render',
     description:
-      'Spec-driven content: discover the schema, validate a payload, or create a json-render / graph node. Action "describe-schema" returns the json-render component catalog + create schemas; "validate" checks a spec or graph payload without creating a node; "add-json-render" creates a json-render node from a complete spec; "stream-json-render" progressively builds one from SpecStream patches (omit nodeId to create, pass it back to append, done=true to finish); "add-graph" creates a chart node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph).',
-    actionSummary: 'describe-schema | validate | add-json-render | stream-json-render | add-graph',
+      'Spec-driven content: discover the schema, validate a payload, or create a json-render / graph node. Action "describe-schema" returns the json-render component catalog + create schemas; "validate" checks a spec or graph payload without creating a node; "add-json-render" creates a json-render node from a complete spec; "stream-json-render" progressively builds one from SpecStream patches (omit nodeId to create, pass it back to append, done=true to finish); "add-graph" creates a chart node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph); "workboard" materializes a live AX work-item board (a json-render node with a column per status) that auto-refreshes whenever work items change — idempotent, rebuilding the existing board in place.',
+    actionSummary: 'describe-schema | validate | add-json-render | stream-json-render | add-graph | workboard',
     actions: {
       'describe-schema': 'schema.describe',
       validate: 'spec.validate',
       'add-json-render': 'jsonrender.add',
       'stream-json-render': 'jsonrender.stream',
       'add-graph': 'graph.add',
+      workboard: 'render.workboard',
     },
   },
   {

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

@@ -375,6 +375,14 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
     // ctx.emit). After the loop completes, emit ONE final canvas-layout-update.
     const envelope = await runWithSuppressedEmits(() => runBatch(operations));
     ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    // The suppression window also swallows the pins op's context-pins-changed
+    // frame, leaving the client's pin state (menus, indicators) stale until
+    // reload (0.4.5 report Finding X). If the batch touched pins, follow the
+    // layout frame with ONE final pins frame carrying the end state.
+    if (operations.some((entry) => entry.op.startsWith('pin.'))) {
+      const nodeIds = Array.from(canvasState.contextPinnedNodeIds);
+      ctx.emit('context-pins-changed', { count: nodeIds.length, nodeIds });
+    }
     return envelope;
   },
 });

package/src/server/operations/ops/json-render.ts

@@ -39,6 +39,7 @@ import {
 } from '../../canvas-operations.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from '../../canvas-schema.js';
 import { isHtmlPrimitiveKind } from '../../html-primitives.js';
+import { renderWorkboard } from '../../workboard.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import {
   buildNodeResponse,
@@ -311,6 +312,48 @@ const jsonRenderStreamOperation = defineOperation<z.infer<typeof jsonRenderStrea
   // Wire shape is `{ id, url, ok, applied, ... }` — handler output verbatim.
 });
 
+// ── render.workboard ──────────────────────────────────────────
+
+const workboardRenderShape = {
+  intentId: z
+    .string()
+    .optional()
+    .catch(undefined)
+    .describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
+  x: z.number().optional().catch(undefined).describe('Optional X position (only used when creating the board)'),
+  y: z.number().optional().catch(undefined).describe('Optional Y position (only used when creating the board)'),
+};
+
+const workboardRenderSchema = z.looseObject(workboardRenderShape);
+
+const workboardRenderOperation = defineOperation<
+  z.infer<typeof workboardRenderSchema>,
+  ReturnType<typeof renderWorkboard>
+>({
+  name: 'render.workboard',
+  mutates: true,
+  input: workboardRenderSchema,
+  inputShape: workboardRenderShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/workboard',
+  },
+  mcp: {
+    toolName: 'canvas_render_workboard',
+    description:
+      'Materialize a live work-item board: a json-render node with one column per status (todo → in-progress → blocked → done → cancelled) showing every AX work item as a card (title, agentId chip, detail). Idempotent: rebuilds the existing board node in place when one exists, otherwise creates it. The board auto-refreshes whenever work items change.',
+  },
+  handler: (input) => {
+    const body: Record<string, unknown> = input;
+    const x = pickFiniteNumber(body, 'x');
+    const y = pickFiniteNumber(body, 'y');
+    return renderWorkboard({
+      ...(x !== undefined ? { x } : {}),
+      ...(y !== undefined ? { y } : {}),
+    });
+  },
+});
+
 // ── graph.add ─────────────────────────────────────────────────
 
 const graphAddShape = {
@@ -829,6 +872,7 @@ const specValidateOperation = defineOperation<z.infer<typeof specValidateSchema>
 export const jsonRenderOperations: Operation[] = [
   jsonRenderAddOperation,
   jsonRenderStreamOperation,
+  workboardRenderOperation,
   graphAddOperation,
   schemaDescribeOperation,
   specValidateOperation,