pmx-canvas 0.4.8 → 0.5.1

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

@@ -188,7 +188,7 @@ const groupRemoveOperation = defineOperation<z.infer<typeof groupRemoveSchema>,
   mcp: {
     toolName: 'canvas_ungroup',
     description:
-      'Remove all children from a group, releasing them as independent nodes. The group node itself remains (delete it separately with canvas_remove_node if desired).',
+      'Dissolve a group: its children become independent nodes (members of the enclosing group when nested) and the frame is removed — one undo step, the same result as the human’s Ungroup.',
     extraShape: {
       groupId: z.string().describe('The group node ID to ungroup'),
     },
@@ -199,9 +199,10 @@ const groupRemoveOperation = defineOperation<z.infer<typeof groupRemoveSchema>,
   handler: (input) => {
     const groupId = typeof input.groupId === 'string' ? input.groupId : '';
     if (!groupId) throw new OperationError('Missing groupId.');
+    const title = canvasState.getNode(groupId)?.data.title;
     const { ok } = ungroupCanvasNodes(groupId);
-    if (!ok) throw new OperationError('Group not found or empty.');
-    return { ok: true, groupId };
+    if (!ok) throw new OperationError('Group not found.', 404);
+    return { ok: true, groupId, ...(typeof title === 'string' ? { title } : {}) };
   },
 });
 

package/src/server/operations/ops/human-presence.ts

@@ -0,0 +1,35 @@
+/**
+ * human.presence.set / human.presence.get — the workbench's own heartbeat
+ * (rail-chrome-v2 phase 8). HTTP only: tabs report themselves; agents read
+ * the snapshot through `canvas_ax_state { action: "presence" }`'s sibling
+ * GET if they want to know who is on the board. Never counts as agent
+ * activity (registry exempt list).
+ */
+import { z } from 'zod';
+import { HUMAN_PRESENCE_SHAPE, humanPresence } from '../../human-presence.js';
+import { defineOperation } from '../types.js';
+
+const setSchema = z.looseObject(HUMAN_PRESENCE_SHAPE);
+
+export const humanPresenceSetOperation = defineOperation<z.infer<typeof setSchema>, Record<string, unknown>>({
+  name: 'human.presence.set',
+  mutates: false,
+  input: setSchema,
+  inputShape: HUMAN_PRESENCE_SHAPE,
+  http: { method: 'POST', path: '/api/canvas/human-presence' },
+  handler: (input) => ({ ok: true, human: humanPresence.set(input) }),
+});
+
+const getShape = {};
+const getSchema = z.looseObject(getShape);
+
+export const humanPresenceGetOperation = defineOperation<z.infer<typeof getSchema>, Record<string, unknown>>({
+  name: 'human.presence.get',
+  mutates: false,
+  input: getSchema,
+  inputShape: getShape,
+  http: { method: 'GET', path: '/api/canvas/human-presence' },
+  handler: () => ({ ok: true, ...humanPresence.snapshot() }),
+});
+
+export const humanPresenceOperations = [humanPresenceSetOperation, humanPresenceGetOperation];

package/src/server/operations/ops/json-render.ts

@@ -113,6 +113,11 @@ const jsonRenderAddShape = {
   y: z.number().optional().catch(undefined).describe('Optional Y position'),
   width: z.number().optional().catch(undefined).describe('Optional node width'),
   height: z.number().optional().catch(undefined).describe('Optional node height'),
+  nodeHeight: z
+    .number()
+    .optional()
+    .catch(undefined)
+    .describe('Alias for height — the frame-height name the graph and stream actions use'),
   strictSize: z
     .boolean()
     .optional()
@@ -146,7 +151,12 @@ const jsonRenderAddOperation = defineOperation<
     // Legacy fallback: a body without an object `spec` is treated as the spec
     // itself (bare-component compatibility path).
     const rawSpec = body.spec && typeof body.spec === 'object' && !Array.isArray(body.spec) ? body.spec : body;
-    const geometry = resolveCreateGeometry(body);
+    // `nodeHeight` is the frame-height name the sibling actions (add-graph,
+    // stream-json-render) teach callers — dropping it here silently produced
+    // default-height frames (0.5.0 readiness, Copilot finding).
+    const geometry = resolveCreateGeometry(
+      body.nodeHeight !== undefined && body.height === undefined ? { ...body, height: body.nodeHeight } : body,
+    );
     try {
       return createCanvasJsonRenderNode({
         ...(title ? { title } : {}),

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

@@ -28,6 +28,8 @@ import {
   LEDGER_NODE_DEFAULT_SIZE,
 } from '../../canvas-operations.js';
 import { normalizeNodeAxCapabilities } from '../../ax-interaction.js';
+import { applyFileContentToNodeData, readFileNodeContent } from '../../file-content.js';
+import { unwatchFileForNode, watchFileForNode } from '../../file-watcher.js';
 import {
   buildHtmlPrimitive,
   getHtmlPrimitiveDescriptor,
@@ -241,7 +243,7 @@ export function setGroupChildrenFromApi(groupId: string, childIds: string[]): bo
     if (currentChildIds.length !== dataChildIds.length || currentChildIds.some((id) => !dataChildIds.includes(id))) {
       canvasState.updateNode(groupId, { data: { ...group.data, children: currentChildIds } });
     }
-    canvasState.ungroupNodes(groupId);
+    canvasState.releaseGroupChildren(groupId);
   }
   if (childIds.length === 0) return true;
 
@@ -308,7 +310,6 @@ export function compactNodePayload(node: CanvasNodeState | undefined): Record<st
     size: serialized.size,
     pinned: serialized.pinned,
     collapsed: serialized.collapsed,
-    dockPosition: serialized.dockPosition,
     provenance: serialized.provenance,
   };
 }
@@ -404,6 +405,30 @@ export function createBasicCanvasNode(
       throw new OperationError('HTML node field "data.html" must be a string.');
     }
   }
+  // Loud rejection of the two dead-field traps (gauntlet, 2026-08-27): these
+  // names read as if they work, were dropped silently, and the node rendered
+  // empty. The canonical create field is `content` for every type.
+  if (body.src !== undefined) {
+    throw new OperationError(
+      type === 'image'
+        ? 'Unknown field "src" — pass the image source (path, URL, or data: URI) as `content`.'
+        : 'Unknown field "src" — node content lives in `content`.',
+    );
+  }
+  if (body.path !== undefined && type !== 'image') {
+    throw new OperationError(
+      type === 'file'
+        ? 'Unknown field "path" for file nodes — pass the workspace path as `content`.'
+        : '"path" is only an image-node compatibility alias — use `content`.',
+    );
+  }
+  // Docking was removed in 0.5.0 — a create that still sends it silently
+  // succeeded and read as "docking works" (0.5.0 Copilot report, PASS-ish).
+  if (body.dockPosition !== undefined) {
+    throw new OperationError(
+      'Unknown field "dockPosition" — docking was removed in 0.5.0; use `position` and `pinned`.',
+    );
+  }
   const content =
     type === 'image' && typeof body.path === 'string' && typeof body.content !== 'string' ? body.path : body.content;
   // For html nodes, accept top-level `html` AND `axCapabilities` and merge into data
@@ -472,6 +497,28 @@ export function buildNodePatch(
   existing: CanvasNodeState,
   body: Record<string, unknown>,
 ): { patch: Partial<CanvasNodeState>; groupChildIds?: string[] } {
+  // Same dead-field traps as create (gauntlet, 2026-08-27): reject loudly
+  // instead of dropping — and note that patching `content` on a file node
+  // updates the FILE CONTENT snapshot, it does not re-point the node.
+  if (body.src !== undefined) {
+    throw new OperationError('Unknown field "src" — update the image source via `content`.');
+  }
+  if (body.dockPosition !== undefined) {
+    throw new OperationError(
+      'Unknown field "dockPosition" — docking was removed in 0.5.0; use `position` and `pinned`.',
+    );
+  }
+  if (body.path !== undefined && existing.type !== 'image') {
+    if (existing.type === 'file') {
+      // Repoint: `path` on a file-node patch moves the node to another file
+      // (content re-read, watcher rewired) while keeping its edges and pins.
+      if (typeof body.path !== 'string' || !body.path.trim()) {
+        throw new OperationError('File node "path" must be a non-empty string.');
+      }
+    } else {
+      throw new OperationError('"path" is only an image-node compatibility alias — use `content`.');
+    }
+  }
   const groupChildList = existing.type === 'group' ? pickGroupChildIds(body) : {};
   if (groupChildList.error) throw new OperationError(`Cannot update group: ${groupChildList.error}`);
   const groupChildIds = groupChildList.value;
@@ -482,9 +529,6 @@ export function buildNodePatch(
   const patch: Record<string, unknown> = resolvePatchGeometry(body, existing);
   if (body.collapsed !== undefined) patch.collapsed = body.collapsed;
   if (body.pinned !== undefined) patch.pinned = Boolean(body.pinned);
-  if (body.dockPosition === null || body.dockPosition === 'left' || body.dockPosition === 'right') {
-    patch.dockPosition = body.dockPosition;
-  }
   if (hasStructuredNodeUpdateFields(body)) {
     try {
       patch.data = buildStructuredNodeUpdate(existing, body).data;
@@ -499,9 +543,11 @@ export function buildNodePatch(
     typeof body.strictSize === 'boolean' ||
     (existing.type === 'trace' && hasTraceNodeDataFields(body)) ||
     (existing.type === 'html' && body.html !== undefined) ||
+    (existing.type === 'file' && typeof body.path === 'string') ||
     body.axCapabilities !== undefined
   ) {
     const data = { ...existing.data };
+    if (existing.type === 'file' && typeof body.path === 'string') data.path = body.path.trim();
     if (body.title !== undefined) {
       data.title = String(body.title);
       if (existing.type === 'webpage') {
@@ -995,10 +1041,6 @@ const nodeUpdateShape = {
   resultSummary: z.string().optional().catch(undefined).describe('Trace node result summary'),
   error: z.string().optional().catch(undefined).describe('Trace node error message'),
   collapsed: z.unknown().optional().describe('Collapse or expand the node'),
-  dockPosition: z
-    .unknown()
-    .optional()
-    .describe('Dock the node to the left/right HUD column, or pass null to return it to the canvas'),
   pinned: z.unknown().optional().describe('Pin or unpin the node to exclude it from auto-arrange'),
   arrangeLocked: z
     .boolean()
@@ -1039,7 +1081,7 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
   },
   mcp: {
     toolName: 'canvas_update_node',
-    description: 'Update an existing node. You can change its content, title, position, size, dock placement, or data.',
+    description: 'Update an existing node. You can change its content, title, position, size, or data.',
     extraShape: {
       title: z.string().optional().describe('New title'),
       content: z.string().optional().describe('New content'),
@@ -1053,11 +1095,6 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
       yKey: z.string().optional().describe('Graph y/value key'),
       chartHeight: z.number().optional().describe('Graph chart content height, distinct from node height'),
       collapsed: z.boolean().optional().describe('Collapse or expand the node'),
-      dockPosition: z
-        .enum(['left', 'right'])
-        .nullable()
-        .optional()
-        .describe('Dock the node to the left/right HUD column, or pass null to return it to the canvas'),
       pinned: z.boolean().optional().describe('Pin or unpin the node to exclude it from auto-arrange'),
       arrangeLocked: z
         .boolean()
@@ -1107,7 +1144,7 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
       };
     },
   },
-  handler: async (input) => {
+  handler: async (input, ctx) => {
     const body: Record<string, unknown> = input;
     const id = input.id;
     const existing = canvasState.getNode(id);
@@ -1130,6 +1167,30 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
     if (groupChildIds !== undefined && !setGroupChildrenFromApi(id, groupChildIds)) {
       throw new OperationError(`Group "${id}" not found.`, 404);
     }
+    // File repoint: a data.path change re-reads the new file and rewires the
+    // watcher IN PLACE — before this, pointing a file node elsewhere meant
+    // recreating it, which lost its edges, pins, and position.
+    if (existing.type === 'file') {
+      const prevPath = typeof existing.data.path === 'string' ? existing.data.path : null;
+      const repointed = canvasState.getNode(id);
+      const nextPath = repointed && typeof repointed.data.path === 'string' ? repointed.data.path : null;
+      if (nextPath && nextPath !== prevPath) {
+        if (prevPath) unwatchFileForNode(id, prevPath);
+        const data = { ...repointed!.data };
+        // The title follows the file unless the caller pinned one in this
+        // patch or had renamed the node away from the old filename.
+        const prevBase = prevPath?.split(/[\\/]/).pop();
+        if (typeof body.title !== 'string' && (!data.title || data.title === prevBase)) {
+          data.title = nextPath.split(/[\\/]/).pop();
+        }
+        applyFileContentToNodeData(data, readFileNodeContent(nextPath));
+        canvasState.updateNode(id, { data });
+        watchFileForNode(id, nextPath);
+        scheduleCodeGraphRecompute(() => {
+          ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+        });
+      }
+    }
     const updated = canvasState.getNode(id);
     return updated ? buildNodeResponse(updated) : { ok: true, id };
   },

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

@@ -180,6 +180,7 @@ const historyGetOperation = defineOperation<z.infer<typeof historyGetSchema>, Re
   handler: () => ({
     text: mutationHistory.toHumanReadable(),
     entries: mutationHistory.getSummaries(),
+    top: mutationHistory.top(),
     canUndo: mutationHistory.canUndo(),
     canRedo: mutationHistory.canRedo(),
   }),

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

@@ -29,9 +29,9 @@ import {
   gcCanvasSnapshots,
   listCanvasSnapshots,
   restoreCanvasSnapshot,
-  saveCanvasSnapshot,
+  saveCanvasSnapshotWithReuse,
 } from '../../canvas-operations.js';
-import { diffLayouts, formatDiff } from '../../mutation-history.js';
+import { formatDiff, diffLayouts } from '../../mutation-history.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
 
@@ -128,9 +128,12 @@ const snapshotSaveOperation = defineOperation<z.infer<typeof snapshotSaveSchema>
   handler: (input) => {
     const name = typeof input.name === 'string' ? input.name.trim() : '';
     if (!name) throw new OperationError('Missing snapshot name');
-    const snapshot = saveCanvasSnapshot(name);
+    // A save of an unchanged board reuses the newest snapshot instead of
+    // stacking an identical copy — via the ONE shared path the SDK uses too
+    // (0.5.0 Codex finding V).
+    const { snapshot, reused } = saveCanvasSnapshotWithReuse(name);
     if (!snapshot) throw new OperationError('Failed to save snapshot');
-    return { ok: true, id: snapshot.id, snapshot };
+    return { ok: true, id: snapshot.id, snapshot, ...(reused ? { reused: true } : {}) };
   },
 });
 

package/src/server/operations/registry.ts

@@ -9,6 +9,10 @@
  */
 import { canvasState } from '../canvas-state.js';
 import { intentRegistry } from '../intent-registry.js';
+import { humanPresence } from '../human-presence.js';
+import { setMutationActor } from '../mutation-history.js';
+import { agentPresence, describeWrite } from '../agent-presence.js';
+import { checkScopeFence, checkScopeOwnership } from '../scope-fence.js';
 import type { PmxAxIntent, PmxAxIntentKind } from '../../shared/ax-intent.js';
 import { OperationError, type Operation, type OperationContext } from './types.js';
 
@@ -193,6 +197,149 @@ export interface ExecuteOperationMeta {
    * its inner dispatches (batch churn is exempt, matching the skill contract).
    */
   suppressAutoGhost?: boolean;
+  /**
+   * Who is calling — the presence writer label ('mcp', 'sdk', 'api', …).
+   * Defaults to 'api'. Workbench calls (suppressAutoGhost) never touch presence.
+   */
+  source?: string;
+  /**
+   * The human's own browser issued this call. Distinct from suppressAutoGhost
+   * (which batch also sets for its inner dispatches): the scope fence applies
+   * to agents only, and batch inner writes are always agent-originated.
+   */
+  fromWorkbench?: boolean;
+}
+
+/**
+ * Agent presence (rail-chrome-v2 phase 2): every agent-originated MUTATION —
+ * the same calls that synthesize auto-ghosts — touches the caller's presence
+ * as `tooling`. Reads never do (polling an agent's own context is not work).
+ * Presence must never break the mutation, so this is fire-and-forget.
+ */
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+/**
+ * Ops that change which group a node belongs to — a held member is a held
+ * target. `node.update` is here because `node.update {id:G, children:[X]}`
+ * reparents X: the scope fence already counts that as a write to X
+ * (`scope-fence.ts` `groupChildren`), and the edit-lock must agree, or a
+ * human's in-progress drag is overridden through the ordinary reparent path.
+ */
+const MEMBERSHIP_OPS = new Set(['node.remove', 'group.remove', 'group.add', 'group.create', 'node.update']);
+
+/** The node an agent write targets, if a human currently holds it. */
+function heldByHuman(name: string, rawInput: unknown): { nodeId: string; name: string } | null {
+  const locked = humanPresence.lockedNodes();
+  if (locked.size === 0) return null;
+  const input = asRecord(rawInput);
+  const ids = [input.id, input.nodeId, input.groupId, input.from, input.to].filter(isString);
+  if (MEMBERSHIP_OPS.has(name)) {
+    for (const key of ['childIds', 'children']) {
+      const list = input[key];
+      if (Array.isArray(list)) ids.push(...list.filter(isString));
+    }
+    // node.update carries the reparent list under data.children too.
+    const data = asRecord(input.data);
+    if (Array.isArray(data.children)) ids.push(...data.children.filter(isString));
+    // Removing a group dissolves it: every member changes hands too.
+    for (const id of [...ids]) {
+      const node = canvasState.getNode(id);
+      if (node?.type === 'group' && Array.isArray(node.data.children)) ids.push(...node.data.children.filter(isString));
+    }
+  }
+  for (const id of ids) {
+    const name = locked.get(id);
+    if (name) return { nodeId: id, name };
+  }
+  return null;
+}
+
+/** The node an operation touched — the agent cursor glides there. */
+function nodeIdFromResult(record: Record<string, unknown>): string | null {
+  if (typeof record.id === 'string') return record.id;
+  const node = asRecord(record.node);
+  return typeof node.id === 'string' ? node.id : null;
+}
+
+function touchedNodeId(rawInput: unknown, result: unknown): string | null {
+  const input = asRecord(rawInput);
+  if (typeof input.id === 'string') return input.id;
+  if (typeof input.nodeId === 'string') return input.nodeId;
+  const res = asRecord(result);
+  const direct = nodeIdFromResult(res);
+  if (direct) return direct;
+  // canvas.batch: park the presence cursor on the LAST op that touched a node —
+  // batch-writing agents (ghost-approved creates) otherwise never get a focus,
+  // which left their cursor invisible through entire rounds of work.
+  if (Array.isArray(res.results)) {
+    for (let i = res.results.length - 1; i >= 0; i -= 1) {
+      const id = nodeIdFromResult(asRecord(res.results[i]));
+      if (id) return id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Ops that are writes for PRESENCE purposes but must not touch it themselves:
+ * the presence endpoint (it IS the explicit phase — a derived `tooling` touch
+ * would clobber it) and activity ingest (observeActivity already mapped it,
+ * and re-touching after a `session-end` would resurrect the writer).
+ */
+const PRESENCE_EXEMPT_OPS = new Set([
+  'ax.presence.set',
+  'ax.presence.get',
+  'ax.activity.ingest',
+  'human.presence.set',
+  'human.presence.get',
+]);
+
+/** Layout mutations AND non-GET AX writes (work items, gates, evidence, steering) are agent activity. */
+function isPresenceWrite(op: Operation): boolean {
+  if (PRESENCE_EXEMPT_OPS.has(op.name)) return false;
+  return op.mutates || (op.http != null && op.http.method !== 'GET');
+}
+
+function notePresence(
+  name: string,
+  rawInput: unknown,
+  meta: ExecuteOperationMeta,
+  op: Operation,
+  result: unknown,
+): void {
+  if (!isPresenceWrite(op) || meta.suppressAutoGhost) return;
+  const input = asRecord(rawInput);
+  // 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
+  // signal the human reads.
+  const isDeliveryOp = name.startsWith('ax.delivery.');
+  try {
+    const touched = touchedNodeId(rawInput, result);
+    // Work items, gates, and evidence results carry ids too — only a REAL
+    // canvas node may become the cursor's focus (orchestration review #9:
+    // the cursor aimed at a work-item id and pointed at nothing).
+    const focusNodeId = touched && canvasState.getNode(touched) ? touched : null;
+    const { summary, nodeId } = describeWrite(name, rawInput, result);
+    const consumerIdentity =
+      isDeliveryOp && typeof input.consumer === 'string' && input.consumer.trim() ? input.consumer.trim() : null;
+    agentPresence.touch({
+      source: meta.source ?? 'api',
+      agentId: typeof input.agentId === 'string' ? input.agentId : (consumerIdentity ?? null),
+      phase: 'tooling',
+      derivedTooling: true,
+      detail: name,
+      ...(focusNodeId ? { focusNodeId } : {}),
+      op: true,
+      ...(isDeliveryOp ? {} : { activity: { op: name, summary, nodeId } }),
+    });
+  } catch {
+    // never let presence bookkeeping fail a mutation
+  }
 }
 
 export async function executeOperation(
@@ -200,8 +347,53 @@ export async function executeOperation(
   rawInput: unknown,
   meta: ExecuteOperationMeta = {},
 ): Promise<unknown> {
+  // History entries recorded while this op runs carry who made them (item
+  // 10: the session panel offers undo on the agent's latest edit).
+  const historyWriter =
+    typeof asRecord(rawInput).agentId === 'string' && String(asRecord(rawInput).agentId).trim()
+      ? String(asRecord(rawInput).agentId).trim()
+      : (meta.source ?? 'api');
+  setMutationActor(meta.fromWorkbench ? 'human' : 'agent', historyWriter);
+  try {
+    return await executeOperationInner(name, rawInput, meta);
+  } finally {
+    setMutationActor(null);
+  }
+}
+
+async function executeOperationInner(name: string, rawInput: unknown, meta: ExecuteOperationMeta): Promise<unknown> {
   const op = getOperation(name);
-  const intentId = linkedIntentId(rawInput);
+  // Scope fence (design item 4): an attached agent's writes must stay inside
+  // the fence the human granted. Reads and the human's own writes pass, and
+  // the fence itself is the human's to set — an agent cannot clear or widen it.
+  if (!meta.fromWorkbench) {
+    // Fence identity: the same key presence uses — the write's agentId when it
+    // carries one, else its transport/source label.
+    const rawAgentId = asRecord(rawInput).agentId;
+    const writerKey = typeof rawAgentId === 'string' && rawAgentId.trim() ? rawAgentId.trim() : (meta.source ?? 'api');
+    const refusal = op.mutates
+      ? checkScopeFence(op, rawInput, writerKey)
+      : name === 'ax.policy.set'
+        ? checkScopeOwnership(rawInput, writerKey)
+        : null;
+    if (refusal) throw new OperationError(`Outside the agent scope: ${refusal}`, 403);
+    // User wins (item 6): a node a human is holding right now is not the
+    // agent's to change — refuse with 409 so the agent requeues the edit.
+    if (op.mutates) {
+      const held = heldByHuman(name, rawInput);
+      if (held) {
+        throw new OperationError(
+          `Node "${held.nodeId}" is being edited by ${held.name} right now — requeue this change and try again in a moment.`,
+          409,
+        );
+      }
+    }
+  }
+  const linkedId = linkedIntentId(rawInput);
+  // A ghost that expired QUIETLY (no veto) does not block its mutation — the
+  // write proceeds unlinked (and takes the auto-ghost path below). Vetoed and
+  // already-committing intents still refuse inside runCommit.
+  const intentId = linkedId && intentRegistry.commitDisposition(linkedId) !== 'absent' ? linkedId : undefined;
   const allowedKinds = intentId ? allowedIntentKinds(name, rawInput) : undefined;
   if (intentId && !allowedKinds) {
     throw new OperationError(`Operation "${name}" cannot be committed through a ghost intent.`);
@@ -215,6 +407,7 @@ export async function executeOperation(
         if (op.mutates) {
           emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
         }
+        notePresence(name, rawInput, meta, op, result);
         return result;
       },
       settledNodeId,
@@ -253,6 +446,7 @@ export async function executeOperation(
         const result = await op.execute(rawInput, operationContext);
         if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
         intentRegistry.clear(ghostId, { settledNodeId: settledNodeId(result, ghost) ?? undefined });
+        notePresence(name, rawInput, meta, op, result);
         return result;
       } catch (error) {
         intentRegistry.clear(ghostId);
@@ -263,5 +457,6 @@ export async function executeOperation(
 
   const result = await op.execute(rawInput, operationContext);
   if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  notePresence(name, rawInput, meta, op, result);
   return result;
 }

package/src/server/operations/types.ts

@@ -12,7 +12,7 @@
 import type { ZodRawShape } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 
-export type OperationErrorStatus = 400 | 404 | 409;
+export type OperationErrorStatus = 400 | 403 | 404 | 409;
 
 /** Operation failure that maps to an HTTP status + `{ ok:false, error }` body and MCP `isError`. */
 export class OperationError extends Error {