pmx-canvas 0.2.5 → 0.2.7

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -3,6 +3,7 @@ import { AppBridge } from '@modelcontextprotocol/ext-apps/app-bridge';
 import type { CanvasNodeState } from '../types';
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
+type ExtAppFrameStatus = 'loading' | 'ready' | 'done';
 interface ExtAppHostDimensionsTarget {
     clientWidth?: number;
     clientHeight?: number;
@@ -18,6 +19,8 @@ interface ExtAppHostDimensionsTarget {
  * everywhere we can test (Chrome / Codex / Playwright).
  */
 export declare function isWebKitOnlyHost(userAgent: string): boolean;
+export declare function nextWebkitRepaintSlot(): number;
+export declare function shouldScheduleWebKitRepaint(status: ExtAppFrameStatus, hasReplayToolResult: boolean): boolean;
 export declare function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number): string;
 export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMode, isExpanded: boolean): {
     nextMode: DisplayMode;

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.5",
+  "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,6 +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 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
 
@@ -197,11 +208,15 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   openable.
 - 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
-  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). The canvas auto-remounts the iframe once on load under WebKit to force a
-  repaint; if a tile is still black, expand-then-close it (forces a remount) or open the workbench
-  in a normal browser. Do not diagnose a healthy app session as a broken node.
+  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). The canvas forces a one-time post-boot repaint remount under
+  WebKit, which reliably repaints a **single** present-at-load
+  ext-app — but a board with **several** ext-apps present at WebKit panel-load can still black out
+  (the simultaneous cold-hydration burst overwhelms the WebKit compositor). Recovery is
+  deterministic: **expand-then-close** any 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; the durable fix is upstream in the host panel.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
   Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look

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,7 +392,18 @@ Agents tend to pack boards too tightly. Give nodes room to breathe — readabili
 
 ### Colors (Semantic)
 
-Use color consistently to convey meaning:
+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
+color an arbitrary region, group the nodes and set the group's `color`.
+
+When you do set a color (group/graph), use this palette consistently to convey meaning:
 - **Green** (`#22c55e`) — success, done, healthy
 - **Yellow** (`#eab308`) — in progress, warning, attention needed
 - **Red** (`#ef4444`) — error, blocked, failing
@@ -523,7 +540,7 @@ retrying the generic add.
 - `content`: markdown text for most types. For `file`, pass the **file path** (e.g. `"src/auth/login.ts"`) —
   the server auto-loads + watches it. For `image`, pass a file path, URL, or data URI.
 - `path`: compatibility alias for image paths only; prefer `content` for new image calls
-- `x`, `y`: position (prefer omitting for auto-layout); `width`, `height`: dimensions (sensible defaults); `color`: semantic color; `metadata`: arbitrary JSON
+- `x`, `y`: position (prefer omitting for auto-layout); `width`, `height`: dimensions (sensible defaults); `metadata`: arbitrary JSON. (`color` applies to **group**/**graph** nodes only — it is ignored on basic node types; see Colors (Semantic).)
 - Returns: `{ id: "<node-id>" }` — capture this ID for edges and groups
 
 **`canvas_node { action: "update", id, … }`** — Update an existing node in place (preferred over

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/client/nodes/ExtAppFrame.tsx

@@ -23,6 +23,7 @@ type McpUiTheme = 'light' | 'dark';
 
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
+type ExtAppFrameStatus = 'loading' | 'ready' | 'done';
 
 interface ExtAppHostDimensionsTarget {
   clientWidth?: number;
@@ -58,6 +59,28 @@ export function isWebKitOnlyHost(userAgent: string): boolean {
   return /AppleWebKit/.test(userAgent) && !/Chrome|Chromium|CriOS|Edg|Android/.test(userAgent);
 }
 
+// Finding F (0.2.5): SERIALIZED WebKit repaint slots. The black tile is a cold-
+// hydration BURST problem — a single ext-app repaints fine into an idle panel (like
+// a live-created node, or expand+close), but several compositing at once overwhelm
+// WebKit and all stay black. We give each mounting ext-app an increasing slot so its
+// one-time repaint remount fires into a progressively-quieter panel (one app at a
+// time), turning the burst back into a sequence of single repaints. The shared
+// counter resets after the burst so a later board load starts from slot 0.
+let webkitRepaintSlot = 0;
+let webkitRepaintSlotResetTimer: ReturnType<typeof setTimeout> | null = null;
+export function nextWebkitRepaintSlot(): number {
+  const slot = webkitRepaintSlot++;
+  if (typeof window !== 'undefined') {
+    if (webkitRepaintSlotResetTimer) clearTimeout(webkitRepaintSlotResetTimer);
+    webkitRepaintSlotResetTimer = setTimeout(() => { webkitRepaintSlot = 0; }, 3000);
+  }
+  return slot;
+}
+
+export function shouldScheduleWebKitRepaint(status: ExtAppFrameStatus, hasReplayToolResult: boolean): boolean {
+  return hasReplayToolResult ? status === 'done' : status === 'ready' || status === 'done';
+}
+
 export function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number): string {
   const html = typeof node.data.html === 'string' ? node.data.html : '';
   const serverName = typeof node.data.serverName === 'string' ? node.data.serverName : '';
@@ -208,7 +231,8 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const bridgeReadyRef = useRef(false);
   const themeUnsubRef = useRef<(() => void) | null>(null);
   const webkitRepaintDoneRef = useRef(false);
-  const [status, setStatus] = useState<'loading' | 'ready' | 'done'>('loading');
+  const webkitRepaintTimerRef = useRef<number | null>(null);
+  const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
   const [retryKey, setRetryKey] = useState(0);
 
@@ -231,6 +255,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const maxHeight = node.size.height;
   const nodeId = node.id;
   const frameKey = getExtAppBridgeInitKey(node, retryKey);
+  const hasReplayToolResult = toolResult != null;
   const iframeSandbox = resolveExtAppSandbox(null);
   // Phase 6 — opt-in ext-app AX bridge. When the node sets data.axCapabilities.enabled,
   // inject window.PMX_AX into the app HTML and accept emits below (server re-validates).
@@ -277,26 +302,42 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     return () => window.removeEventListener('message', onAxMessage);
   }, [axEnabled, axToken, nodeId]);
 
-  // Finding F (0.2.4): in a WebKit host panel (e.g. the GitHub Copilot app's
-  // WKWebView), the doubly-nested ext-app iframe (workbench iframe → mcp-app.html
-  // iframe) can lose the initial-paint race during board hydration and come up as a
-  // black tile for nodes already present at panel-load — clean in Blink (Chrome /
-  // Codex / our Playwright e2e) and clean for nodes created live after hydration.
-  // The deterministic recovery is an iframe remount (exactly what expand+close, and
-  // the error-retry button, already do). Replicate that recovery ONCE, on mount, in
-  // WebKit-only — gated on the engine so it is a strict no-op in Blink and cannot
-  // regress the engine we test against. Inline board instance only (the one that
-  // loads black); the expanded overlay already remounts on open.
+  // Finding F (0.2.4/0.2.5): in a WebKit host panel (e.g. the GitHub Copilot app's
+  // WKWebView, and Bun's headless WebKit WebView) the doubly-nested ext-app iframe
+  // (workbench iframe → mcp-app.html iframe) can come up as a black tile for nodes
+  // present at panel-load. The mcp-app shell loads blank, then the app boots over the
+  // bridge and draws its content AFTER load; under a cold-hydration burst WebKit does
+  // not composite that late draw, so the layer stays black (clean in Blink, and clean
+  // for a node created live into an already-idle panel). A parent-side transform/src
+  // nudge does NOT repair a black layer — only a full remount (new iframe element +
+  // bridge re-init, what expand+close does) does, and only when it lands in an idle
+  // moment. So: once the app has booted — `ready` for empty apps, `done` for restored
+  // apps that must replay saved tool output — under WebKit only, force ONE remount,
+  // SERIALIZED per node (an increasing slot delay) so concurrent ext-apps
+  // don't re-form a single compositing burst (the 0.2.4 fixed-250ms-on-mount remount
+  // fired mid-burst before the app had even booted, and all siblings re-raced —
+  // insufficient). This reliably repaints a SINGLE present-at-load ext-app; a board
+  // with several ext-apps present at WebKit panel-load can still black out (a host
+  // compositor limit — expand+close or Chrome remains the fallback; see SKILL.md).
+  // Strict no-op in Blink/Gecko; the e2e engine is unaffected. Inline instance only.
   useEffect(() => {
     if (expanded || webkitRepaintDoneRef.current) return;
+    if (!shouldScheduleWebKitRepaint(status, hasReplayToolResult)) return;
     if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     webkitRepaintDoneRef.current = true;
-    // Let the initial hydration burst settle, then force one remount so the nested
-    // iframe repaints (mirrors the post-hydration expand+close recovery).
-    const timer = window.setTimeout(() => setRetryKey((k) => k + 1), 250);
-    return () => window.clearTimeout(timer);
+    // Serialize: each ext-app repaints into a progressively-quieter panel so the
+    // cold-hydration burst becomes a sequence of single (always-successful) repaints.
+    // The timer is held in a ref and cleared only on UNMOUNT (separate effect), NOT in
+    // this effect's cleanup — otherwise a later status change (ready→done) would cancel
+    // the one-shot remount before it fires. The gate above runs once per node.
+    const delayMs = 250 + nextWebkitRepaintSlot() * 450;
+    webkitRepaintTimerRef.current = window.setTimeout(() => setRetryKey((k) => k + 1), delayMs);
     // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [status, hasReplayToolResult]);
+
+  useEffect(() => () => {
+    if (webkitRepaintTimerRef.current !== null) window.clearTimeout(webkitRepaintTimerRef.current);
   }, []);
 
   const toMcpTheme = (theme: string): McpUiTheme => (theme === 'light' ? 'light' : 'dark');
@@ -829,6 +870,10 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           {...iframeDocument.attributes}
           sandbox={iframeSandbox}
           allow={buildAllowAttribute(resourceMeta?.permissions)}
+          // NB: do NOT add the `.mcp-app-frame` GPU-layer class (translateZ(0)) here —
+          // it creates a stacking context that breaks the AX emit→ack round-trip in the
+          // expanded ext-app overlay (#55 e2e); the post-boot WebKit repaint remount
+          // below recovers a single present-at-load ext-app without it (Finding F).
           style={{
             flex: 1,
             width: '100%',

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;