pmx-canvas 0.10.0 → 0.12.0

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

@@ -32,6 +32,7 @@ import {
 } from '../../canvas-operations.js';
 import { resolveCreateGeometry, resolvePatchGeometry, validateCanvasNodePatch } from '../../canvas-geometry.js';
 import { normalizeNodeAxCapabilities } from '../../ax-interaction.js';
+import { isWorkCardState } from '../../../shared/ax-kinds.js';
 import { applyFileContentToNodeData, readFileNodeContent } from '../../file-content.js';
 import { unwatchFileForNode, watchFileForNode } from '../../file-watcher.js';
 import {
@@ -327,6 +328,21 @@ export function createdNodePayloadFromNode(
 
 // ── Operation cores (the SDK wraps these directly) ────────────
 
+function validateWorkCardData(data: Record<string, unknown> | undefined): void {
+  if (!data || data.workState === undefined) return;
+  if (!isWorkCardState(data.workState))
+    throw new OperationError('workState must be todo, in-progress, blocked, done or cancelled.');
+  if (data.detail !== undefined && typeof data.detail !== 'string')
+    throw new OperationError('Work card detail must be a string.');
+  if (
+    data.progress !== undefined &&
+    data.progress !== null &&
+    (typeof data.progress !== 'number' || !Number.isFinite(data.progress) || data.progress < 0 || data.progress > 100)
+  ) {
+    throw new OperationError('Work card progress must be a number from 0 to 100, or null to clear it.');
+  }
+}
+
 /**
  * Create a basic (non-webpage / non-group / non-primitive) node. Union of the
  * legacy handleCanvasAddNode generic branch; the SDK passes fileMode 'path',
@@ -338,6 +354,34 @@ export function createBasicCanvasNode(
 ): { node: CanvasNodeState; needsCodeGraphRecompute: boolean; sizeAdjustment?: CanvasSizeAdjustment } {
   const type = typeof body.type === 'string' ? body.type : '';
   const extraData = isRecord(body.data) ? body.data : undefined;
+  if (type === 'status' && extraData?.workItemId !== undefined) {
+    if (body.boardId !== undefined || options.prepareOnlyNodes)
+      throw new OperationError('Live work cards must be created on the active board.');
+    const owner = extraData.workItemBoardId ?? canvasState.activeBoardId;
+    if (
+      typeof extraData.workItemId !== 'string' ||
+      (owner !== null && typeof owner !== 'string') ||
+      !(owner === null ? canvasState.getWorkItems() : canvasState.getWorkItemsOnBoard(owner)).some(
+        (item) => item.id === extraData.workItemId,
+      )
+    )
+      throw new OperationError('Live work card requires an existing work item on its owning board.');
+    if (
+      ['title', 'content'].some((key) => body[key] !== undefined) ||
+      [
+        'title',
+        'content',
+        'workState',
+        'detail',
+        'progress',
+        'axWorkStatus',
+        'liveWorkAvailable',
+        'liveWorkSource',
+      ].some((key) => key in extraData)
+    )
+      throw new OperationError('Live work card fields are read-only; update the work item instead.');
+  }
+  if (type === 'status') validateWorkCardData(extraData);
   if (
     extraData &&
     ('attachmentId' in extraData || (isRecord(extraData.source) && 'attachmentId' in extraData.source))
@@ -415,6 +459,9 @@ export function createBasicCanvasNode(
           : {}),
       ...(typeof content === 'string' ? { content } : {}),
       ...(htmlMergedData && Object.keys(htmlMergedData).length > 0 ? { data: htmlMergedData } : {}),
+      ...(type === 'status' && typeof extraData?.workItemId === 'string'
+        ? { data: { ...extraData, workItemBoardId: extraData.workItemBoardId ?? canvasState.activeBoardId } }
+        : {}),
       ...(type === 'trace' && typeof body.toolName === 'string' ? { toolName: body.toolName } : {}),
       ...(type === 'trace' && typeof body.category === 'string' ? { category: body.category } : {}),
       ...(type === 'trace' && typeof body.status === 'string' ? { status: body.status } : {}),
@@ -446,6 +493,28 @@ export function buildNodePatch(
   body: Record<string, unknown>,
 ): { patch: Partial<CanvasNodeState>; groupChildIds?: string[] } {
   if (body.type !== undefined && body.type !== existing.type) throw new OperationError('Node type is immutable.');
+  if (existing.type === 'status') {
+    const data = isRecord(body.data) ? body.data : {};
+    if (
+      'workItemId' in data ||
+      'workItemBoardId' in data ||
+      (typeof existing.data.workItemId === 'string' &&
+        (body.title !== undefined ||
+          body.content !== undefined ||
+          [
+            'title',
+            'content',
+            'workState',
+            'detail',
+            'progress',
+            'axWorkStatus',
+            'liveWorkAvailable',
+            'liveWorkSource',
+          ].some((key) => key in data)))
+    ) {
+      throw new OperationError('Live work cards are read-only; create a presentation or update the work item instead.');
+    }
+  }
   if (
     existing.type === 'file' &&
     typeof existing.data.attachmentId === 'string' &&
@@ -561,6 +630,7 @@ export function buildNodePatch(
     }
     patch.data = existing.type === 'trace' ? mergeTraceNodeDataFields(data, body) : data;
   }
+  if (existing.type === 'status' && isRecord(patch.data)) validateWorkCardData(patch.data);
   const error = validateCanvasNodePatch({
     ...(patch.position ? { position: patch.position as { x: number; y: number } } : {}),
     ...(patch.size ? { size: patch.size as { width: number; height: number } } : {}),

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

@@ -284,6 +284,11 @@ const contextShape = {
   consumer: z.unknown().optional().describe('Stable consumer id used for the durable board-scoped cursor'),
   since: z.unknown().optional().describe('Explicit content revision; bypasses the durable consumer cursor'),
   budget: z.unknown().optional().describe('Maximum response size in UTF-16 code units'),
+  contextDelivery: z
+    .boolean()
+    .optional()
+    .describe('False prepares a brief without recording delivery or advancing a cursor.'),
+  includeSteering: z.boolean().optional().describe('False omits steering for hosts that deliver it separately.'),
 };
 const contextSchema = z.looseObject(contextShape);
 
@@ -292,8 +297,20 @@ const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<s
   mutates: false,
   input: contextSchema,
   inputShape: contextShape,
-  http: { method: 'GET', path: '/api/canvas/context' },
+  http: {
+    method: 'GET',
+    path: '/api/canvas/context',
+    readInput: (_req, params, url) => {
+      const input: Record<string, unknown> = { ...Object.fromEntries(url.searchParams), ...params };
+      for (const key of ['contextDelivery', 'includeSteering']) {
+        if (input[key] === 'false') input[key] = false;
+        else if (input[key] === 'true') input[key] = true;
+      }
+      return input;
+    },
+  },
   handler: (input) => {
+    canvasState.refreshContextWorkCards();
     const active = canvasState.getActiveBoard();
     if (!active) throw new OperationError('Open a board before requesting its context.', 409);
     const consumer =
@@ -507,7 +524,10 @@ const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<s
         })),
     );
     entries.push(
-      ...canvasState.getPendingSteering({ consumer: consumer ?? undefined, limit: 50 }).map((item) => ({
+      ...(input.includeSteering === false
+        ? []
+        : canvasState.getPendingSteering({ consumer: consumer ?? undefined, limit: 50 })
+      ).map((item) => ({
         sourceBoardId: active.id,
         nodeId: `steering:${item.id}`,
         reason: 'steer' as const,
@@ -553,7 +573,14 @@ const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<s
       entries,
       budget,
     });
-    if (consumer && !explicitSince && result.document && result.nextCursor !== null && !result.invalidCursor) {
+    if (
+      input.contextDelivery !== false &&
+      consumer &&
+      !explicitSince &&
+      result.document &&
+      result.nextCursor !== null &&
+      !result.invalidCursor
+    ) {
       canvasState.advanceContextBriefCursor(active.id, consumer, result.nextCursor);
     }
     return (result.document ?? {
@@ -634,6 +661,7 @@ const undoOperation = defineOperation<z.infer<typeof undoRedoSchema>, Record<str
       count: canvasState.contextPinnedNodeIds.size,
       nodeIds: Array.from(canvasState.contextPinnedNodeIds),
     });
+    ctx.emit('ax-state-changed', {});
     return { ok: true, description: `Undid: ${entry.description}` };
   },
 });
@@ -662,6 +690,7 @@ const redoOperation = defineOperation<z.infer<typeof undoRedoSchema>, Record<str
       count: canvasState.contextPinnedNodeIds.size,
       nodeIds: Array.from(canvasState.contextPinnedNodeIds),
     });
+    ctx.emit('ax-state-changed', {});
     return { ok: true, description: `Redid: ${entry.description}` };
   },
 });

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

@@ -364,6 +364,7 @@ const snapshotRestoreNodeOperation = defineOperation<
   handler: ({ id, nodeId, preserveHumanEdits }) => {
     const snapshot = canvasState.getSnapshotData(id ?? '');
     if (!snapshot) throw new OperationError('Snapshot not found', 404);
+    canvasState.assertSnapshotRestorable(id ?? '');
     const current = canvasState.getNode(nodeId ?? '');
     const earlier = snapshot.nodes.find((node) => node.id === nodeId);
     if (!current || !earlier)

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

@@ -13,7 +13,7 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
-import { tourSchema, rectSchema, cameraSchema, tourStopSchema } from '../../../shared/tour.js';
+import { tourSchema, rectSchema, cameraSchema, tourStopSchema, tourPresenterSchema } from '../../../shared/tour.js';
 import { canvasState } from '../../canvas-state.js';
 import {
   arrangeCanvasNodes,
@@ -339,6 +339,7 @@ const tourGetOperation = defineOperation({
 const tourGoShape = {
   stop: z.number().int().nonnegative().optional().describe('Zero-based stop index to go to'),
   step: z.enum(['next', 'previous']).optional().describe('Step relative to the current stop (clamped at the ends)'),
+  presenter: tourPresenterSchema.optional().describe('Document intent order and expected board activation'),
   present: z
     .boolean()
     .optional()
@@ -360,23 +361,24 @@ const tourGoOperation = defineOperation({
     if ((input.stop === undefined) === (input.step === undefined)) {
       throw new OperationError('Give exactly one of stop (index) or step ("next" | "previous").');
     }
-    const result = goToTourStop(input.stop ?? (input.step as 'next' | 'previous'));
-    ctx.emit('canvas-tour-step', { ...result, present: input.present !== false });
+    const result = goToTourStop(input.stop ?? (input.step as 'next' | 'previous'), input.presenter);
+    if (!('superseded' in result)) ctx.emit('canvas-tour-step', { ...result, present: input.present !== false });
     return { ok: true, ...result };
   },
 });
 
+const tourExitShape = { presenter: tourGoShape.presenter };
 const tourExitOperation = defineOperation({
   name: 'tour.exit',
   mutates: false,
-  input: z.object({}),
-  inputShape: {},
+  input: z.object(tourExitShape),
+  inputShape: tourExitShape,
   http: { method: 'POST', path: '/api/canvas/tour/exit' },
   mcp: { toolName: 'canvas_tour_exit', description: 'Leave presentation in every viewer.' },
-  handler: (_input, ctx) => {
-    exitTour();
-    ctx.emit('canvas-tour-exit', {});
-    return { ok: true };
+  handler: (input, ctx) => {
+    const result = exitTour(input.presenter);
+    if (!('superseded' in result)) ctx.emit('canvas-tour-exit', { ...result });
+    return { ok: true, ...result };
   },
 });
 

package/src/server/operations/registry.ts

@@ -359,6 +359,7 @@ function notePresence(
 ): void {
   if (!isPresenceWrite(op) || meta.suppressAutoGhost) return;
   const input = asRecord(rawInput);
+  if (name === 'board.move-selection' && (input.preview === true || asRecord(result).replayed === true)) return;
   // Delivery plumbing (claim/mark) must not book an anonymous transport
   // writer nor spam the timeline: attribute it to the consumer that marked,
   // and record no activity row — the Steer row flipping to delivered IS the
@@ -388,11 +389,52 @@ function notePresence(
   }
 }
 
+const operationTarget = new AsyncLocalStorage<{ boardId: string; agentId?: string }>();
+
+/** Also used by batch's internal node path, which does not dispatch an operation. */
+export function validateOperationTarget(name: string, input: Record<string, unknown>): string | undefined {
+  const inherited = operationTarget.getStore();
+  const target = input.targetBoardId === undefined ? inherited?.boardId : input.targetBoardId;
+  if (target === undefined) return undefined;
+  if (typeof target !== 'string' || !target.trim())
+    throw new OperationError('targetBoardId must be an existing board ID.');
+  if (
+    inherited &&
+    (target !== inherited.boardId || (input.agentId !== undefined && input.agentId !== inherited.agentId))
+  )
+    throw new OperationError('Nested operations must retain their board and agent identity.', 409);
+  if (name === 'board.update' && input.id !== target)
+    throw new OperationError('Board id conflicts with targetBoardId. Rebind before editing another board.', 409);
+  for (const key of [
+    'board',
+    'expectedBoardId',
+    'destinationBoardId',
+    ...(name === 'board.move-selection' ? ['sourceBoardId'] : []),
+  ]) {
+    if (input[key] !== undefined && input[key] !== target)
+      throw new OperationError(`${key} conflicts with targetBoardId. Rebind before targeting another board.`, 409);
+  }
+  if (['board.open', 'board.delete', 'backup.restore'].includes(name) || name.startsWith('webview.'))
+    throw new OperationError('This operation controls the shared view or workspace, not a scoped board.', 409);
+  return target;
+}
+
 export async function executeOperation(
   name: string,
   rawInput: unknown,
   meta: ExecuteOperationMeta = {},
 ): Promise<unknown> {
+  const input = asRecord(rawInput);
+  const target = validateOperationTarget(name, input);
+  if (target === undefined) return executeOnCurrentBoard(name, rawInput, meta);
+  const agentId =
+    operationTarget.getStore()?.agentId ?? (typeof input.agentId === 'string' ? input.agentId : undefined);
+  return operationTarget.run({ boardId: target, agentId }, () =>
+    canvasState.withBoard(target, () => executeOnCurrentBoard(name, { ...input, agentId }, meta)),
+  );
+}
+
+async function executeOnCurrentBoard(name: string, rawInput: unknown, meta: ExecuteOperationMeta): Promise<unknown> {
   // Check before attribution, board auto-open, ghosts, or any handler writes.
   meta.signal?.throwIfAborted();
   // Attribution follows this call chain across awaits and nested operations.
@@ -406,7 +448,8 @@ export async function executeOperation(
     async () => {
       const input = asRecord(rawInput);
       const deliversContext =
-        name !== 'node.get' || (input.contextDelivery !== false && input.contextDelivery !== 'false');
+        !['node.get', 'context.get'].includes(name) ||
+        (input.contextDelivery !== false && input.contextDelivery !== 'false');
       const recordRead = CONTEXT_READ_OPS.has(name) && deliversContext && !meta.fromWorkbench && !meta.proxiedRead;
       const requestedBoard =
         recordRead && 'board' in getOperation(name).inputShape && isString(input.board) && input.board.trim()
@@ -510,7 +553,8 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   const rawExpectedBoard = asRecord(rawInput).expectedBoardId;
   // HTTP DELETE query values are strings, including Home's JSON null.
   const expectedBoard = rawExpectedBoard === 'null' ? null : rawExpectedBoard;
-  if (expectedBoard !== undefined && expectedBoard !== canvasState.activeBoardId) {
+  // Relocations check their durable receipt first, then their explicit source board.
+  if (name !== 'board.move-selection' && expectedBoard !== undefined && expectedBoard !== canvasState.activeBoardId) {
     throw new OperationError('The active board changed. Refresh before retrying this action.', 409);
   }
   // File drops carry their captured board through the HTTP round trip. Check
@@ -638,8 +682,9 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   }
 
   const beforeBoard = canvasState.activeBoardId;
-  const beforeRevision =
-    name === 'board.create-from' || name === 'board.delete' ? canvasState.getContentRevision().revision : null;
+  const beforeRevision = ['board.create-from', 'board.delete', 'board.move-selection'].includes(name)
+    ? canvasState.getContentRevision().revision
+    : null;
   meta.signal?.throwIfAborted();
   const result = await op.execute(rawInput, operationContext);
   // Library writes can invalidate relations on the open board without being

package/src/server/server.ts

@@ -47,8 +47,8 @@ import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'nod
 import * as marked from 'marked';
 import { renderWikiMarkdown, resolveWikiLinks, wikiReferences } from './wiki-links.js';
 import { wikiLinksFromData } from '../shared/memory-graph.js';
-import { type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
-import { boardCatalogEpoch, boardsPayload } from './operations/ops/boards.js';
+import { type CanvasNodeState, IMAGE_MIME_MAP, boardCatalogEpoch, canvasState } from './canvas-state.js';
+import { boardsPayload } from './operations/ops/boards.js';
 import {
   buildAxBridge,
   buildAxStateBridge,
@@ -72,16 +72,16 @@ import { buildAgentContextPreamble } from '../shared/agent-context.js';
 import { buildCanvasAxSurfaceSnapshot } from './ax-context.js';
 import { resolveNodeAxCapabilities } from './ax-interaction.js';
 import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
-import { canvasThemeScheme, isCanvasTheme } from '../shared/themes.js';
+import { isCanvasTheme } from '../shared/themes.js';
 import { canOpenNodeAsSurface } from '../shared/surface.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
   cancelCodeGraphRecompute,
-  primeCanvasRuntimeBackends,
   setCanvasLayoutUpdateEmitter,
-  syncCanvasRuntimeBackends,
+  startBoardRuntime,
 } from './canvas-operations.js';
+import { createBoardLocal } from './board-local.js';
 import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENT_NAME_LENGTH } from './document-import.js';
 import { dispatchOperationRoute, setOperationEventEmitter } from './operations/index.js';
 import { intentRegistry } from './intent-registry.js';
@@ -105,7 +105,10 @@ const DEFAULT_PORT = 4313;
 
 let server: ReturnType<typeof Bun.serve> | null = null;
 let activeWorkspaceRoot = resolve(process.cwd());
-let primaryWorkbenchPath: string | null = null;
+const boardReplay = createBoardLocal(() => ({
+  path: null as string | null,
+  contextCards: null as Record<string, unknown> | null,
+}));
 let primaryWorkbenchSessionId = `pmx-${Date.now().toString(36)}`;
 let nextWorkbenchEventId = 1;
 let nextWorkbenchSubscriberId = 1;
@@ -113,7 +116,6 @@ const workbenchSubscribers = new Map<number, ReadableStreamDefaultController<Uin
 const textEncoder = new TextEncoder();
 let primaryWorkbenchAutoOpenEnabled = true;
 const initialCanvasThemeSetting = normalizeCanvasTheme(process.env.PMX_CANVAS_THEME);
-let lastWorkbenchContextCardsEnvelope: Record<string, unknown> | null = null;
 
 // Operation-registry SSE wiring (plan-005): the registry never imports this
 // module — the workbench event emitter is injected here, mirroring the
@@ -941,6 +943,21 @@ export function onWorkbenchEvent(listener: (event: string) => void): () => void
 }
 
 function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPayload): void {
+  if (canvasState.isBackgroundBoard) {
+    if (event === 'canvas-layout-update' || event === 'boards-changed')
+      canvasState.withVisibleBoard(() => broadcastWorkbenchEvent('boards-changed', boardsPayload()));
+    else if (event === 'ax-state-changed') {
+      const ownerBoardId = canvasState.activeBoardId;
+      canvasState.withVisibleBoard(() => {
+        const layout = canvasState.getLayout();
+        if (layout.nodes.some((node) => node.type === 'status' && node.data.workItemBoardId === ownerBoardId))
+          broadcastWorkbenchEvent('canvas-layout-update', { layout });
+      });
+    } else if (event === 'agent-presence')
+      canvasState.withVisibleBoard(() => broadcastWorkbenchEvent(event, { ...payload, ...agentPresence.snapshot() }));
+    return;
+  }
+  payload = { ...payload, boardId: canvasState.visibleBoardId };
   let remoteEdgesChanged = false;
   if (event === 'canvas-layout-update') {
     // Remote footer titles come from the catalog. Refresh it on endpoint changes
@@ -960,7 +977,7 @@ function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPa
     payload = {
       ...payload,
       catalogEpoch: boardCatalogEpoch,
-      boardGeneration: canvasState.boardGeneration,
+      boardGeneration: canvasState.visibleBoardGeneration,
       boardId: canvasState.activeBoardId,
     };
   }
@@ -990,8 +1007,8 @@ function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPa
 
 function setPrimaryWorkbenchPath(safePath: string, source: string): void {
   const resolved = resolve(safePath);
-  if (primaryWorkbenchPath === resolved) return;
-  primaryWorkbenchPath = resolved;
+  if (boardReplay.current.path === resolved) return;
+  boardReplay.current.path = resolved;
   broadcastWorkbenchEvent('workbench-open', {
     path: resolved,
     title: basename(resolved),
@@ -1504,44 +1521,6 @@ function handleIframeProbe(): Response {
   );
 }
 
-// ── Ext-app recovery diagnostics (0.3.2 report Finding N) ──────
-//
-// The WebKit black-tile recovery trail is otherwise trapped inside host panels
-// without devtools (the Copilot WKWebView). Clients mirror their bounded
-// recovery log here; agents/testers read it back over HTTP. In-memory only,
-// diagnostics-grade: no persistence, no snapshots.
-const EXT_APP_RECOVERY_LOG_MAX = 500;
-const EXT_APP_RECOVERY_FIELD_MAX = 300;
-const extAppRecoveryEntries: Array<Record<string, unknown>> = [];
-
-/**
- * Clamp a reported entry to the known trail shape ({ t, nodeId, event,
- * visibility }) with bounded string lengths. The count trim below caps the
- * number of entries; this caps bytes per entry, so the in-memory log stays
- * diagnostics-sized no matter what a client posts.
- */
-function clampExtAppRecoveryEntry(entry: Record<string, unknown>): Record<string, unknown> {
-  const clamped: Record<string, unknown> = {};
-  if (typeof entry.t === 'number' && Number.isFinite(entry.t)) clamped.t = entry.t;
-  for (const key of ['nodeId', 'event', 'visibility'] as const) {
-    const value = entry[key];
-    if (typeof value === 'string') clamped[key] = value.slice(0, EXT_APP_RECOVERY_FIELD_MAX);
-  }
-  return clamped;
-}
-
-function handleExtAppRecoveryReport(entries: unknown): Response {
-  if (!Array.isArray(entries)) return responseJson({ ok: false, error: 'entries must be an array' }, 400);
-  for (const entry of entries.slice(0, 100)) {
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
-    extAppRecoveryEntries.push(clampExtAppRecoveryEntry(entry as Record<string, unknown>));
-  }
-  if (extAppRecoveryEntries.length > EXT_APP_RECOVERY_LOG_MAX) {
-    extAppRecoveryEntries.splice(0, extAppRecoveryEntries.length - EXT_APP_RECOVERY_LOG_MAX);
-  }
-  return responseJson({ ok: true, total: extAppRecoveryEntries.length });
-}
-
 // ── Node surfaces ("Open as site") ─────────────────────────────
 //
 // One stable, node-addressable URL — /api/canvas/surface/:nodeId — that serves
@@ -1841,14 +1820,7 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
   );
 
   const themeValue = url.searchParams.get('theme');
-  // The viewer bundle themes dark/light/high-contrast directly; other named
-  // canvas themes (midnight, sepia, …) collapse to their dark/light scheme.
-  const theme =
-    themeValue === 'dark' || themeValue === 'light' || themeValue === 'high-contrast'
-      ? themeValue
-      : isCanvasTheme(themeValue)
-        ? canvasThemeScheme(themeValue)
-        : undefined;
+  const theme = themeValue === 'dark' || themeValue === 'light' || isCanvasTheme(themeValue) ? themeValue : 'harbor';
   const title = (node.data.title as string) || node.id;
   // Devtools panel is double-gated: the operator must opt in via the env flag
   // AND the request must carry ?devtools=1. Off by default in all normal runs.
@@ -2118,6 +2090,7 @@ function handleRead(pathLike: string): Response {
 
 function handleWorkbenchState(): Response {
   const mcpAppHost = getMcpAppHostSnapshot();
+  const primaryWorkbenchPath = boardReplay.current.path;
   if (!primaryWorkbenchPath) {
     return responseJson({
       sessionId: primaryWorkbenchSessionId,
@@ -2130,7 +2103,7 @@ function handleWorkbenchState(): Response {
 
   const safePath = resolveWorkspaceMarkdownPath(primaryWorkbenchPath);
   if (!safePath || !existsSync(safePath)) {
-    primaryWorkbenchPath = null;
+    boardReplay.current.path = null;
     return responseJson({
       sessionId: primaryWorkbenchSessionId,
       path: null,
@@ -2247,6 +2220,7 @@ async function handleWorkbenchIntent(req: Request): Promise<Response> {
 function buildWorkbenchConnectSnapshot(
   requestedSessionId: string,
 ): Array<{ event: string; payload: Record<string, unknown> }> {
+  const { path: primaryWorkbenchPath, contextCards: lastWorkbenchContextCardsEnvelope } = boardReplay.current;
   const continuity =
     requestedSessionId.length === 0
       ? 'fresh'
@@ -2274,6 +2248,9 @@ function buildWorkbenchConnectSnapshot(
       timestamp: new Date().toISOString(),
     },
   });
+  // Establish ownership in this ordered stream before layouts and live tour
+  // commands. The separate catalog HTTP response may arrive after either.
+  events.push({ event: 'boards-changed', payload: boardsPayload() });
   if (primaryWorkbenchPath) {
     events.push({
       event: 'workbench-open',
@@ -3353,10 +3330,16 @@ export function emitPrimaryWorkbenchEvent(event: string, payload: PrimaryWorkben
     timestamp: new Date().toISOString(),
   };
   if (event === 'context-cards') {
-    lastWorkbenchContextCardsEnvelope = { ...envelope };
+    boardReplay.current.contextCards = { ...envelope };
   }
   syncEventToCanvasState(event, envelope);
-  if (primaryWorkbenchAutoOpenEnabled && (event === 'workbench-open' || event === 'ext-app-open')) {
+  // Events can create server state. Apply them to their producer's board before
+  // deciding whether they belong in the human's currently visible projection.
+  if (
+    !canvasState.isBackgroundBoard &&
+    primaryWorkbenchAutoOpenEnabled &&
+    (event === 'workbench-open' || event === 'ext-app-open')
+  ) {
     ensureCanvasBrowserOpen();
   }
   broadcastWorkbenchEvent(event, envelope);
@@ -3443,6 +3426,27 @@ export interface CanvasServerOptions {
   allowExternalMcp?: boolean;
 }
 
+// SDK/MCP producers can own cards before an HTTP listener starts.
+canvasState.setMoveRuntimeBlockers(() => {
+  const blockers = new Map<string, string>();
+  for (const id of traceManager.ownedNodeIds) blockers.set(id, 'the trace manager still owns this card');
+  for (const [response, prompt] of serverResponseToThreadMap) {
+    blockers.set(response, 'an active response is routed to this card');
+    blockers.set(prompt, 'an active response is routed to this prompt');
+  }
+  for (const intent of pendingWorkbenchIntents) {
+    if (intent.type !== 'canvas-prompt') continue;
+    for (const id of [
+      intent.payload.nodeId,
+      intent.payload.parentNodeId,
+      ...(Array.isArray(intent.payload.contextNodeIds) ? intent.payload.contextNodeIds : []),
+    ]) {
+      if (typeof id === 'string') blockers.set(id, 'a queued prompt still refers to this card');
+    }
+  }
+  return blockers;
+});
+
 export function startCanvasServer(options: CanvasServerOptions = {}): string | null {
   if (server) {
     return typeof server.port === 'number' ? loopbackBaseUrl(server.port) : null;
@@ -3489,12 +3493,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   });
   if (loaded) {
     console.log('  Canvas state restored from .pmx-canvas/canvas.db');
-    primeCanvasRuntimeBackends({ forceRehydrateExtApps: true });
-    const rehydrate = () => syncCanvasRuntimeBackends({ forceRehydrateExtApps: true, alreadyPrimed: true });
-    const pending = options.allowExternalMcp === false ? withoutExternalMcp(rehydrate) : rehydrate();
-    void pending.finally(() => {
-      emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-    });
+    const rehydrate = () => startBoardRuntime({ forceRehydrateExtApps: true });
+    if (options.allowExternalMcp === false) withoutExternalMcp(rehydrate);
+    else rehydrate();
   }
 
   rotatePrimaryWorkbenchSessionIfNeeded();
@@ -3549,6 +3550,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
               workspace: activeWorkspaceRoot,
               pid: process.pid,
               version: serverPackageVersion(),
+              // The stamp open tabs reload on, read once per process: after a rebuild it lags
+              // dist/ on disk, and already-open tabs keep old JS until the server restarts.
+              bundleStamp: canvasBundleStamp(),
               contracts: [CANVAS_APP_WRITE_CONTRACT],
               persistence: canvasState.persistenceHealth,
             });
@@ -3571,16 +3575,6 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleJsonRenderView(url);
           }
 
-          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'POST') {
-            const body = await readJson(req);
-            if (body === null) return malformedJsonResponse();
-            return handleExtAppRecoveryReport(body.entries);
-          }
-
-          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'GET') {
-            return responseJson({ ok: true, entries: extAppRecoveryEntries });
-          }
-
           if (url.pathname === '/api/canvas/frame-documents' && req.method === 'POST') {
             return handleCreateFrameDocument(req);
           }