onbuzz 4.5.0 → 4.6.0

package/src/core/stateManager.js

@@ -621,8 +621,10 @@ class StateManager {
       throw new Error(`Flow ${flowId} not found`);
     }
 
-    // Only allow updating specific fields
-    const allowedFields = ['name', 'description', 'nodes', 'edges', 'variables'];
+    // Only allow updating specific fields. `version` and `schemaVersion`
+    // are added so the Phase 6 version-stamp write-back persists, and
+    // so v2 flows can be marked when typed I/O is added.
+    const allowedFields = ['name', 'description', 'nodes', 'edges', 'variables', 'version', 'schemaVersion'];
     for (const field of allowedFields) {
       if (updates[field] !== undefined) {
         flowIndex[flowId][field] = updates[field];
@@ -786,25 +788,77 @@ class StateManager {
     const stateDir = this.getStateDir(projectDir);
     const stateFile = path.join(stateDir, agentInfo.stateFile);
     const conversationsFile = path.join(stateDir, agentInfo.conversationsFile);
-    
+
+    // Skeleton defaults the resilient loader falls back to when a state
+    // file is missing, empty, or unrepairable. The state skeleton derives
+    // the agent name from the index entry so even a total wipe leaves
+    // the agent identifiable in the UI rather than ending up nameless.
+    const stateDefault = () => ({
+      version: 2,
+      agentId,
+      state: {
+        id: agentId,
+        name: agentInfo.name || agentId,
+        type: agentInfo.type || 'user-created',
+        status: 'active',
+        mode: 'chat',
+        currentModel: agentInfo.preferredModel || agentInfo.model || null,
+        preferredModel: agentInfo.preferredModel || agentInfo.model || null,
+        systemPrompt: '',
+        capabilities: agentInfo.capabilities || [],
+        taskList: { tasks: [], lastUpdated: new Date().toISOString() },
+        messageQueues: { userMessages: [], interAgentMessages: [], toolResults: [] },
+        interAgentTracking: {},
+      },
+      lastPersisted: new Date().toISOString(),
+    });
+    const conversationsDefault = () => ({
+      version: 2,
+      agentId,
+      conversations: {
+        // Empty `full` conversation — required by validateModelConversations
+        // and the agent loop's history reader. New per-model entries are
+        // added on demand at first use.
+        full: { messages: [], lastUpdated: new Date().toISOString() },
+      },
+      lastPersisted: new Date().toISOString(),
+    });
+
+    // Recovery reports for any auto-fixed files. Attached to the
+    // returned agent so the caller (orchestrator → webServer) can
+    // broadcast each one as a toast in the UI. Empty array on the
+    // happy path; harmless presence otherwise.
+    const recoveries = [];
+
     try {
-      // Load agent state
-      const stateData = await this.loadJSON(stateFile);
-      const conversationsData = await this.loadJSON(conversationsFile);
-      
+      const stateRes = await this.loadJSONResilient(stateFile, stateDefault, {
+        label: `agent state (${agentInfo.name || agentId})`,
+      });
+      const conversationsRes = await this.loadJSONResilient(conversationsFile, conversationsDefault, {
+        label: `agent conversations (${agentInfo.name || agentId})`,
+      });
+      const stateData = stateRes.data;
+      const conversationsData = conversationsRes.data;
+      if (stateRes.recovery) recoveries.push(stateRes.recovery);
+      if (conversationsRes.recovery) recoveries.push(conversationsRes.recovery);
+
       // Validate model conversations integrity
       await this.validateModelConversations(conversationsData.conversations);
-      
+
       // Check if agent is paused
       const pauseStatus = await this.checkAgentPauseStatus(agentId, projectDir);
-      
+
       const restoredAgent = {
         ...stateData.state,
         conversations: conversationsData.conversations,
         isPaused: pauseStatus.isPaused,
         pausedUntil: pauseStatus.pausedUntil,
         isRestored: true,
-        restoredAt: new Date().toISOString()
+        restoredAt: new Date().toISOString(),
+        // Non-enumerable would be cleaner, but agentPool serializes the
+        // whole object — keeping it as a plain field. The orchestrator
+        // strips it before persisting (see import handler).
+        _restoreRecoveries: recoveries,
       };
 
       // CRITICAL: Restore interAgentTracking as a Map (it comes as plain object from JSON)
@@ -813,15 +867,16 @@ class StateManager {
       } else if (!(restoredAgent.interAgentTracking instanceof Map)) {
         restoredAgent.interAgentTracking = new Map(Object.entries(restoredAgent.interAgentTracking));
       }
-      
+
       this.logger.info(`Agent restored: ${agentId}`, {
         name: restoredAgent.name,
         status: restoredAgent.status,
-        messageCount: restoredAgent.conversations?.full?.messages?.length || 0
+        messageCount: restoredAgent.conversations?.full?.messages?.length || 0,
+        recoveryCount: recoveries.length,
       });
-      
+
       return restoredAgent;
-      
+
     } catch (error) {
       this.logger.error(`Agent restoration failed: ${agentId}`, error.message);
       throw error;
@@ -1074,7 +1129,7 @@ class StateManager {
   }
 
   /**
-   * Load JSON data from file
+   * Load JSON data from file (strict — throws on missing or corrupt).
    * @private
    */
   async loadJSON(filePath) {
@@ -1082,6 +1137,185 @@ class StateManager {
     return JSON.parse(data);
   }
 
+  /**
+   * Load JSON with best-effort recovery from common breakage modes.
+   * Designed so a single bad state file doesn't take down the entire
+   * agent-load flow — instead the caller gets back a usable object plus
+   * a `recovery` report that callers can surface as a toast.
+   *
+   * Recovery ladder (first match wins):
+   *   1. Missing file (ENOENT)             → recreate with `defaultValue`,
+   *                                          report `kind='not-found'`
+   *   2. Empty / whitespace-only file       → overwrite with `defaultValue`,
+   *                                          report `kind='empty-recreated'`
+   *   3. Common syntax issues               → repaired in memory and saved
+   *      (trailing comma, BOM, unclosed       back to disk; report
+   *      braces/brackets, stray garbage       `kind='repaired'`
+   *      after the JSON object)
+   *   4. Salvageable first JSON block       → use the salvaged object,
+   *      (anywhere in the buffer)             archive the original to
+   *                                          `<file>.corrupt-<ts>.json`,
+   *                                          report `kind='partial'`
+   *   5. Nothing usable                     → use `defaultValue`, archive
+   *                                          original (if any), report
+   *                                          `kind='unrepairable'`
+   *
+   * @param {string} filePath - Absolute path to the JSON file
+   * @param {Object|Array|null|Function} defaultValue - Value to use when
+   *   the file is missing/empty/unrepairable. If a function is provided
+   *   it's called with the file path and its return value is used.
+   * @param {Object} [options]
+   * @param {boolean} [options.persistRecreated=true] - Whether to write
+   *   the default back to disk on missing/empty/unrepairable cases.
+   * @param {string} [options.label] - Human-readable label used in toast
+   *   messages (e.g. 'agent state', 'agent conversations'). Falls back
+   *   to the file's basename.
+   * @returns {Promise<{data: any, recovery: ?Object}>}
+   */
+  async loadJSONResilient(filePath, defaultValue, options = {}) {
+    const { persistRecreated = true } = options;
+    const label = options.label || path.basename(filePath);
+    const defaultOf = () =>
+      typeof defaultValue === 'function' ? defaultValue(filePath) : defaultValue;
+
+    // 1. Missing file → recreate with default
+    let raw;
+    try {
+      raw = await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        const data = defaultOf();
+        if (persistRecreated && data !== undefined) {
+          try { await this.saveJSON(filePath, data); } catch { /* tolerate read-only mounts */ }
+        }
+        const recovery = {
+          kind: 'not-found', filePath, label,
+          message: `${label} file was missing — created an empty one.`,
+        };
+        this.logger?.info(`[stateManager] ${recovery.message}`, { filePath });
+        return { data, recovery };
+      }
+      throw err; // unexpected read error (permissions, etc) — let caller handle
+    }
+
+    // 2. Empty or whitespace-only → recreate
+    if (!raw || raw.trim().length === 0) {
+      const data = defaultOf();
+      if (persistRecreated && data !== undefined) {
+        try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+      }
+      const recovery = {
+        kind: 'empty-recreated', filePath, label,
+        message: `${label} file was empty — recreated with a default skeleton.`,
+      };
+      this.logger?.warn(`[stateManager] ${recovery.message}`, { filePath });
+      return { data, recovery };
+    }
+
+    // 3. Strict parse — happy path
+    try {
+      return { data: JSON.parse(raw), recovery: null };
+    } catch (firstErr) {
+      // 3a. Quick repairs: BOM, trailing comma before close, junk after
+      // the closing brace, smart quotes that occasionally creep in via
+      // copy-paste. None of these is exotic — they're the top-3 reasons
+      // hand-edited or partially-flushed files break.
+      let repaired = raw;
+      if (repaired.charCodeAt(0) === 0xFEFF) repaired = repaired.slice(1);
+      // Strip ASCII control chars except tab/newline/CR
+      repaired = repaired.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
+      // Trim whitespace
+      repaired = repaired.trim();
+      // Drop trailing commas before a closing } or ]
+      repaired = repaired.replace(/,(\s*[}\]])/g, '$1');
+      // Cut anything after the last balanced } / ] (junk after JSON).
+      const lastClose = Math.max(repaired.lastIndexOf('}'), repaired.lastIndexOf(']'));
+      if (lastClose > 0 && lastClose < repaired.length - 1) {
+        repaired = repaired.slice(0, lastClose + 1);
+      }
+      try {
+        const data = JSON.parse(repaired);
+        if (persistRecreated && repaired !== raw) {
+          try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+        }
+        const recovery = {
+          kind: 'repaired', filePath, label,
+          message: `${label} file had a minor syntax issue (${firstErr.message}) — auto-repaired.`,
+        };
+        this.logger?.warn(`[stateManager] ${recovery.message}`, { filePath });
+        return { data, recovery };
+      } catch { /* fall through */ }
+
+      // 3b. Salvage: walk the buffer for the first balanced { ... } block
+      // and try to parse just that. Catches truncated-mid-file cases.
+      const salvaged = this._extractFirstJsonBlock(raw);
+      if (salvaged) {
+        try {
+          const data = JSON.parse(salvaged);
+          const archivePath = `${filePath}.corrupt-${Date.now()}.json`;
+          try { await fs.writeFile(archivePath, raw, 'utf8'); } catch { /* ok */ }
+          if (persistRecreated) {
+            try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+          }
+          const recovery = {
+            kind: 'partial', filePath, label,
+            message: `${label} file was partially corrupt — recovered the first valid section. Original archived to ${path.basename(archivePath)}.`,
+            archivePath,
+          };
+          this.logger?.warn(`[stateManager] ${recovery.message}`, { filePath, archivePath });
+          return { data, recovery };
+        } catch { /* fall through */ }
+      }
+
+      // 4. Nothing parseable — archive the corrupt file and use default
+      const data = defaultOf();
+      const archivePath = `${filePath}.corrupt-${Date.now()}.json`;
+      try { await fs.writeFile(archivePath, raw, 'utf8'); } catch { /* ok */ }
+      if (persistRecreated && data !== undefined) {
+        try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+      }
+      const recovery = {
+        kind: 'unrepairable', filePath, label,
+        message: `${label} file is corrupt and could not be repaired — restored a default skeleton. Original archived to ${path.basename(archivePath)}.`,
+        archivePath,
+        originalError: firstErr.message,
+      };
+      this.logger?.error(`[stateManager] ${recovery.message}`, { filePath, archivePath, error: firstErr.message });
+      return { data, recovery };
+    }
+  }
+
+  /**
+   * Walk a string and return the substring of the first balanced
+   * `{ ... }` block, respecting string literals so braces inside strings
+   * don't confuse the count. Returns null if no complete block exists.
+   * @private
+   */
+  _extractFirstJsonBlock(s) {
+    if (typeof s !== 'string') return null;
+    const start = s.indexOf('{');
+    if (start < 0) return null;
+    let depth = 0;
+    let inStr = false;
+    let escape = false;
+    for (let i = start; i < s.length; i++) {
+      const ch = s[i];
+      if (inStr) {
+        if (escape) { escape = false; continue; }
+        if (ch === '\\') { escape = true; continue; }
+        if (ch === '"') { inStr = false; }
+        continue;
+      }
+      if (ch === '"') { inStr = true; continue; }
+      if (ch === '{') depth++;
+      else if (ch === '}') {
+        depth--;
+        if (depth === 0) return s.slice(start, i + 1);
+      }
+    }
+    return null;
+  }
+
   /**
    * Delete agent state from storage
    * @param {string} agentId - Agent identifier

package/src/index.js

@@ -384,6 +384,14 @@ class LoxiaApplication {
       this.stateManager
     );
 
+    // Expose toolsRegistry on the orchestrator so downstream wiring (e.g.
+    // webServer's flowExecutor init at webServer.js:574 → jobDoneTool
+    // setFlowExecutor) can reach it through the orchestrator handle. Without
+    // this, `this.orchestrator?.toolsRegistry` is undefined at wiring time
+    // and JobDoneTool's flow-contract validation (Phase 8) silently no-ops
+    // for the entire process lifetime.
+    this.orchestrator.toolsRegistry = this.toolsRegistry;
+
     // Set cross-references between components
     this.messageProcessor.orchestrator = this.orchestrator;
     this.messageProcessor.setScheduler(this.agentScheduler);

package/src/interfaces/webServer.js

@@ -43,6 +43,14 @@ import { initFileExplorerModule } from '../modules/fileExplorer/index.js';
 
 // Import FlowExecutor for flow pipeline execution
 import FlowExecutor from '../core/flowExecutor.js';
+// Flow definition gate — rejects malformed flows BEFORE persistence/execution.
+import { validateFlowDefinition } from '../core/flowSchema.js';
+// Phase 4: disk checkpoint store backs resume/restart of failed runs.
+import { FlowCheckpointStore } from '../core/flowCheckpointStore.js';
+// Phase 5: editor lint — soft warnings (unbound placeholders, etc.)
+import { lintFlow } from '../core/flowLint.js';
+// Phase 6: append-only flow version archive (rollback support).
+import { FlowVersionStore } from '../core/flowVersionStore.js';
 
 // Scheduler visualizer routes (extracted for testability)
 import { registerSchedulerRoutes } from './schedulerRoutes.js';
@@ -536,6 +544,39 @@ class WebServer {
       // WebServer has broadcastToSession method that FlowExecutor will use
       this.flowExecutor.setWebSocketManager(this);
 
+      // Phase 4: wire a disk checkpoint store so failed/interrupted
+      // flow runs can be resumed instead of starting over from scratch.
+      // Stored under the user data dir alongside agent state so the
+      // data survives `npm i -g` updates and follows the user across
+      // working-directory changes. (Earlier code read `dataPaths?.dataDir`
+      // which doesn't exist on getUserDataPaths() — that fell through to
+      // process.cwd() and dropped checkpoints into whatever directory the
+      // process happened to start in. Use `state` instead, grouping with
+      // agents/, operations/, models/, skills/.)
+      try {
+        const dataPaths = getUserDataPaths();
+        const checkpointDir = path.join(dataPaths?.state || process.cwd(), 'flow-checkpoints');
+        const store = new FlowCheckpointStore({ baseDir: checkpointDir });
+        this.flowExecutor.setCheckpointStore(store);
+        this.logger.info('FlowExecutor checkpoint store enabled', { baseDir: checkpointDir });
+      } catch (err) {
+        // Non-fatal: continue without resumability rather than failing init.
+        this.logger.warn('Failed to enable flow checkpoint store (non-fatal)', { error: err.message });
+      }
+
+      // Phase 6: wire a version store so every flow save records an
+      // immutable snapshot. Used by /api/flows/:id/versions and
+      // /api/flows/:id/rollback. Stored alongside checkpoints under
+      // user data dir (see comment above for path-fix history).
+      try {
+        const dataPaths = getUserDataPaths();
+        const versionDir = path.join(dataPaths?.state || process.cwd(), 'flow-versions');
+        this.flowVersionStore = new FlowVersionStore({ baseDir: versionDir });
+        this.logger.info('Flow version store enabled', { baseDir: versionDir });
+      } catch (err) {
+        this.logger.warn('Failed to enable flow version store (non-fatal)', { error: err.message });
+      }
+
       // Wire FlowExecutor into jobDoneTool so it can signal completion directly
       const toolsRegistry = this.orchestrator?.toolsRegistry;
       if (toolsRegistry) {
@@ -4249,9 +4290,37 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           });
         }
 
+        // If the resilient state loader recovered from missing/empty/
+        // corrupt files, broadcast each recovery as a UI toast so the
+        // operator sees what was salvaged. The reports were attached to
+        // the restored agent in stateManager.restoreAgent.
+        const recoveries = Array.isArray(agent._restoreRecoveries) ? agent._restoreRecoveries : [];
+        if (recoveries.length > 0 && this.wsManager) {
+          for (const r of recoveries) {
+            this.wsManager.broadcast({
+              type: 'state-file-recovery',
+              level: r.kind === 'unrepairable' ? 'error'
+                   : r.kind === 'partial'      ? 'warning'
+                   : 'info',
+              agentId: agent.id,
+              agentName: agent.name,
+              recovery: {
+                kind: r.kind,
+                label: r.label,
+                message: r.message,
+                archivePath: r.archivePath || null,
+              },
+            });
+          }
+        }
+        // Strip the recovery payload before logging/serializing back to
+        // the client — it's an internal hint, not part of the agent shape.
+        delete agent._restoreRecoveries;
+
         this.logger.info('Agent imported successfully', {
           agentId: agent.id,
-          name: agent.name
+          name: agent.name,
+          recoveryCount: recoveries.length,
         });
 
         res.json({
@@ -4264,7 +4333,12 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
             capabilities: agent.capabilities,
             lastActivity: agent.lastActivity
           },
-          message: `Agent ${agent.name} imported successfully`
+          message: `Agent ${agent.name} imported successfully`,
+          // Surfaced to the importer too so a non-WS client (curl) sees
+          // them in the response body.
+          ...(recoveries.length > 0 ? { recoveries: recoveries.map(r => ({
+            kind: r.kind, label: r.label, message: r.message,
+          })) } : {}),
         });
       } catch (error) {
         this.logger.error('Failed to import agent', {
@@ -4723,10 +4797,15 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       try {
         const { name, description, nodes, edges, variables } = req.body;
 
-        if (!name) {
+        // Schema gate: reject malformed flows BEFORE they reach persistence
+        // (avoids "saved but unexecutable" states). 400 with structured
+        // errors so the editor can highlight specific problems inline.
+        const validation = validateFlowDefinition({ name, nodes: nodes || [], edges: edges || [], variables });
+        if (!validation.ok) {
           return res.status(400).json({
             success: false,
-            error: 'Flow name is required'
+            error: 'Flow definition is invalid',
+            details: validation.errors
           });
         }
 
@@ -4739,6 +4818,20 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           variables
         }, projectDir);
 
+        // Phase 6: record initial version (v1). Best-effort — the flow
+        // is already saved; failing to version is a non-fatal warning.
+        // Stamp the version number back onto the flow record so runs
+        // can record which definition produced their output.
+        if (this.flowVersionStore && flow?.id) {
+          try {
+            const v = await this.flowVersionStore.recordVersion(flow.id, flow);
+            const projectDir = this.orchestrator.config.project?.directory || process.cwd();
+            await this.orchestrator.stateManager.updateFlow(flow.id, { version: v.version }, projectDir);
+            flow.version = v.version;
+          }
+          catch (e) { this.logger.warn('flow version record failed', { error: e.message }); }
+        }
+
         // Broadcast flow created event
         if (this.wsManager) {
           this.wsManager.broadcast({
@@ -4794,6 +4887,35 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
         const { name, description, nodes, edges, variables } = req.body;
         const projectDir = this.orchestrator.config.project?.directory || process.cwd();
 
+        // PUT supports partial updates (e.g. just `{ nodes, edges }`
+        // when the user clicks Save in the editor). Load the existing
+        // flow and merge the patch before validating, so the schema
+        // gate sees the full resulting record — not just the diff.
+        const existing = await this.orchestrator.stateManager.getFlow(flowId, projectDir);
+        if (!existing) {
+          return res.status(404).json({ success: false, error: `Flow ${flowId} not found` });
+        }
+        const merged = {
+          ...existing,
+          ...(name        !== undefined ? { name }        : {}),
+          ...(description !== undefined ? { description } : {}),
+          ...(nodes       !== undefined ? { nodes }       : {}),
+          ...(edges       !== undefined ? { edges }       : {}),
+          ...(variables   !== undefined ? { variables }   : {}),
+        };
+
+        // Same schema gate as POST. Editing a flow into an invalid state
+        // is just as bad as creating one — both should be caught here, not
+        // 90s into a future execution.
+        const validation = validateFlowDefinition(merged);
+        if (!validation.ok) {
+          return res.status(400).json({
+            success: false,
+            error: 'Flow definition is invalid',
+            details: validation.errors
+          });
+        }
+
         const flow = await this.orchestrator.stateManager.updateFlow(flowId, {
           name,
           description,
@@ -4802,6 +4924,17 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           variables
         }, projectDir);
 
+        // Phase 6: record a new version snapshot on every PUT and
+        // stamp the new version number onto the live record.
+        if (this.flowVersionStore && flow?.id) {
+          try {
+            const v = await this.flowVersionStore.recordVersion(flow.id, flow);
+            await this.orchestrator.stateManager.updateFlow(flow.id, { version: v.version }, projectDir);
+            flow.version = v.version;
+          }
+          catch (e) { this.logger.warn('flow version record failed', { error: e.message }); }
+        }
+
         // Broadcast flow updated event
         if (this.wsManager) {
           this.wsManager.broadcast({
@@ -4956,6 +5089,140 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       }
     });
 
+    // Phase 6: list versions of a flow (lightweight metadata only).
+    this.app.get('/api/flows/:flowId/versions', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const versions = await this.flowVersionStore.listVersions(req.params.flowId);
+        res.json({ success: true, data: versions });
+      } catch (error) {
+        this.logger.error('list versions failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 6: read a specific version snapshot (full flow definition).
+    this.app.get('/api/flows/:flowId/versions/:version', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const v = parseInt(req.params.version, 10);
+        if (!Number.isFinite(v) || v < 1) {
+          return res.status(400).json({ success: false, error: 'version must be a positive integer' });
+        }
+        const snap = await this.flowVersionStore.loadVersion(req.params.flowId, v);
+        if (!snap) return res.status(404).json({ success: false, error: 'version not found' });
+        res.json({ success: true, data: snap });
+      } catch (error) {
+        this.logger.error('load version failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 6: rollback — restore version N as the live flow record.
+    // Body: { version: N }. Records ANOTHER new version after rollback
+    // so history stays append-only ("rolled back to v3" produces v(N+1)).
+    this.app.post('/api/flows/:flowId/rollback', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const { flowId } = req.params;
+        const target = parseInt(req.body?.version, 10);
+        if (!Number.isFinite(target) || target < 1) {
+          return res.status(400).json({ success: false, error: 'body.version must be a positive integer' });
+        }
+        const snap = await this.flowVersionStore.loadVersion(flowId, target);
+        if (!snap) return res.status(404).json({ success: false, error: `version ${target} not found` });
+
+        // Validate the target snapshot before promoting it. A flow that
+        // passed validation when first saved may now be invalid against
+        // a newer schema — surfacing that here is better than at execute.
+        const validation = validateFlowDefinition(snap.flow);
+        if (!validation.ok) {
+          return res.status(400).json({
+            success: false,
+            error: `version ${target} fails current validation`,
+            details: validation.errors,
+          });
+        }
+
+        const projectDir = this.orchestrator.config.project?.directory || process.cwd();
+        const restored = await this.orchestrator.stateManager.updateFlow(flowId, {
+          name:        snap.flow.name,
+          description: snap.flow.description,
+          nodes:       snap.flow.nodes,
+          edges:       snap.flow.edges,
+          variables:   snap.flow.variables,
+        }, projectDir);
+
+        // Append a new version entry tagging the rollback
+        try {
+          await this.flowVersionStore.recordVersion(flowId, {
+            ...restored,
+            _rollbackOf: target,
+          });
+        } catch (e) {
+          this.logger.warn('post-rollback version record failed', { error: e.message });
+        }
+
+        if (this.wsManager) {
+          this.wsManager.broadcast({ type: 'flow-updated', flow: restored });
+        }
+        res.json({ success: true, data: restored, rolledBackTo: target });
+      } catch (error) {
+        this.logger.error('rollback failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 5: dry-run / lint an unsaved flow definition.
+    // Posted body IS the flow definition (so the editor can lint
+    // unsaved drafts). Combines schema gate + lint warnings into a
+    // single report so the editor can highlight everything inline.
+    this.app.post('/api/flows/dry-run', async (req, res) => {
+      try {
+        const flow = req.body || {};
+        const validation = validateFlowDefinition(flow);
+        const lint = lintFlow(flow);
+        res.json({
+          success: true,
+          ok: validation.ok && lint.errors.length === 0,
+          schemaErrors: validation.errors,
+          lintErrors: lint.errors,
+          lintWarnings: lint.warnings,
+        });
+      } catch (error) {
+        this.logger.error('Dry-run failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 4: resume a failed / interrupted flow run.
+    // Per-node checkpoints on disk let us skip already-completed nodes
+    // and re-run from the first non-completed one. The run record lives
+    // under runId regardless of the flow it belongs to, so this lookup
+    // does not require the flowId in the URL.
+    this.app.post('/api/flows/runs/:runId/resume', async (req, res) => {
+      try {
+        const { runId } = req.params;
+        const { sessionId } = req.body || {};
+        if (!this.flowExecutor) {
+          return res.status(503).json({ success: false, error: 'FlowExecutor not initialized' });
+        }
+        // Async: kick off and return immediately so the HTTP request
+        // doesn't sit open for minutes. Errors propagate via WebSocket
+        // (flow_run_failed) and the run record's status field.
+        this.flowExecutor.resumeFlow(runId, sessionId || null).catch(err => {
+          this.logger.error(`Resume flow failed for run ${runId}`, { error: err.message });
+        });
+        res.json({ success: true, runId, status: 'resuming' });
+      } catch (error) {
+        this.logger.error('Failed to resume flow run', { error: error.message, runId: req.params.runId });
+        const status = /not found/i.test(error.message) ? 404
+                     : /checkpoint store/i.test(error.message) ? 503
+                     : 500;
+        res.status(status).json({ success: false, error: error.message });
+      }
+    });
+
     // Stop a flow run
     this.app.post('/api/flows/:flowId/stop', async (req, res) => {
       try {