pmx-canvas 0.4.4 → 0.4.6

package/skills/pmx-canvas-orchestration/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pmx-canvas-orchestration
+description: Choreography for running multi-agent orchestration ON a PMX Canvas board — the agent host (Claude Code, Copilot, Codex) executes; the canvas is the shared graph, state, human-steering surface, and audit trail. Load this in the ORCHESTRATOR session and in EVERY subagent that touches the board.
+---
+
+# PMX Canvas Orchestration
+
+The division of labor is fixed: **the agent host runs the loop** (spawning, scheduling,
+fan-out/join, retries); **the canvas is the graph** (persistent shared state, the live visual,
+human gates and steering, the timeline). The canvas never executes anything. This skill is the
+choreography that makes that split work — both the orchestrator and every subagent must follow
+it, or the board silently diverges from reality.
+
+## Identity
+
+- Every participant picks a stable `agentId` (kebab-case role name: `orchestrator`,
+  `researcher`, `impl-auth`, …) and passes it on EVERY AX write that supports it (work items,
+  timeline events, steering). `source` stays the host label (`mcp`, `cli`, `amp`, …);
+  `agentId` is who within the host.
+- One canvas node + one work item per subagent, created BY THE ORCHESTRATOR at spawn time
+  (title = the agentId). The subagent updates its own work item; it never creates its own
+  identity row.
+- Tag every run: put the same `data.runId` on every NODE (work items carry no free-form data —
+  their run scoping comes from the run-prefixed `agentId`, e.g. `run7:impl-auth`), so
+  consecutive orchestrations don't interleave in the bounded timeline.
+
+## Graph semantics
+
+- `flow` edges = planned sequence. `depends-on` edges = blocking dependency (the visual DAG).
+  `relation`/`references` = context only — never scheduling.
+- The orchestrator owns the topology: it creates all nodes and edges up front with one
+  `canvas_batch`, then only mutates statuses. Subagents mutate their OWN node/work item only.
+- The host's real execution order is authoritative. When the host reorders or skips, the
+  orchestrator updates the edges — a board that contradicts execution is worse than no board.
+
+## Status discipline
+
+- Work-item status is the single source of step state: `todo → in-progress → done`
+  (or `blocked` / `cancelled`). Update the work item FIRST; linked nodes mirror the status automatically
+  (0.4.5+) — do not hand-edit a status node to fake progress.
+- Signal `canvas_intent` before each phase of visible board mutation (the auto-ghost floor
+  covers forgotten signals, but only an explicit signal gives the human a veto window and your
+  reasoning).
+
+## Gates and human input
+
+- ALL approval gates, elicitations, and mode requests are created and awaited by the
+  ORCHESTRATOR, never by subagents. `canvas_ax_gate { action: "await" }` blocks at most ~120s
+  per call — the orchestrator re-awaits in a loop; a subagent burning turns on a gate wait is
+  a bug.
+- A pending gate is NOT approval. Execution-class actions stay blocked until the gate is
+  explicitly `approved`.
+
+## Steering
+
+- Humans steer through the board; agents MUST poll for it — MCP notifications cannot wake a
+  subagent, so everything is pull. Cadence: check `canvas://ax-pending-steering` (or
+  `canvas_ax_delivery { action: "claim", consumer: "<agentId or host>" }`) between every major
+  step.
+- Address a specific agent with the steering `target` field (0.4.5+). Untargeted steers are
+  broadcast: only the ORCHESTRATOR claims them and re-routes; subagents claim only steers
+  targeted at their own `agentId`.
+- Mark delivery ONLY after acting on the message. The mark is compare-and-set: a
+  `delivered:false` response means another consumer owned it — drop it, do not act twice.
+
+## Run lifecycle
+
+1. Orchestrator: snapshot the board (`canvas_snapshot save`) before the run.
+2. Orchestrator: one `canvas_batch` creating the run's nodes + edges (+ `data.runId`), one
+   work item per step/subagent, intent-signaled.
+3. Spawn subagents; each loads this skill, learns its `agentId`, node id, and work-item id
+   from the spawn prompt.
+4. Subagents: flip work item to `in-progress`, do the work, attach evidence
+   (`canvas_ax_timeline { action: "add-evidence" }`), flip to `done`, poll steering between
+   steps.
+5. Orchestrator: join on host-side completion (the host knows the real DAG), resolve gates,
+   record a final timeline event, and validate the board (`canvas_query { action: "validate" }`).
+6. On abort/failure: leave work items in their true state (`blocked` + a timeline failure
+   event), never green-wash.
+
+The acceptance bar: a human watching the board and a human reading the host transcript must
+see the same story.

package/skills/pmx-canvas-testing/SKILL.md

@@ -95,6 +95,9 @@ Prefer extending the existing suites before inventing a one-off script.
 - When checking embedded frame fit manually, start from a clean seeded state, rebuild stale bundles,
   and inspect the actual iframe document in a browser. Server dimensions can look correct while the
   embedded content is still clipped.
+- User-facing creation flows must end with the new nodes visible: after the create (plus the
+  skill-mandated focus/fit), a screenshot must show them without any manual pan. A `panned: true`
+  API result alone is not proof — verify the frame is on-screen and unobscured.
 
 ## Failure Handling
 

package/src/cli/agent.ts

@@ -32,6 +32,7 @@ import './commands/webview.js';
 import './commands/apps.js';
 import './commands/copilot.js';
 import './commands/skills.js';
+import './commands/smoke.js';
 
 // Re-exported for existing importers (tests import it from this module).
 export { extractGlobalTargetFlags };
@@ -75,6 +76,7 @@ Canvas commands:
   pmx-canvas arrange [--layout MODE]  Auto-arrange (grid|column|flow)
   pmx-canvas batch [--file FILE]      Run many canvas operations at once
   pmx-canvas validate                 Check collisions and containment issues
+  pmx-canvas smoke                    One-command environment check of a running canvas
   pmx-canvas validate spec            Validate json-render/graph payloads without creating nodes
   pmx-canvas watch [options]          Watch semantic canvas changes over SSE
   pmx-canvas focus <id>               Pan viewport to node

package/src/cli/commands/ax.ts

@@ -53,6 +53,7 @@ cmd(
   [
     'pmx-canvas ax event add --kind tool-start --summary "ran tests"',
     'pmx-canvas ax event add --kind failure --summary "build broke" --detail "..." node1 node2',
+    'pmx-canvas ax event add --kind tool-start --summary "ran tests" --agent-id builder-1',
   ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
@@ -61,12 +62,14 @@ cmd(
     const kind = requireFlag(flags, 'kind', 'pmx-canvas ax event add --kind <kind> --summary <text>');
     const summary = requireFlag(flags, 'summary', 'pmx-canvas ax event add --kind <kind> --summary <text>');
     const detail = getStringFlag(flags, 'detail');
+    const agentId = getStringFlag(flags, 'agent-id');
 
     output(
       await invokeOperation('ax.event.record', {
         kind,
         summary,
         ...(detail ? { detail } : {}),
+        ...(agentId ? { agentId } : {}),
         ...(positional.length > 0 ? { nodeIds: positional } : {}),
         source: resolveAxSource(flags),
       }),
@@ -77,7 +80,11 @@ cmd(
 cmd(
   'ax steer',
   'Send a steering message to the active agent session',
-  ['pmx-canvas ax steer "focus on the failing test first"', 'pmx-canvas ax steer --message "stop and re-plan"'],
+  [
+    'pmx-canvas ax steer "focus on the failing test first"',
+    'pmx-canvas ax steer --message "stop and re-plan"',
+    'pmx-canvas ax steer "wave 2 is unblocked" --agent-id orchestrator --target builder-1',
+  ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('ax steer');
@@ -86,8 +93,17 @@ cmd(
     if (!message) {
       die('Missing steering message', 'pmx-canvas ax steer <message>');
     }
+    const agentId = getStringFlag(flags, 'agent-id');
+    const target = getStringFlag(flags, 'target');
 
-    output(await invokeOperation('ax.steer', { message, source: resolveAxSource(flags) }));
+    output(
+      await invokeOperation('ax.steer', {
+        message,
+        ...(agentId ? { agentId } : {}),
+        ...(target ? { target } : {}),
+        source: resolveAxSource(flags),
+      }),
+    );
   },
 );
 
@@ -374,6 +390,7 @@ cmd(
   [
     'pmx-canvas ax work add --title "Wire up auth" --status in-progress',
     'pmx-canvas ax work add --title "Review API" node1 node2',
+    'pmx-canvas ax work add --title "Wire up auth" --agent-id builder-1',
   ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
@@ -382,12 +399,14 @@ cmd(
     const title = requireFlag(flags, 'title', 'pmx-canvas ax work add --title <text>');
     const status = getStringFlag(flags, 'status');
     const detail = getStringFlag(flags, 'detail');
+    const agentId = getStringFlag(flags, 'agent-id');
 
     output(
       await invokeOperation('ax.work.create', {
         title,
         ...(status ? { status } : {}),
         ...(detail ? { detail } : {}),
+        ...(agentId ? { agentId } : {}),
         ...(positional.length > 0 ? { nodeIds: positional } : {}),
         source: resolveAxSource(flags),
       }),
@@ -398,7 +417,11 @@ cmd(
 cmd(
   'ax work update',
   'Update a canvas-bound AX work item by ID',
-  ['pmx-canvas ax work update <id> --status done', 'pmx-canvas ax work update <id> --title "New title" --detail "..."'],
+  [
+    'pmx-canvas ax work update <id> --status done',
+    'pmx-canvas ax work update <id> --title "New title" --detail "..."',
+    'pmx-canvas ax work update <id> --agent-id builder-2',
+  ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('ax work update');
@@ -408,6 +431,7 @@ cmd(
     const title = getStringFlag(flags, 'title');
     const status = getStringFlag(flags, 'status');
     const detail = getStringFlag(flags, 'detail');
+    const agentId = getStringFlag(flags, 'agent-id');
 
     output(
       await invokeOperation('ax.work.update', {
@@ -415,6 +439,7 @@ cmd(
         ...(title ? { title } : {}),
         ...(status ? { status } : {}),
         ...(detail ? { detail } : {}),
+        ...(agentId ? { agentId } : {}),
         ...(positional.length > 1 ? { nodeIds: positional.slice(1) } : {}),
         source: resolveAxSource(flags),
       }),

package/src/cli/commands/skills.ts

@@ -13,7 +13,7 @@ import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { cmd, output, parseFlags, showCommandHelp } from '../shared.js';
 
-export const BUNDLED_SKILLS = ['pmx-canvas', 'pmx-canvas-testing'] as const;
+export const BUNDLED_SKILLS = ['pmx-canvas', 'pmx-canvas-testing', 'pmx-canvas-orchestration'] as const;
 
 function listFilesRecursive(root: string, prefix = ''): string[] {
   const out: string[] = [];

package/src/cli/commands/smoke.ts

@@ -0,0 +1,212 @@
+// One-command environment check: does a running canvas actually work here?
+//
+// Runs the checks every host test report hand-rolls — health + workspace,
+// MCP stdio initialize, a temp-node create/search/remove round-trip, and
+// structural board validation — and reports them as a single JSON result
+// with a pass/fail exit code. Designed for fresh orbs/hosts: `pmx-canvas
+// smoke` answers "does the canvas work in this environment?" in one call.
+//
+// The command tests a RUNNING server (like every other agent command); it
+// never starts one. Board validation gates only on structural issues
+// (missing edge endpoints) — node overlaps are a layout choice on real
+// boards, so collisions are reported but never fail the smoke.
+
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { HttpOperationInvoker } from '../../server/operations/index.js';
+import { cmd, getBaseUrl, isRecord, output, parseFlags, showCommandHelp } from '../shared.js';
+
+interface SmokeCheck {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+const MCP_INITIALIZE_TIMEOUT_MS = 10_000;
+
+function cliPackageVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf-8')) as {
+      version?: string;
+    };
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+async function checkHealth(baseUrl: string, cliVersion: string): Promise<SmokeCheck & { serverVersion?: string }> {
+  const name = 'health';
+  let body: unknown;
+  try {
+    const response = await fetch(`${baseUrl}/health`);
+    if (!response.ok) return { name, ok: false, detail: `GET /health returned HTTP ${response.status}` };
+    body = await response.json();
+  } catch (error) {
+    return {
+      name,
+      ok: false,
+      detail: `Cannot connect to pmx-canvas at ${baseUrl}: ${error instanceof Error ? error.message : String(error)}. Start the server first: pmx-canvas --no-open`,
+    };
+  }
+  if (!isRecord(body) || body.ok !== true) {
+    return { name, ok: false, detail: `GET /health returned an unhealthy body: ${JSON.stringify(body)}` };
+  }
+  const serverVersion = typeof body.version === 'string' ? body.version : 'unknown';
+  const persistence = isRecord(body.persistence) && body.persistence.ok === false ? 'DEGRADED' : 'ok';
+  const skew =
+    serverVersion !== 'unknown' && serverVersion !== cliVersion
+      ? ` — differs from CLI v${cliVersion} (version skew)`
+      : '';
+  return {
+    name,
+    ok: true,
+    serverVersion,
+    detail: `workspace ${String(body.workspace)}, server v${serverVersion}${skew}, pid ${String(body.pid)}, persistence ${persistence}`,
+  };
+}
+
+/**
+ * Spawn the bundled MCP server over stdio (same entry `pmx-canvas --mcp`
+ * runs) and verify a JSON-RPC initialize handshake completes. The transport
+ * is newline-delimited JSON; the child is killed as soon as the response
+ * with our request id arrives.
+ */
+function checkMcpInitialize(cliVersion: string): Promise<SmokeCheck> {
+  const name = 'mcp-initialize';
+  const entry = fileURLToPath(new URL('../../mcp/server.ts', import.meta.url));
+  return new Promise((resolveCheck) => {
+    const child = spawn(process.execPath, ['run', entry], {
+      stdio: ['pipe', 'pipe', 'ignore'],
+      env: process.env,
+    });
+    let settled = false;
+    let stdoutBuffer = '';
+    const finish = (ok: boolean, detail: string) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill();
+      resolveCheck({ name, ok, detail });
+    };
+    const timer = setTimeout(
+      () => finish(false, `no initialize response within ${MCP_INITIALIZE_TIMEOUT_MS}ms`),
+      MCP_INITIALIZE_TIMEOUT_MS,
+    );
+    child.on('error', (error) => finish(false, `failed to spawn MCP server: ${error.message}`));
+    child.on('exit', (code) => finish(false, `MCP server exited before responding (code ${code ?? 'unknown'})`));
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdoutBuffer += chunk.toString('utf-8');
+      const lines = stdoutBuffer.split('\n');
+      stdoutBuffer = lines.pop() ?? '';
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let message: unknown;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (!isRecord(message) || message.id !== 1) continue;
+        const result = isRecord(message.result) ? message.result : null;
+        const serverInfo = result && isRecord(result.serverInfo) ? result.serverInfo : null;
+        if (serverInfo) {
+          finish(true, `initialize ok: ${String(serverInfo.name)} v${String(serverInfo.version)}`);
+        } else {
+          finish(false, `initialize returned an error: ${JSON.stringify(message.error ?? message)}`);
+        }
+        return;
+      }
+    });
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-06-18',
+          capabilities: {},
+          clientInfo: { name: 'pmx-canvas-smoke', version: cliVersion },
+        },
+      })}\n`,
+    );
+  });
+}
+
+async function checkNodeLifecycle(invoker: HttpOperationInvoker): Promise<SmokeCheck> {
+  const name = 'node-lifecycle';
+  const marker = `pmx-smoke-${Math.random().toString(36).slice(2, 10)}`;
+  const searchHits = async (): Promise<Set<string>> => {
+    const result = await invoker.invoke('search', { q: marker });
+    const results = isRecord(result) && Array.isArray(result.results) ? result.results : [];
+    return new Set(results.filter(isRecord).map((entry) => String(entry.id)));
+  };
+  let nodeId: string | null = null;
+  try {
+    const added = await invoker.invoke('node.add', {
+      type: 'markdown',
+      title: marker,
+      content: `Temporary smoke-check node (${marker}). Safe to remove.`,
+      x: 100_000,
+      y: 100_000,
+    });
+    const node = isRecord(added) && isRecord(added.node) ? added.node : null;
+    nodeId = node && typeof node.id === 'string' ? node.id : null;
+    if (!nodeId) return { name, ok: false, detail: `node.add returned no node id: ${JSON.stringify(added)}` };
+    const found = (await searchHits()).has(nodeId);
+    // Remove BEFORE reporting either way: an early return here (search miss —
+    // exactly the version-skew case this command exists to detect) would skip
+    // the catch-block cleanup and park the temp node on the user's real board.
+    await invoker.invoke('node.remove', { id: nodeId });
+    nodeId = null;
+    if (!found) return { name, ok: false, detail: 'search did not find the created node' };
+    return { name, ok: true, detail: 'create → search → remove round-trip ok' };
+  } catch (error) {
+    // Best-effort cleanup so a failed smoke never leaves its temp node behind.
+    if (nodeId) await invoker.invoke('node.remove', { id: nodeId }).catch(() => {});
+    return { name, ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+async function checkValidation(invoker: HttpOperationInvoker): Promise<SmokeCheck> {
+  const name = 'validate';
+  try {
+    const result = await invoker.invoke('validate.get', {});
+    const summary = isRecord(result) && isRecord(result.summary) ? result.summary : {};
+    const missingEdgeEndpoints = Number(summary.missingEdgeEndpoints ?? 0);
+    const detail = `${String(summary.nodes ?? '?')} nodes, ${String(summary.edges ?? '?')} edges, ${String(
+      summary.collisions ?? '?',
+    )} collisions (informational), ${missingEdgeEndpoints} broken edges`;
+    return { name, ok: missingEdgeEndpoints === 0, detail };
+  } catch (error) {
+    return { name, ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+cmd(
+  'smoke',
+  'One-command check that a running canvas works in this environment',
+  ['pmx-canvas smoke', 'pmx-canvas smoke --skip-mcp', 'pmx-canvas smoke --port 4750'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('smoke');
+
+    const baseUrl = getBaseUrl();
+    const cliVersion = cliPackageVersion();
+    const invoker = new HttpOperationInvoker(baseUrl);
+    const checks: SmokeCheck[] = [];
+
+    const health = await checkHealth(baseUrl, cliVersion);
+    checks.push({ name: health.name, ok: health.ok, detail: health.detail });
+    if (health.ok) {
+      if (!flags['skip-mcp']) checks.push(await checkMcpInitialize(cliVersion));
+      checks.push(await checkNodeLifecycle(invoker));
+      checks.push(await checkValidation(invoker));
+    }
+
+    const ok = checks.every((check) => check.ok);
+    output({ ok, target: baseUrl, cliVersion, serverVersion: health.serverVersion ?? null, checks });
+    if (!ok) process.exit(1);
+  },
+);

package/src/cli/index.ts

@@ -67,6 +67,7 @@ const AGENT_COMMANDS = new Set([
   'serve',
   'copilot',
   'skills',
+  'smoke',
 ]);
 
 const firstArg = args[0] ?? '';
@@ -166,7 +167,13 @@ const serveSubcommand = firstArg === 'serve' ? (args[1] ?? '') : '';
 
 if (firstArg === 'serve' && (serveSubcommand === 'status' || serveSubcommand === 'stop')) {
   const port = parseInt(
-    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    readOption('port') ??
+      process.env.PMX_WEB_CANVAS_PORT ??
+      process.env.PMX_CANVAS_PORT ??
+      // Amp orbs assign the portal port via $PORT; honored only under AMP_ORB
+      // so a stray PORT in normal shells never shifts the default.
+      (process.env.AMP_ORB ? process.env.PORT || undefined : undefined) ??
+      '4313',
     10,
   );
   const daemonLogFile = resolve(readOption('log-file') ?? `.pmx-canvas/daemon-${port}.log`);
@@ -214,7 +221,13 @@ if (AGENT_COMMANDS.has(routedCommand) && routedCommand !== 'serve') {
 } else {
   // "serve" is also accessible via flags (backward compat)
   const port = parseInt(
-    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    readOption('port') ??
+      process.env.PMX_WEB_CANVAS_PORT ??
+      process.env.PMX_CANVAS_PORT ??
+      // Amp orbs assign the portal port via $PORT; honored only under AMP_ORB
+      // so a stray PORT in normal shells never shifts the default.
+      (process.env.AMP_ORB ? process.env.PORT || undefined : undefined) ??
+      '4313',
     10,
   );
   const demo = hasFlag('demo');

package/src/cli/shared.ts

@@ -164,6 +164,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
     'files',
     'ui-prompts',
     'check',
+    'skip-mcp',
   ]);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];

package/src/client/canvas/CanvasNode.tsx

@@ -140,7 +140,15 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     requestAnimationFrame(() => renameRef.current?.focus());
   }, []);
 
-  const title = (node.data.title as string) || TYPE_LABELS[node.type];
+  const title =
+    (node.data.title as string) ||
+    // Untitled file nodes (created before titles were synthesized server-side)
+    // still show their filename instead of a bare type label.
+    (node.type === 'file'
+      ? // Separator-agnostic: node paths are OS-native (backslashes on Windows).
+        (((node.data.path as string) || (node.data.content as string) || '').split(/[\\/]/).pop() ?? '')
+      : '') ||
+    TYPE_LABELS[node.type];
 
   const commitRename = useCallback(
     (value: string) => {
@@ -254,6 +262,9 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
           })()}
         </span>
         <span class="node-type-badge">{TYPE_LABELS[node.type]}</span>
+        {typeof node.data.axWorkStatus === 'string' && (
+          <span class={`node-ax-status node-ax-status-${node.data.axWorkStatus}`}>{node.data.axWorkStatus}</span>
+        )}
         {renaming ? (
           <input
             ref={renameRef}

package/src/client/canvas/CanvasViewport.tsx

@@ -1,8 +1,10 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 import { ContextNode } from '../nodes/ContextNode';
+import { DiffNode } from '../nodes/DiffNode';
 import { FileNode } from '../nodes/FileNode';
 import { LedgerNode } from '../nodes/LedgerNode';
 import { MarkdownNode } from '../nodes/MarkdownNode';
+import { MermaidNode } from '../nodes/MermaidNode';
 import { McpAppNode } from '../nodes/McpAppNode';
 import { StatusNode } from '../nodes/StatusNode';
 import { ImageNode } from '../nodes/ImageNode';
@@ -64,6 +66,10 @@ function renderNodeContent(node: CanvasNodeState) {
       return <TraceNode node={node} />;
     case 'file':
       return <FileNode node={node} />;
+    case 'diff':
+      return <DiffNode node={node} />;
+    case 'mermaid':
+      return <MermaidNode node={node} />;
     case 'image':
       return <ImageNode node={node} />;
     case 'html':

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -1,9 +1,11 @@
 import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { ContextNode } from '../nodes/ContextNode';
+import { DiffNode } from '../nodes/DiffNode';
 import { FileNode } from '../nodes/FileNode';
 import { LedgerNode } from '../nodes/LedgerNode';
 import { MarkdownNode } from '../nodes/MarkdownNode';
+import { MermaidNode } from '../nodes/MermaidNode';
 import { McpAppNode } from '../nodes/McpAppNode';
 import { StatusNode } from '../nodes/StatusNode';
 import { ImageNode } from '../nodes/ImageNode';
@@ -50,6 +52,10 @@ function renderContent(node: CanvasNodeState, expanded: boolean) {
       return <TraceNode node={node} />;
     case 'file':
       return <FileNode node={node} expanded={expanded} />;
+    case 'diff':
+      return <DiffNode node={node} />;
+    case 'mermaid':
+      return <MermaidNode node={node} expanded={expanded} />;
     case 'image':
       return <ImageNode node={node} expanded={expanded} />;
     case 'html':
@@ -64,6 +70,10 @@ function getNodeTextContent(node: CanvasNodeState): string {
   switch (node.type) {
     case 'markdown':
       return (node.data.content as string) || '';
+    case 'diff':
+      return (node.data.content as string) || '';
+    case 'mermaid':
+      return (node.data.content as string) || '';
     case 'file':
       return (node.data.fileContent as string) || '';
     case 'webpage':

package/src/client/canvas/IntentLayer.tsx

@@ -59,8 +59,10 @@ function center(rect: Rect): { x: number; y: number } {
 }
 
 function ghostOpacity(intent: ClientIntent): number {
-  if (typeof intent.confidence !== 'number') return 0.82;
-  return 0.4 + Math.max(0, Math.min(1, intent.confidence)) * 0.55;
+  const base = typeof intent.confidence !== 'number' ? 0.82 : 0.4 + Math.max(0, Math.min(1, intent.confidence)) * 0.55;
+  // Auto-ghosts (server-synthesized, no deliberate signal) read lighter than
+  // an explicit canvas_intent so the two are visually distinguishable.
+  return intent.auto ? base * 0.62 : base;
 }
 
 function bezierPath(a: { x: number; y: number }, b: { x: number; y: number }): string {
@@ -89,7 +91,7 @@ function GhostInfo({ intent }: { intent: ClientIntent }) {
         )}
         <span class="intent-chip-label">{label}</span>
         {confidencePct && <span class="intent-confidence">{confidencePct}</span>}
-        {intent.phase === 'forming' && (
+        {intent.phase === 'forming' && !intent.auto && (
           <button
             type="button"
             class="intent-veto"
@@ -114,7 +116,7 @@ function GhostBox({ intent, rect }: { intent: ClientIntent; rect: Rect }) {
   const typeLabel = isKnownNodeType(intent.nodeType) ? TYPE_LABELS[intent.nodeType] : 'Node';
   return (
     <div
-      class={`intent-ghost intent-ghost-box is-${intent.phase}`}
+      class={`intent-ghost intent-ghost-box is-${intent.phase}${intent.auto ? ' is-auto' : ''}`}
       data-intent-id={intent.id}
       style={{
         left: `${rect.left}px`,
@@ -138,7 +140,7 @@ function GhostBox({ intent, rect }: { intent: ClientIntent; rect: Rect }) {
 function GhostOverlay({ intent, rect, variant }: { intent: ClientIntent; rect: Rect; variant: 'remove' | 'edit' }) {
   return (
     <div
-      class={`intent-ghost intent-ghost-${variant} is-${intent.phase}`}
+      class={`intent-ghost intent-ghost-${variant} is-${intent.phase}${intent.auto ? ' is-auto' : ''}`}
       data-intent-id={intent.id}
       style={{
         left: `${rect.left}px`,
@@ -199,7 +201,7 @@ function renderGhost(intent: ClientIntent) {
       return (
         <div
           key={intent.id}
-          class={`intent-ghost intent-ghost-connect is-${intent.phase}`}
+          class={`intent-ghost intent-ghost-connect is-${intent.phase}${intent.auto ? ' is-auto' : ''}`}
           data-intent-id={intent.id}
           style={{
             left: `${rect.left}px`,

package/src/client/canvas/Minimap.tsx

@@ -36,6 +36,8 @@ function getNodeColors(): Record<CanvasNodeState['type'], string> {
     ledger: t.dim,
     trace: t.purple,
     file: t.accent,
+    diff: t.ok,
+    mermaid: t.purple,
     image: t.ok,
     html: t.warn,
     group: t.dim,

package/src/client/canvas/auto-fit.ts

@@ -21,6 +21,7 @@ export const AUTO_FIT_BODY_PADDING = 24;
 function isIframeNode(node: CanvasNodeState): boolean {
   return (
     node.type === 'html' ||
+    node.type === 'mermaid' ||
     node.type === 'json-render' ||
     node.type === 'graph' ||
     node.type === 'mcp-app' ||
@@ -33,6 +34,7 @@ function isIframeNode(node: CanvasNodeState): boolean {
  *  viewers (unbounded/scrolling content that must not drive node height). */
 function isContentFitSurface(node: CanvasNodeState): boolean {
   if (node.type === 'html') return node.data.presentation !== true;
+  if (node.type === 'mermaid') return true;
   if (node.type === 'json-render' || node.type === 'graph') return true;
   if (node.type === 'mcp-app') return node.data.viewerType === 'web-artifact';
   return false;

package/src/client/icons.tsx

@@ -473,6 +473,10 @@ export function getNodeIcon(type: string): (p: IconProps) => JSX.Element {
       return IconNodeResponse;
     case 'file':
       return IconNodeFile;
+    case 'diff':
+      return IconNodeFile;
+    case 'mermaid':
+      return IconNodeGraph;
     case 'image':
       return IconNodeImage;
     case 'webpage':