pmx-canvas 0.3.3 → 0.4.0

package/src/server/canvas-state.ts

@@ -7,20 +7,13 @@
  *
  * Persistence: canvas state auto-saves to `.pmx-canvas/canvas.db` (SQLite WAL mode)
  * in the workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
- * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
+ * Legacy pre-0.2 formats (`.pmx-canvas/state.json`, `.pmx-canvas.json`,
+ * `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of 0.4.0 —
+ * the one-shot boot migration into SQLite was retired.
  */
 
 import { createHash } from 'node:crypto';
-import {
-  existsSync,
-  readFileSync,
-  writeFileSync,
-  mkdirSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  unlinkSync,
-} from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
 import { isAbsolute, join, dirname, relative } from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { normalizeCanvasNodeData } from './canvas-provenance.js';
@@ -34,7 +27,6 @@ import {
   deleteSnapshotFromDB,
   writeBlobToDB,
   readBlobFromDB,
-  hasBlobInDB,
   isDbPopulated,
   checkpointCanvasDb,
   finalizeCanvasDbForClose,
@@ -97,12 +89,9 @@ function normalizeSnapshotTimestamp(value: string | undefined): string | undefin
 }
 
 export const PMX_CANVAS_DIR = '.pmx-canvas';
-const STATE_FILENAME = 'state.json';
 const DB_FILENAME = 'canvas.db';
 const SNAPSHOTS_SUBDIR = 'snapshots';
 const BLOBS_SUBDIR = 'blobs';
-const LEGACY_STATE_FILENAME = '.pmx-canvas.json';
-const LEGACY_SNAPSHOTS_DIR = '.pmx-canvas-snapshots';
 const SAVE_DEBOUNCE_MS = 500;
 const BLOB_JSON_THRESHOLD_BYTES = Number(process.env.PMX_CANVAS_BLOB_THRESHOLD_BYTES ?? '2048');
 const BLOB_DATA_FIELDS = new Set([
@@ -393,10 +382,23 @@ class CanvasStateManager {
   }
 
   // ── Mutation recorder (for undo/redo history) ─────────────
+  //
+  // Single slot BY DESIGN, last-write-wins (plan-009 L5): the only logical
+  // consumer is the `mutationHistory` singleton, wired by `startCanvasServer()`
+  // (server.ts) on every fresh start. A listener LIST here would record every
+  // mutation twice into the history ring (breaking undo) if a second wire ever
+  // appeared, so keep it a single slot and wire recorders in one place only.
   private _mutationRecorder: ((info: MutationRecordInfo) => void) | null = null;
+  // The ONE recording-suppression counter (depth-counted so nested suppressed
+  // scopes compose). Two related mechanisms are deliberately NOT merged into
+  // it: `mutationHistory._replaying` guards direct `record()` calls during
+  // undo/redo replay, and the operation registry's `suppressEmitDepth`
+  // suppresses SSE emits during meta-ops (canvas.batch) — whose sub-ops must
+  // still record history, just as undo/redo still emits SSE while recording is
+  // suppressed here. The three counters are active at different times.
   private _suppressRecordingDepth = 0;
 
-  /** Register a mutation recorder. Used by mutation-history to capture undo/redo closures. */
+  /** Register THE mutation recorder (single slot, last-write-wins — see note above). */
   onMutation(cb: (info: MutationRecordInfo) => void): void {
     this._mutationRecorder = cb;
   }
@@ -617,7 +619,6 @@ class CanvasStateManager {
   }
 
   // ── Persistence ────────────────────────────────────────────
-  private _stateFilePath: string | null = null;
   private _db: import('bun:sqlite').Database | null = null;
   private _saveTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -630,9 +631,9 @@ class CanvasStateManager {
   setWorkspaceRoot(workspaceRoot: string): void {
     this.close();
     this._workspaceRoot = workspaceRoot;
-    this.migrateLegacyLayout(workspaceRoot);
 
-    // Determine DB path
+    // Determine DB path. PMX_CANVAS_DB_PATH wins; PMX_CANVAS_STATE_FILE is
+    // honored only as a legacy alias when it points at a `.db` file.
     const dbOverride = (process.env.PMX_CANVAS_DB_PATH ?? '').trim();
     const stateFileOverride = (process.env.PMX_CANVAS_STATE_FILE ?? '').trim();
     let dbPath: string;
@@ -643,16 +644,20 @@ class CanvasStateManager {
     } else {
       dbPath = join(workspaceRoot, PMX_CANVAS_DIR, DB_FILENAME);
     }
+    if (stateFileOverride && !stateFileOverride.endsWith('.db')) {
+      logCanvasStateWarning(
+        'PMX_CANVAS_STATE_FILE ignored',
+        'legacy JSON state files are no longer supported as of 0.4.0 — use PMX_CANVAS_DB_PATH',
+        { stateFileOverride },
+      );
+    }
 
-    // Keep legacy _stateFilePath for JSON migration detection
-    this._stateFilePath =
-      stateFileOverride && !stateFileOverride.endsWith('.db')
-        ? stateFileOverride
-        : join(workspaceRoot, PMX_CANVAS_DIR, STATE_FILENAME);
-
+    // Legacy pre-0.2 formats (`.pmx-canvas/state.json`, `.pmx-canvas.json`,
+    // `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of
+    // 0.4.0 — the one-shot boot migration that copied them into SQLite and
+    // renamed the originals to `.bak` was retired.
     try {
       this._db = openCanvasDb(dbPath);
-      this.migrateJsonToSqlite();
     } catch (error) {
       logCanvasStateWarning('open canvas database failed', error, { dbPath });
     }
@@ -745,7 +750,7 @@ class CanvasStateManager {
       }
     }
 
-    // Fallback to filesystem (for legacy blobs not yet migrated)
+    // Fallback to filesystem (legacy on-disk blobs are still readable in place)
     const filePath = this.resolveBlobPath(ref);
     if (!filePath) return ref;
     try {
@@ -804,112 +809,6 @@ class CanvasStateManager {
     };
   }
 
-  /**
-   * One-time migration: rename files from the pre-consolidation layout
-   * (`.pmx-canvas.json` + `.pmx-canvas-snapshots/`) into `.pmx-canvas/`.
-   * No-op when the new layout already exists.
-   */
-  private migrateLegacyLayout(workspaceRoot: string): void {
-    const newDir = join(workspaceRoot, PMX_CANVAS_DIR);
-    const legacyState = join(workspaceRoot, LEGACY_STATE_FILENAME);
-    const newState = join(newDir, STATE_FILENAME);
-    const legacySnapshots = join(workspaceRoot, LEGACY_SNAPSHOTS_DIR);
-    const newSnapshots = join(newDir, SNAPSHOTS_SUBDIR);
-
-    try {
-      if (existsSync(legacyState) && !existsSync(newState)) {
-        mkdirSync(newDir, { recursive: true });
-        renameSync(legacyState, newState);
-      }
-      if (existsSync(legacySnapshots) && !existsSync(newSnapshots)) {
-        mkdirSync(newDir, { recursive: true });
-        renameSync(legacySnapshots, newSnapshots);
-      }
-    } catch (error) {
-      logCanvasStateWarning('legacy layout migration failed', error, {
-        workspaceRoot,
-      });
-    }
-  }
-
-  /**
-   * One-time migration: import state.json + snapshot JSON files + blob files
-   * into the SQLite database. Renames originals to `.bak`.
-   */
-  private migrateJsonToSqlite(): void {
-    if (!this._db || !this._stateFilePath) return;
-    const db = this._db;
-
-    if (isDbPopulated(this._db)) return; // DB already initialized
-
-    if (existsSync(this._stateFilePath)) {
-      try {
-        const raw = readFileSync(this._stateFilePath, 'utf-8');
-        const parsed = JSON.parse(raw) as PersistedCanvasState;
-        if (parsed && parsed.version === 1) {
-          saveStateToDB(db, parsed);
-          renameSync(this._stateFilePath, `${this._stateFilePath}.bak`);
-        }
-      } catch (error) {
-        logCanvasStateWarning('migrate state.json to sqlite failed', error, {
-          path: this._stateFilePath,
-        });
-      }
-    }
-
-    // Migrate snapshot JSON files
-    const snapshotsDir = this.snapshotsDir;
-    if (snapshotsDir && existsSync(snapshotsDir)) {
-      try {
-        const files = readdirSync(snapshotsDir).filter((f) => f.endsWith('.json'));
-        for (const file of files) {
-          try {
-            const filePath = join(snapshotsDir, file);
-            const raw = readFileSync(filePath, 'utf-8');
-            const parsed = JSON.parse(raw) as PersistedCanvasState & { snapshot?: CanvasSnapshot };
-            if (parsed.snapshot && parsed.version === 1) {
-              saveSnapshotToDB(db, parsed.snapshot, parsed);
-              renameSync(filePath, `${filePath}.bak`);
-            }
-          } catch (error) {
-            logCanvasStateWarning('migrate snapshot file to sqlite failed', error, { file });
-          }
-        }
-      } catch (error) {
-        logCanvasStateWarning('migrate snapshots dir failed', error, { snapshotsDir });
-      }
-    }
-
-    // Migrate blob files
-    const blobsDir = this.blobsDir;
-    if (blobsDir && existsSync(blobsDir)) {
-      try {
-        const prefixes = readdirSync(blobsDir).filter((d) => d.length === 2);
-        for (const prefix of prefixes) {
-          const prefixDir = join(blobsDir, prefix);
-          const blobFiles = readdirSync(prefixDir).filter((f) => f.endsWith('.json.gz'));
-          for (const blobFile of blobFiles) {
-            try {
-              const blobPath = join(prefixDir, blobFile);
-              const sha256 = blobFile.replace('.json.gz', '');
-              if (!hasBlobInDB(db, sha256)) {
-                const compressed = readFileSync(blobPath);
-                const json = gunzipSync(compressed).toString('utf-8');
-                writeBlobToDB(db, sha256, json);
-              }
-              const backupPath = `${blobPath}.bak`;
-              if (!existsSync(backupPath)) renameSync(blobPath, backupPath);
-            } catch (error) {
-              logCanvasStateWarning('migrate blob file to sqlite failed', error, { blobFile });
-            }
-          }
-        }
-      } catch (error) {
-        logCanvasStateWarning('migrate blobs dir failed', error, { blobsDir });
-      }
-    }
-  }
-
   getWorkspaceRoot(): string {
     return this._workspaceRoot;
   }
@@ -927,11 +826,12 @@ class CanvasStateManager {
     };
   }
 
-  /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
+  /** Load canvas state from SQLite. Call once on server startup. */
   loadFromDisk(options: LoadFromDiskOptions = {}): boolean {
     // Host capability lives in its own table (not snapshotted / not in PmxAxState).
     this.ax.loadHostCapabilityFromDb();
-    // Try SQLite first (only if DB has been populated)
+    // Only a populated DB counts as saved state (legacy `state.json` loading was
+    // retired with the 0.4.0 boot-migration removal).
     if (this._db && isDbPopulated(this._db)) {
       try {
         const state = loadStateFromDB(this._db);
@@ -944,21 +844,6 @@ class CanvasStateManager {
       }
     }
 
-    // Fallback to JSON (for edge cases where migration hasn't happened)
-    if (this._stateFilePath && existsSync(this._stateFilePath)) {
-      try {
-        const raw = readFileSync(this._stateFilePath, 'utf-8');
-        const parsed = JSON.parse(raw) as PersistedCanvasState;
-        if (!parsed || parsed.version !== 1) return false;
-        this.applyPersistedState(parsed);
-        return true;
-      } catch (error) {
-        logCanvasStateWarning('load state from json fallback failed', error, {
-          path: this._stateFilePath,
-        });
-      }
-    }
-
     if (options.clearExisting) {
       this.applyPersistedState(this.emptyPersistedState());
     }
@@ -1015,11 +900,26 @@ class CanvasStateManager {
         ax: this.getAxState(),
       });
       saveStateToDB(this._db, payload);
+      this._lastPersistenceError = null;
     } catch (error) {
+      // Persistence failures are otherwise warn-and-continue (the canvas keeps
+      // working from memory) — record the failure so /health can report a
+      // degraded persistence state instead of silently losing durability (M4).
+      this._lastPersistenceError = {
+        message: error instanceof Error ? error.message : String(error),
+        at: new Date().toISOString(),
+      };
       logCanvasStateWarning('save state to sqlite failed', error, {});
     }
   }
 
+  private _lastPersistenceError: { message: string; at: string } | null = null;
+
+  /** Health view of state persistence: ok until a save fails, ok again after the next success. */
+  get persistenceHealth(): { ok: boolean; lastError: { message: string; at: string } | null } {
+    return { ok: this._lastPersistenceError === null, lastError: this._lastPersistenceError };
+  }
+
   /** Close the SQLite database cleanly. Call on server shutdown. */
   close(): void {
     if (this._saveTimer) {
@@ -1098,7 +998,7 @@ class CanvasStateManager {
       if (result) return result;
     }
 
-    // Fallback to filesystem (for legacy snapshots not yet migrated)
+    // Fallback to filesystem (legacy on-disk snapshots are still readable in place)
     const dir = this.snapshotsDir;
     if (!dir || !existsSync(dir)) return null;
 

package/src/server/diagram-presets.ts

@@ -41,6 +41,20 @@ export const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig = {
   url: EXCALIDRAW_MCP_URL,
 };
 
+/**
+ * The diagram preset targets the hosted Excalidraw MCP server. Tests set
+ * PMX_CANVAS_EXCALIDRAW_MCP_COMMAND (a stdio command line, e.g.
+ * "bun run tests/fixtures/mcp-app-fixture.ts") so the unit suite never does a
+ * real network round-trip — the hosted dependency made diagram tests time out
+ * under parallel load (plan-009 M8).
+ */
+export function resolveExcalidrawTransport(): ExternalMcpTransportConfig {
+  const override = process.env.PMX_CANVAS_EXCALIDRAW_MCP_COMMAND?.trim();
+  if (!override) return EXCALIDRAW_MCP_TRANSPORT;
+  const [command = override, ...args] = override.split(/\s+/);
+  return { type: 'stdio', command, args };
+}
+
 export interface DiagramPresetOpenInput {
   elements: unknown;
   nodeId?: string;
@@ -379,7 +393,7 @@ export function ensureExcalidrawCheckpointId(
 export function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): ExcalidrawOpenMcpAppInput {
   const elements = normalizeExcalidrawElementsForToolInput(input.elements);
   const out: ExcalidrawOpenMcpAppInput = {
-    transport: EXCALIDRAW_MCP_TRANSPORT,
+    transport: resolveExcalidrawTransport(),
     toolName: EXCALIDRAW_CREATE_VIEW_TOOL,
     serverName: EXCALIDRAW_SERVER_NAME,
     toolArguments: { elements },

package/src/server/html-surface.ts

@@ -15,6 +15,11 @@
  * postMessage required.
  */
 
+import {
+  AX_SURFACE_ACK_SOURCE,
+  AX_SURFACE_EMIT_SOURCE,
+  HTML_SURFACE_PUSH_SOURCE,
+} from '../shared/ax-surface-protocol.js';
 import { contentHeightReporterTag } from '../shared/content-height-reporter.js';
 
 export type SurfaceTheme = 'dark' | 'light' | 'high-contrast';
@@ -54,7 +59,7 @@ function buildThemeBridge(themeToken: string): string {
 const PMX_CANVAS_THEME_TOKEN = ${token};
 window.addEventListener('message', (event) => {
   const message = event.data;
-  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'theme-update' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
+  if (!message || message.source !== '${HTML_SURFACE_PUSH_SOURCE}' || message.type !== 'theme-update' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
   if (typeof message.theme !== 'string') return;
   document.documentElement.setAttribute('data-pmx-canvas-theme', message.theme);
   document.documentElement.setAttribute('data-theme', message.theme);
@@ -74,12 +79,12 @@ function buildPresentationEscapeBridge(exitToken: string): string {
 const PMX_CANVAS_PRESENTATION_EXIT_TOKEN = ${token};
 document.addEventListener('keydown', (event) => {
   if (event.key === 'Escape') {
-    window.parent.postMessage({ source: 'pmx-canvas-html-node', type: 'presentation-exit', token: PMX_CANVAS_PRESENTATION_EXIT_TOKEN }, '*');
+    window.parent.postMessage({ source: '${HTML_SURFACE_PUSH_SOURCE}', type: 'presentation-exit', token: PMX_CANVAS_PRESENTATION_EXIT_TOKEN }, '*');
   }
 }, true);
 window.addEventListener('message', (event) => {
   const message = event.data;
-  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'presentation-key' || message.token !== PMX_CANVAS_PRESENTATION_EXIT_TOKEN) return;
+  if (!message || message.source !== '${HTML_SURFACE_PUSH_SOURCE}' || message.type !== 'presentation-key' || message.token !== PMX_CANVAS_PRESENTATION_EXIT_TOKEN) return;
   if (typeof message.key !== 'string') return;
   if (typeof window.PMX_CANVAS_PRESENTATION_HANDLE_KEY === 'function') {
     window.PMX_CANVAS_PRESENTATION_HANDLE_KEY(message.key);
@@ -131,7 +136,7 @@ export function buildAxBridge(axToken: string, nodeId: string): string {
     seq += 1;
     const correlationId = PMX_AX_NODE_ID + '-' + seq + '-' + (Date.now ? Date.now() : 0);
     window.parent.postMessage({
-      source: 'pmx-canvas-ax',
+      source: '${AX_SURFACE_EMIT_SOURCE}',
       token: PMX_AX_TOKEN,
       nodeId: PMX_AX_NODE_ID,
       correlationId: correlationId,
@@ -152,7 +157,7 @@ export function buildAxBridge(axToken: string, nodeId: string): string {
   };
   window.addEventListener('message', function (event) {
     const m = event.data;
-    if (!m || m.source !== 'pmx-canvas-ax-ack' || m.token !== PMX_AX_TOKEN) return;
+    if (!m || m.source !== '${AX_SURFACE_ACK_SOURCE}' || m.token !== PMX_AX_TOKEN) return;
     const result = m.result || { ok: false };
     const resolver = m.correlationId ? pending.get(m.correlationId) : undefined;
     if (resolver) { pending.delete(m.correlationId); resolver(result); }
@@ -182,7 +187,7 @@ export function buildAxStateBridge(axToken: string, snapshotJson: string): strin
   window.PMX_AX.state = ${snapshotJson};
   window.addEventListener('message', function (event) {
     const m = event.data;
-    if (!m || m.source !== 'pmx-canvas-html-node' || m.type !== 'ax-update' || m.token !== PMX_AX_STATE_TOKEN) return;
+    if (!m || m.source !== '${HTML_SURFACE_PUSH_SOURCE}' || m.type !== 'ax-update' || m.token !== PMX_AX_STATE_TOKEN) return;
     window.PMX_AX.state = m.state;
     try { window.dispatchEvent(new CustomEvent('pmx-ax-update', { detail: m.state })); } catch (e) {}
   });

package/src/server/index.ts

@@ -176,15 +176,9 @@ export class PmxCanvas extends EventEmitter {
     this._server = base;
     this._port = getCanvasServerPort() ?? this._port;
 
-    // Wire up mutation history recorder
-    canvasState.onMutation((info) => {
-      mutationHistory.record({
-        description: info.description,
-        operationType: info.operationType,
-        forward: info.forward,
-        inverse: info.inverse,
-      });
-    });
+    // The mutation-history recorder is wired by startCanvasServer above —
+    // onMutation is a single slot, so wiring it again here would only
+    // re-install an identical forwarder (plan-009 L5).
 
     // Wire up prompt handler to emit events
     setPrimaryWorkbenchCanvasPromptHandler(async (request) => {

package/src/server/operations/composites.ts

@@ -16,27 +16,12 @@
  * operation (plan-005 slices 1–7 + plan-008 Wave 1) that is now reachable ONLY
  * through its composite (or `canvas_batch`).
  *
- * Deferred to v0.4: the `canvas_snapshot` composite (still a name collision —
- * see below). Its 6 legacy snapshot standalones (`canvas_snapshot`,
- * `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`,
- * `canvas_gc_snapshots`, `canvas_diff`) stay registered in v0.3.0 but are marked
- * deprecated (description-prefixed) per docs/api-stability.md's
- * deprecate-one-minor-before-removal rule. (`canvas_webview` shipped in plan-008
- * Wave 3 via runner injection; `canvas_app` shipped in Wave 4 — open-mcp-app /
- * diagram / build-artifact. Wave 5 folded the last three legacy tools
- * deprecate-only — NO per-action input-injection mechanism was needed:
- * `canvas_add_html_node` / `canvas_add_html_primitive` → `canvas_node` action
- * "add" (type:"html" [+ primitive]); `canvas_refresh_webpage_node` → `canvas_node`
- * action "update" (refresh:true). `canvas_screenshot` stays standalone — it
- * returns a binary image payload the composite/registry JSON wire shape does not
- * model.)
- *
- * Not shipped here: the `canvas_snapshot` composite (plan-006 #7). Its target
- * name is ALREADY a legacy standalone tool (the save-snapshot tool, op
- * `snapshot.save`), so it cannot be added additively without a name clash, and
- * repurposing `canvas_snapshot` to be action-discriminated now would break
- * existing callers. It lands in v0.4, in the same change that removes the 6
- * kept-but-deprecated legacy snapshot tools and frees the name.
+ * v0.4.0 completed the fold: the `canvas_snapshot` composite shipped (its name
+ * was held by the legacy save-snapshot standalone through v0.3.x, which — with
+ * the other 5 snapshot standalones — was deprecated in 0.3.0 and removed here
+ * per docs/api-stability.md's deprecate-one-minor-before-removal rule).
+ * `canvas_screenshot` stays standalone — it returns a binary image payload the
+ * composite/registry JSON wire shape does not model.
  *
  * This module must never import server.ts or index.ts.
  */
@@ -94,12 +79,6 @@ export interface CompositeToolDefinition {
    * raise a loud error instead of silently no-op'ing.
    */
   resolveOp?: (input: { kind: string; action: string }) => string | undefined;
-  /**
-   * Two-discriminator extension: human-readable `(kind, action)` for a member op
-   * (the inverse of `resolveOp`), used to build that op's deprecation note. The
-   * `kind` field-collision is resolved here (see `gateFieldRemap`).
-   */
-  describeOp?: (opName: string) => { kind: string; action: string } | undefined;
   /**
    * Field-name remap applied to the composite's advertised schema and undone at
    * dispatch. Resolves a collision between a discriminator name and a member-op
@@ -131,7 +110,7 @@ function resolveGateOp(input: { kind: string; action: string }): string | undefi
   return undefined;
 }
 
-/** The 9 gate ops, in (kind, action) order — single source for memberOps + describeOp. */
+/** The 9 gate ops, in (kind, action) order — single source for memberOps. */
 const GATE_OPS: Array<{ op: string; kind: string; action: string }> = GATE_KINDS.flatMap((kind) =>
   GATE_ACTIONS.map((action) => {
     const op = resolveGateOp({ kind, action });
@@ -143,12 +122,25 @@ const GATE_OPS: Array<{ op: string; kind: string; action: string }> = GATE_KINDS
   }),
 );
 
-function describeGateOp(opName: string): { kind: string; action: string } | undefined {
-  const match = GATE_OPS.find((entry) => entry.op === opName);
-  return match ? { kind: match.kind, action: match.action } : undefined;
-}
-
 export const compositeToolDefinitions: CompositeToolDefinition[] = [
+  {
+    // v0.4.0: the long-deferred snapshot composite (plan-006 #7). The name was
+    // held by the legacy save-snapshot standalone through v0.3.x; listing the
+    // composite here suppresses all 6 legacy snapshot standalones via
+    // compositeFoldedOpNames and frees the name in the same change.
+    toolName: 'canvas_snapshot',
+    description:
+      'Canvas snapshots: save the current state, list saved snapshots, restore one, delete one, garbage-collect old ones, or diff the live canvas against one. Action "save" stores a named snapshot; "list" returns saved snapshots (newest first); "restore" replaces the live canvas with a snapshot; "delete" removes one; "gc" keeps the newest N and deletes the rest (dryRun to preview); "diff" shows added/removed/modified nodes and edges versus a snapshot (by name or id).',
+    actionSummary: 'save | list | restore | delete | gc | diff',
+    actions: {
+      save: 'snapshot.save',
+      list: 'snapshot.list',
+      restore: 'snapshot.restore',
+      delete: 'snapshot.delete',
+      gc: 'snapshot.gc',
+      diff: 'snapshot.diff',
+    },
+  },
   {
     toolName: 'canvas_node',
     description:
@@ -289,7 +281,6 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
     },
     memberOps: GATE_OPS.map((entry) => entry.op),
     resolveOp: resolveGateOp,
-    describeOp: describeGateOp,
     // ax.approval.request defines its own optional `action` field (a
     // machine-readable identifier the gate guards) — it collides with the gate
     // lifecycle `action` discriminator. Namespace it to `approvalAction` in the

package/src/server/operations/invoker.ts

@@ -68,19 +68,26 @@ export class HttpOperationInvoker implements OperationInvoker {
     const response = await fetch(url, init);
     const text = await response.text();
     let parsed: unknown = null;
+    let parsedAsJson = false;
     if (text.length > 0) {
       try {
         parsed = JSON.parse(text) as unknown;
+        parsedAsJson = true;
       } catch {
         parsed = { error: text };
       }
     }
     if (!response.ok) {
-      if (route.errorBodyAsResult) return parsed;
+      // errorBodyAsResult carries the route's STRUCTURED partial-failure
+      // envelope (e.g. canvas_batch { ok:false, failedIndex, ... }) through as
+      // a result. A non-JSON error body (an HTML 502 from a proxy, a foreign
+      // service) is not that envelope — fall through to the throw path so the
+      // caller still fails loudly with a nonzero exit.
+      if (route.errorBodyAsResult && parsedAsJson) return parsed;
       const message =
-        parsed !== null && typeof parsed === 'object' && 'error' in parsed
+        parsedAsJson && parsed !== null && typeof parsed === 'object' && 'error' in parsed
           ? String((parsed as { error?: unknown }).error)
-          : `HTTP ${response.status}`;
+          : `HTTP ${response.status}${text.length > 0 ? `: ${text.slice(0, 200)}` : ''}`;
       throw new OperationError(message, toOperationErrorStatus(response.status));
     }
     return parsed;

package/src/server/operations/mcp.ts

@@ -11,7 +11,7 @@ import { z, type ZodRawShape, type ZodTypeAny } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { getOperation, listOperations } from './registry.js';
 import type { OperationInvoker } from './invoker.js';
-import { OperationError, type OperationMcpToolHost } from './types.js';
+import { OperationError, type Operation, type OperationMcpToolHost } from './types.js';
 import { compositeFoldedOpNames, compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
 
 export interface OperationToolHost extends OperationMcpToolHost {
@@ -176,6 +176,43 @@ function stripCompositeDiscriminators(
   return out;
 }
 
+/**
+ * Per-op cache of the MCP arg names its extraShape marks REQUIRED (a schema
+ * that rejects `undefined`). These are the standalone tools' old contracts,
+ * which buildCompositeShape flattens to all-optional — the composite handler
+ * re-enforces them at dispatch so a missing required field fails loudly and
+ * names the field, instead of failing deep in the handler or silently
+ * no-oping (the `q`-vs-`query` zero-results trap from the 0.3.1 test report).
+ */
+const requiredFieldsCache = new WeakMap<object, string[]>();
+
+// Advertised input aliases that satisfy a required extraShape field: the op's
+// handler accepts either name, so the pre-dispatch check must too. (The only
+// such collision across all 15 composites — edges.ts advertises `edge_id` as a
+// legacy alias for `id` and its handler reads `edge_id ?? id`.)
+const REQUIRED_FIELD_ALIASES: Record<string, Record<string, readonly string[]>> = {
+  'edge.remove': { id: ['edge_id'] },
+};
+
+function requiredFieldSatisfied(opName: string, field: string, rest: Record<string, unknown>): boolean {
+  if (rest[field] !== undefined) return true;
+  const aliases = REQUIRED_FIELD_ALIASES[opName]?.[field] ?? [];
+  return aliases.some((alias) => rest[alias] !== undefined);
+}
+
+function requiredMcpFields(op: Operation): string[] {
+  const tool = op.mcp;
+  if (!tool?.extraShape) return [];
+  let keys = requiredFieldsCache.get(tool);
+  if (!keys) {
+    keys = Object.entries(tool.extraShape)
+      .filter(([, schema]) => !(schema as ZodTypeAny).safeParse(undefined).success)
+      .map(([key]) => key);
+    requiredFieldsCache.set(tool, keys);
+  }
+  return keys;
+}
+
 /**
  * Register composite (action-discriminated) MCP tools (plan-006). Each action
  * dispatches to a registered operation, reusing that op's `mcp.buildInput` and
@@ -188,6 +225,12 @@ export function registerCompositeTools(
   definitions: CompositeToolDefinition[] = compositeToolDefinitions,
 ): void {
   for (const def of definitions) {
+    // Public composite name for each op field (inverse of fieldRemap), so
+    // required-field errors name the argument the agent actually sends.
+    const publicFieldName = new Map<string, string>();
+    for (const [publicKey, opField] of Object.entries(def.fieldRemap ?? {})) {
+      publicFieldName.set(opField, publicKey);
+    }
     server.tool(def.toolName, def.description, buildCompositeShape(def), async (input: Record<string, unknown>) => {
       try {
         const host = await getHost();
@@ -197,6 +240,13 @@ export function registerCompositeTools(
         // and undo any field remap; the rest is the op's raw MCP args — the same
         // value the standalone tool would receive.
         const rest = stripCompositeDiscriminators(def, input);
+        const missing = requiredMcpFields(op).filter((field) => !requiredFieldSatisfied(opName, field, rest));
+        if (missing.length > 0) {
+          const named = missing.map((field) => `"${publicFieldName.get(field) ?? field}"`).join(', ');
+          throw new OperationError(
+            `${def.toolName} action "${String(input.action)}" requires ${named}. Unknown parameters are ignored — check the argument names.`,
+          );
+        }
         const opInput = op.mcp?.buildInput ? op.mcp.buildInput(rest) : rest;
         const result = await host.invoker().invoke(opName, opInput);
         if (op.mcp?.formatResult) {

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

@@ -405,6 +405,11 @@ const webArtifactOperation = defineOperation<z.infer<typeof webArtifactSchema>,
   http: {
     method: 'POST',
     path: '/api/canvas/web-artifact',
+    // Build failures throw OperationError, served as { ok:false, error }. The
+    // CLI prints that failure envelope on STDOUT and exits 1
+    // (cli-node.test.ts:2502-2548 pins it), so the HTTP invoker must return
+    // the non-2xx body instead of throwing — mirrors canvas.batch/webview.start.
+    errorBodyAsResult: true,
   },
   mcp: {
     toolName: 'canvas_build_web_artifact',