pmx-canvas 0.7.2 → 0.8.0

package/src/server/demo-state.json

@@ -3134,7 +3134,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 41,
+      "contentRevision": 46,
       "kind": "markdown",
       "title": "Sprint 41 — canvas polish",
       "content": "Three nodes, one frame. Moving the frame moves the children; ungrouping leaves them exactly where they are.\n\n- Group children keep their own positions by default\n- `childLayout` opts into auto-packing\n- The frame is stored as `data.children` on the group",
@@ -3174,7 +3174,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 42,
+      "contentRevision": 47,
       "kind": "status",
       "title": "Sprint state",
       "content": null,
@@ -3215,7 +3215,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 43,
+      "contentRevision": 48,
       "kind": "trace",
       "title": "canvas_group",
       "content": null,
@@ -3256,7 +3256,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 44,
+      "contentRevision": 45,
       "kind": "group",
       "title": "Sprint 41",
       "content": null,
@@ -3292,7 +3292,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 45,
+      "contentRevision": 49,
       "kind": "markdown",
       "title": "⑦ HTML primitives",
       "content": "All 21 generated communication surfaces — self-contained sandboxed documents, no build step.",
@@ -3377,7 +3377,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 46,
+      "contentRevision": 50,
       "kind": "html",
       "title": "How should the demo board be generated?",
       "content": "Side-by-side options with tradeoffs, pros, cons, and code or evidence snippets.",
@@ -3487,7 +3487,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 47,
+      "contentRevision": 51,
       "kind": "html",
       "title": "Demo board rebuild",
       "content": "Implementation plan with milestones, data flow, code checkpoints, and risks.",
@@ -3566,7 +3566,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 48,
+      "contentRevision": 52,
       "kind": "html",
       "title": "Review — auto-fit floor",
       "content": "Annotated PR/code review sheet with severity-colored findings and diff excerpts.",
@@ -3654,7 +3654,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 49,
+      "contentRevision": 53,
       "kind": "html",
       "title": "PR — replace the demo board",
       "content": "Reviewer-ready PR narrative with motivation, before/after, file tour, test plan, and rollout notes.",
@@ -3766,7 +3766,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 50,
+      "contentRevision": 54,
       "kind": "html",
       "title": "Canvas server map",
       "content": "Module or architecture map with boxes, relationships, entry points, and hot paths.",
@@ -3895,7 +3895,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 51,
+      "contentRevision": 55,
       "kind": "html",
       "title": "Walkthrough — creating a node",
       "content": "Guided code-path map with modules, ordered file steps, snippets, key files, and gotchas.",
@@ -3998,7 +3998,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 52,
+      "contentRevision": 56,
       "kind": "html",
       "title": "Board typography directions",
       "content": "Visual design directions, tokens, swatches, type samples, and rationale.",
@@ -4081,7 +4081,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 53,
+      "contentRevision": 57,
       "kind": "html",
       "title": "Node titlebar states",
       "content": "Contact sheet for component variants, states, sizes, and accessibility notes.",
@@ -4179,7 +4179,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 54,
+      "contentRevision": 58,
       "kind": "html",
       "title": "Node expand transition",
       "content": "Throwaway interaction or motion sandbox with a live stage, controls, annotations, and copyable config.",
@@ -4265,7 +4265,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 55,
+      "contentRevision": 59,
       "kind": "html",
       "title": "Release pipeline",
       "content": "Clickable flowchart for pipelines, user journeys, process diagrams, and failure paths.",
@@ -4360,7 +4360,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 56,
+      "contentRevision": 60,
       "kind": "html",
       "title": "Why a spatial canvas",
       "content": "Arrow-key HTML deck with sections, speaker notes, and copyable JSON payload. Slides: Chat is a queue, work is a graph, The canvas is the agent’s working memory, Pinning is the steering wheel.",
@@ -4478,7 +4478,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 57,
+      "contentRevision": 61,
       "kind": "html",
       "title": "PMX Canvas 0.4.7 briefing",
       "content": "PowerPoint-style fullscreen-ready HTML presentation with slide navigation, progress, speaker notes, and presentation metadata. Slides: Where we are, What changed in 0.4.7, Next.",
@@ -4643,7 +4643,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 58,
+      "contentRevision": 62,
       "kind": "html",
       "title": "Figures — the collaboration loop",
       "content": "Inline SVG figure sheet with captions and per-figure SVG copy/export controls.",
@@ -4749,7 +4749,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 59,
+      "contentRevision": 63,
       "kind": "html",
       "title": "How context pins work",
       "content": "Readable explainer with TLDR, collapsible steps, annotated snippets, FAQ, and glossary.",
@@ -4870,7 +4870,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 60,
+      "contentRevision": 64,
       "kind": "html",
       "title": "Blank ext-app tiles on WebKit",
       "content": "Post-incident report with impact metrics, minute-by-minute timeline, root cause, log excerpts, and action checklist.",
@@ -4956,7 +4956,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 61,
+      "contentRevision": 65,
       "kind": "html",
       "title": "Weekly canvas status",
       "content": "Skimmable report with metrics, shipped/slipped lists, blockers, and next actions.",
@@ -5042,7 +5042,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 62,
+      "contentRevision": 66,
       "kind": "html",
       "title": "Post-0.4.7 triage",
       "content": "Draggable Now/Next/Later/Cut board with copy-as-markdown export.",
@@ -5134,7 +5134,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 63,
+      "contentRevision": 67,
       "kind": "html",
       "title": "Canvas feature flags",
       "content": "Form-like editor for flags or structured config with dependency warnings and copy-diff export.",
@@ -5203,7 +5203,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 64,
+      "contentRevision": 68,
       "kind": "html",
       "title": "Board summary prompt",
       "content": "Side-by-side prompt/template editor with live variable previews and copy export.",
@@ -5256,7 +5256,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 65,
+      "contentRevision": 69,
       "kind": "html",
       "title": "Agent board",
       "content": "Live agent work board: hand the agent tasks, watch status, steer, and run bounded task loops.",
@@ -5337,7 +5337,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 77,
+      "contentRevision": 85,
       "kind": "html",
       "title": "Release flow",
       "content": "HTML primitive: ax-flow\nLive task-flow control panel: a step diagram with an explicit loop-back, per-step status, and a one-click materialize onto the board.\nRelease flow PMX HTML primitive / ax-flow Release flow Live task-flow control panel: a step diagram with an explicit loop-back, per-step status, and a one-click materialize onto the board. Copy JSON Copy prompt AX bridge unavailable This flow is not running as an AX-enabled canvas node, so its controls are inert. Release flow Each step is a canvas AX work item. Materialize drops the same flow onto the board as real nodes. loops back to step 1 · max 3 runs Run the flow Queue every step A step is queued once — after that its status control advances it (todo → in-progress → done). or run the whole flow as a bounded loop: max runs Start loop Steer Queue steering message Queued for the agent's next turn — steering is recorded on the timeline, it does not wake a running agent. Loop run 0 of 0 Each run is its own work item. When you mark the current run done , the surface opens the next run...",
@@ -5373,7 +5373,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 67,
+      "contentRevision": 71,
       "kind": "markdown",
       "title": "⑧ Agent at work",
       "content": "A task caught mid-flight: one work item per step, status chips on the nodes, controls that steer the agent.",
@@ -5454,7 +5454,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 78,
+      "contentRevision": 86,
       "kind": "markdown",
       "title": "1. Reproduce",
       "content": "Ran the publish gate 20× in a loop. Fails 3 in 20, always on the registry probe.",
@@ -5500,7 +5500,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 79,
+      "contentRevision": 87,
       "kind": "markdown",
       "title": "2. Fix",
       "content": "Retry the probe with backoff instead of failing the gate on the first timeout.",
@@ -5592,7 +5592,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 81,
+      "contentRevision": 83,
       "kind": "markdown",
       "title": "4. Ship",
       "content": "Land the patch, then watch the next three releases.",
@@ -5628,7 +5628,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 82,
+      "contentRevision": 88,
       "kind": "markdown",
       "title": "How to read this band",
       "content": "Each step is a real **AX work item**, so the chip on a step node is the\nagent’s live status — it moves as the agent works.\n\nThe buttons in each step footer steer it: **Start**, **Done** and\n**Blocked** write that step’s work item, which the agent reads back from\n`canvas://ax-work`.\n\nStep 2 is pinned, so `canvas://pinned-context` hands the agent the\nstep it is actually on.",

package/src/server/html-surface.ts

@@ -226,12 +226,11 @@ export function buildMermaidSurfaceHtml(
 ): string {
   // srcdoc-rendered surfaces in hosts that block sub-frame subresources (the
   // Claude Code desktop browser blocks the script request too, not just the
-  // frame document) get the renderer embedded as a data: URL — no network
-  // request for the host to block, and base64 has no `<` for the HTML script
-  // parser to trip on (a 3.5MB bundle inlined as literal script text hits the
-  // `<!--` script-data-escaped states and renders as page text).
+  // frame document) get an inline bootstrap. Assigning decoded script text
+  // avoids HTML parser escaped states (`<!--`, `</script>`) in the bundle,
+  // without requiring data: script URLs that MCP App hosts may prohibit.
   const entry = inlineEntry
-    ? `<script src="data:text/javascript;charset=utf-8;base64,${Buffer.from(inlineEntry, 'utf-8').toString('base64')}"></script>`
+    ? `<script>(()=>{const s=document.createElement('script');s.textContent=new TextDecoder().decode(Uint8Array.from(atob('${Buffer.from(inlineEntry, 'utf-8').toString('base64')}'),c=>c.charCodeAt(0)));document.head.appendChild(s)})()</script>`
     : '<script src="/canvas/mermaid-entry.js"></script>';
   return `<pre class="mermaid-source" data-fit="${fit}" data-frame-token="${sanitizeFrameToken(frameToken)}" style="display:none">${escapeSurfaceHtml(source)}</pre>${entry}`;
 }

package/src/server/index.ts

@@ -218,6 +218,8 @@ export class PmxCanvas extends EventEmitter {
   async start(options?: {
     open?: boolean;
     automationWebView?: boolean | CanvasAutomationWebViewOptions;
+    /** Embedded startup must not launch external MCP backends from saved nodes. */
+    allowExternalMcp?: boolean;
     /**
      * Bind a nearby free port when the preferred one is taken instead of
      * failing. Default false (an explicit SDK port is honored exactly); the
@@ -225,7 +227,11 @@ export class PmxCanvas extends EventEmitter {
      */
     allowPortFallback?: boolean;
   }): Promise<void> {
-    const base = startCanvasServer({ port: this._port, allowPortFallback: options?.allowPortFallback ?? false });
+    const base = startCanvasServer({
+      port: this._port,
+      allowPortFallback: options?.allowPortFallback ?? false,
+      allowExternalMcp: options?.allowExternalMcp,
+    });
     if (!base) {
       throw new Error(`Failed to start canvas server on port ${this._port}`);
     }
@@ -900,6 +906,11 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getContextReads(limit);
   }
 
+  /** Per node on a board: when an agent last read its content, who, and the content revision it read. */
+  getNodeReadStatus(board?: string): ReturnType<typeof canvasState.getNodeReadStatus> {
+    return canvasState.getNodeReadStatus(board ?? canvasState.activeBoardId);
+  }
+
   listWorkItems(): PmxAxWorkItem[] {
     return canvasState.getWorkItems();
   }
@@ -1298,8 +1309,13 @@ export class PmxCanvas extends EventEmitter {
     return applyCanvasNodeUpdates(updates);
   }
 
-  setContextPins(nodeIds: string[], mode: 'set' | 'add' | 'remove' = 'set'): { count: number; nodeIds: string[] } {
-    const result = setCanvasContextPins(nodeIds, mode);
+  /** `reason` is kept with newly pinned nodes and shown to the human on hover. */
+  setContextPins(
+    nodeIds: string[],
+    mode: 'set' | 'add' | 'remove' = 'set',
+    reason?: string,
+  ): { count: number; nodeIds: string[] } {
+    const result = setCanvasContextPins(nodeIds, mode, reason);
     emitPrimaryWorkbenchEvent('context-pins-changed', { count: result.count, nodeIds: result.nodeIds });
     return result;
   }

package/src/server/mcp-app-runtime.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
@@ -18,6 +19,13 @@ import type { McpUiClientCapabilities, McpUiResourceCsp, McpUiResourceMeta } fro
 import { getToolUiResourceUri } from '@modelcontextprotocol/ext-apps/app-bridge';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 
+// A restriction follows async rehydration spawned by an embedded operation,
+// without disabling independent requests from the local workbench.
+const externalMcpDisabled = new AsyncLocalStorage<boolean>();
+export function withoutExternalMcp<T>(run: () => T): T {
+  return externalMcpDisabled.run(true, run);
+}
+
 export interface ExternalMcpHttpTransportConfig {
   type: 'http';
   url: string;
@@ -210,6 +218,9 @@ async function createSession(
   serverName?: string,
   timeoutMs?: number,
 ): Promise<McpAppSession> {
+  if (externalMcpDisabled.getStore()) {
+    throw new Error('Open external MCP apps from the local PMX workbench; embedded actions cannot launch them.');
+  }
   const transport = buildTransport(transportConfig);
   const client = new Client({ name: 'pmx-canvas-app-host', version: '0.1.0' }, { capabilities: clientCapabilities });
   await client.connect(transport, requestOptions(timeoutMs));

package/src/server/operations/composites.ts

@@ -323,14 +323,15 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_ax_timeline',
     description:
-      'Read or write the bounded PMX AX timeline. Action "read" returns recent agent-events, evidence, and steering messages plus counts (limit); "record-event" records a normalized agent-event (kind prompt|assistant-message|tool-start|tool-result|failure|approval|steering, summary, detail, data); "add-evidence" records an evidence item (kind logs|tool-result|screenshot|file|diff|test-output, title, body, ref); "send-steering" records a steering message (message); "reads" returns the context read log — which canvas context each agent read and which pinned nodes reached it — with a per-consumer summary (limit). Timeline rows persist for diagnostics/continuity but are not restored by snapshots; exposed via canvas://ax-timeline.',
-    actionSummary: 'read | record-event | add-evidence | send-steering | reads',
+      'Read or write the bounded PMX AX timeline. Action "read" returns recent agent-events, evidence, and steering messages plus counts (limit); "record-event" records a normalized agent-event (kind prompt|assistant-message|tool-start|tool-result|failure|approval|steering, summary, detail, data); "add-evidence" records an evidence item (kind logs|tool-result|screenshot|file|diff|test-output, title, body, ref); "send-steering" records a steering message (message); "reads" returns the context read log — which canvas context each agent read and which pinned nodes reached it — with a per-consumer summary (limit); "read-status" returns, per node on a board, when an agent last read its content, who, and the content revision it read (board). Timeline rows persist for diagnostics/continuity but are not restored by snapshots; exposed via canvas://ax-timeline.',
+    actionSummary: 'read | record-event | add-evidence | send-steering | reads | read-status',
     actions: {
       read: 'ax.timeline.get',
       'record-event': 'ax.event.record',
       'add-evidence': 'ax.evidence.add',
       'send-steering': 'ax.steer',
       reads: 'ax.reads.list',
+      'read-status': 'ax.reads.status',
     },
   },
   {
@@ -346,7 +347,7 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_intent',
     description:
-      'Ghost Cursor of Intent — announce the spatial move you are ABOUT to make so the canvas paints a faint pre-commit placeholder (legibility: the human sees the next move forming, and can veto it). Action "signal" registers an intent (kind create|move|connect|remove|edit; pass position for create/move, nodeId for move/edit/remove, edge for connect; optional label, reason, confidence 0..1, seq, ttlMs, and a stable id); "update" patches a live intent by id; "clear" abandons/dissolves it. To make veto authoritative, pass the returned id as intentId on the real canvas_node/canvas_edge/canvas_group/canvas_render mutation: vetoed or expired intents are rejected, and a successful linked mutation settles the ghost automatically. Intents are ephemeral presence: never persisted, never snapshotted, auto-expire (~8s).',
+      'Ghost Cursor of Intent — announce the spatial move you are ABOUT to make so the canvas paints a faint pre-commit placeholder (legibility: the human sees the next move forming, and can veto it). Action "signal" registers an intent (kind create|move|connect|remove|edit; pass position for move — omit it for create to ghost where the canvas will place the node, and the linked create lands there — nodeId for move/edit/remove, edge for connect; optional label, reason, confidence 0..1, seq, ttlMs, and a stable id); "update" patches a live intent by id; "clear" abandons/dissolves it. To make veto authoritative, pass the returned id as intentId on the real canvas_node/canvas_edge/canvas_group/canvas_render mutation: vetoed or expired intents are rejected, and a successful linked mutation settles the ghost automatically. Intents are ephemeral presence: never persisted, never snapshotted, auto-expire (~8s).',
     actionSummary: 'signal | update | clear',
     actions: {
       signal: 'intent.signal',

package/src/server/operations/http.ts

@@ -20,7 +20,7 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
-function matchPath(template: string, pathname: string): Record<string, string> | null {
+export function matchOperationPath(template: string, pathname: string): Record<string, string> | null {
   const templateSegments = template.split('/');
   const pathSegments = pathname.split('/');
   if (templateSegments.length !== pathSegments.length) return null;
@@ -58,7 +58,7 @@ export async function readJsonValue(req: Request): Promise<unknown> {
   }
 }
 
-async function defaultReadInput(
+export async function readOperationInput(
   req: Request,
   params: Record<string, string>,
   url: URL,
@@ -80,12 +80,12 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
   for (const op of listOperations()) {
     const route = op.http;
     if (!route || route.method !== req.method) continue;
-    const params = matchPath(route.path, url.pathname);
+    const params = matchOperationPath(route.path, url.pathname);
     if (!params) continue;
     try {
       const input = route.readInput
         ? await route.readInput(req, params, url)
-        : await defaultReadInput(req, params, url);
+        : await readOperationInput(req, params, url);
       // The workbench marks its own HTTP calls: a human dragging/editing in
       // the browser is not agent activity, so it never synthesizes an
       // auto-ghost. Everything else (CLI, scripts, adapters) counts as agent.

package/src/server/operations/invoker.ts

@@ -32,13 +32,17 @@ export class LocalOperationInvoker implements OperationInvoker {
   private readonly proxiedRead: boolean;
 
   /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
-  constructor(source = 'api') {
+  constructor(
+    source = 'api',
+    private readonly allowExternalMcp = true,
+  ) {
     this.source = agentSourceLabel(source);
     this.proxiedRead = source === 'mcp';
   }
 
   async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
-    return await executeOperation(name, defaultPresenceSource(name, input, this.source), {
+    const args = this.allowExternalMcp ? input : { ...input, allowExternalMcp: false };
+    return await executeOperation(name, defaultPresenceSource(name, args, this.source), {
       source: this.source,
       proxiedRead: this.proxiedRead,
     });
@@ -56,14 +60,19 @@ export class HttpOperationInvoker implements OperationInvoker {
   private readonly proxiedRead: boolean;
 
   /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
-  constructor(baseUrl: string, source = 'api') {
+  constructor(
+    baseUrl: string,
+    source = 'api',
+    private readonly allowExternalMcp = true,
+  ) {
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.source = agentSourceLabel(source);
     this.proxiedRead = source === 'mcp';
   }
 
   async invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown> {
-    const input = defaultPresenceSource(name, rawInput, this.source);
+    const args = this.allowExternalMcp ? rawInput : { ...rawInput, allowExternalMcp: false };
+    const input = defaultPresenceSource(name, args, this.source);
     const op = getOperation(name);
     const route = op.http;
     if (!route) throw new OperationError(`Operation "${name}" has no HTTP route.`, 400);

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

@@ -13,7 +13,7 @@
  */
 import { agentPresence } from '../../agent-presence.js';
 import { z } from 'zod';
-import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../../agent-context.js';
+import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../../../shared/agent-context.js';
 import { buildCanvasAxContext, buildCanvasAxSurfaceSnapshot } from '../../ax-context.js';
 import { applyAxInteraction } from '../../ax-interaction.js';
 import {

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

@@ -502,6 +502,10 @@ const axReadsRecordShape = {
   source: z.string().optional().describe('Transport label (default "api").'),
   pinnedNodeIds: z.array(z.string()).optional().describe('Pins at read time; defaults to the current pins.'),
   deliveredNodeIds: z.array(z.string()).describe('Pinned ids present in what the agent received.'),
+  readNodeIds: z
+    .array(z.string())
+    .optional()
+    .describe('Ids of every serialized node in what the agent received; defaults to deliveredNodeIds.'),
   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.'),
 };
@@ -527,6 +531,7 @@ const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchem
         agentId: input.agentId ?? null,
         pinnedNodeIds: input.pinnedNodeIds ?? [...canvasState.contextPinnedNodeIds],
         deliveredNodeIds: input.deliveredNodeIds,
+        ...(input.readNodeIds ? { readNodeIds: input.readNodeIds } : {}),
         bytes: input.bytes,
       },
       input.boardId === undefined ? canvasState.activeBoardId : input.boardId,
@@ -535,6 +540,37 @@ const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchem
   },
 });
 
+const axReadsStatusShape = {
+  board: z.string().optional().describe('Board id; defaults to the open board.'),
+};
+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.
+ */
+const axReadsStatusOperation = defineOperation<z.infer<typeof axReadsStatusSchema>, Record<string, unknown>>({
+  name: 'ax.reads.status',
+  mutates: false,
+  input: axReadsStatusSchema,
+  inputShape: axReadsStatusShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/context-status',
+  },
+  handler: (input) => {
+    const boardId =
+      typeof input.board === 'string' && input.board.trim() ? input.board.trim() : canvasState.activeBoardId;
+    const pins =
+      boardId === canvasState.activeBoardId
+        ? canvasState.getContextPinMeta()
+        : boardId
+          ? (canvasState.readBoard(boardId, false)?.state.contextPinMeta ?? {})
+          : {};
+    return { ok: true, boardId, nodes: canvasState.getNodeReadStatus(boardId), pins };
+  },
+});
+
 export const axTimelineOperations: Operation[] = [
   axEventRecordOperation,
   axEvidenceAddOperation,
@@ -545,4 +581,5 @@ export const axTimelineOperations: Operation[] = [
   axCommandInvokeOperation,
   axReadsListOperation,
   axReadsRecordOperation,
+  axReadsStatusOperation,
 ];

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

@@ -15,7 +15,7 @@ import { z } from 'zod';
 import { normalizeBoardCategory } from '../../../shared/boards.js';
 import { canvasState, type CanvasLayout } from '../../canvas-state.js';
 import { openCanvasBoard } from '../../canvas-operations.js';
-import { summarizeNodeForAgentContext } from '../../agent-context.js';
+import { summarizeNodeForAgentContext } from '../../../shared/agent-context.js';
 import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
 
 export function boardsPayload(): Record<string, unknown> {

package/src/server/operations/ops/canvas-wire.ts

@@ -70,15 +70,15 @@ const applyUpdatesSchema = z.looseObject(applyUpdatesShape);
 
 const applyUpdatesOperation = defineOperation<z.infer<typeof applyUpdatesSchema>, Record<string, unknown>>({
   name: 'canvas.apply-updates',
-  mutates: false,
+  mutates: true,
   input: applyUpdatesSchema,
   inputShape: applyUpdatesShape,
   http: {
     method: 'POST',
     path: '/api/canvas/update',
   },
-  // Legacy wire: one layout update only when something actually applied.
-  handler: (input, ctx) => {
+  // The registry emits the layout update, as for other mutating operations.
+  handler: (input) => {
     const body: Record<string, unknown> = input;
     const updates = Array.isArray(body.updates) ? body.updates : [];
     const result =
@@ -94,9 +94,6 @@ const applyUpdatesOperation = defineOperation<z.infer<typeof applyUpdatesSchema>
             return suppressedResult;
           })()
         : applyCanvasNodeUpdates(updates);
-    if (result.applied > 0) {
-      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
-    }
     return { ok: true, ...result };
   },
 });

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

@@ -15,9 +15,12 @@
  */
 import { z } from 'zod';
 import { INTENT_EDGE_TYPES, INTENT_KINDS } from '../../../shared/ax-intent.js';
+import { canvasState } from '../../canvas-state.js';
 import { intentRegistry } from '../../intent-registry.js';
+import { findOpenCanvasPosition } from '../../placement.js';
 import { readJsonValue } from '../http.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
+import { defaultNodeSize } from './nodes.js';
 
 const positionShape = z.object({ x: z.number(), y: z.number() });
 
@@ -28,7 +31,11 @@ const intentSignalShape = {
     .enum(INTENT_KINDS)
     .optional()
     .describe('create | move | connect | remove | edit — the move about to be made.'),
-  position: positionShape.optional().describe('World coords: where a create forms, or the destination of a move.'),
+  position: positionShape
+    .optional()
+    .describe(
+      'World coords: the destination of a move, or where a create forms. Omit it for a create to ghost where the canvas will place the node.',
+    ),
   nodeId: z.string().optional().describe('The existing node a move/edit/remove targets.'),
   edge: z
     .object({ from: z.string(), to: z.string(), type: z.enum(INTENT_EDGE_TYPES) })
@@ -46,6 +53,24 @@ const intentSignalShape = {
 
 const intentSignalSchema = z.looseObject(intentSignalShape);
 
+/**
+ * Where a create without a position will land: the same auto-placement the
+ * create ops use, with live create ghosts as obstacles so staged ghosts do not
+ * stack. An agent announcing work before it knows the layout must not have to
+ * guess a position (a guessed 0,0 put every first ghost in the top-left corner).
+ */
+function openPositionForCreate(nodeType: unknown): { x: number; y: number } {
+  const size = defaultNodeSize(typeof nodeType === 'string' ? nodeType : 'markdown');
+  const ghosts = intentRegistry
+    .list()
+    .flatMap((intent) =>
+      intent.kind === 'create' && intent.position
+        ? [{ position: intent.position, size: defaultNodeSize(intent.nodeType ?? 'markdown') }]
+        : [],
+    );
+  return findOpenCanvasPosition([...canvasState.getLayout().nodes, ...ghosts], size.width, size.height);
+}
+
 const intentSignalOperation = defineOperation<z.infer<typeof intentSignalSchema>, Record<string, unknown>>({
   name: 'intent.signal',
   mutates: false,
@@ -53,7 +78,11 @@ const intentSignalOperation = defineOperation<z.infer<typeof intentSignalSchema>
   inputShape: intentSignalShape,
   http: { method: 'POST', path: '/api/canvas/ax/intent' },
   handler: (input) => {
-    const intent = intentRegistry.signal(input);
+    const placed =
+      input.kind === 'create' && !input.position
+        ? { ...input, position: openPositionForCreate(input.nodeType) }
+        : input;
+    const intent = intentRegistry.signal(placed);
     return { ok: true, intent } as unknown as Record<string, unknown>;
   },
 });