pmx-canvas 0.2.6 → 0.2.7

package/dist/types/mcp/canvas-access.d.ts

@@ -65,5 +65,28 @@ export interface CanvasAccess {
     screenshotAutomationWebView(options?: AutomationScreenshotOptions): Promise<Uint8Array>;
 }
 export declare function refreshCanvasAccess(access: CanvasAccess): Promise<CanvasAccess>;
+/**
+ * Finding I (0.2.6): decide whether to ATTACH to the daemon already holding the
+ * preferred port instead of spawning a split daemon on a fallback port. True only
+ * when the split is not opted in AND the preferred port is held by a healthy canvas
+ * daemon that reports a workspace (i.e. a real different-workspace daemon, the
+ * "wrong-workspace split" trap — not a free port or a non-canvas occupant). Pure +
+ * exported for deterministic testing.
+ */
+export declare function shouldAttachToExistingDaemon(occupant: {
+    ok?: boolean;
+    workspace?: unknown;
+} | null, allowSplit: boolean): boolean;
+/**
+ * Finding I (0.2.6, first-binder gap): true when the launch cwd looks like a
+ * host/agent config dir rather than a project root — the home dir itself, or a
+ * dot-prefixed DIRECT child of home (e.g. `~/.copilot`, `~/.codex`, `~/.claude`,
+ * `~/.config`). POSITIVE-signal ONLY — never "absence of project markers", because
+ * the MCP/SDK test harness runs from bare `mkdtemp` temp dirs (under `os.tmpdir()`,
+ * never under home) that a marker-absence heuristic would misflag. Both sides are
+ * canonicalized (realpath) so a symlinked home matches. Pure + exported for tests;
+ * FS-safe (defaults to false on any error).
+ */
+export declare function looksLikeIncidentalCwd(cwd: string): boolean;
 export declare function createCanvasAccess(): Promise<CanvasAccess>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "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",

package/skills/pmx-canvas/SKILL.md

@@ -58,15 +58,17 @@ Both surfaces report `workspace`. It must match the intended workspace root.
 - Target that port and re-check `/health`.
 - `PMX_CANVAS_PORT` is the agent CLI target; the server's startup port is controlled by `--port`
   or `PMX_WEB_CANVAS_PORT`.
-- **MCP transport caveat (wrong-workspace split).** An MCP server (`pmx-canvas --mcp`) holds its own
-  in-memory canvas and, if its preferred port is already taken by a *different* workspace's daemon,
-  binds the next free port adopting **its own launch `cwd`** as the workspace — so its writes land on
-  a daemon the browser panel never renders (it self-reports this fallback on stderr). Before trusting
-  MCP-written state, confirm the MCP server's workspace matches the panel's (`/health` on both ports)
-  and that no stray higher-numbered listener exists. The durable fix is to launch the MCP server with
-  `cwd=<project>` or `PMX_CANVAS_PORT=<panel-port>`. The CLI's query/mutation commands are a thin HTTP
-  client and never start a server of their own (only `serve` / `--mcp` spawn a process), so prefer
-  those CLI commands for watcher/automation loops until the launch config is pinned.
+- **MCP transport workspace resolution.** An MCP server (`pmx-canvas --mcp`) holds its own in-memory
+  canvas. To avoid the old "wrong-workspace split" (a `--mcp` launched from an incidental dir, e.g.
+  `~/.copilot`, silently binding a fallback port the panel never renders): when the preferred port is
+  held by a healthy daemon serving a *different* workspace, the MCP server now **attaches** to it
+  (inherits its workspace) so writes are visible where the panel renders; and if it launched from an
+  incidental host/agent config dir on a *free* port, it still binds but emits a loud stderr warning
+  instead of silently adopting that cwd. To pin the intended workspace deterministically set
+  **`PMX_CANVAS_WORKSPACE_ROOT=<abs project root>`** (recommended for host adapters); for a genuinely
+  separate canvas set `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1` or a distinct `PMX_CANVAS_PORT`. The CLI's
+  query/mutation commands are a thin HTTP client and never start a server of their own (only `serve` /
+  `--mcp` spawn a process).
 
 ## Choose the Smallest Useful Node Type
 

package/skills/pmx-canvas/references/full-reference.md

@@ -157,10 +157,10 @@ file, sends SIGTERM, and cleans up on exit.
 
 ### Verify workspace identity BEFORE mutating (required)
 
-> **"Start once, reuse always" has one hard exception: never reuse a listener that belongs to
-> another workspace.** A healthy, responsive server on the default port `4313` can be serving a
-> *different project's* canvas (a leftover daemon, or another repo's session). Mutating it would
-> corrupt the wrong board. Always preflight:
+> **"Start once, reuse always" has one hard exception for direct CLI/HTTP work: never mutate a
+> listener that belongs to another workspace.** A healthy, responsive server on the default port
+> `4313` can be serving a *different project's* canvas (a leftover daemon, or another repo's
+> session). Mutating it directly would corrupt the wrong board. Always preflight:
 
 1. **Read `GET /health`** (or `pmx-canvas serve status`). Both return a top-level
    `workspace` field. **`workspace` MUST equal your intended workspace root**
@@ -172,7 +172,13 @@ file, sends SIGTERM, and cleans up on exit.
    `pmx-canvas serve --daemon --no-open --port=<free-port>` — and target that port. (`PMX_CANVAS_PORT`
    alone may still attach to an existing `4313` listener; prefer an explicit `--port`.) Then
    **re-read `/health`** to confirm the workspace now matches.
-4. **After any version upgrade**, run a behavior canary (e.g. a batch `node.add` with no `type`
+4. **MCP transport exception:** `pmx-canvas --mcp` launched from an incidental host dir may attach to
+   the healthy daemon already on the preferred port when no explicit workspace root is set, so writes
+   land in the visible workbench instead of a hidden fallback workspace. Host adapters should set
+   `PMX_CANVAS_WORKSPACE_ROOT=<abs project root>` for deterministic targeting; set
+   `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1` or a distinct `PMX_CANVAS_PORT` only when a separate canvas is
+   intentional.
+5. **After any version upgrade**, run a behavior canary (e.g. a batch `node.add` with no `type`
    must return `400`) to confirm the listener is the version you expect, not a stale old daemon.
 
 ## Browser Workflows
@@ -386,10 +392,12 @@ Agents tend to pack boards too tightly. Give nodes room to breathe — readabili
 
 ### Colors (Semantic)
 
-A `color` parameter is honored only for **group** nodes (frame accent) and **graph** nodes
-(series/accent color). It is **not** a parameter for `markdown` / `status` / `context` nodes — a
-top-level `color` on those is silently ignored over both HTTP and the CLI (report Finding H). Their
-meaning comes from the node **type** and value instead: a `status` node colors its indicator from its
+A `color` parameter is honored as a **renderer** color only for **group** nodes (frame accent) and
+**graph** nodes (series/accent color). It is **not** a renderer parameter for `markdown` / `status` /
+`context` nodes: a top-level `color` on those is dropped on both HTTP and the CLI, and while an
+arbitrary `data.color` you POST under `data` persists like any other `data.*` metadata, it is **not**
+read as a render color for basic node types (report Finding H — renderer-semantic, not raw-storage,
+contract). Their meaning comes from the node **type** and value instead: a `status` node colors its indicator from its
 **phase** (`idle`/`running`/`planning`/`thinking`/`drafting`/`tooling`/`review`/`waiting-approval`/
 `waiting` — e.g. `review` → green, `running` → accent; an unrecognized phase renders gray), and a
 `trace` node from its `status` field (`success` → green, `failed` → red, `running` → accent). To

package/src/client/App.tsx

@@ -38,6 +38,7 @@ import {
   walkGraph,
 } from './state/canvas-store';
 import { connectSSE } from './state/sse-bridge';
+import { intents } from './state/intent-store';
 import { saveCanvasTheme } from './state/intent-bridge';
 import {
   IconArrange,
@@ -556,7 +557,7 @@ export function App() {
         annotationMode={annotationTool !== null}
         annotationTool={annotationTool}
       />
-      {hasInitialLayout && allNodes.filter((n) => !n.dockPosition).length === 0 && (
+      {hasInitialLayout && allNodes.filter((n) => !n.dockPosition).length === 0 && intents.value.size === 0 && (
         <WelcomeCard onOpenPalette={() => setPaletteOpen(true)} />
       )}
       {selectedNodeIds.value.size > 0 && <SelectionBar />}

package/src/mcp/canvas-access.ts

@@ -1,5 +1,6 @@
 import { realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { basename, dirname, resolve } from 'node:path';
 import {
   createCanvas,
   canvasState,
@@ -526,24 +527,126 @@ export async function refreshCanvasAccess(access: CanvasAccess): Promise<CanvasA
   return remoteBaseUrl ? new RemoteCanvasAccess(remoteBaseUrl) : access;
 }
 
+/**
+ * Finding I (0.2.6): decide whether to ATTACH to the daemon already holding the
+ * preferred port instead of spawning a split daemon on a fallback port. True only
+ * when the split is not opted in AND the preferred port is held by a healthy canvas
+ * daemon that reports a workspace (i.e. a real different-workspace daemon, the
+ * "wrong-workspace split" trap — not a free port or a non-canvas occupant). Pure +
+ * exported for deterministic testing.
+ */
+export function shouldAttachToExistingDaemon(
+  occupant: { ok?: boolean; workspace?: unknown } | null,
+  allowSplit: boolean,
+): boolean {
+  return !allowSplit && occupant?.ok === true && typeof occupant.workspace === 'string' && occupant.workspace.length > 0;
+}
+
+/**
+ * Finding I (0.2.6, first-binder gap): true when the launch cwd looks like a
+ * host/agent config dir rather than a project root — the home dir itself, or a
+ * dot-prefixed DIRECT child of home (e.g. `~/.copilot`, `~/.codex`, `~/.claude`,
+ * `~/.config`). POSITIVE-signal ONLY — never "absence of project markers", because
+ * the MCP/SDK test harness runs from bare `mkdtemp` temp dirs (under `os.tmpdir()`,
+ * never under home) that a marker-absence heuristic would misflag. Both sides are
+ * canonicalized (realpath) so a symlinked home matches. Pure + exported for tests;
+ * FS-safe (defaults to false on any error).
+ */
+export function looksLikeIncidentalCwd(cwd: string): boolean {
+  let home: string;
+  try {
+    home = canonicalWorkspacePath(homedir());
+  } catch {
+    return false;
+  }
+  if (!home || home === '/') return false;
+  const canonical = canonicalWorkspacePath(cwd);
+  if (canonical === home) return true;
+  // A dot-prefixed direct child of home: ~/.copilot, ~/.codex, ~/.claude, ~/.config …
+  return dirname(canonical) === home && basename(canonical).startsWith('.');
+}
+
 export async function createCanvasAccess(): Promise<CanvasAccess> {
-  const workspaceRoot = resolve(process.cwd());
+  // PMX_CANVAS_WORKSPACE_ROOT (Finding I escape hatch): an explicit project root the
+  // host can pass so the MCP server keys off it instead of an incidental launch cwd
+  // (e.g. ~/.copilot). When set, it overrides process.cwd() for the whole acquisition
+  // and suppresses the incidental-cwd guard below (the operator stated intent).
+  const override = process.env.PMX_CANVAS_WORKSPACE_ROOT?.trim();
+  const explicitRoot = Boolean(override);
+  const workspaceRoot = explicitRoot ? resolve(override as string) : resolve(process.cwd());
   const port = targetPort();
   const remoteBaseUrl = await findExistingCanvasServer(workspaceRoot, port);
   if (remoteBaseUrl) return new RemoteCanvasAccess(remoteBaseUrl);
 
-  // No same-workspace server to attach to. Allow a port fallback so a daemon
-  // already holding the preferred port (e.g. one serving a *different*
-  // workspace) doesn't crash this MCP/SDK session with EADDRINUSE — start our
-  // own canvas on a free port instead, and explain how to share one if intended.
+  // No SAME-workspace server to attach to. The preferred port may still be held by
+  // a healthy canvas daemon serving a DIFFERENT workspace. The old behavior silently
+  // started our own canvas on a FALLBACK port adopting this process's launch cwd as
+  // the workspace — but the open workbench panel renders the PREFERRED port and never
+  // shows that fallback, so MCP writes land on a phantom workspace nobody sees (report
+  // Finding I, the "wrong-workspace daemon split"; the launch cwd is often incidental,
+  // e.g. the host spawns `--mcp` from ~/.copilot). Default to the safer behavior:
+  // ATTACH to the existing preferred-port daemon (inherit its workspace) so writes are
+  // visible where the human is looking. Opt back into a separate canvas with
+  // PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1 or by pinning a distinct PMX_CANVAS_PORT.
+  // An explicit PMX_CANVAS_WORKSPACE_ROOT is an operator statement of intent and WINS:
+  // skip the heuristic attach so the pinned root is honored (it binds its own daemon —
+  // on a fallback port if the preferred port is foreign-held) rather than silently
+  // inheriting the foreign daemon's workspace. So the pin is genuinely deterministic.
+  const occupantBaseUrl = `http://127.0.0.1:${port}`;
+  const allowSplit = process.env.PMX_CANVAS_ALLOW_WORKSPACE_SPLIT === '1';
+  if (!explicitRoot) {
+    const occupant = await readHealth(occupantBaseUrl);
+    if (occupant && shouldAttachToExistingDaemon(occupant, allowSplit)) {
+      // stderr only — stdout is the MCP stdio JSON-RPC channel.
+      process.stderr.write(
+        `[pmx-canvas] port ${port} is serving a different workspace (${occupant.workspace}); this ` +
+          `MCP server launched from ${workspaceRoot}. Attaching to that canvas so writes are visible ` +
+          `in the open workbench instead of splitting to a hidden fallback port. For a SEPARATE canvas, ` +
+          `set PMX_CANVAS_PORT to a free port or PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1.\n`,
+      );
+      return new RemoteCanvasAccess(occupantBaseUrl);
+    }
+  }
+
+  // First-binder gap (Finding I): the attach branch above only fires when the
+  // preferred port is HELD. If it is FREE (or a non-canvas occupant) AND this process
+  // launched from an incidental host/agent config dir (e.g. ~/.copilot), binding the
+  // preferred port here would adopt that incidental cwd as the workspace — a canvas the
+  // human's project panel would never render. Don't silently do that.
+  if (!allowSplit && !explicitRoot && looksLikeIncidentalCwd(workspaceRoot)) {
+    // Race-tolerant: a real daemon may have appeared on the preferred port since the
+    // first probe. Attach to ANY healthy canvas now there (inherit its workspace)
+    // rather than inventing a phantom workspace under the incidental launch dir.
+    const racedOccupant = await readHealth(occupantBaseUrl);
+    if (racedOccupant?.ok === true) {
+      process.stderr.write(
+        `[pmx-canvas] launch cwd ${workspaceRoot} looks like a host config dir; attaching to the ` +
+          `canvas now on port ${port}.\n`,
+      );
+      return new RemoteCanvasAccess(occupantBaseUrl);
+    }
+    // Still free: bind it anyway (the agent always gets a working canvas) but warn
+    // loudly so a wrong-workspace canvas is diagnosed, not silent. stderr only.
+    process.stderr.write(
+      `[pmx-canvas] launch cwd ${workspaceRoot} looks like a host/agent config dir, not a project ` +
+        `root. This canvas will persist under it and may not be visible in a workbench opened for ` +
+        `your project. Set PMX_CANVAS_WORKSPACE_ROOT=/abs/project to target it, PMX_CANVAS_URL to ` +
+        `attach to a running daemon, or PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1 / PMX_CANVAS_PORT=<free ` +
+        `port> for a deliberate separate canvas.\n`,
+    );
+  }
+
+  // Either the split is opted in, the root is explicit, the cwd is a real project, or
+  // the preferred port is genuinely free / not a canvas daemon. Allow a port fallback
+  // so a non-canvas occupant doesn't crash this session with EADDRINUSE — start our
+  // own canvas and explain how to share one.
   const canvas = createCanvas({ port });
   await canvas.start({ open: true, allowPortFallback: true });
   const boundPort = canvas.port;
   if (boundPort !== port) {
-    const occupant = await readHealth(`http://127.0.0.1:${port}`);
+    const occupant = await readHealth(occupantBaseUrl);
     const occupantWorkspace =
       typeof occupant?.workspace === 'string' ? ` (serving ${occupant.workspace})` : '';
-    // stderr only — stdout is the MCP stdio JSON-RPC channel.
     process.stderr.write(
       `[pmx-canvas] preferred port ${port} was in use${occupantWorkspace}; ` +
         `started this canvas on port ${boundPort} instead. To share one canvas, run the daemon ` +

package/src/server/server.ts

@@ -422,7 +422,10 @@ async function withCanvasAutomationWebViewTimeout<T>(task: Promise<T>, action: s
           reject(
             new Error(
               `Timed out after ${getCanvasAutomationWebViewTimeoutMs()}ms while ${action}. ` +
-                'Bun.WebView may be unavailable in this environment.',
+                'The Bun.WebView backend may be slow to launch or unavailable in this environment ' +
+                '(the chrome backend is known-flaky on some hosts). On macOS prefer the webkit ' +
+                'backend (start --backend webkit), or raise PMX_CANVAS_WEBVIEW_TIMEOUT_MS for a ' +
+                'slow-but-available backend.',
             ),
           );
         }, getCanvasAutomationWebViewTimeoutMs());
@@ -3482,7 +3485,12 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
     return typeof server.port === 'number' ? loopbackBaseUrl(server.port) : null;
   }
 
-  const workspaceRoot = options.workspaceRoot ?? process.cwd();
+  // An explicit `options.workspaceRoot` wins. Otherwise honor PMX_CANVAS_WORKSPACE_ROOT
+  // (Finding I escape hatch) before falling back to the launch cwd, so a host that
+  // spawns from an incidental dir (e.g. ~/.copilot) can still pin the real project root
+  // for the daemon it binds — not just for the MCP same-workspace lookup.
+  const envWorkspaceRoot = process.env.PMX_CANVAS_WORKSPACE_ROOT?.trim();
+  const workspaceRoot = options.workspaceRoot ?? (envWorkspaceRoot ? resolve(envWorkspaceRoot) : process.cwd());
   activeWorkspaceRoot = normalizeWorkspaceRoot(workspaceRoot);
   if (options.autoOpenBrowser !== undefined) {
     primaryWorkbenchAutoOpenEnabled = options.autoOpenBrowser;