pmx-canvas 0.7.2 → 0.8.0

package/src/mcp/workbench-app.ts

@@ -0,0 +1,211 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { listOperations, OperationError } from '../server/operations/index.js';
+import { matchOperationPath, readOperationInput } from '../server/operations/http.js';
+import type { CanvasAccess } from './canvas-access.js';
+
+// Explicitly bounded to workbench operations. No shell, automation, arbitrary
+// HTTP proxy, external MCP tool calls, or caller-supplied authority headers.
+const writes = new Set([
+  'board.create',
+  'board.open',
+  'board.update',
+  'board.create-from',
+  'board.delete',
+  'node.add',
+  'jsonrender.add',
+  'graph.add',
+  'node.update',
+  'node.remove',
+  'node.refresh',
+  'edge.add',
+  'edge.update',
+  'edge.remove',
+  'group.create',
+  'group.add',
+  'group.remove',
+  'pin.set',
+  'annotation.add',
+  'annotation.remove',
+  'theme.set',
+  'viewport.set',
+  'canvas.apply-updates',
+  'canvas.clear',
+  'arrange',
+  'node.focus',
+  'view.fit',
+  'snapshot.save',
+  'snapshot.restore',
+  'snapshot.delete',
+  'tour.set',
+  'ax.focus.set',
+  'ax.policy.set',
+  'ax.work.create',
+  'ax.work.update',
+  'ax.review.add',
+  'ax.review.update',
+  'ax.elicitation.respond',
+  'ax.mode.resolve',
+  'ax.steer',
+  'ax.event.record',
+  'ax.presence.set',
+  'ax.interaction.submit',
+  'intent.clear',
+  'import.request',
+  'import.cancel',
+  'import.commit',
+  'export.run',
+]);
+
+function readableAsset(path: string): boolean {
+  return (
+    [
+      '/health',
+      '/api/workbench/poll',
+      '/api/workbench/state',
+      '/api/file',
+      '/api/canvas/json-render/view',
+      '/api/canvas/file-bytes',
+    ].includes(path) ||
+    /^\/api\/canvas\/(surface|image|frame-documents|exports)\/[^/]+$/.test(path) ||
+    /^\/api\/canvas\/attachments\/[^/]+\/bytes$/.test(path)
+  );
+}
+
+/** HTTP-shaped replies let the real workbench retain its existing API contracts. */
+export function registerWorkbenchApp(server: McpServer, ensureCanvas: () => Promise<CanvasAccess>): void {
+  server.registerTool(
+    'pmx_workbench_request',
+    {
+      title: 'PMX workbench transport',
+      description: 'App-only transport for the PMX workbench. Not an assistant tool.',
+      inputSchema: {
+        path: z.string().max(8192),
+        method: z.enum(['GET', 'POST', 'PATCH', 'PUT', 'DELETE', 'HEAD']),
+        body: z.string().max(4_000_000).optional(),
+        expectedBoardId: z.string().nullable(),
+      },
+      // Workbench webpage/image actions can fetch user-chosen external URLs.
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+      _meta: { ui: { visibility: ['app'] } },
+    },
+    async (input) => {
+      const reply = (status: number, body: string, contentType = 'application/json', encoding = 'text') => ({
+        content: [
+          { type: 'text' as const, text: status < 400 ? 'Workbench request completed.' : 'Workbench request refused.' },
+        ],
+        _meta: { response: { status, body, contentType, encoding } },
+      });
+      try {
+        const canvas = await ensureCanvas();
+        const base = canvas.remoteBaseUrl ?? `http://127.0.0.1:${canvas.port}`;
+        const url = new URL(input.path, base);
+        if (
+          !input.path.startsWith('/') ||
+          input.path.startsWith('//') ||
+          input.path.includes('\\') ||
+          url.origin !== new URL(base).origin ||
+          url.username ||
+          url.password ||
+          url.hash
+        ) {
+          throw new OperationError('Only local PMX workbench paths are allowed.', 403);
+        }
+        const req = new Request(url, {
+          method: input.method,
+          headers: { 'Content-Type': 'application/json' },
+          ...(input.body === undefined ? {} : { body: input.body }),
+        });
+        for (const op of listOperations()) {
+          const route = op.http;
+          if (!route || route.method !== input.method) continue;
+          const params = matchOperationPath(route.path, url.pathname);
+          if (!params) continue;
+          if (!url.pathname.startsWith('/api/canvas/') || (input.method !== 'GET' && !writes.has(op.name)))
+            throw new OperationError('This action requires the local PMX workbench.', 403);
+          const args = route.readInput
+            ? await route.readInput(req, params, url)
+            : await readOperationInput(req, params, url);
+          if (input.method !== 'GET') args.expectedBoardId = input.expectedBoardId;
+          // This profile is one agent transport, never browser/system authority
+          // or a caller-selected writer whose wider territory could bypass a fence.
+          args.source = 'mcp';
+          delete args.agentId;
+          if (
+            op.name === 'ax.interaction.submit' &&
+            (args.type === 'ax.approval.resolve' || args.type === 'ax.flow.materialize')
+          )
+            throw new OperationError('Resolve approvals and materialize flows in the local PMX workbench.', 403);
+          if (op.name === 'node.add' || op.name === 'node.update') {
+            const data = args.data;
+            const nodeType = op.name === 'node.add' ? args.type : (await canvas.getNode(String(args.id)))?.type;
+            // Trace tool names describe past activity; they never launch a backend.
+            const launchFields = ['transportConfig', 'toolInput', 'serverName', 'appSessionId'];
+            if (nodeType !== 'trace') launchFields.push('toolName');
+            if (
+              (op.name === 'node.add' && args.type === 'mcp-app') ||
+              (data && typeof data === 'object' && launchFields.some((field) => field in data))
+            )
+              throw new OperationError('Configure external MCP apps in the local PMX workbench.', 403);
+          }
+          if (
+            op.name === 'node.update' &&
+            ('content' in args || (args.data && typeof args.data === 'object' && 'content' in args.data))
+          ) {
+            if (typeof args.expectedContentRevision !== 'number')
+              throw new OperationError('Read the note before editing: a content revision is required.', 409);
+            const node = await canvas.getNode(String(args.id));
+            if (node?.data.path) throw new OperationError('Edit file-linked content in the local PMX workbench.', 403);
+          }
+          const result = await canvas.invoker().invoke(op.name, args);
+          return reply(route.status ? route.status(result) : 200, JSON.stringify(result));
+        }
+        if (
+          !((input.method === 'GET' || input.method === 'HEAD') && readableAsset(url.pathname)) &&
+          !(input.method === 'POST' && url.pathname === '/api/render')
+        ) {
+          throw new OperationError('This action requires the local PMX workbench.', 403);
+        }
+        // Resolve only PMX's internal surface redirects. Never follow to arbitrary
+        // hosts or return the workbench HTML (which carries its human boot token).
+        let target = url;
+        let response: Response | undefined;
+        for (let redirects = 0; redirects < 3; redirects++) {
+          response = await fetch(target, {
+            method: input.method,
+            body: input.body,
+            headers: { 'Content-Type': 'application/json' },
+            redirect: 'manual',
+            signal: AbortSignal.timeout(15_000),
+          });
+          if (response.status < 300 || response.status >= 400) break;
+          const next = new URL(response.headers.get('location') ?? '', target);
+          if (next.origin !== url.origin || !readableAsset(next.pathname))
+            throw new OperationError('External surfaces must be opened outside the embedded workbench.', 403);
+          target = next;
+        }
+        if (!response || (response.status >= 300 && response.status < 400))
+          throw new OperationError('Could not resolve the PMX surface.');
+        const bytes = await response.arrayBuffer();
+        if (bytes.byteLength > 24 * 1024 * 1024)
+          throw new OperationError('This asset is too large for the MCP connection.');
+        const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+        const text = /^(text\/|application\/(json|javascript))/.test(contentType);
+        return reply(
+          response.status,
+          text ? new TextDecoder().decode(bytes) : Buffer.from(bytes).toString('base64'),
+          contentType,
+          text ? 'text' : 'base64',
+        );
+      } catch (error) {
+        if (error instanceof OperationError)
+          return reply(error.status, JSON.stringify({ ok: false, error: error.message }));
+        console.error('[workbench-app] request failed', error);
+        return reply(
+          502,
+          JSON.stringify({ ok: false, error: 'PMX workbench request failed. Check the daemon and retry.' }),
+        );
+      }
+    },
+  );
+}

package/src/server/agent-presence.ts

@@ -32,7 +32,7 @@ import {
   PRESENCE_TOOLING_SETTLE_MS,
   TRANSPORT_SOURCES,
 } from '../shared/agent-presence.js';
-import { serializeNodeForAgentContext } from './agent-context.js';
+import { serializeNodeForAgentContext } from '../shared/agent-context.js';
 import type { PmxAxActivityKind } from './ax-state.js';
 import { type CanvasNodeState, canvasState } from './canvas-state.js';
 import { OperationError } from './operations/types.js';
@@ -205,6 +205,8 @@ interface StoredPresence extends AgentPresence {
   lastActivityNodeId: string | null;
   /** Snapshot of the board taken when this session attached (the receipt diffs against it). */
   startSnapshotId: string | null;
+  /** When this session attached (ISO); the receipt counts reads and pins from here. */
+  startedAt: string | null;
 }
 
 function presenceKey(source: string, agentId: string | null | undefined): string {
@@ -230,7 +232,12 @@ export function estimateContextBudget(): ContextBudget {
 /** Returns the id of the pre-session snapshot the server took, if any. */
 type SessionStartListener = (presence: AgentPresence) => string | null;
 export type SessionEndReason = 'human' | 'agent' | 'idle-timeout';
-type SessionEndListener = (presence: AgentPresence, startSnapshotId: string | null, endedBy: SessionEndReason) => void;
+type SessionEndListener = (
+  presence: AgentPresence,
+  startSnapshotId: string | null,
+  endedBy: SessionEndReason,
+  startedAt: string | null,
+) => void;
 
 export class AgentPresenceRegistry {
   private readonly presences = new Map<string, StoredPresence>();
@@ -392,6 +399,7 @@ export class AgentPresenceRegistry {
       phaseSetMs: now,
       toolingUntilMs: null,
       startSnapshotId: null,
+      startedAt: null,
     };
     const wasAttached = stored.attached;
     stored.lastSeenMs = now;
@@ -448,6 +456,7 @@ export class AgentPresenceRegistry {
       // moment stays the receipt baseline via the inherited snapshot. A
       // placeholder that already adopted work is a real session and stays.
       let inheritedSnapshotId: string | null = null;
+      let inheritedStartedAt: string | null = null;
       if (stored.source !== 'browser') {
         const placeholder = [...this.presences.values()].find(
           (presence) =>
@@ -463,13 +472,20 @@ export class AgentPresenceRegistry {
             if (target === placeholder.sessionId) this.aliases.set(channel, key);
           }
           inheritedSnapshotId = placeholder.startSnapshotId;
+          inheritedStartedAt = placeholder.startedAt;
         }
       }
       stored.startSnapshotId = inheritedSnapshotId ?? this.onSessionStart(this.publicView(stored, now));
+      stored.startedAt = inheritedStartedAt ?? new Date(now).toISOString();
     }
     if (input.attached === false) {
       if (wasAttached)
-        this.onSessionEnd(this.publicView(stored, now), stored.startSnapshotId, input.endedBy ?? 'agent');
+        this.onSessionEnd(
+          this.publicView(stored, now),
+          stored.startSnapshotId,
+          input.endedBy ?? 'agent',
+          stored.startedAt,
+        );
       // An explicit detach always removes the presence. In particular, a
       // worker that reports attached:false must not be refreshed into another
       // full activity TTL as an external writer.
@@ -481,7 +497,24 @@ export class AgentPresenceRegistry {
     }
     if (input.focusNodeId !== undefined) stored.focusNodeId = input.focusNodeId;
     if (input.parentAgentId !== undefined) stored.parentAgentId = input.parentAgentId;
-    if (input.cursor !== undefined) stored.cursor = input.cursor;
+    if (input.cursor !== undefined) {
+      // A MOVING cursor is the agent visibly working: it keeps a live explicit
+      // `tooling` from settling (a host streaming cursor moves after one
+      // `tooling` report read as Idle within seconds). A stationary heartbeat
+      // is not activity, and `thinking` keeps its own longer clock (below).
+      const moved =
+        input.cursor !== null && (stored.cursor?.x !== input.cursor.x || stored.cursor?.y !== input.cursor.y);
+      if (
+        moved &&
+        input.phase === undefined &&
+        stored.phase === 'tooling' &&
+        stored.toolingUntilMs !== null &&
+        stored.toolingUntilMs > now
+      ) {
+        stored.toolingUntilMs = now + PRESENCE_TOOLING_SETTLE_MS;
+      }
+      stored.cursor = input.cursor;
+    }
     if (input.contextUsage !== undefined) stored.contextUsage = input.contextUsage;
     if (input.phase === 'tooling' && input.derivedTooling) {
       // Copilot's finding: an op-derived tooling touch used to CLOBBER the
@@ -585,7 +618,8 @@ export class AgentPresenceRegistry {
     const removed = this.presences.delete(sessionId);
     if (removed) {
       this.dropAliasesTo(sessionId);
-      if (stored?.attached) this.onSessionEnd(this.publicView(stored, Date.now()), stored.startSnapshotId, 'agent');
+      if (stored?.attached)
+        this.onSessionEnd(this.publicView(stored, Date.now()), stored.startSnapshotId, 'agent', stored.startedAt);
       this.scheduleEmit();
     }
     this.maybeStopSweeper();
@@ -700,7 +734,12 @@ export class AgentPresenceRegistry {
         this.presences.delete(key);
         this.dropAliasesTo(key);
         if (presence.attached)
-          this.onSessionEnd(this.publicView(presence, now), presence.startSnapshotId, 'idle-timeout');
+          this.onSessionEnd(
+            this.publicView(presence, now),
+            presence.startSnapshotId,
+            'idle-timeout',
+            presence.startedAt,
+          );
         changed = true;
         continue;
       }

package/src/server/ax-context.ts

@@ -1,4 +1,4 @@
-import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../shared/agent-context.js';
 import {
   type PmxAxHumanAnnotation,
   buildAxContext,

package/src/server/ax-state.ts

@@ -1,7 +1,7 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import { clampGateTtlMs, DEFAULT_GATE_TTL_MS } from '../shared/approval-gates.js';
 import type { AxApprovalStatus, AxEventKind, AxWorkItemStatus } from '../shared/ax-kinds.js';
-import type { AgentContextNode } from './agent-context.js';
+import type { AgentContextNode } from '../shared/agent-context.js';
 import type { ActorAttribution } from './attribution.js';
 
 export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';

package/src/server/board-export.ts

@@ -208,6 +208,8 @@ async function collect(
   if (!read) return null;
   const { board, state } = read;
   const theme = canvasThemeScheme(state.theme ?? canvasState.theme);
+  // Exports collapse to a scheme; surface documents take the theme that draws it.
+  const surfaceTheme = theme === 'light' ? 'daylight' : 'harbor';
   const remoteImages = new Set<string>();
   const links = new Set<string>();
   const frameNetworkDestinations = new Set<string>();
@@ -383,7 +385,8 @@ async function collect(
         const html = text(data.html) || text(data.content);
         collectFrameNetworkDestinations(html, frameNetworkDestinations);
         manifest.frames += 1;
-        if (withFrames) card.frame = buildHtmlSurfaceDocument(html, { theme, title, inlineThemeCss: themeCss });
+        if (withFrames)
+          card.frame = buildHtmlSurfaceDocument(html, { theme: surfaceTheme, title, inlineThemeCss: themeCss });
         break;
       }
       case 'mermaid':
@@ -395,7 +398,7 @@ async function collect(
               '<script src="/canvas/mermaid-entry.js"></script>',
               `<script src="${MERMAID_SRC}"></script>`,
             ),
-            { theme, title, inlineThemeCss: themeCss },
+            { theme: surfaceTheme, title, inlineThemeCss: themeCss },
           );
         }
         break;

package/src/server/canvas-db.ts

@@ -6,6 +6,7 @@
  */
 
 import { Database } from 'bun:sqlite';
+import type { ActorAttribution } from './attribution.js';
 import { CONTEXT_READS_SCHEMA_SQL } from './context-reads.js';
 import { MIGRATED_SNAPSHOT_CATEGORY, normalizeBoardCategory } from '../shared/boards.js';
 import { tourSchema, type Tour } from '../shared/tour.js';
@@ -48,7 +49,7 @@ const SCHEMA_VERSION = 2;
 
 export type CanvasTheme = CanvasThemeName;
 
-export function normalizeCanvasTheme(value: unknown, fallback: CanvasTheme = 'dark'): CanvasTheme {
+export function normalizeCanvasTheme(value: unknown, fallback: CanvasTheme = 'harbor'): CanvasTheme {
   return normalizeCanvasThemeName(value, fallback);
 }
 
@@ -122,6 +123,7 @@ const SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS context_pins (
     board_id TEXT NOT NULL,
     node_id TEXT NOT NULL,
+    meta TEXT,
     PRIMARY KEY (board_id, node_id)
   );
 
@@ -185,6 +187,7 @@ const SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS snapshot_pins (
     snapshot_id TEXT NOT NULL,
     node_id TEXT NOT NULL,
+    meta TEXT,
     PRIMARY KEY (snapshot_id, node_id)
   );
 
@@ -335,10 +338,29 @@ export interface PersistedCanvasState {
   edges: CanvasEdge[];
   annotations?: CanvasAnnotation[];
   contextPins: string[];
+  /** Who pinned each context pin, when and why; pins without an entry have an unknown pinner. */
+  contextPinMeta?: Record<string, ContextPinMeta>;
   ax?: PmxAxState;
   revisionState?: PersistedRevisionState;
 }
 
+export interface ContextPinMeta {
+  pinnedBy: ActorAttribution;
+  pinnedAt: string;
+  reason?: string;
+}
+
+function pinMetaJson(state: PersistedCanvasState, nodeId: string): string | null {
+  const meta = state.contextPinMeta?.[nodeId];
+  return meta ? JSON.stringify(meta) : null;
+}
+
+function pinMetaFromRows(rows: Array<{ node_id: string; meta: string | null }>): Record<string, ContextPinMeta> {
+  const meta: Record<string, ContextPinMeta> = {};
+  for (const row of rows) if (row.meta) meta[row.node_id] = JSON.parse(row.meta) as ContextPinMeta;
+  return meta;
+}
+
 export interface PersistedRevisionState {
   revision: number;
   floor: number;
@@ -400,6 +422,9 @@ export function openCanvasDb(dbPath: string, options: OpenCanvasDbOptions = {}):
   ensureColumn(db, 'ax_steering', 'agent_id', 'agent_id TEXT');
   ensureColumn(db, 'ax_steering', 'target', 'target TEXT');
   ensureColumn(db, 'context_reads', 'board_id', 'board_id TEXT');
+  ensureColumn(db, 'context_reads', 'read_nodes', "read_nodes TEXT NOT NULL DEFAULT '{}'");
+  ensureColumn(db, 'context_pins', 'meta', 'meta TEXT');
+  ensureColumn(db, 'snapshot_pins', 'meta', 'meta TEXT');
   ensureColumn(db, 'boards', 'category', 'category TEXT');
   ensureColumn(db, 'boards', 'readme_node_id', 'readme_node_id TEXT');
   ensureColumn(db, 'nodes', 'attribution', "attribution TEXT NOT NULL DEFAULT '{}' ");
@@ -470,6 +495,7 @@ function migrateToBoards(db: Database, dbPath: string, boardName: string): void
       if (existing.has(table)) db.exec(`ALTER TABLE ${table} RENAME TO ${table}_v1`);
     }
     if (existing.has('snapshots')) ensureColumn(db, 'snapshots', 'board_id', 'board_id TEXT');
+    if (existing.has('snapshot_pins')) ensureColumn(db, 'snapshot_pins', 'meta', 'meta TEXT');
     db.exec(SCHEMA_SQL);
 
     if (hasBoard) {
@@ -552,10 +578,10 @@ function snapshotsToBoards(db: Database): void {
       `INSERT INTO annotations (board_id, ${annotationColumns}) SELECT ?, ${annotationColumns} FROM snapshot_annotations WHERE snapshot_id = ?`,
       [boardId, snapshot.id],
     );
-    db.run('INSERT INTO context_pins (board_id, node_id) SELECT ?, node_id FROM snapshot_pins WHERE snapshot_id = ?', [
-      boardId,
-      snapshot.id,
-    ]);
+    db.run(
+      'INSERT INTO context_pins (board_id, node_id, meta) SELECT ?, node_id, meta FROM snapshot_pins WHERE snapshot_id = ?',
+      [boardId, snapshot.id],
+    );
     const ax = meta.get('ax_state');
     if (ax) db.run("INSERT INTO ax_state (board_id, key, value) VALUES (?, 'state', ?)", [boardId, ax]);
     deleteSnapshotFromDB(db, snapshot.id);
@@ -775,10 +801,12 @@ export function saveStateToDB(db: Database, boardId: string, state: PersistedCan
     }
     deleteMissingRows(db, 'annotations', 'id', boardId, new Set(annotations.map((annotation) => annotation.id)));
 
-    // Save context pins (node_id is the whole row — nothing to update)
-    const insertPin = db.prepare('INSERT OR IGNORE INTO context_pins (board_id, node_id) VALUES (?, ?)');
+    // Save context pins with who pinned them
+    const insertPin = db.prepare(
+      'INSERT INTO context_pins (board_id, node_id, meta) VALUES (?, ?, ?) ON CONFLICT(board_id, node_id) DO UPDATE SET meta = excluded.meta WHERE context_pins.meta IS NOT excluded.meta',
+    );
     for (const pinId of state.contextPins) {
-      insertPin.run(boardId, pinId);
+      insertPin.run(boardId, pinId, pinMetaJson(state, pinId));
     }
     deleteMissingRows(db, 'context_pins', 'node_id', boardId, new Set(state.contextPins));
 
@@ -905,9 +933,11 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
   // Load context pins
   interface PinRow {
     node_id: string;
+    meta: string | null;
   }
-  const pinRows = db.query<PinRow, [string]>('SELECT node_id FROM context_pins WHERE board_id = ?').all(id);
+  const pinRows = db.query<PinRow, [string]>('SELECT node_id, meta FROM context_pins WHERE board_id = ?').all(id);
   const contextPins = pinRows.map((row) => row.node_id);
+  const contextPinMeta = pinMetaFromRows(pinRows);
 
   const axRow = db
     .query<{ value: string }, [string, string]>('SELECT value FROM ax_state WHERE board_id = ? AND key = ?')
@@ -925,6 +955,7 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
     edges,
     annotations,
     contextPins,
+    contextPinMeta,
     ax: parsePersistedAxState(axRow?.value),
     revisionState: revisionRaw ? (JSON.parse(revisionRaw) as PersistedRevisionState) : undefined,
   };
@@ -1191,9 +1222,9 @@ export function saveSnapshotToDB(
     }
 
     // Insert snapshot pins
-    const insertPin = db.prepare('INSERT INTO snapshot_pins (snapshot_id, node_id) VALUES (?, ?)');
+    const insertPin = db.prepare('INSERT INTO snapshot_pins (snapshot_id, node_id, meta) VALUES (?, ?, ?)');
     for (const pinId of state.contextPins) {
-      insertPin.run(snapshot.id, pinId);
+      insertPin.run(snapshot.id, pinId, pinMetaJson(state, pinId));
     }
     db.run('INSERT INTO snapshot_meta (snapshot_id, key, value) VALUES (?, ?, ?)', [
       snapshot.id,
@@ -1348,11 +1379,13 @@ export function loadSnapshotFromDB(
   // Load snapshot pins
   interface PinRow {
     node_id: string;
+    meta: string | null;
   }
   const pinRows = db
-    .query<PinRow, [string]>('SELECT node_id FROM snapshot_pins WHERE snapshot_id = ?')
+    .query<PinRow, [string]>('SELECT node_id, meta FROM snapshot_pins WHERE snapshot_id = ?')
     .all(snapshotRow.id);
   const contextPins = pinRows.map((row) => row.node_id);
+  const contextPinMeta = pinMetaFromRows(pinRows);
 
   return {
     snapshot,
@@ -1364,6 +1397,7 @@ export function loadSnapshotFromDB(
       edges,
       annotations,
       contextPins,
+      contextPinMeta,
       ax: parsePersistedAxState(metaMap.get('ax_state')),
       revisionState: metaMap.has('revision_state')
         ? (JSON.parse(metaMap.get('revision_state')!) as PersistedRevisionState)

package/src/server/canvas-geometry.ts

@@ -0,0 +1,64 @@
+import type { CanvasNodeState, CanvasNodeUpdate } from './canvas-state.js';
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function finite(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+/** Flat fields take precedence over nested aliases; absent axes remain absent. */
+export function resolveCreateGeometry(body: Record<string, unknown>) {
+  const position = record(body.position);
+  const size = record(body.size);
+  return {
+    x: finite(body.x) ?? finite(position.x),
+    y: finite(body.y) ?? finite(position.y),
+    width: finite(body.width) ?? finite(size.width),
+    height: finite(body.height) ?? finite(size.height),
+  };
+}
+
+/** Guards and PATCH execution must resolve aliases and single-axis moves identically. */
+export function resolvePatchGeometry(body: Record<string, unknown>, existing: CanvasNodeState) {
+  const { x, y, width, height } = resolveCreateGeometry(body);
+  return {
+    ...(x !== undefined || y !== undefined
+      ? { position: { x: x ?? existing.position.x, y: y ?? existing.position.y } }
+      : {}),
+    ...(width !== undefined || height !== undefined
+      ? { size: { width: width ?? existing.size.width, height: height ?? existing.size.height } }
+      : {}),
+  };
+}
+
+export function validateCanvasNodePatch(patch: { position?: unknown; size?: unknown }): string | null {
+  if (patch.position !== undefined) {
+    const position = record(patch.position);
+    if (finite(position.x) === undefined || finite(position.y) === undefined) {
+      return 'Position must contain finite x and y values.';
+    }
+  }
+  if (patch.size !== undefined) {
+    const size = record(patch.size);
+    const width = finite(size.width);
+    const height = finite(size.height);
+    if (width === undefined || height === undefined) return 'Size must contain finite width and height values.';
+    if (width <= 0 || height <= 0) return 'Size width and height must be greater than zero.';
+  }
+  return null;
+}
+
+/** Invalid patches cannot count as explicit child-position overrides. */
+export function validCanvasNodeUpdates(input: unknown): CanvasNodeUpdate[] {
+  if (!Array.isArray(input)) return [];
+  return input.filter((value: unknown): value is CanvasNodeUpdate => {
+    const update = record(value);
+    return (
+      typeof update.id === 'string' &&
+      (update.collapsed === undefined || typeof update.collapsed === 'boolean') &&
+      validateCanvasNodePatch(update) === null
+    );
+  });
+}

package/src/server/canvas-operations.ts

@@ -23,6 +23,7 @@ import {
 import { mutationHistory } from './mutation-history.js';
 import { intentRegistry } from './intent-registry.js';
 import { clampCreateNodeSize } from './canvas-validation.js';
+import { validCanvasNodeUpdates } from './canvas-geometry.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
@@ -730,26 +731,6 @@ export async function syncCanvasRuntimeBackends(
   return { rehydrated, failed };
 }
 
-export function validateCanvasNodePatch(patch: {
-  position?: { x: number; y: number };
-  size?: { width: number; height: number };
-}): string | null {
-  if (patch.position) {
-    if (!Number.isFinite(patch.position.x) || !Number.isFinite(patch.position.y)) {
-      return 'Position must contain finite x and y values.';
-    }
-  }
-  if (patch.size) {
-    if (!Number.isFinite(patch.size.width) || !Number.isFinite(patch.size.height)) {
-      return 'Size must contain finite width and height values.';
-    }
-    if (patch.size.width <= 0 || patch.size.height <= 0) {
-      return 'Size width and height must be greater than zero.';
-    }
-  }
-  return null;
-}
-
 let codeGraphTimer: ReturnType<typeof setTimeout> | null = null;
 
 function shouldTreatFileContentAsPath(input: CanvasAddNodeInput): boolean {
@@ -1406,22 +1387,23 @@ export function arrangeCanvasNodes(layout: CanvasArrangeMode): { arranged: numbe
 }
 
 export function applyCanvasNodeUpdates(updates: CanvasNodeUpdate[]): { applied: number; skipped: number } {
-  const safe = updates.filter((update) => validateCanvasNodePatch(update) === null);
-  return canvasState.applyUpdates(safe);
+  return canvasState.applyUpdates(validCanvasNodeUpdates(updates));
 }
 
 export function setCanvasContextPins(
   nodeIds: string[],
   mode: CanvasPinMode = 'set',
+  reason?: string,
 ): { count: number; nodeIds: string[] } {
   const normalizePins = (ids: string[]): string[] =>
     ids.filter((id, index) => ids.indexOf(id) === index).slice(0, MAX_CONTEXT_PINS);
   const normalizedNodeIds = normalizePins(nodeIds);
+  const options = reason ? { reason } : {};
   if (mode === 'set') {
-    canvasState.setContextPins(normalizedNodeIds);
+    canvasState.setContextPins(normalizedNodeIds, options);
   } else if (mode === 'add') {
     const current = Array.from(canvasState.contextPinnedNodeIds);
-    canvasState.setContextPins(normalizePins([...current, ...normalizedNodeIds]));
+    canvasState.setContextPins(normalizePins([...current, ...normalizedNodeIds]), options);
   } else {
     const current = Array.from(canvasState.contextPinnedNodeIds);
     canvasState.setContextPins(current.filter((id) => !normalizedNodeIds.includes(id)));