onbuzz 4.5.0 → 4.6.0

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

@@ -0,0 +1,147 @@
+/**
+ * flowTypes — type registry + compat matrix that backs Flows v2 typed I/O.
+ *
+ * Why these tests exist: edges in v2 connect a *typed output* to a *typed
+ * input*. The compatibility matrix decides which connections are allowed.
+ * Get this wrong and either:
+ *   - too lax: agents receive payloads they can't parse (silent break)
+ *   - too strict: trivial-looking flows refuse to connect (UX paper-cut)
+ *
+ * The matrix below is the contract. Every cell is justified by a test.
+ *
+ * Allowed implicit conversions (no cast node needed):
+ *   - exact match               always
+ *   - any scalar  → text        (auto-stringify; text is the universal sink)
+ *   - any         → json        (everything wraps as a JSON value)
+ *   - file        → file[]      (singleton-as-list; common ergonomic case)
+ *   - text        → list<text>  (single-line as 1-element list)
+ *
+ * Disallowed (must use an explicit cast/transform node):
+ *   - text/number/json → file or file[]   (text is not a path)
+ *   - file → text                          (don't auto-read file contents)
+ *   - number ← text (parse direction)     (lossy; force user to declare)
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  TYPES,
+  isKnownType,
+  isCompatible,
+  describeCompat,
+} from '../flowTypes.js';
+
+describe('TYPES registry', () => {
+  test('exposes the v2 minimum types', () => {
+    expect(TYPES).toEqual(expect.arrayContaining([
+      'text', 'number', 'boolean', 'json', 'file', 'file[]', 'list<text>',
+    ]));
+  });
+
+  test('isKnownType true for declared types', () => {
+    for (const t of TYPES) expect(isKnownType(t)).toBe(true);
+  });
+
+  test('isKnownType false for unknown types', () => {
+    for (const bad of ['', null, undefined, 'string', 'int', 'list', 'list<json>', 'TEXT']) {
+      expect(isKnownType(bad)).toBe(false);
+    }
+  });
+});
+
+describe('isCompatible — exact match', () => {
+  test('every type is compatible with itself', () => {
+    for (const t of TYPES) expect(isCompatible(t, t)).toBe(true);
+  });
+});
+
+describe('isCompatible — text as universal sink', () => {
+  test.each([
+    ['number', 'text'],
+    ['boolean', 'text'],
+    ['json', 'text'],   // JSON.stringify is well-defined
+  ])('%s → text is allowed (auto-stringify)', (from, to) => {
+    expect(isCompatible(from, to)).toBe(true);
+  });
+
+  test('file → text is NOT allowed (would auto-read; surprising)', () => {
+    expect(isCompatible('file', 'text')).toBe(false);
+  });
+
+  test('file[] → text is NOT allowed', () => {
+    expect(isCompatible('file[]', 'text')).toBe(false);
+  });
+});
+
+describe('isCompatible — json as universal sink', () => {
+  test.each(['text', 'number', 'boolean', 'list<text>'])(
+    '%s → json is allowed (wraps as JSON value)',
+    (from) => { expect(isCompatible(from, 'json')).toBe(true); }
+  );
+
+  test('file → json is NOT allowed (don\'t auto-read)', () => {
+    expect(isCompatible('file', 'json')).toBe(false);
+  });
+});
+
+describe('isCompatible — file singleton-as-list', () => {
+  test('file → file[] is allowed (singleton-as-list)', () => {
+    expect(isCompatible('file', 'file[]')).toBe(true);
+  });
+
+  test('file[] → file is NOT allowed (lossy: which one?)', () => {
+    expect(isCompatible('file[]', 'file')).toBe(false);
+  });
+});
+
+describe('isCompatible — text → list<text>', () => {
+  test('text → list<text> is allowed (1-element list)', () => {
+    expect(isCompatible('text', 'list<text>')).toBe(true);
+  });
+
+  test('list<text> → text is NOT allowed (lossy: how to join?)', () => {
+    expect(isCompatible('list<text>', 'text')).toBe(false);
+  });
+});
+
+describe('isCompatible — disallowed pairs (require cast node)', () => {
+  test.each([
+    ['text', 'number'],     // parse — declare it
+    ['text', 'boolean'],    // parse — declare it
+    ['text', 'file'],       // text is not a path
+    ['text', 'file[]'],
+    ['json', 'file'],
+    ['number', 'file'],
+    ['boolean', 'number'],  // would silently coerce
+  ])('%s → %s is rejected', (from, to) => {
+    expect(isCompatible(from, to)).toBe(false);
+  });
+});
+
+describe('isCompatible — defensive', () => {
+  test('unknown source type returns false', () => {
+    expect(isCompatible('blob', 'text')).toBe(false);
+  });
+  test('unknown target type returns false', () => {
+    expect(isCompatible('text', 'blob')).toBe(false);
+  });
+  test('null/undefined return false', () => {
+    expect(isCompatible(null, 'text')).toBe(false);
+    expect(isCompatible('text', null)).toBe(false);
+    expect(isCompatible(undefined, undefined)).toBe(false);
+  });
+});
+
+describe('describeCompat — diagnostic messages', () => {
+  test('returns a usable explanation for incompatible pairs', () => {
+    const msg = describeCompat('file', 'text');
+    expect(typeof msg).toBe('string');
+    expect(msg.length).toBeGreaterThan(0);
+    expect(msg.toLowerCase()).toContain('file');
+    expect(msg.toLowerCase()).toContain('text');
+  });
+
+  test('returns null/empty for compatible pairs', () => {
+    const msg = describeCompat('text', 'text');
+    expect(msg === null || msg === '' || msg === undefined).toBe(true);
+  });
+});

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

@@ -0,0 +1,123 @@
+/**
+ * FlowVersionStore — append-only history of flow definitions.
+ *
+ * Layout:
+ *   <baseDir>/<flowId>/v-<n>.json   (n is monotonically increasing)
+ *
+ * On every PUT to a flow, the webServer also writes a new version
+ * snapshot. Versions are immutable once written. listVersions returns
+ * { version, savedAt } metadata sorted ascending. loadVersion reads
+ * the full snapshot. rollback reads version N and lets the caller
+ * persist it as the live record (the store itself is read/write of
+ * the version archive — the actual "live record swap" stays in the
+ * webServer route so we don't tangle responsibilities).
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import path from 'path';
+import os from 'os';
+import { promises as fs } from 'fs';
+import { FlowVersionStore } from '../flowVersionStore.js';
+
+let tmpRoot;
+beforeEach(async () => {
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'flow-version-test-'));
+});
+afterEach(async () => {
+  try { await fs.rm(tmpRoot, { recursive: true, force: true }); } catch {}
+});
+
+const newStore = () => new FlowVersionStore({ baseDir: tmpRoot });
+
+describe('FlowVersionStore — recordVersion', () => {
+  test('first version is 1', async () => {
+    const store = newStore();
+    const v = await store.recordVersion('f1', { id: 'f1', name: 'A', nodes: [], edges: [] });
+    expect(v.version).toBe(1);
+    expect(typeof v.savedAt).toBe('string');
+  });
+
+  test('subsequent versions increment monotonically', async () => {
+    const store = newStore();
+    const v1 = await store.recordVersion('f1', { id: 'f1', name: 'A', nodes: [], edges: [] });
+    const v2 = await store.recordVersion('f1', { id: 'f1', name: 'A2', nodes: [], edges: [] });
+    const v3 = await store.recordVersion('f1', { id: 'f1', name: 'A3', nodes: [], edges: [] });
+    expect([v1.version, v2.version, v3.version]).toEqual([1, 2, 3]);
+  });
+
+  test('versions for different flow IDs are independent', async () => {
+    const store = newStore();
+    const a1 = await store.recordVersion('a', { name: 'a' });
+    const b1 = await store.recordVersion('b', { name: 'b' });
+    const a2 = await store.recordVersion('a', { name: 'a2' });
+    expect(a1.version).toBe(1);
+    expect(b1.version).toBe(1);
+    expect(a2.version).toBe(2);
+  });
+
+  test('records include savedAt ISO timestamp', async () => {
+    const store = newStore();
+    const v = await store.recordVersion('f1', { name: 'A' });
+    expect(v.savedAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+  });
+});
+
+describe('FlowVersionStore — listVersions', () => {
+  test('returns [] for unknown flow', async () => {
+    const store = newStore();
+    expect(await store.listVersions('ghost')).toEqual([]);
+  });
+
+  test('returns metadata sorted ascending', async () => {
+    const store = newStore();
+    await store.recordVersion('f1', { name: 'v1' });
+    await store.recordVersion('f1', { name: 'v2' });
+    await store.recordVersion('f1', { name: 'v3' });
+    const list = await store.listVersions('f1');
+    expect(list.map(v => v.version)).toEqual([1, 2, 3]);
+    for (const v of list) {
+      expect(typeof v.savedAt).toBe('string');
+      expect(v.name).toBeDefined();
+    }
+  });
+});
+
+describe('FlowVersionStore — loadVersion', () => {
+  test('returns the exact snapshot persisted', async () => {
+    const store = newStore();
+    const flow = { id: 'f1', name: 'A', nodes: [{ id: 'n1' }], edges: [] };
+    await store.recordVersion('f1', flow);
+    const loaded = await store.loadVersion('f1', 1);
+    expect(loaded.flow).toEqual(flow);
+    expect(loaded.version).toBe(1);
+    expect(loaded.savedAt).toBeDefined();
+  });
+
+  test('returns null for unknown version', async () => {
+    const store = newStore();
+    expect(await store.loadVersion('f1', 99)).toBe(null);
+  });
+});
+
+describe('FlowVersionStore — defensive', () => {
+  test('refuses path-traversal in flowId', async () => {
+    const store = newStore();
+    await expect(store.recordVersion('../escape', { name: 'x' })).rejects.toThrow();
+  });
+
+  test('handles flow id with slashes/colons via sanitization', async () => {
+    const store = newStore();
+    const v = await store.recordVersion('flow:complex/id', { name: 'x' });
+    expect(v.version).toBe(1);
+    const list = await store.listVersions('flow:complex/id');
+    expect(list).toHaveLength(1);
+  });
+
+  test('does not mutate the input flow object', async () => {
+    const store = newStore();
+    const flow = { id: 'f', name: 'orig', nodes: [] };
+    const snap = JSON.parse(JSON.stringify(flow));
+    await store.recordVersion('f', flow);
+    expect(flow).toEqual(snap);
+  });
+});

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

@@ -80,6 +80,44 @@ describe('Orchestrator', () => {
     );
   });
 
+  // ───── Cross-component wiring (regression locks) ─────
+
+  describe('toolsRegistry exposure', () => {
+    // Background: webServer's FlowExecutor init reads `this.orchestrator?.toolsRegistry`
+    // (webServer.js:574) to find the JobDoneTool singleton and call
+    // setFlowExecutor on it. Without that wiring, JobDoneTool's
+    // Phase 8 contract validation silently no-ops because
+    // `this.flowExecutor` stays undefined, and partial job-done calls
+    // fall through to the legacy pendingTasks rejection path. The fix
+    // is `index.js` setting `this.orchestrator.toolsRegistry =
+    // this.toolsRegistry` after the orchestrator is constructed.
+    // This test locks that contract: orchestrator must accept and
+    // expose a toolsRegistry assignment so the webServer lookup works.
+
+    test('exposes toolsRegistry after external assignment', () => {
+      const fakeRegistry = {
+        getTool: jest.fn().mockReturnValue({
+          setFlowExecutor: jest.fn(),
+        }),
+      };
+      orchestrator.toolsRegistry = fakeRegistry;
+
+      // Simulate the webServer lookup at webServer.js:574
+      const found = orchestrator?.toolsRegistry?.getTool?.('jobdone');
+      expect(found).toBeDefined();
+      expect(typeof found.setFlowExecutor).toBe('function');
+      expect(orchestrator.toolsRegistry).toBe(fakeRegistry);
+    });
+
+    test('toolsRegistry lookup yields undefined when not wired (smoke)', () => {
+      // If a future refactor breaks the wiring, this lookup pattern
+      // returns undefined — which is exactly the failure mode that
+      // caused Phase 8 to silently no-op for an entire process lifetime.
+      // Keeping this assertion makes the failure mode visible.
+      expect(orchestrator.toolsRegistry).toBeUndefined();
+    });
+  });
+
   // ───── Request Routing ─────
 
   describe('processRequest routing', () => {

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

@@ -372,4 +372,285 @@ describe('StateManager', () => {
       expect(written.projectDir).toBe('/project');
     });
   });
+
+  // ─── 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) {