onbuzz 4.5.0 → 4.6.1

package/src/core/__tests__/stateManager.test.js

@@ -372,4 +372,352 @@ describe('StateManager', () => {
       expect(written.projectDir).toBe('/project');
     });
   });
+
+  // ─── createFlow edge-id stamping (renders arrows for templates) ────────
+  describe('createFlow edge-id stamping', () => {
+    test('stamps a stable id on every edge that arrives without one', async () => {
+      // Templates + marketplace-installed flows arrive WITHOUT edge ids.
+      // ReactFlow silently drops edges missing `id`, so the canvas
+      // showed nodes-without-arrows for every freshly-loaded template
+      // until this stamp ran.
+      mockReadFile.mockResolvedValueOnce('{}');     // empty flow index
+      const flowData = {
+        name: 'arrow-test',
+        nodes: [
+          { id: 'a', type: 'agent', position: { x: 0, y: 0 } },
+          { id: 'b', type: 'agent', position: { x: 200, y: 0 } },
+        ],
+        edges: [
+          { source: 'a', sourceField: 'topic', target: 'b', targetField: 'topic' },
+          { source: 'a', sourceField: 'extra', target: 'b', targetField: 'extra' },
+        ],
+      };
+      const created = await sm.createFlow(flowData, '/proj');
+      // Every edge now has an id.
+      expect(created.edges).toHaveLength(2);
+      expect(created.edges.every(e => typeof e.id === 'string' && e.id.length > 0)).toBe(true);
+      // Ids reflect source/target/fields so they're stable across saves.
+      expect(created.edges[0].id).toMatch(/^e-a:topic-b:topic-/);
+      expect(created.edges[1].id).toMatch(/^e-a:extra-b:extra-/);
+    });
+
+    test('preserves existing edge ids — does NOT clobber them', async () => {
+      mockReadFile.mockResolvedValueOnce('{}');
+      const flowData = {
+        name: 'preserve-test',
+        nodes: [],
+        edges: [
+          { id: 'user-supplied-id', source: 'a', target: 'b' },
+        ],
+      };
+      const created = await sm.createFlow(flowData, '/proj');
+      expect(created.edges[0].id).toBe('user-supplied-id');
+    });
+
+    test('handles edges without sourceField/targetField (untyped flows)', async () => {
+      mockReadFile.mockResolvedValueOnce('{}');
+      const flowData = {
+        name: 'untyped',
+        nodes: [],
+        edges: [{ source: 'a', target: 'b' }],
+      };
+      const created = await sm.createFlow(flowData, '/proj');
+      expect(created.edges[0].id).toMatch(/^e-a-b-/);
+    });
+
+    test('persists createdBy when provided (used by platformcontrol create-flow)', async () => {
+      mockReadFile.mockResolvedValueOnce('{}');
+      const flow = await sm.createFlow({
+        name: 'authored', nodes: [], edges: [], createdBy: 'agent-x'
+      }, '/proj');
+      expect(flow.createdBy).toBe('agent-x');
+    });
+
+    test('omits createdBy when not provided (UI-created flows stay minimal)', async () => {
+      mockReadFile.mockResolvedValueOnce('{}');
+      const flow = await sm.createFlow({ name: 'plain', nodes: [], edges: [] }, '/proj');
+      expect(flow).not.toHaveProperty('createdBy');
+    });
+  });
+
+  // ─── loadJSONResilient — corrupt file recovery ─────────────────────────
+  describe('loadJSONResilient', () => {
+    test('happy path: parses clean JSON without recovery', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({ ok: true }));
+      const result = await sm.loadJSONResilient('/file.json', { fallback: true });
+      expect(result.data).toEqual({ ok: true });
+      expect(result.recovery).toBeNull();
+      // Default not written when parse succeeds
+      expect(mockWriteFile).not.toHaveBeenCalled();
+    });
+
+    test('missing file (ENOENT): recreates with default + reports not-found', async () => {
+      const enoent = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+      mockReadFile.mockRejectedValueOnce(enoent);
+      const result = await sm.loadJSONResilient('/file.json', { fresh: true });
+      expect(result.data).toEqual({ fresh: true });
+      expect(result.recovery.kind).toBe('not-found');
+      expect(result.recovery.message).toMatch(/missing/i);
+      expect(mockWriteFile).toHaveBeenCalled(); // default persisted
+    });
+
+    test('empty file: recreates with default + reports empty-recreated', async () => {
+      mockReadFile.mockResolvedValueOnce('');
+      const result = await sm.loadJSONResilient('/file.json', { skeleton: 1 });
+      expect(result.data).toEqual({ skeleton: 1 });
+      expect(result.recovery.kind).toBe('empty-recreated');
+      expect(mockWriteFile).toHaveBeenCalled();
+    });
+
+    test('whitespace-only file: treated as empty', async () => {
+      mockReadFile.mockResolvedValueOnce('   \n\n\t  ');
+      const result = await sm.loadJSONResilient('/file.json', () => ({ defaulted: true }));
+      expect(result.data).toEqual({ defaulted: true });
+      expect(result.recovery.kind).toBe('empty-recreated');
+    });
+
+    test('trailing comma: auto-repaired in place', async () => {
+      // Trailing comma before close brace — common hand-edit mistake.
+      mockReadFile.mockResolvedValueOnce('{"a": 1, "b": [1, 2,],}');
+      const result = await sm.loadJSONResilient('/file.json', null);
+      expect(result.data).toEqual({ a: 1, b: [1, 2] });
+      expect(result.recovery.kind).toBe('repaired');
+      expect(mockWriteFile).toHaveBeenCalled(); // canonicalized form persisted
+    });
+
+    test('BOM-prefixed JSON: auto-repaired', async () => {
+      const bom = String.fromCharCode(0xFEFF);
+      mockReadFile.mockResolvedValueOnce(bom + '{"x": 7}');
+      const result = await sm.loadJSONResilient('/file.json', null);
+      expect(result.data).toEqual({ x: 7 });
+      expect(result.recovery.kind).toBe('repaired');
+    });
+
+    test('partial JSON with junk after: salvages first balanced block', async () => {
+      // Valid JSON followed by half a write (interrupted-flush scenario)
+      mockReadFile.mockResolvedValueOnce('{"valid": true, "deep": {"nested": 1}}{"another": "broken');
+      const result = await sm.loadJSONResilient('/file.json', { fallback: true });
+      // The "junk after the JSON" repair path catches this — reports either
+      // 'repaired' (cut) or 'partial' (salvaged), depending on which branch
+      // matches first. Either is acceptable; data must be the valid prefix.
+      expect(result.data).toEqual({ valid: true, deep: { nested: 1 } });
+      expect(['repaired', 'partial']).toContain(result.recovery.kind);
+    });
+
+    test('completely unrepairable: returns default + archives original', async () => {
+      mockReadFile.mockResolvedValueOnce('this is not json at all, no braces here');
+      const result = await sm.loadJSONResilient('/file.json', { recovered: 'default' });
+      expect(result.data).toEqual({ recovered: 'default' });
+      expect(result.recovery.kind).toBe('unrepairable');
+      expect(result.recovery.archivePath).toMatch(/\.corrupt-\d+\.json$/);
+      // Two writes: archive + default replacement
+      expect(mockWriteFile.mock.calls.length).toBeGreaterThanOrEqual(2);
+    });
+
+    test('persistRecreated=false: does not write default to disk', async () => {
+      mockReadFile.mockResolvedValueOnce('');
+      const result = await sm.loadJSONResilient(
+        '/file.json',
+        { skeleton: 1 },
+        { persistRecreated: false }
+      );
+      expect(result.data).toEqual({ skeleton: 1 });
+      expect(result.recovery.kind).toBe('empty-recreated');
+      expect(mockWriteFile).not.toHaveBeenCalled();
+    });
+
+    test('non-ENOENT read error: bubbles up unchanged', async () => {
+      mockReadFile.mockRejectedValueOnce(Object.assign(new Error('EACCES'), { code: 'EACCES' }));
+      await expect(sm.loadJSONResilient('/file.json', {})).rejects.toThrow('EACCES');
+    });
+
+    test('control characters (NUL/0x08/0x1f) are stripped during repair', async () => {
+      // Editor crash + partial write can leave random control chars
+      // sprinkled through an otherwise valid JSON. The repair pass should
+      // strip them and return clean data.
+      const dirty = '{"a": 1, "b": [1,2]}';
+      mockReadFile.mockResolvedValueOnce(dirty);
+      const result = await sm.loadJSONResilient('/file.json', null);
+      expect(result.data).toEqual({ a: 1, b: [1, 2] });
+      expect(result.recovery.kind).toBe('repaired');
+    });
+
+    test('defaultValue as a function is invoked per-call with the file path', async () => {
+      // Lazy default lets callers build expensive skeletons only when
+      // needed (avoiding allocation on every happy-path load).
+      const factory = jest.fn((p) => ({ created: 'lazy', path: p }));
+      const enoent = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+      mockReadFile.mockRejectedValueOnce(enoent);
+      const result = await sm.loadJSONResilient('/lazy/path.json', factory);
+      expect(factory).toHaveBeenCalledTimes(1);
+      expect(factory).toHaveBeenCalledWith('/lazy/path.json');
+      expect(result.data).toEqual({ created: 'lazy', path: '/lazy/path.json' });
+    });
+
+    test('happy path: defaultValue function NOT invoked when file parses cleanly', async () => {
+      // Avoid wasted allocation when the loader doesn't need the default.
+      const factory = jest.fn(() => ({ never: 'used' }));
+      mockReadFile.mockResolvedValueOnce('{"clean": true}');
+      const result = await sm.loadJSONResilient('/file.json', factory);
+      expect(factory).not.toHaveBeenCalled();
+      expect(result.data).toEqual({ clean: true });
+    });
+  });
+
+  // ─── _extractFirstJsonBlock — balanced-brace walker ─────────────────────
+  describe('_extractFirstJsonBlock', () => {
+    test('returns null for empty / no opening brace', () => {
+      expect(sm._extractFirstJsonBlock('')).toBeNull();
+      expect(sm._extractFirstJsonBlock('no braces here')).toBeNull();
+      expect(sm._extractFirstJsonBlock(null)).toBeNull();
+      expect(sm._extractFirstJsonBlock(undefined)).toBeNull();
+    });
+
+    test('extracts a simple balanced object', () => {
+      expect(sm._extractFirstJsonBlock('{"a":1}')).toBe('{"a":1}');
+    });
+
+    test('skips leading prose / log noise before the first {', () => {
+      const buf = '[2026-04-30] some log line\n{"agent":"a5"}\ntrailing junk';
+      expect(sm._extractFirstJsonBlock(buf)).toBe('{"agent":"a5"}');
+    });
+
+    test('respects string literals — braces inside quotes do not affect depth', () => {
+      const buf = '{"sql": "SELECT * WHERE x = \\"{open}\\""}';
+      // The whole object is one balanced block; the inner braces are
+      // inside a string and must NOT confuse the walker.
+      expect(sm._extractFirstJsonBlock(buf)).toBe(buf);
+    });
+
+    test('handles escaped quotes in strings', () => {
+      const buf = '{"msg":"say \\"hi\\""}';
+      expect(sm._extractFirstJsonBlock(buf)).toBe(buf);
+    });
+
+    test('picks the FIRST balanced block when multiple are present', () => {
+      const buf = '{"first":1}{"second":2}';
+      expect(sm._extractFirstJsonBlock(buf)).toBe('{"first":1}');
+    });
+
+    test('returns null when braces never balance (truncated mid-object)', () => {
+      const buf = '{"a": {"b": "incomplete';
+      expect(sm._extractFirstJsonBlock(buf)).toBeNull();
+    });
+
+    test('handles deeply nested objects', () => {
+      const buf = '{"l1":{"l2":{"l3":{"l4":{"l5":"deep"}}}}}';
+      expect(sm._extractFirstJsonBlock(buf)).toBe(buf);
+    });
+
+    test('non-string input returns null (defensive)', () => {
+      expect(sm._extractFirstJsonBlock(42)).toBeNull();
+      expect(sm._extractFirstJsonBlock({})).toBeNull();
+      expect(sm._extractFirstJsonBlock([])).toBeNull();
+    });
+  });
+
+  // ─── restoreAgent — integration with the resilient loader ───────────────
+  describe('restoreAgent (resilient state-file recovery)', () => {
+    /**
+     * Helper: arrange the two readFile calls restoreAgent makes (state
+     * file + conversations file) plus the sub-call for checkAgentPauseStatus
+     * (paused-agents file → ENOENT). Returns the agentInfo object that
+     * matches what the agent index would have stored.
+     */
+    function arrangeRestore({ stateOutcome, conversationsOutcome }) {
+      const enoent = (msg = 'ENOENT') => Object.assign(new Error(msg), { code: 'ENOENT' });
+      // restoreAgent calls: readFile(stateFile), readFile(conversationsFile),
+      // then checkAgentPauseStatus → readFile(pausedFile).
+      const seq = [stateOutcome, conversationsOutcome, { reject: enoent('paused file missing') }];
+      mockReadFile.mockReset();
+      for (const o of seq) {
+        if (o.reject) mockReadFile.mockRejectedValueOnce(o.reject);
+        else          mockReadFile.mockResolvedValueOnce(o.resolve);
+      }
+      mockWriteFile.mockResolvedValue(undefined);
+      return {
+        agentId: 'agent-test-1',
+        name: 'Test Agent',
+        type: 'user-created',
+        preferredModel: 'gpt-5',
+        capabilities: ['filesystem'],
+        stateFile: 'agents/agent-agent-test-1-state.json',
+        conversationsFile: 'agents/agent-agent-test-1-conversations.json',
+      };
+    }
+
+    test('happy path: clean files load with no recoveries attached', async () => {
+      const enoent = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+      const stateJson = JSON.stringify({
+        version: 2, agentId: 'agent-test-1',
+        state: { id: 'agent-test-1', name: 'Test Agent', status: 'active', mode: 'chat' },
+      });
+      const convJson = JSON.stringify({
+        version: 2, agentId: 'agent-test-1', conversations: { full: { messages: [] } },
+      });
+      const agentInfo = arrangeRestore({
+        stateOutcome:         { resolve: stateJson },
+        conversationsOutcome: { resolve: convJson },
+      });
+      const restored = await sm.restoreAgent('agent-test-1', agentInfo, '/proj');
+      expect(restored.id).toBe('agent-test-1');
+      expect(restored.name).toBe('Test Agent');
+      // Recovery array exists but is empty.
+      expect(restored._restoreRecoveries).toEqual([]);
+    });
+
+    test('missing state file: builds skeleton from agentInfo, attaches not-found recovery', async () => {
+      const enoent = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+      const convJson = JSON.stringify({ version: 2, conversations: { full: { messages: [] } } });
+      const agentInfo = arrangeRestore({
+        stateOutcome:         { reject: enoent },
+        conversationsOutcome: { resolve: convJson },
+      });
+      const restored = await sm.restoreAgent('agent-test-1', agentInfo, '/proj');
+      // Skeleton derives identity from agentInfo, NOT from a missing file.
+      expect(restored.id).toBe('agent-test-1');
+      expect(restored.name).toBe('Test Agent');
+      expect(restored.preferredModel).toBe('gpt-5');
+      expect(restored.capabilities).toEqual(['filesystem']);
+      expect(restored.taskList).toBeDefined();
+      expect(restored.messageQueues).toBeDefined();
+      // Recovery report flowed through.
+      expect(restored._restoreRecoveries).toHaveLength(1);
+      expect(restored._restoreRecoveries[0].kind).toBe('not-found');
+      expect(restored._restoreRecoveries[0].label).toContain('agent state');
+    });
+
+    test('both state + conversations corrupt: produces 2 separate recovery reports', async () => {
+      const agentInfo = arrangeRestore({
+        // Empty file → empty-recreated
+        stateOutcome:         { resolve: '' },
+        // Garbage file → unrepairable
+        conversationsOutcome: { resolve: 'not json at all, no braces' },
+      });
+      const restored = await sm.restoreAgent('agent-test-1', agentInfo, '/proj');
+      expect(restored._restoreRecoveries).toHaveLength(2);
+      const kinds = restored._restoreRecoveries.map(r => r.kind).sort();
+      expect(kinds).toEqual(['empty-recreated', 'unrepairable']);
+      // Labels distinguish which file was touched, so the toast is actionable.
+      const labels = restored._restoreRecoveries.map(r => r.label);
+      expect(labels.some(l => l.includes('agent state'))).toBe(true);
+      expect(labels.some(l => l.includes('agent conversations'))).toBe(true);
+    });
+
+    test('partial salvage: recovery archives original + flags partial', async () => {
+      // Valid prefix + corrupted tail (interrupted-flush style).
+      const partialState = '{"version":2,"agentId":"agent-test-1","state":{"id":"agent-test-1","name":"Test Agent"}}{"truncated mid-object';
+      const cleanConv = JSON.stringify({ version: 2, conversations: { full: { messages: [] } } });
+      const agentInfo = arrangeRestore({
+        stateOutcome:         { resolve: partialState },
+        conversationsOutcome: { resolve: cleanConv },
+      });
+      const restored = await sm.restoreAgent('agent-test-1', agentInfo, '/proj');
+      expect(restored.name).toBe('Test Agent');
+      expect(restored._restoreRecoveries).toHaveLength(1);
+      // 'repaired' (junk-after-JSON cut) and 'partial' (block salvage) are
+      // both correct outcomes for this shape — accept either.
+      expect(['repaired', 'partial']).toContain(restored._restoreRecoveries[0].kind);
+    });
+  });
 });

package/src/core/agentScheduler.js

@@ -1977,18 +1977,49 @@ class AgentScheduler {
       try {
         const lastUserMsg = [...conversationHistory].reverse().find(m => m.role === 'user');
         if (lastUserMsg?.isFlowExecution && lastUserMsg?.flowMetadata) {
-          const flowContext = this.flowContextService.buildFlowAgentContext(
+          // Phase 8: when running inside a flow, by default REPLACE the
+          // agent's persisted system prompt with a flow-worker prompt
+          // built from the node's role + contract. This prevents the
+          // agent's native identity (e.g. "you are a software developer")
+          // from fighting the flow's structured-output requirements.
+          //
+          // Opt-out: if the flow node sets useNativeSystemPrompt:true OR
+          // the node has no instructions/outputs to assert, fall back
+          // to legacy append-context behavior so v1 flows + curated
+          // single-purpose agents still work as before.
+          const opt = lastUserMsg.nodeContract?.useNativeSystemPrompt === true;
+          const replacement = opt ? null : this.flowContextService.buildFlowAgentSystemPrompt(
             lastUserMsg.flowMetadata,
-            lastUserMsg.previousAgentData
+            lastUserMsg.previousAgentData,
+            lastUserMsg.nodeContract
           );
 
-          if (flowContext) {
-            enhancedSystemPrompt = (enhancedSystemPrompt || '') + flowContext;
-            this.logger.info(`Injected flow execution context for agent ${agentId}`, {
+          if (replacement) {
+            // REPLACE mode — the flow node's role becomes the agent's
+            // identity for this turn. Agent's persisted prompt is
+            // intentionally discarded for this invocation only.
+            enhancedSystemPrompt = replacement;
+            this.logger.info(`Replaced system prompt with flow-worker prompt for agent ${agentId}`, {
               flowName: lastUserMsg.flowMetadata.flowName,
               nodePosition: `${lastUserMsg.flowMetadata.nodePosition}/${lastUserMsg.flowMetadata.totalNodes}`,
-              hasPreviousAgent: !!lastUserMsg.previousAgentData
+              hasPreviousAgent: !!lastUserMsg.previousAgentData,
+              promptLength: replacement.length,
             });
+          } else {
+            // APPEND mode (legacy) — used for v1 flows + opt-out cases.
+            const flowContext = this.flowContextService.buildFlowAgentContext(
+              lastUserMsg.flowMetadata,
+              lastUserMsg.previousAgentData,
+              lastUserMsg.nodeContract
+            );
+            if (flowContext) {
+              enhancedSystemPrompt = (enhancedSystemPrompt || '') + flowContext;
+              this.logger.info(`Appended flow execution context for agent ${agentId}`, {
+                flowName: lastUserMsg.flowMetadata.flowName,
+                nodePosition: `${lastUserMsg.flowMetadata.nodePosition}/${lastUserMsg.flowMetadata.totalNodes}`,
+                hasPreviousAgent: !!lastUserMsg.previousAgentData
+              });
+            }
           }
         }
       } catch (error) {

package/src/core/flowCheckpointStore.js

@@ -0,0 +1,146 @@
+/**
+ * FlowCheckpointStore — disk persistence for flow run state.
+ *
+ * Layout:
+ *   <baseDir>/<runId>/run.json         — top-level run metadata + nodeStates
+ *   <baseDir>/<runId>/node-<id>.json   — per-node recorded result
+ *
+ * Why per-node files: a single run.json rewritten after every node is
+ * fine for small flows but loses partial-write safety. Per-node files
+ * are written once per completion (atomic via tmp+rename) and let the
+ * resume path reconstruct progress even if run.json is missing or stale.
+ *
+ * API surface (intentionally narrow — pure data layer):
+ *   saveRun(run)                         → void
+ *   loadRun(runId)                       → run | null
+ *   saveNodeResult(runId, nodeId, value) → void
+ *   loadNodeResult(runId, nodeId)        → value | null
+ *   listNodeResults(runId)               → string[]
+ *   loadAllNodeResults(runId)            → { [nodeId]: value }
+ *   clearRun(runId)                      → void
+ */
+
+import path from 'path';
+import { promises as fs } from 'fs';
+
+// Filenames sanitize node IDs that contain slashes / colons / other
+// characters that aren't safe to drop into a path. We ALSO encode the
+// original id in the file content so loads round-trip exactly.
+function _safeName(s) {
+  return String(s).replace(/[^a-zA-Z0-9_.-]+/g, '_');
+}
+
+function _resolveRunDir(baseDir, runId) {
+  // Defense against ".." escapes — the resolved dir MUST stay under baseDir.
+  const safeId = _safeName(runId);
+  const dir = path.resolve(baseDir, safeId);
+  const baseResolved = path.resolve(baseDir);
+  if (!dir.startsWith(baseResolved + path.sep) && dir !== baseResolved) {
+    throw new Error(`runId resolves outside baseDir (refusing): ${runId}`);
+  }
+  // Also reject obviously-malicious raw inputs to give a clearer error.
+  if (typeof runId === 'string' && (runId.includes('..') || runId.startsWith('/') || runId.startsWith('\\'))) {
+    throw new Error(`runId must not contain "..", absolute path segments, or escape attempts: ${runId}`);
+  }
+  return dir;
+}
+
+async function _writeAtomic(filePath, json) {
+  const tmp = filePath + '.tmp-' + process.pid + '-' + Date.now();
+  await fs.writeFile(tmp, json, 'utf8');
+  await fs.rename(tmp, filePath);
+}
+
+export class FlowCheckpointStore {
+  constructor({ baseDir }) {
+    if (!baseDir || typeof baseDir !== 'string') {
+      throw new Error('FlowCheckpointStore requires a string baseDir');
+    }
+    this.baseDir = baseDir;
+  }
+
+  async saveRun(run) {
+    if (!run || typeof run.id !== 'string') {
+      throw new Error('saveRun requires run.id');
+    }
+    const dir = _resolveRunDir(this.baseDir, run.id);
+    await fs.mkdir(dir, { recursive: true });
+    await _writeAtomic(path.join(dir, 'run.json'), JSON.stringify(run, null, 2));
+  }
+
+  async loadRun(runId) {
+    const dir = _resolveRunDir(this.baseDir, runId);
+    try {
+      const raw = await fs.readFile(path.join(dir, 'run.json'), 'utf8');
+      return JSON.parse(raw);
+    } catch (e) {
+      if (e?.code === 'ENOENT') return null;
+      throw e;
+    }
+  }
+
+  /**
+   * Per-node result file. We store the original nodeId inside the JSON
+   * so listNodeResults can return the original ids regardless of how
+   * the filename was sanitized.
+   */
+  async saveNodeResult(runId, nodeId, value) {
+    const dir = _resolveRunDir(this.baseDir, runId);
+    await fs.mkdir(dir, { recursive: true });
+    const safe = _safeName(nodeId);
+    const fname = `node-${safe}.json`;
+    const payload = { nodeId, value };
+    await _writeAtomic(path.join(dir, fname), JSON.stringify(payload, null, 2));
+  }
+
+  async loadNodeResult(runId, nodeId) {
+    const dir = _resolveRunDir(this.baseDir, runId);
+    const safe = _safeName(nodeId);
+    try {
+      const raw = await fs.readFile(path.join(dir, `node-${safe}.json`), 'utf8');
+      const obj = JSON.parse(raw);
+      return obj && 'value' in obj ? obj.value : null;
+    } catch (e) {
+      if (e?.code === 'ENOENT') return null;
+      throw e;
+    }
+  }
+
+  async listNodeResults(runId) {
+    const dir = _resolveRunDir(this.baseDir, runId);
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch (e) {
+      if (e?.code === 'ENOENT') return [];
+      throw e;
+    }
+    const ids = [];
+    for (const name of entries) {
+      if (!name.startsWith('node-') || !name.endsWith('.json')) continue;
+      try {
+        const raw = await fs.readFile(path.join(dir, name), 'utf8');
+        const obj = JSON.parse(raw);
+        if (obj?.nodeId) ids.push(obj.nodeId);
+      } catch { /* skip unreadable entries */ }
+    }
+    return ids;
+  }
+
+  async loadAllNodeResults(runId) {
+    const ids = await this.listNodeResults(runId);
+    const out = {};
+    for (const id of ids) {
+      const v = await this.loadNodeResult(runId, id);
+      if (v !== null) out[id] = v;
+    }
+    return out;
+  }
+
+  async clearRun(runId) {
+    const dir = _resolveRunDir(this.baseDir, runId);
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+export default FlowCheckpointStore;