pmx-canvas 0.4.4 → 0.4.5

package/src/server/canvas-state.ts

@@ -1716,18 +1716,61 @@ class CanvasStateManager {
   }
 
   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 {
-    return this.ax.addWorkItem(input, options);
+    const item = this.ax.addWorkItem(input, options);
+    this.mirrorAxWorkStatusToNodes(item.nodeIds, [], item.status);
+    return item;
   }
 
   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 {
-    return this.ax.updateWorkItem(id, patch, options);
+    const previousNodeIds = this.ax.getWorkItems().find((w) => w.id === id)?.nodeIds ?? [];
+    const item = this.ax.updateWorkItem(id, patch, options);
+    if (!item) return null;
+    this.mirrorAxWorkStatusToNodes(item.nodeIds, previousNodeIds, item.status);
+    return item;
+  }
+
+  /**
+   * Mirror a work item's status onto every linked canvas node's `data.axWorkStatus`,
+   * through the standard node-update path (persistence + undo/redo, same as any other
+   * node data change). Nodes unlinked by an updateWorkItem nodeIds change have the
+   * mirrored status cleared.
+   */
+  private mirrorAxWorkStatusToNodes(nodeIds: string[], previousNodeIds: string[], status: PmxAxWorkItemStatus): void {
+    for (const nodeId of nodeIds) {
+      const node = this.nodes.get(nodeId);
+      if (!node) continue;
+      // No-op guard: a title-/agentId-only work-item patch must not push
+      // history entries and SSE churn for chips that aren't changing.
+      if (node.data.axWorkStatus === status) continue;
+      this.updateNode(nodeId, { data: { ...node.data, axWorkStatus: status } });
+    }
+    for (const nodeId of previousNodeIds) {
+      if (nodeIds.includes(nodeId)) continue;
+      const node = this.nodes.get(nodeId);
+      if (!node || node.data.axWorkStatus === undefined) continue;
+      const data = { ...node.data };
+      delete data.axWorkStatus;
+      this.updateNode(nodeId, { data });
+    }
   }
 
   // ── Approval gates (canvas-bound) ─────────────────────────────────
@@ -1873,7 +1916,7 @@ class CanvasStateManager {
       nodeIds?: string[];
       data?: Record<string, unknown> | null;
     },
-    options: { source?: PmxAxSource } = {},
+    options: { source?: PmxAxSource; agentId?: string | null } = {},
   ): PmxAxEvent {
     return this.ax.recordAxEvent(input, options);
   }
@@ -1892,7 +1935,10 @@ class CanvasStateManager {
     return this.ax.addEvidence(input, options);
   }
 
-  recordSteeringMessage(message: string, options: { source?: PmxAxSource } = {}): PmxAxSteeringMessage {
+  recordSteeringMessage(
+    message: string,
+    options: { source?: PmxAxSource; agentId?: string | null; target?: string | null } = {},
+  ): PmxAxSteeringMessage {
     return this.ax.recordSteeringMessage(message, options);
   }
 

package/src/server/intent-registry.ts

@@ -50,6 +50,7 @@ const intentSignalSchema = z.looseObject({
   seq: z.number().int().min(0).max(9999).optional(),
   ttlMs: z.number().positive().max(MAX_INTENT_TTL_MS).optional(),
   source: z.string().max(60).optional(),
+  auto: z.boolean().optional(),
 });
 
 const intentUpdateSchema = z.looseObject({
@@ -146,6 +147,7 @@ export class IntentRegistry {
       ...(typeof input.confidence === 'number' ? { confidence: input.confidence } : {}),
       ...(typeof input.seq === 'number' ? { seq: input.seq } : {}),
       ...(input.source ? { source: input.source } : {}),
+      ...(input.auto === true ? { auto: true } : {}),
       createdAt: existing?.createdAt ?? now,
       expiresAt: now + ttl,
     };

package/src/server/operations/http.ts

@@ -84,7 +84,11 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       const input = route.readInput
         ? await route.readInput(req, params, url)
         : await defaultReadInput(req, params, url);
-      const result = await executeOperation(op.name, input);
+      // 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.
+      const fromWorkbench = req.headers.get('x-pmx-workbench') === '1';
+      const result = await executeOperation(op.name, input, { suppressAutoGhost: fromWorkbench });
       return responseJson(result, route.status ? route.status(result) : 200);
     } catch (error) {
       if (error instanceof OperationError) {

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

@@ -12,11 +12,30 @@ import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { PmxAxSource } from '../../ax-state.js';
 
-export const AX_SOURCES = ['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'] as const;
+export const AX_SOURCES = [
+  'agent',
+  'amp',
+  'api',
+  'browser',
+  'cli',
+  'codex',
+  'copilot',
+  'mcp',
+  'sdk',
+  'system',
+] as const;
 
 /** Zod schema for the optional `source` field shared by AX MCP tool shapes. */
 export const AX_SOURCE_SHAPE = z.enum(AX_SOURCES).optional().describe('Optional host/source label. Defaults to mcp.');
 
+/** Zod schema for the optional `agentId` field shared by AX MCP tool shapes. */
+export const AX_AGENT_ID_SHAPE = z
+  .string()
+  .min(1)
+  .max(80)
+  .optional()
+  .describe('Per-agent identity within the host (orchestration); source stays the host label.');
+
 /** An absent or unrecognized source falls back to the per-surface default. */
 export function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource {
   return (AX_SOURCES as readonly string[]).includes(value as string) ? (value as PmxAxSource) : fallback;

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

@@ -27,7 +27,7 @@ import { buildCanvasAxContext } from '../../ax-context.js';
 import type { PmxAxPolicy } from '../../ax-state.js';
 import { defineOperation, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
-import { normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
+import { AX_SOURCES, normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
 
 // ── ax.get (canvas_get_ax) ────────────────────────────────────
 
@@ -112,7 +112,7 @@ const axFocusSetOperation = defineOperation<z.infer<typeof axFocusSetSchema>, Re
     extraShape: {
       nodeIds: z.array(z.string()).describe('Node IDs to place in the AX focus field. Missing nodes are ignored.'),
       source: z
-        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .enum(AX_SOURCES)
         .optional()
         .describe(
           'Optional host/source label for adapter-originated focus. Defaults to mcp. Use codex from the Codex app adapter.',
@@ -167,7 +167,7 @@ const axPolicySetOperation = defineOperation<z.infer<typeof axPolicySetSchema>,
         })
         .optional(),
       prompt: z.object({ systemAppend: z.string().optional(), mode: z.string().optional() }).optional(),
-      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']).optional(),
+      source: z.enum(AX_SOURCES).optional(),
     },
     // Legacy MCP tool forwarded only the present tools/prompt fields (source split out).
     buildInput: (input) => ({
@@ -236,10 +236,7 @@ const axHostCapabilityReportOperation = defineOperation<
       files: z.boolean().optional(),
       uiPrompts: z.boolean().optional(),
       raw: z.record(z.string(), z.unknown()).optional().describe('Optional raw capability payload for diagnostics.'),
-      source: z
-        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
-        .optional()
-        .describe('Optional host/source label. Defaults to mcp.'),
+      source: z.enum(AX_SOURCES).optional().describe('Optional host/source label. Defaults to mcp.'),
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: (result) => {

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

@@ -51,7 +51,13 @@ import { buildPendingAxActivity, isAxEventKind, isAxEvidenceKind } from '../../a
 import type { PmxAxEventKind, PmxAxEvidenceKind } from '../../ax-state.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
-import { AX_SOURCE_SHAPE, axJsonResult, normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
+import {
+  AX_AGENT_ID_SHAPE,
+  AX_SOURCE_SHAPE,
+  axJsonResult,
+  normalizeAxNodeIds,
+  normalizeAxSource,
+} from './ax-shared.js';
 
 const AX_EVENT_KINDS = [
   'prompt',
@@ -73,6 +79,7 @@ const axEventRecordShape = {
   nodeIds: z.unknown().optional().describe('Optional node IDs this event relates to.'),
   data: z.unknown().optional().describe('Optional structured data payload.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
 };
 
 const axEventRecordSchema = z.looseObject(axEventRecordShape);
@@ -97,6 +104,7 @@ const axEventRecordOperation = defineOperation<z.infer<typeof axEventRecordSchem
       nodeIds: z.array(z.string()).optional().describe('Optional node IDs this event relates to.'),
       data: z.record(z.string(), z.unknown()).optional().describe('Optional structured data payload.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -113,7 +121,10 @@ const axEventRecordOperation = defineOperation<z.infer<typeof axEventRecordSchem
         nodeIds: normalizeAxNodeIds(input.nodeIds),
         data: isRecord(input.data) ? input.data : null,
       },
-      { source: normalizeAxSource(input.source, 'api') },
+      {
+        source: normalizeAxSource(input.source, 'api'),
+        ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
+      },
     );
     ctx.emit('ax-event-created', { event });
     return { ok: true, event } as unknown as Record<string, unknown>;
@@ -184,6 +195,8 @@ const axEvidenceAddOperation = defineOperation<z.infer<typeof axEvidenceAddSchem
 const axSteerShape = {
   message: z.unknown().optional().describe('The steering instruction to deliver to the active agent session.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
+  target: z.unknown().optional().describe('Optional agentId/consumer this steer is addressed to. Omit to broadcast.'),
 };
 
 const axSteerSchema = z.looseObject(axSteerShape);
@@ -204,6 +217,13 @@ const axSteerOperation = defineOperation<z.infer<typeof axSteerSchema>, Record<s
     extraShape: {
       message: z.string().describe('The steering instruction to deliver to the active agent session.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
+      target: z
+        .string()
+        .min(1)
+        .max(80)
+        .optional()
+        .describe('The agentId/consumer this steer is addressed to. Omit to broadcast to all consumers.'),
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -214,6 +234,8 @@ const axSteerOperation = defineOperation<z.infer<typeof axSteerSchema>, Record<s
     }
     const steering = canvasState.recordSteeringMessage(input.message, {
       source: normalizeAxSource(input.source, 'api'),
+      ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
+      ...(typeof input.target === 'string' ? { target: input.target } : {}),
     });
     ctx.emit('ax-event-created', { steering });
     return { ok: true, steering } as unknown as Record<string, unknown>;
@@ -328,7 +350,8 @@ const axDeliveryMarkOperation = defineOperation<z.infer<typeof axDeliveryMarkSch
   },
   mcp: {
     toolName: 'canvas_mark_ax_delivery',
-    description: 'Mark a PMX AX steering message as delivered so it is not handed out again.',
+    description:
+      'Mark a PMX AX steering message as delivered so it is not handed out again. Compare-and-set: `delivered:true` only on the actual undelivered→delivered transition — a false means the id was unknown OR another consumer already marked it, so do NOT treat the message as your delivery.',
     extraShape: {
       id: z.string().describe('The steering message id to mark delivered.'),
     },

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

@@ -57,7 +57,14 @@ import type {
 } from '../../ax-state.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
-import { AX_SOURCE_SHAPE, AX_SOURCES, axJsonResult, normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
+import {
+  AX_AGENT_ID_SHAPE,
+  AX_SOURCE_SHAPE,
+  AX_SOURCES,
+  axJsonResult,
+  normalizeAxNodeIds,
+  normalizeAxSource,
+} from './ax-shared.js';
 
 const AX_WORK_ITEM_STATUSES = new Set(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
 function normalizeAxWorkItemStatus(value: unknown): PmxAxWorkItemStatus | undefined {
@@ -98,6 +105,7 @@ const axWorkCreateShape = {
   detail: z.unknown().optional().describe('Optional longer description.'),
   nodeIds: z.unknown().optional().describe('Optional node IDs this work item is tied to.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
 };
 
 const axWorkCreateSchema = z.looseObject(axWorkCreateShape);
@@ -124,6 +132,7 @@ const axWorkCreateOperation = defineOperation<z.infer<typeof axWorkCreateSchema>
       detail: z.string().optional().describe('Optional longer description.'),
       nodeIds: z.array(z.string()).optional().describe('Optional node IDs this work item is tied to.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -146,10 +155,18 @@ const axWorkCreateOperation = defineOperation<z.infer<typeof axWorkCreateSchema>
         ...(status ? { status } : {}),
         ...(typeof input.detail === 'string' ? { detail: input.detail } : {}),
         ...(Array.isArray(input.nodeIds) ? { nodeIds: normalizeAxNodeIds(input.nodeIds) } : {}),
+        ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
       },
       { source: normalizeAxSource(input.source, 'api') },
     );
     ctx.emit('ax-state-changed', { workItem });
+    // The status mirror writes data.axWorkStatus onto linked nodes, but this
+    // op is mutates:false (AX writes must not spam layout frames) — so emit
+    // the ONE layout frame ourselves when links exist, or open boards never
+    // see the chip until an unrelated mutation happens to refresh them.
+    if (workItem.nodeIds.length > 0) {
+      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    }
     return { ok: true, workItem } as unknown as Record<string, unknown>;
   },
 });
@@ -163,6 +180,7 @@ const axWorkUpdateShape = {
   detail: z.unknown().optional().describe('New detail text.'),
   nodeIds: z.unknown().optional().describe('Replacement node IDs.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
 };
 
 const axWorkUpdateSchema = z.looseObject(axWorkUpdateShape);
@@ -187,6 +205,7 @@ const axWorkUpdateOperation = defineOperation<z.infer<typeof axWorkUpdateSchema>
       detail: z.string().optional().describe('New detail text.'),
       nodeIds: z.array(z.string()).optional().describe('Replacement node IDs.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -207,11 +226,18 @@ const axWorkUpdateOperation = defineOperation<z.infer<typeof axWorkUpdateSchema>
         ...(status ? { status } : {}),
         ...(typeof input.detail === 'string' || input.detail === null ? { detail: input.detail as string | null } : {}),
         ...(Array.isArray(input.nodeIds) ? { nodeIds: normalizeAxNodeIds(input.nodeIds) } : {}),
+        ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
       },
       { source: normalizeAxSource(input.source, 'api') },
     );
     if (!workItem) throw new OperationError('work item not found.', 404);
     ctx.emit('ax-state-changed', { workItem });
+    // Same as create: the mirror touched node data only if the patch carried
+    // status or nodeIds — emit the layout frame those chips need (this op is
+    // mutates:false, so nothing else will).
+    if (input.status !== undefined || input.nodeIds !== undefined) {
+      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    }
     return { ok: true, workItem } as unknown as Record<string, unknown>;
   },
 });

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

@@ -238,7 +238,9 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
         continue;
       }
       const dispatch = resolveDispatch(operation.op, args);
-      const raw = await executeOperation(dispatch.name, dispatch.args);
+      // Batch churn is exempt from auto-ghosts (matches the skill's explicit
+      // ghost-cursor exemption for batch operations).
+      const raw = await executeOperation(dispatch.name, dispatch.args, { suppressAutoGhost: true });
       const result = shapeBatchEntry(operation.op, raw);
       results.push(result);
       if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {

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

@@ -69,6 +69,11 @@ export function defaultNodeSize(type: string): { width: number; height: number }
   switch (type) {
     case 'html':
       return { width: 720, height: 640 };
+    case 'file':
+      // Code preview needs real width and enough height for the header bar +
+      // a useful snippet — the generic default rendered as a content-less bar
+      // (0.4.4 portal feedback).
+      return { width: 520, height: 360 };
     case 'markdown':
       return MARKDOWN_NODE_DEFAULT_SIZE;
     case 'mcp-app':
@@ -415,7 +420,16 @@ export function createBasicCanvasNode(
   try {
     const { node, needsCodeGraphRecompute } = addCanvasNode({
       type: type as CanvasNodeState['type'],
-      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      ...(typeof body.title === 'string'
+        ? { title: body.title }
+        : // Untitled file nodes get the filename — otherwise the title bar
+          // reads as a bare "FILE" chip with nothing identifying the file.
+          type === 'file' && typeof content === 'string' && content.trim()
+          ? // Separator-agnostic: Windows paths use backslashes (0.3.2's
+            // basename fix class — a '/'-only split makes the whole path
+            // the title there).
+            { title: content.trim().split(/[\\/]/).pop() }
+          : {}),
       ...(typeof content === 'string' ? { content } : {}),
       ...(htmlMergedData && Object.keys(htmlMergedData).length > 0 ? { data: htmlMergedData } : {}),
       ...(type === 'trace' && typeof body.toolName === 'string' ? { toolName: body.toolName } : {}),

package/src/server/operations/registry.ts

@@ -105,6 +105,19 @@ function allowedIntentKinds(name: string, rawInput: unknown): readonly PmxAxInte
   return INTENT_KINDS_BY_OPERATION[name];
 }
 
+/**
+ * Ops exempt from auto-ghost SYNTHESIS only (explicit intent linking above is
+ * unaffected). Stream appends arrive in rapid succession — a fresh ghost per
+ * chunk is exactly the high-frequency churn class the batch exemption exists
+ * for; the stream's CREATING call (no nodeId yet) still ghosts once.
+ */
+function autoGhostExempt(name: string, rawInput: unknown): boolean {
+  if (name !== 'jsonrender.stream') return false;
+  const input =
+    rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput) ? (rawInput as Record<string, unknown>) : {};
+  return typeof input.nodeId === 'string' && input.nodeId.length > 0;
+}
+
 function settledNodeId(result: unknown, intent: PmxAxIntent): string | undefined {
   if (intent.kind === 'connect' || intent.kind === 'remove') return undefined;
   if (!result || typeof result !== 'object' || Array.isArray(result)) return undefined;
@@ -118,7 +131,75 @@ function settledNodeId(result: unknown, intent: PmxAxIntent): string | undefined
   return typeof record.id === 'string' ? record.id : undefined;
 }
 
-export async function executeOperation(name: string, rawInput: unknown): Promise<unknown> {
+/** Verb for the synthesized auto-ghost chip, per intent kind. */
+const AUTO_GHOST_VERBS: Record<string, string> = {
+  create: 'Adding',
+  move: 'Moving',
+  edit: 'Updating',
+  connect: 'Connecting',
+  remove: 'Removing',
+};
+
+const AUTO_GHOST_EDGE_TYPES = new Set(['flow', 'depends-on', 'relation', 'references']);
+
+/**
+ * Build a valid signal input for a synthesized ghost, or null when the raw
+ * input can't satisfy the kind's required fields (e.g. a create with server
+ * auto-placement has no position to ghost at) — in that case the mutation
+ * simply runs unghosted.
+ */
+function autoGhostInput(name: string, rawInput: unknown, kind: string): Record<string, unknown> | null {
+  const body =
+    rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput) ? (rawInput as Record<string, unknown>) : {};
+  const subject =
+    typeof body.title === 'string' && body.title.trim()
+      ? body.title.trim().slice(0, 80)
+      : typeof body.type === 'string'
+        ? `${body.type} node`
+        : typeof body.id === 'string'
+          ? body.id
+          : name.split('.')[0];
+  const base = {
+    kind,
+    label: `${AUTO_GHOST_VERBS[kind] ?? 'Changing'} ${subject}`,
+    ...(typeof body.type === 'string' ? { nodeType: body.type } : {}),
+    source: 'auto',
+    auto: true,
+    ttlMs: 6000,
+  };
+  const position = typeof body.x === 'number' && typeof body.y === 'number' ? { x: body.x, y: body.y } : undefined;
+  switch (kind) {
+    case 'create':
+      return position ? { ...base, position } : null;
+    case 'move':
+      return typeof body.id === 'string' && position ? { ...base, nodeId: body.id, position } : null;
+    case 'edit':
+    case 'remove':
+      return typeof body.id === 'string' ? { ...base, nodeId: body.id } : null;
+    case 'connect': {
+      if (typeof body.from !== 'string' || typeof body.to !== 'string') return null;
+      const edgeType = typeof body.type === 'string' && AUTO_GHOST_EDGE_TYPES.has(body.type) ? body.type : 'flow';
+      return { ...base, nodeType: undefined, edge: { from: body.from, to: body.to, type: edgeType } };
+    }
+    default:
+      return null;
+  }
+}
+
+export interface ExecuteOperationMeta {
+  /**
+   * Skip the synthesized auto-ghost: set by the workbench's own HTTP calls
+   * (a human dragging a node is not agent activity) and by canvas.batch for
+   * its inner dispatches (batch churn is exempt, matching the skill contract).
+   */
+  suppressAutoGhost?: boolean;
+}
+
+export async function executeOperation(
+  name: string,
+  rawInput: unknown,
+  meta: ExecuteOperationMeta = {},
+): Promise<unknown> {
   const op = getOperation(name);
   const intentId = linkedIntentId(rawInput);
   const allowedKinds = intentId ? allowedIntentKinds(name, rawInput) : undefined;
@@ -140,6 +221,46 @@ export async function executeOperation(name: string, rawInput: unknown): Promise
     );
   }
 
+  // Auto-ghost: an agent-originated visible mutation with NO explicit intent
+  // still shows its move on the canvas — a server-synthesized ghost that
+  // settles the moment the mutation lands (the client's minimum-dwell keeps
+  // the flash perceptible). Explicit canvas_intent signalling stays the
+  // richer path (labels, reasons, a real veto window before the mutation).
+  const autoKinds = allowedIntentKinds(name, rawInput);
+  if (
+    autoKinds &&
+    !meta.suppressAutoGhost &&
+    !autoGhostExempt(name, rawInput) &&
+    process.env.PMX_CANVAS_AUTO_INTENT !== '0'
+  ) {
+    // Ghost synthesis must NEVER break the mutation: skip silently when the
+    // input can't satisfy a kind's required fields or signalling throws.
+    let ghost: PmxAxIntent | null = null;
+    try {
+      for (const kind of autoKinds) {
+        const input = autoGhostInput(name, rawInput, kind);
+        if (input) {
+          ghost = intentRegistry.signal(input);
+          break;
+        }
+      }
+    } catch {
+      ghost = null;
+    }
+    if (ghost) {
+      const ghostId = ghost.id;
+      try {
+        const result = await op.execute(rawInput, operationContext);
+        if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+        intentRegistry.clear(ghostId, { settledNodeId: settledNodeId(result, ghost) ?? undefined });
+        return result;
+      } catch (error) {
+        intentRegistry.clear(ghostId);
+        throw error;
+      }
+    }
+  }
+
   const result = await op.execute(rawInput, operationContext);
   if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   return result;

package/src/server/server.ts

@@ -455,7 +455,7 @@ export async function startCanvasAutomationWebView(
   return runCanvasAutomationWebViewTask(async () => {
     const WebView = getCanvasWebViewConstructor();
     if (!WebView) {
-      const message = 'Bun.WebView is not available in this Bun runtime. Bun >=1.3.12 is required.';
+      const message = `Bun.WebView is not available in this Bun runtime (Bun ${Bun.version}). Bun >=1.3.12 is required — the canvas itself keeps working; only WebView automation/screenshots are unavailable.`;
       canvasAutomationWebViewStatus = {
         ...canvasAutomationWebViewStatus,
         lastError: message,
@@ -2999,7 +2999,15 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   // M11: PMX_WEB_CANVAS_PORT (server-specific) wins, then PMX_CANVAS_PORT — so
   // setting only the client var no longer splits the client and server ports.
   const preferredPort =
-    options.port ?? Number(process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? DEFAULT_PORT);
+    options.port ??
+    Number(
+      process.env.PMX_WEB_CANVAS_PORT ??
+        process.env.PMX_CANVAS_PORT ??
+        // Amp orbs assign the portal port via $PORT (gated on AMP_ORB so a
+        // stray PORT in normal shells never shifts the default).
+        (process.env.AMP_ORB ? process.env.PORT || undefined : undefined) ??
+        DEFAULT_PORT,
+    );
   const portCandidates =
     options.port === 0
       ? [0]

package/src/shared/ax-intent.ts

@@ -44,6 +44,12 @@ export interface PmxAxIntent {
   seq?: number;
   /** Source label of the surface that signalled the intent (mcp/api/sdk/...). */
   source?: string;
+  /**
+   * Server-synthesized ghost for an agent mutation that arrived WITHOUT an
+   * explicit canvas_intent signal (auto-ghost). Rendered visually lighter than
+   * a deliberate signal, and not vetoable — it settles immediately.
+   */
+  auto?: boolean;
   /** Epoch ms when the intent was first signalled. */
   createdAt: number;
   /** Epoch ms when the intent auto-dissolves if not settled/cleared first. */

package/src/shared/themes.ts

@@ -51,7 +51,7 @@ export const CANVAS_THEME_META: Record<CanvasThemeName, CanvasThemeMeta> = {
   arctic: { label: 'Arctic', scheme: 'dark', swatchBg: '#20242E', swatchAccent: '#7FC8DE' },
   ember: { label: 'Ember', scheme: 'dark', swatchBg: '#0B0B0C', swatchAccent: '#F34E1C' },
   forest: { label: 'Forest', scheme: 'dark', swatchBg: '#0C1712', swatchAccent: '#5CCF8F' },
-  volt: { label: 'Volt', scheme: 'dark', swatchBg: '#0B0D0B', swatchAccent: '#F34E3F' },
+  volt: { label: 'Volt', scheme: 'dark', swatchBg: '#0B0D0B', swatchAccent: '#DFDFC1' },
 };
 
 /** Collapse a theme to the dark/light scheme embedded dark|light-only viewers understand. */