pmx-canvas 0.4.5 → 0.4.6

package/dist/types/server/index.d.ts

@@ -161,9 +161,12 @@ export declare class PmxCanvas extends EventEmitter {
         data?: Record<string, unknown> | null;
     }, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
     }): PmxAxEvent;
     sendSteering(message: string, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
+        target?: string | null;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
     /**
@@ -198,6 +201,7 @@ export declare class PmxCanvas extends EventEmitter {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem;
@@ -206,6 +210,7 @@ export declare class PmxCanvas extends EventEmitter {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem | null;

package/dist/types/server/operations/ops/nodes.d.ts

@@ -1,6 +1,6 @@
 import { type CanvasLayout, type CanvasNodeState } from '../../canvas-state.js';
 import { type Operation } from '../types.js';
-export declare const NODE_TYPES: readonly ["markdown", "status", "context", "ledger", "trace", "file", "image", "mcp-app", "webpage", "html", "group"];
+export declare const NODE_TYPES: readonly ["markdown", "status", "context", "ledger", "trace", "file", "diff", "mermaid", "image", "mcp-app", "webpage", "html", "group"];
 /** Per-type default node frame size (formerly copy-pasted ladders). */
 export declare function defaultNodeSize(type: string): {
     width: number;

package/dist/types/server/workboard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Live AX work-item board, materialized as a json-render node.
+ *
+ * `buildWorkboardSpec` is the pure spec builder (status columns of work-item
+ * cards); `renderWorkboard` is the operation core (create-or-rebuild the
+ * single `data.workboard === true` json-render node); `refreshWorkboardNodes`
+ * is the live-refresh hook this module registers on `canvasState` so every
+ * addWorkItem/updateWorkItem rebuilds the board from the fresh work-item list
+ * through the SAME spec/update path the operation uses.
+ *
+ * The refresh runs inside `withSuppressedRecording` so live board rebuilds do
+ * not spam undo/redo history (persistence and SSE emits are unaffected).
+ */
+import type { JsonRenderSpec } from '../json-render/server.js';
+import type { PmxAxWorkItem } from './ax-state.js';
+export declare const WORKBOARD_NODE_TITLE = "Work Board";
+export declare const WORKBOARD_NODE_SIZE: {
+    width: number;
+    height: number;
+};
+/**
+ * Build the workboard json-render spec from a work-item list: one column per
+ * status (todo → in-progress → blocked → done → cancelled; empty statuses are
+ * omitted), each item a Card with an agentId Badge and detail Text when
+ * present. An empty list renders a single muted "No work items" text block.
+ */
+export declare function buildWorkboardSpec(workItems: PmxAxWorkItem[]): JsonRenderSpec;
+/**
+ * Operation core for `render.workboard`: rebuild the existing workboard node
+ * in place, or create one (tagged `data.workboard: true`) when none exists.
+ */
+export declare function renderWorkboard(input?: {
+    x?: number;
+    y?: number;
+}): {
+    ok: true;
+    id: string;
+    created: boolean;
+    itemCount: number;
+};
+/**
+ * Live refresh: rebuild every workboard node's spec from the current work-item
+ * list. Registered below as the canvasState work-item change listener. Node
+ * updates never touch work items, so this cannot recurse.
+ */
+export declare function refreshWorkboardNodes(): void;

package/dist/types/shared/ax-surface-protocol.d.ts

@@ -16,3 +16,10 @@ export declare const AX_SURFACE_ACK_SOURCE = "pmx-canvas-ax-ack";
 export declare const HTML_SURFACE_PUSH_SOURCE = "pmx-canvas-html-node";
 /** Ext-app boot beacon: the iframe's scripts executed (WebKit watchdog liveness). */
 export declare const EXT_APP_BOOT_BEACON_SOURCE = "pmx-canvas-ext-app-alive";
+/**
+ * Parent→ext-app paint probe (Finding N): the parent asks the app document to
+ * answer with a double-rAF `paint-tick` beacon. A frame whose rendering
+ * pipeline is live answers within a frame or two; silence past the timeout is
+ * the paint-fail signal that drives the recovery ladder.
+ */
+export declare const EXT_APP_PAINT_PROBE_SOURCE = "pmx-canvas-ext-app-paint-probe";

package/docs/cli.md

@@ -201,6 +201,18 @@ pmx-canvas ax policy get
 pmx-canvas ax policy set --excluded-tools shell,write --mode concise
 ```
 
+## Environment smoke check
+
+```bash
+pmx-canvas smoke                 # one-command check of a running canvas
+pmx-canvas smoke --port 4750     # target a specific daemon
+```
+
+Verifies server health + workspace, CLI/server version skew, the MCP
+initialize handshake, a temporary node create/search/remove round-trip (the
+temp node is always removed, including on failure), and board validation.
+Prints a JSON report and exits 1 if any check fails.
+
 ## Copilot adapter
 
 Install the bundled GitHub Copilot extension adapter into a repo. The adapter

package/docs/http-api.md

@@ -306,6 +306,18 @@ curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?settledNodeId=no
 curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?vetoed=true"
 ```
 
+## Live work board
+
+```bash
+# Materialize (or refresh) the one board node showing all AX work items by status.
+curl -X POST http://localhost:4313/api/canvas/workboard \
+  -H 'Content-Type: application/json' -d '{}'
+```
+
+The board is a `json-render` node tagged `data.workboard: true`. Repeat calls
+are idempotent (`created: false`) and the board refreshes itself whenever a
+work item changes — no polling needed.
+
 ## Diagrams (Excalidraw preset)
 
 ```bash

package/docs/mcp.md

@@ -38,7 +38,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | Composite | `action` values | Replaced (removed in v0.3.0) |
 |-----------|-----------------|----------|
 | `canvas_node` | `add` · `get` · `update` · `remove` | `canvas_add_node`, `canvas_get_node`, `canvas_update_node`, `canvas_remove_node`, `canvas_add_html_node` (`add` + `type:"html"`), `canvas_add_html_primitive` (`add` + `type:"html"`, `primitive:"<kind>"`), `canvas_refresh_webpage_node` (`update` + `refresh:true`) |
-| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
+| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
 | `canvas_edge` | `add` · `remove` | `canvas_add_edge`, `canvas_remove_edge` |
 | `canvas_group` | `create` · `add` · `ungroup` | `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup` |
 | `canvas_history` | `undo` · `redo` | `canvas_undo`, `canvas_redo` |

package/docs/node-types.md

@@ -15,6 +15,8 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `ledger` | Execution ledger summary |
 | `trace` | Agent trace pills (tool calls, subagent activity) |
 | `file` | Live file viewer with auto-update on disk changes |
+| `diff` | Unified diff viewer: per-file headers, hunk rows, +/− colored lines |
+| `mermaid` | Mermaid diagram rendered client-side from text (flowchart, sequence, state, …) |
 | `image` | Image viewer (file paths, data URIs, URLs) |
 | `webpage` | Persisted webpage snapshot with stored URL, extracted text, refresh |
 | `mcp-app` | Tool-backed hosted MCP App iframes (Excalidraw, etc.) |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pmx-canvas",
-  "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",
+  "version": "0.4.6",
+  "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",
   "module": "./src/server/index.ts",
@@ -32,7 +32,7 @@
     "dev:demo": "bun run src/cli/index.ts --demo",
     "dev:portless": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313",
     "dev:portless:demo": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313 --demo",
-    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css && cp src/client/theme/surface-theme.css dist/canvas/surface-theme.css",
+    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && bun build src/client/mermaid-entry.ts --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css && cp src/client/theme/surface-theme.css dist/canvas/surface-theme.css",
     "build:json-render": "bash scripts/build-json-render.sh",
     "build:types": "tsc -p tsconfig.types.json",
     "build": "bun run build:client && bun run build:json-render && bun run build:types",
@@ -68,6 +68,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@preact/signals": "^2.0.0",
     "marked": "^15.0.0",
+    "mermaid": "^11.16.1",
     "preact": "^10.25.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",

package/skills/pmx-canvas/SKILL.md

@@ -52,6 +52,10 @@ Humans curate agent context by pinning nodes; agents read that curation through
 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" }`.
+7b. **Show the human.** After creating user-facing output, bring the camera to it: a single node
+   gets `canvas_view { action: "focus", id }` (pans by default), a small cluster gets
+   `canvas_view { action: "fit", nodeIds: [...] }` with exactly the new ids. See
+   **In-View Placement & Sizing** below — auto-placement is board-relative, not camera-relative.
 8. **Verify context pins.** Pin with `canvas_pin_nodes` or the browser's **Pin as context**, then
    read `canvas://pinned-context`.
 9. **Clean up temporary nodes.** Remove retry/test fixtures and restore the baseline snapshot when
@@ -67,6 +71,10 @@ pmx-canvas serve status
 ```
 
 Both surfaces report `workspace`. It must match the intended workspace root.
+For a full environment check in one command (health + workspace, CLI/server
+version skew, MCP initialize handshake, temp-node create/search/remove
+round-trip, board validation), run `pmx-canvas smoke` (0.4.6+) — JSON report,
+exit 1 on failure.
 
 - If `responsive: true` but `pidRunning: false`, treat the listener as potentially stale.
 - On mismatch, do not mutate. Start the intended workspace on an explicit free port:
@@ -97,14 +105,17 @@ Both surfaces report `workspace`. It must match the intended workspace root.
 | Persistent context cards | `context` via `canvas_node` |
 | Event/check stream | `ledger` or `trace` via `canvas_node` |
 | Local source with live updates | `file` via `canvas_node` |
+| Code review / unified diff (0.4.6+) | `diff` via `canvas_node` (content = diff text; link to its file node with a `references` edge) |
+| Flowchart / sequence / state diagram (0.4.6+) | `mermaid` via `canvas_node` (content = mermaid source; renders client-side, no hosted app) |
 | Image | `image` via `canvas_node` |
 | Cached URL content | `webpage` via `canvas_node` |
 | Structured UI | `json-render` via `canvas_render` |
 | Chart | `graph` via `canvas_render` |
+| Live work-item board (0.4.6+) | `canvas_render { action: "workboard" }` — one board node, auto-refreshes on work-item changes |
 | Generated communication surface | HTML primitive via `canvas_node` |
 | Self-contained HTML/JS | `html` via `canvas_node` |
 | Hosted interactive MCP app | `canvas_app { action: "open-mcp-app" }` |
-| Excalidraw diagram | `canvas_app { action: "diagram" }` |
+| Excalidraw diagram (interactive/human drawing) | `canvas_app { action: "diagram" }` — prefer `mermaid` for agent-authored diagrams |
 | Bundled React artifact | `canvas_app { action: "build-artifact" }` |
 
 Use the lightest tier that communicates the result. Do not build a web artifact when markdown,
@@ -164,6 +175,35 @@ v0.4.0 after their deprecated 0.3.x window.
 - Edge types: `flow`, `depends-on`, `relation`, `references`.
 - After manual or batch layout changes, run `canvas_query { action: "validate" }`.
 
+## In-View Placement & Sizing (required for user-facing nodes)
+
+Auto-placement (omitting `x`/`y`) is **board-relative, not camera-relative**: it places right of
+the last node or scans rows from the origin, ignoring where the human is looking. On a board with
+distant nodes, an auto-placed node lands off-camera.
+
+1. Omit `x`/`y` only on an empty or locally dense board. Otherwise place near the human's
+   attention: the pinned/focused neighborhood, or explicit coordinates beside the last
+   user-facing output (gap ≥ 24–48 px).
+2. After creating nodes the human should see, pan the camera (operating-sequence step 7b):
+   `focus` for one node, `fit` with exactly the new `nodeIds` for a cluster. Use `noPan`
+   (`focus --no-pan`) only when you must not steal the camera.
+3. Never fit the whole board to "show" new work — on a board with outliers that miniaturizes
+   everything. Always pass explicit `nodeIds` to `fit`.
+4. Never leave user-facing output at far coordinates without a focus/fit.
+
+**Size for content.** Omitting `width`/`height` gives readable per-type defaults — prefer them:
+markdown 640×420, status 360×200, file 520×360, diff 640×420, mermaid 640×460, html 720×640,
+graph 760×520, mcp-app 960×600, web-artifact 960×720. Since 0.4.6 the server clamps explicit creation sizes UP to per-type
+readability floors (e.g. markdown 360×180, graph/json-render/html 420×280, mcp-app 480×320) —
+a tiny probe size silently becomes the floor. `strictSize: true` is the only opt-out (a fixed
+scrolling frame you genuinely want small). `canvas_query { action: "validate" }` additionally
+reports any node below its floor as an advisory `sizeWarnings` entry — treat a non-empty list
+as layout work left to do.
+
+**Token hygiene.** For routine state checks use `canvas_ax_state { action: "get" }` WITHOUT
+`includeContext` — the full AX context payload is ~10× larger; request it only when you are
+actually consuming context.
+
 ## Context Pins
 
 Context pins are the primary human-to-agent bridge:
@@ -245,24 +285,21 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   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
-  `sessionStatus` is `ready`; it renders fine in Chrome, the Codex browser, and for nodes created
-  live after the panel hydrates). Under WebKit the canvas ATTEMPTS auto-recovery: after boot,
-  each present-at-load ext-app is remounted through a serialized, boot-aware queue (one app at a
-  time), with a watchdog retry for iframes that never boot and a re-arm when a panel that loaded
-  hidden becomes visible. Treat the auto-recovery as best-effort, NOT guaranteed — the 0.3.2
-  Copilot-host report shows tiles can still come up black in real WKWebView panels (compositing
-  success is not observable from page JS, so retries are bounded). Since 0.4.1 the canvas also
-  fires a post-boot **repaint nudge** under WebKit (a 1px layout bounce that forces the
-  compositor to re-rasterize the frame — the cheap half of the proven enlarge-close unstick;
-  shows as `repaint-nudge` in the recovery trail). Keep the cautionary behavior anyway:
-  recovery is deterministic via **expand-then-close** of the black tile (forces a fresh mount in
-  the fullscreen overlay, which always paints), or open the workbench in a normal browser
-  (Chrome). Do not diagnose a healthy app session as a broken node. When reporting a black tile,
-  fetch `GET /api/canvas/debug/ext-app-recovery` from the daemon and attach the trace — it shows
-  what the recovery queue actually did in that panel.
+- A hosted ext-app (Excalidraw) node in a **WebKit** host panel (e.g. the GitHub Copilot app's
+  embedded WKWebView) historically could render as a black tile — a host compositor paint race
+  on the nested iframe, **not** a broken node (the session is healthy, `sessionStatus` is
+  `ready`, and it renders fine in Chrome/Codex). Since 0.4.6 the canvas runs a **paint oracle +
+  recovery ladder** under WebKit: present-at-load ext-apps mount strictly one at a time (the
+  cold burst was the trigger), each frame answers a double-rAF **paint probe** after settle, and
+  on silence the ladder escalates — soft-expand cycle (the automatic analogue of the proven
+  enlarge+close) → serialized remount → an explicit "App surface failed to paint / Retry"
+  affordance. The connecting overlay stays up until paint is confirmed, so a black layer is
+  never presented as ready. The recovery trail
+  (`GET /api/canvas/debug/ext-app-recovery` / `window.__PMX_EXTAPP_LOG`) now records
+  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, and `recovery-exhausted` — when
+  diagnosing, trust `paint-ok`/`paint-fail`, and never assert health from `settled` alone. If a
+  tile still shows the Retry affordance, click Retry (fresh recovery budget) or expand-then-close;
+  attach the recovery trail when reporting.
 - Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon
   while a panel stays open leaves ext-app tiles on dead frame URLs (`Frame document not found`,
   0.4.0 report Finding S) until a full workbench reload. Since 0.4.1 the browser revalidates its

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/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);
+  },
+);