pmx-canvas 0.4.4 → 0.4.5

package/dist/canvas/surface-theme.css

@@ -291,7 +291,7 @@
   --c-text-soft: #CBD3CA;
   --c-muted: #9CA49C;
   --c-dim: #626962;
-  --c-accent: #F34E3F;
+  --c-accent: #DFDFC1;
   --c-ok: #52C880;
   --c-warn: #E4C465;
   --c-warn-alt: #FFB300;
@@ -307,7 +307,7 @@
   --color-text-secondary: #CBD3CA;
   --color-text-muted: #9CA49C;
   --color-text-dim: #626962;
-  --color-accent: #F34E3F;
+  --color-accent: #DFDFC1;
   --color-success: #52C880;
   --color-warning: #E4C465;
   --color-danger: #D67670;

package/dist/types/cli/commands/skills.d.ts

@@ -1,4 +1,4 @@
-export declare const BUNDLED_SKILLS: readonly ["pmx-canvas", "pmx-canvas-testing"];
+export declare const BUNDLED_SKILLS: readonly ["pmx-canvas", "pmx-canvas-testing", "pmx-canvas-orchestration"];
 export interface SkillTreeComparison {
     inSync: boolean;
     /** Files present in the package tree but missing or different in the mirror. */

package/dist/types/client/state/intent-store.d.ts

@@ -15,6 +15,12 @@ export interface ClientIntent extends PmxAxIntent {
 export declare const intents: import("@preact/signals-core").Signal<Map<string, ClientIntent>>;
 /** The ghost currently hovered — drives Esc-to-veto. */
 export declare const hoveredIntentId: import("@preact/signals-core").Signal<string | null>;
+/**
+ * Minimum time a ghost stays in its forming state before a settle/dissolve
+ * plays. Fast agents (and every server auto-ghost) signal and settle within
+ * milliseconds — without this floor, correct ghost usage is imperceptible.
+ */
+export declare const MIN_FORMING_MS = 650;
 /** A live `ax-intent` frame: (re)place the ghost in its forming state. */
 export declare function upsertIntent(intent: PmxAxIntent): void;
 export declare function removeIntent(id: string): void;

package/dist/types/server/ax-state-manager.d.ts

@@ -77,6 +77,7 @@ export declare class AxStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem;
@@ -85,6 +86,7 @@ export declare class AxStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem | null;
@@ -173,6 +175,7 @@ export declare class AxStateManager {
         data?: Record<string, unknown> | null;
     }, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
     }): PmxAxEvent;
     addEvidence(input: {
         kind: PmxAxEvidenceKind;
@@ -186,6 +189,8 @@ export declare class AxStateManager {
     }): PmxAxEvidence;
     recordSteeringMessage(message: string, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
+        target?: string | null;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
     /**

package/dist/types/server/ax-state.d.ts

@@ -1,6 +1,6 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import type { AgentContextNode } from './agent-context.js';
-export type PmxAxSource = 'agent' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
+export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
 export interface PmxAxFocusState {
     nodeIds: string[];
     primaryNodeId: string | null;
@@ -24,6 +24,7 @@ export interface PmxAxWorkItem {
     createdAt: string;
     updatedAt: string;
     source: PmxAxSource | null;
+    agentId: string | null;
 }
 export interface PmxAxApprovalGate {
     id: string;
@@ -67,6 +68,7 @@ export interface PmxAxEvent {
     data: Record<string, unknown> | null;
     createdAt: string;
     source: PmxAxSource | null;
+    agentId: string | null;
 }
 export interface PmxAxEvidence {
     id: string;
@@ -87,6 +89,9 @@ export interface PmxAxSteeringMessage {
     delivered: boolean;
     createdAt: string;
     source: PmxAxSource | null;
+    agentId: string | null;
+    /** The agentId/consumer this steer is addressed to; null = broadcast to all consumers. */
+    target: string | null;
 }
 export interface PmxAxHostCapability {
     host: string | null;
@@ -257,6 +262,7 @@ export declare function createAxWorkItem(input: {
     status?: PmxAxWorkItemStatus;
     detail?: string | null;
     nodeIds?: string[];
+    agentId?: string | null;
 }, source: PmxAxSource | null, validNodeIds?: Set<string>): PmxAxWorkItem;
 export declare function createAxApprovalGate(input: {
     title: string;
@@ -280,7 +286,7 @@ export declare function createAxEvent(input: {
     detail?: string | null;
     nodeIds?: string[];
     data?: Record<string, unknown> | null;
-}, source: PmxAxSource | null): Omit<PmxAxEvent, 'seq'>;
+}, source: PmxAxSource | null, agentId?: string | null): Omit<PmxAxEvent, 'seq'>;
 export declare function createAxEvidence(input: {
     kind: PmxAxEvidenceKind;
     title: string;
@@ -289,7 +295,7 @@ export declare function createAxEvidence(input: {
     nodeIds?: string[];
     data?: Record<string, unknown> | null;
 }, source: PmxAxSource | null): Omit<PmxAxEvidence, 'seq'>;
-export declare function createAxSteeringMessage(message: string, source: PmxAxSource | null): Omit<PmxAxSteeringMessage, 'seq'>;
+export declare function createAxSteeringMessage(message: string, source: PmxAxSource | null, agentId?: string | null, target?: string | null): Omit<PmxAxSteeringMessage, 'seq'>;
 export declare function normalizeAxState(input: unknown, validNodeIds?: Set<string>): PmxAxState;
 export declare function buildAxContext(input: {
     layout: CanvasLayout;

package/dist/types/server/canvas-db.d.ts

@@ -56,7 +56,8 @@ export declare function loadPendingAxSteeringFromDB(db: Database, options?: {
 /**
  * NEWEST undelivered steering first (report #57) for the compact AX context lead
  * block — so a fresh steer is visible even behind a long backlog. Loop-safe: excludes
- * the consumer's own steering in SQL so the LIMIT applies after loop-prevention.
+ * the consumer's own steering and steering targeted at a different consumer in SQL
+ * so the LIMIT applies after both filters.
  * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
  * delivery queue uses for ordered processing.
  */
@@ -64,7 +65,7 @@ export declare function loadNewestPendingAxSteeringFromDB(db: Database, options?
     consumer?: string;
     limit?: number;
 }): PmxAxSteeringMessage[];
-/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own). */
+/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own; target-scoped). */
 export declare function countPendingAxSteeringFromDB(db: Database, consumer?: string): number;
 export declare function loadAxTimelineSummaryFromDB(db: Database): PmxAxTimelineSummary;
 export declare function upsertAxHostCapabilityToDB(db: Database, cap: PmxAxHostCapability): void;

package/dist/types/server/canvas-state.d.ts

@@ -280,6 +280,7 @@ declare class CanvasStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem;
@@ -288,9 +289,17 @@ declare class CanvasStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem | null;
+    /**
+     * 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;
     getApprovalGates(): PmxAxApprovalGate[];
     requestApproval(input: {
         title: string;
@@ -376,6 +385,7 @@ declare class CanvasStateManager {
         data?: Record<string, unknown> | null;
     }, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
     }): PmxAxEvent;
     addEvidence(input: {
         kind: PmxAxEvidenceKind;
@@ -389,6 +399,8 @@ declare class CanvasStateManager {
     }): PmxAxEvidence;
     recordSteeringMessage(message: string, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
+        target?: string | null;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
     ingestActivity(input: {

package/dist/types/server/operations/ops/ax-shared.d.ts

@@ -11,9 +11,10 @@
 import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { PmxAxSource } from '../../ax-state.js';
-export declare const AX_SOURCES: readonly ["agent", "api", "browser", "cli", "codex", "copilot", "mcp", "sdk", "system"];
+export declare const AX_SOURCES: readonly ["agent", "amp", "api", "browser", "cli", "codex", "copilot", "mcp", "sdk", "system"];
 /** Zod schema for the optional `source` field shared by AX MCP tool shapes. */
 export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
+    amp: "amp";
     agent: "agent";
     api: "api";
     browser: "browser";
@@ -24,6 +25,8 @@ export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
     sdk: "sdk";
     system: "system";
 }>>;
+/** Zod schema for the optional `agentId` field shared by AX MCP tool shapes. */
+export declare const AX_AGENT_ID_SHAPE: z.ZodOptional<z.ZodString>;
 /** An absent or unrecognized source falls back to the per-surface default. */
 export declare function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource;
 export declare function normalizeAxNodeIds(value: unknown): string[];

package/dist/types/server/operations/registry.d.ts

@@ -11,5 +11,13 @@ export declare function setOperationEventEmitter(emitter: OperationEventEmitter
 export declare function isEmitSuppressed(): boolean;
 /** Run `fn` with all operation SSE emits suppressed; restores depth on finally. */
 export declare function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T>;
-export declare function executeOperation(name: string, rawInput: unknown): Promise<unknown>;
+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 declare function executeOperation(name: string, rawInput: unknown, meta?: ExecuteOperationMeta): Promise<unknown>;
 export {};

package/dist/types/shared/ax-intent.d.ts

@@ -43,6 +43,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/docs/environment.md

@@ -27,6 +27,7 @@ optional; defaults are listed.
 |---|---|---|
 | `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, `volt`. |
 | `AMP_ORB` | server | Set by Amp orb services. When present, the served canvas page tells the browser it is running in an orb, which skips the iframe embed probe, forces `srcdoc` surface rendering when embedded (the orb portal blocks `src`-URL child iframes and the probe is unreliable there), and defaults the event transport to polling instead of SSE (the portal proxy buffers streams; `?transport=sse` overrides for diagnosis). |
+| `PORT` | server | Portal-assigned service port, honored ONLY when `AMP_ORB` is also set (Amp orbs) — after `--port`, `PMX_WEB_CANVAS_PORT`, and `PMX_CANVAS_PORT`, before the 4313 default. A stray `PORT` in normal shells never changes the port. |
 | `PMX_CANVAS_DISABLE_BROWSER_OPEN` | server | `1` suppresses auto-opening the browser (used by tests/CI). |
 | `PMX_CANVAS_DIST` | server | Explicit client bundle directory to serve instead of the packaged `dist/canvas`. |
 | `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` | server | Startup timeout for the Bun.WebView automation session. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Spatial canvas workbench for coding agents \u2014 infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -44,6 +44,11 @@ Humans curate agent context by pinning nodes; agents read that curation through
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
    high-frequency batch churn. The default TTL (~8s) expires between agent turns: signal with
    `ttlMs: 30000` and settle by passing `intentId` on the mutation in the same or next call.
+   Since 0.4.5, an agent mutation WITHOUT a signal still shows a server-synthesized **auto-ghost**
+   (rendered lighter — dimmer, dotted, no veto — and settled instantly). That is a visibility
+   floor, not a replacement: only an explicit signal gives the human a real pre-mutation veto
+   window, your reasoning (`reason`), and staged multi-step previews. Batch and browser-human
+   actions never auto-ghost.
 6. **Mutate through current composites.** Prefer the 16 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.
@@ -236,6 +241,10 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - Hosted MCP-app/ext-app nodes such as Excalidraw require the in-canvas host bridge and are not
   standalone **Open as site** targets. URL-backed viewers and bundled web artifacts remain
   openable.
+- A standalone html surface (`/api/canvas/surface/:id` opened as a site) is a VISUAL view: it
+  renders the same content and theme, but `window.PMX_AX` is not injected without the canvas
+  iframe's per-mount nonce, so AX buttons only work inside the in-canvas node (0.4.4 Codex note).
+  Do not tell a user a standalone tab's controls will steer the agent.
 - A hosted ext-app (Excalidraw) node that is already on the board when a **WebKit** host panel
   loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
   compositor paint race on the nested iframe, **not** a broken node (the session is healthy and
@@ -272,11 +281,12 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   iframe) can block child iframes from loading ANY `src` URL, breaking every iframe-backed node
   with a gray placeholder. The canvas probes this at boot and auto-falls back to fetching
   same-origin surfaces and rendering them inline via `srcdoc` (HTML, graph, json-render, frame
-  documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and stamps
-  the page so the embedded client skips the (there-unreliable) probe, goes straight to `srcdoc`,
-  AND defaults to the polling transport (the portal proxy buffers SSE — waiting out the watchdog
-  could trip the boot modal); HTML surfaces also inline their theme stylesheet so they render
-  styled. External app
+  documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and adapts
+  end to end: it binds the portal-assigned `$PORT` automatically (no port flag in the service
+  command), stamps the page so the embedded client skips the (there-unreliable) probe, goes
+  straight to `srcdoc`, AND defaults to the polling transport (the portal proxy buffers SSE —
+  waiting out the watchdog could trip the boot modal); HTML surfaces also inline their theme
+  stylesheet so they render styled. External app
   URLs cannot be inlined (cross-origin) and may stay blocked in such hosts. Force a mode with
   `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and

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/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/index.ts

@@ -166,7 +166,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 +220,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/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/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/state/intent-bridge.ts

@@ -2,9 +2,18 @@ function logRequestError(action: string, error: unknown): void {
   console.error(`[intent-bridge] ${action} failed`, error);
 }
 
+/**
+ * Every workbench-originated request carries this marker so the server never
+ * synthesizes an auto-ghost for it — a human dragging or editing in the
+ * browser is not agent activity (the ghost cursor shows AGENT moves).
+ */
+function withWorkbenchMarker(init?: RequestInit): RequestInit {
+  return { ...init, headers: { ...(init?.headers as Record<string, string> | undefined), 'X-PMX-Workbench': '1' } };
+}
+
 async function requestJson<T>(action: string, url: string, fallback: T, init?: RequestInit): Promise<T> {
   try {
-    const res = await fetch(url, init);
+    const res = await fetch(url, withWorkbenchMarker(init));
     return (await res.json()) as T;
   } catch (error) {
     logRequestError(action, error);
@@ -14,7 +23,7 @@ async function requestJson<T>(action: string, url: string, fallback: T, init?: R
 
 async function requestOk(action: string, url: string, init?: RequestInit): Promise<{ ok: boolean }> {
   try {
-    const res = await fetch(url, init);
+    const res = await fetch(url, withWorkbenchMarker(init));
     return { ok: res.ok };
   } catch (error) {
     logRequestError(action, error);
@@ -24,7 +33,7 @@ async function requestOk(action: string, url: string, init?: RequestInit): Promi
 
 async function requestBestEffort(action: string, url: string, init?: RequestInit): Promise<void> {
   try {
-    await fetch(url, init);
+    await fetch(url, withWorkbenchMarker(init));
   } catch (error) {
     logRequestError(action, error);
   }

package/src/client/state/intent-store.ts

@@ -23,8 +23,16 @@ export const hoveredIntentId = signal<string | null>(null);
 
 const SETTLE_MS = 480;
 const DISSOLVE_MS = 320;
+/**
+ * Minimum time a ghost stays in its forming state before a settle/dissolve
+ * plays. Fast agents (and every server auto-ghost) signal and settle within
+ * milliseconds — without this floor, correct ghost usage is imperceptible.
+ */
+export const MIN_FORMING_MS = 650;
 
 const exitTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const phaseDelayTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const formedAt = new Map<string, number>();
 let pruneTimer: ReturnType<typeof setInterval> | null = null;
 
 function writeIntents(next: Map<string, ClientIntent>): void {
@@ -40,9 +48,19 @@ function clearExitTimer(id: string): void {
   }
 }
 
+function clearPhaseDelay(id: string): void {
+  const timer = phaseDelayTimers.get(id);
+  if (timer) {
+    clearTimeout(timer);
+    phaseDelayTimers.delete(id);
+  }
+}
+
 /** A live `ax-intent` frame: (re)place the ghost in its forming state. */
 export function upsertIntent(intent: PmxAxIntent): void {
   clearExitTimer(intent.id);
+  clearPhaseDelay(intent.id);
+  if (!intents.value.has(intent.id)) formedAt.set(intent.id, Date.now());
   const next = new Map(intents.value);
   next.set(intent.id, { ...intent, phase: 'forming' });
   writeIntents(next);
@@ -50,6 +68,8 @@ export function upsertIntent(intent: PmxAxIntent): void {
 
 export function removeIntent(id: string): void {
   clearExitTimer(id);
+  clearPhaseDelay(id);
+  formedAt.delete(id);
   if (!intents.value.has(id)) return;
   const next = new Map(intents.value);
   next.delete(id);
@@ -69,19 +89,44 @@ function setPhase(id: string, phase: IntentPhase, ms: number, settledNodeId?: st
   );
 }
 
+/**
+ * Minimum-dwell wrapper: when a settle/dissolve arrives before the ghost has
+ * been visible for MIN_FORMING_MS, hold the forming state until the floor
+ * elapses, then play the exit phase.
+ */
+function setPhaseAfterDwell(id: string, phase: IntentPhase, ms: number, settledNodeId?: string): void {
+  clearPhaseDelay(id);
+  const elapsed = Date.now() - (formedAt.get(id) ?? 0);
+  const delay = Math.max(0, MIN_FORMING_MS - elapsed);
+  if (delay === 0) {
+    setPhase(id, phase, ms, settledNodeId);
+    return;
+  }
+  phaseDelayTimers.set(
+    id,
+    setTimeout(() => {
+      phaseDelayTimers.delete(id);
+      setPhase(id, phase, ms, settledNodeId);
+    }, delay),
+  );
+}
+
 /** Resolve a ghost into a real node — the settle morph, then removal. */
 export function settleIntent(id: string, settledNodeId?: string): void {
-  setPhase(id, 'settling', SETTLE_MS, settledNodeId);
+  setPhaseAfterDwell(id, 'settling', SETTLE_MS, settledNodeId);
 }
 
 /** Dissolve a ghost (expired / vetoed / evicted / abandoned), then remove it. */
 export function dissolveIntent(id: string): void {
-  setPhase(id, 'dissolving', DISSOLVE_MS);
+  setPhaseAfterDwell(id, 'dissolving', DISSOLVE_MS);
 }
 
 export function resetIntents(): void {
   for (const timer of exitTimers.values()) clearTimeout(timer);
   exitTimers.clear();
+  for (const timer of phaseDelayTimers.values()) clearTimeout(timer);
+  phaseDelayTimers.clear();
+  formedAt.clear();
   if (pruneTimer) {
     clearInterval(pruneTimer);
     pruneTimer = null;