onbuzz 4.0.2 → 4.2.0

package/src/tools/__tests__/filesystemTool.test.js

@@ -81,6 +81,15 @@ jest.unstable_mockModule('../baseTool.js', () => ({
       this.lastUsed = null;
       this.usageCount = 0;
     }
+    // Mirror real BaseTool#getEffectiveConfig so the per-agent config gate
+    // in fileSystemTool.execute() works under test. Real helper lives in
+    // src/tools/baseTool.js — change in lockstep if you touch it.
+    getEffectiveConfig(context, fallbacks = {}) {
+      const perAgent = (context && context.toolConfig && typeof context.toolConfig === 'object' && !Array.isArray(context.toolConfig))
+        ? context.toolConfig
+        : {};
+      return { ...fallbacks, ...(this.config || {}), ...perAgent };
+    }
   }
 }));
 
@@ -714,4 +723,93 @@ describe('FileSystemTool', () => {
       expect(actions).toContain('stats');
     });
   });
+
+  // Per-agent overrides via context.toolConfig (agent.toolConfig.filesystem)
+  // — merged into effective config by BaseTool#getEffectiveConfig at
+  // execute time, then applied as a per-action gate above the existing
+  // path-access and size checks.
+  describe('per-agent toolConfig overrides', () => {
+    test('per-agent blockedExtensions blocks a previously-allowed extension', async () => {
+      const { tool, context } = createTestSetup();
+      const result = await tool.execute(
+        { actions: [{ type: 'read', filePath: '/tmp/test/secret.env' }] },
+        { ...context, toolConfig: { blockedExtensions: ['.env'] } }
+      );
+      expect(result.actions[0].success).toBe(false);
+      expect(result.actions[0].error).toMatch(/blocked by agent policy/);
+      // No actual read attempted.
+      expect(fsMock.readFile).not.toHaveBeenCalled();
+    });
+
+    test('per-agent allowedExtensions rejects anything outside the list', async () => {
+      const { tool, context } = createTestSetup();
+      const result = await tool.execute(
+        { actions: [{ type: 'read', filePath: '/tmp/test/app.js' }] },
+        { ...context, toolConfig: { allowedExtensions: ['.ts'] } }
+      );
+      expect(result.actions[0].success).toBe(false);
+      expect(result.actions[0].error).toMatch(/not in the agent's allowed list/);
+      expect(fsMock.readFile).not.toHaveBeenCalled();
+    });
+
+    test('per-agent allowedExtensions accepts matches', async () => {
+      const { tool, context } = createTestSetup();
+      const result = await tool.execute(
+        { actions: [{ type: 'read', filePath: '/tmp/test/app.js' }] },
+        { ...context, toolConfig: { allowedExtensions: ['.js'] } }
+      );
+      expect(result.actions[0].success).toBe(true);
+    });
+
+    test('per-agent maxFileSize rejects oversized write payload', async () => {
+      const { tool, context } = createTestSetup();
+      const bigContent = 'x'.repeat(500);
+      const result = await tool.execute(
+        {
+          actions: [{ type: 'write', outputPath: 'big.txt', content: bigContent }],
+        },
+        { ...context, toolConfig: { maxFileSize: 100 } }
+      );
+      expect(result.actions[0].success).toBe(false);
+      expect(result.actions[0].error).toMatch(/too large/);
+      expect(result.actions[0].error).toMatch(/per-agent maxFileSize/);
+      expect(fsMock.writeFile).not.toHaveBeenCalled();
+    });
+
+    test('per-agent maxFileSize accepts payloads within limit', async () => {
+      const { tool, context } = createTestSetup();
+      const content = 'hello';
+      // Mirror the mock setup used by the existing write tests so the
+      // verify-after-write step finds the file with matching size.
+      fsMock.access.mockRejectedValueOnce(new Error('ENOENT'));
+      fsMock.stat.mockResolvedValue(mockStatResult({ size: Buffer.byteLength(content) }));
+      fsMock.readFile.mockResolvedValue(content);
+
+      const result = await tool.execute(
+        { actions: [{ type: 'write', outputPath: 'ok.txt', content }] },
+        { ...context, toolConfig: { maxFileSize: 1_000_000 } }
+      );
+      expect(result.actions[0].success).toBe(true);
+      expect(fsMock.writeFile).toHaveBeenCalled();
+    });
+
+    test('blocked wins over allowed when both set', async () => {
+      const { tool, context } = createTestSetup();
+      const result = await tool.execute(
+        { actions: [{ type: 'read', filePath: '/tmp/test/app.js' }] },
+        { ...context, toolConfig: { allowedExtensions: ['.js'], blockedExtensions: ['.js'] } }
+      );
+      expect(result.actions[0].success).toBe(false);
+      expect(result.actions[0].error).toMatch(/blocked by agent policy/);
+    });
+
+    test('no toolConfig → original behaviour preserved', async () => {
+      const { tool, context } = createTestSetup();
+      const result = await tool.execute(
+        { actions: [{ type: 'read', filePath: '/tmp/test/app.js' }] },
+        context
+      );
+      expect(result.actions[0].success).toBe(true);
+    });
+  });
 });

package/src/tools/__tests__/memoryTool.reminisce.test.js

@@ -0,0 +1,363 @@
+/**
+ * Integration tests for the memoryTool `reminisce` action.
+ *
+ * Exercises the full path: tool.execute({action: 'reminisce', ...}) →
+ * _executeReminisce → agentPool.getAgent → conversationQuery.<mode> →
+ * shaped result. The per-mode semantics are unit-tested exhaustively in
+ * services/__tests__/conversationQuery.test.js; these tests focus on the
+ * wiring: action validation, context requirements, agent fetching, and
+ * error paths.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+jest.unstable_mockModule('../../services/memoryService.js', () => ({
+  getMemoryService: jest.fn(() => ({
+    initialize: jest.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+const { default: MemoryTool } = await import('../memoryTool.js');
+
+function makeMessages(n) {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `msg_${String(i).padStart(4, '0')}`,
+    role: i % 2 === 0 ? 'user' : 'assistant',
+    content: `message ${i}${i === 5 ? ' contains special keyword' : ''}`,
+    createdAt: new Date(Date.UTC(2026, 0, 1, 0, 0, i)).toISOString(),
+    tokenUsage: { totalTokens: 10 },
+    toolExecutions: i === 7 ? [{ toolId: 'terminal', input: 'ls -la' }] : [],
+  }));
+}
+
+function makeSetup({ messages = null, agentExists = true } = {}) {
+  const tool = new MemoryTool({}, createMockLogger());
+  const agent = agentExists ? {
+    id: 'agent-1',
+    conversations: messages ? { full: { messages } } : { full: { messages: makeMessages(20) } },
+  } : null;
+  const agentPool = {
+    getAgent: jest.fn().mockResolvedValue(agent),
+  };
+  const context = { agentId: 'agent-1', agentPool };
+  return { tool, agent, agentPool, context };
+}
+
+describe('memoryTool reminisce — wiring', () => {
+  let tool, context, agentPool;
+  beforeEach(() => {
+    ({ tool, context, agentPool } = makeSetup());
+  });
+
+  test('overview mode returns archive stats + timeline', async () => {
+    const out = await tool.execute({ action: 'reminisce', mode: 'overview' }, context);
+    expect(out.success).toBe(true);
+    expect(out.mode).toBe('overview');
+    expect(out.result.totalMessages).toBe(20);
+    expect(out.result.timeline.length).toBeGreaterThan(0);
+    expect(out.result.timeline[0].messageId).toBe('msg_0000');
+  });
+
+  test('range mode paginates', async () => {
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'range', offset: 5, limit: 3 },
+      context
+    );
+    expect(out.success).toBe(true);
+    expect(out.result.messages.length).toBe(3);
+    expect(out.result.messages[0].messageId).toBe('msg_0005');
+  });
+
+  test('search finds matches in content', async () => {
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'search', query: 'special keyword' },
+      context
+    );
+    expect(out.success).toBe(true);
+    expect(out.result.matches.length).toBeGreaterThan(0);
+    expect(out.result.matches[0].messageId).toBe('msg_0005');
+  });
+
+  test('around resolves a bookmarked messageId', async () => {
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'around', messageId: 'msg_0010', before: 2, after: 2 },
+      context
+    );
+    expect(out.success).toBe(true);
+    expect(out.result.targetFound).toBe(true);
+    expect(out.result.messages.map(m => m.messageId)).toContain('msg_0010');
+  });
+
+  test('byTool lists tool calls', async () => {
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'byTool' },
+      context
+    );
+    expect(out.success).toBe(true);
+    expect(out.result.toolCalls.length).toBe(1);
+    expect(out.result.toolCalls[0].toolId).toBe('terminal');
+    expect(out.result.toolCalls[0].messageId).toBe('msg_0007');
+  });
+
+  test('read returns the whole message when no window is specified', async () => {
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'read', messageId: 'msg_0005' },
+      context
+    );
+    expect(out.success).toBe(true);
+    expect(out.result.targetFound).toBe(true);
+    expect(out.result.message.messageId).toBe('msg_0005');
+    expect(out.result.message.contentWindow.kind).toBe('full');
+    expect(out.result.message.content).toContain('special keyword');
+  });
+
+  test('read with lineFrom/lineTo returns a line slice', async () => {
+    // Replace msg_0005 with a multi-line message so the slice is meaningful.
+    const bigContent = Array.from({ length: 50 }, (_, i) => `line ${i + 1}`).join('\n');
+    const localMessages = makeMessages(20);
+    localMessages[5] = { ...localMessages[5], content: bigContent };
+    const local = makeSetup({ messages: localMessages });
+
+    const out = await local.tool.execute(
+      { action: 'reminisce', mode: 'read', messageId: 'msg_0005',
+        lineFrom: 10, lineTo: 14 },
+      local.context
+    );
+    expect(out.result.message.contentWindow.kind).toBe('lines');
+    expect(out.result.message.contentWindow.totalLines).toBe(50);
+    const lines = out.result.message.content.split('\n');
+    expect(lines).toEqual(['line 10', 'line 11', 'line 12', 'line 13', 'line 14']);
+  });
+
+  test('read with contentFrom/contentTo returns a char slice', async () => {
+    const localMessages = makeMessages(20);
+    localMessages[5] = { ...localMessages[5], content: 'abcdefghijklmnopqrstuvwxyz' };
+    const local = makeSetup({ messages: localMessages });
+
+    const out = await local.tool.execute(
+      { action: 'reminisce', mode: 'read', messageId: 'msg_0005',
+        contentFrom: 5, contentTo: 10 },
+      local.context
+    );
+    expect(out.result.message.contentWindow.kind).toBe('chars');
+    expect(out.result.message.content).toBe('fghij');
+  });
+
+  test('read with unknown messageId returns targetFound=false (not a crash)', async () => {
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'read', messageId: 'msg_hallucinated' },
+      context
+    );
+    expect(out.success).toBe(true);
+    expect(out.result.targetFound).toBe(false);
+    expect(out.result.message).toBeNull();
+  });
+
+  test('read surfaces hasReasoning + reasoningTokens but omits text by default', async () => {
+    const localMessages = makeMessages(20);
+    localMessages[5] = {
+      ...localMessages[5],
+      reasoning: 'Chain of thought: first I need to analyze...',
+      reasoningTokens: 512,
+    };
+    const local = makeSetup({ messages: localMessages });
+    const out = await local.tool.execute(
+      { action: 'reminisce', mode: 'read', messageId: 'msg_0005' },
+      local.context
+    );
+    expect(out.result.message.hasReasoning).toBe(true);
+    expect(out.result.message.reasoningTokens).toBe(512);
+    expect(out.result.message.reasoning).toBeUndefined();
+  });
+
+  test('read with includeReasoning=true returns the reasoning text', async () => {
+    const localMessages = makeMessages(20);
+    const thought = 'Step 1: analyze. Step 2: decide. Step 3: act.';
+    localMessages[5] = {
+      ...localMessages[5],
+      reasoning: thought,
+      reasoningTokens: 200,
+    };
+    const local = makeSetup({ messages: localMessages });
+    const out = await local.tool.execute(
+      { action: 'reminisce', mode: 'read', messageId: 'msg_0005', includeReasoning: true },
+      local.context
+    );
+    expect(out.result.message.reasoning).toBe(thought);
+  });
+});
+
+describe('memoryTool reminisce — error paths', () => {
+  test('invalid mode returns a clean error', async () => {
+    const { tool, context } = makeSetup();
+    const out = await tool.execute({ action: 'reminisce', mode: 'bogus' }, context);
+    expect(out.success).toBe(false);
+    expect(out.error).toMatch(/mode must be one of/);
+  });
+
+  test('missing mode returns a clean error (not a crash)', async () => {
+    const { tool, context } = makeSetup();
+    const out = await tool.execute({ action: 'reminisce' }, context);
+    expect(out.success).toBe(false);
+    expect(out.error).toMatch(/mode must be one of/);
+  });
+
+  test('missing agentPool in context returns a clean error', async () => {
+    const { tool } = makeSetup();
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'overview' },
+      { agentId: 'agent-1' /* no agentPool */ }
+    );
+    expect(out.success).toBe(false);
+    expect(out.error).toMatch(/agentPool/);
+  });
+
+  test('agent not found returns a clean error', async () => {
+    const { tool, context } = makeSetup({ agentExists: false });
+    const out = await tool.execute({ action: 'reminisce', mode: 'overview' }, context);
+    expect(out.success).toBe(false);
+    expect(out.error).toMatch(/not found/);
+  });
+
+  test('agent with no conversation archive returns success with empty flag', async () => {
+    const tool = new MemoryTool({}, createMockLogger());
+    const agentPool = {
+      getAgent: jest.fn().mockResolvedValue({ id: 'a', conversations: {} }),
+    };
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'overview' },
+      { agentId: 'a', agentPool }
+    );
+    expect(out.success).toBe(true);
+    expect(out.result.empty).toBe(true);
+  });
+});
+
+describe('memoryTool reminisce — archive durability through compaction', () => {
+  /*
+   * Contract test: even after compaction writes to conversations[model],
+   * reminisce must still serve the pre-compaction messages from
+   * conversations.full. This simulates the durability invariant that the
+   * whole feature rests on.
+   */
+  test('reads conversations.full even when per-model compacted views exist', async () => {
+    const fullMessages = makeMessages(10);
+    const compactedMessages = [
+      { id: 'compacted_1', role: 'system', content: '[summary of 10 messages]',
+        createdAt: new Date().toISOString(), tokenUsage: { totalTokens: 200 } },
+    ];
+    const agent = {
+      id: 'a',
+      conversations: {
+        full: { messages: fullMessages },
+        'gpt-5': { messages: compactedMessages },       // compacted view
+        'claude-opus': { messages: compactedMessages }, // another compacted view
+      },
+    };
+    const tool = new MemoryTool({}, createMockLogger());
+    const context = { agentId: 'a', agentPool: { getAgent: () => Promise.resolve(agent) } };
+
+    const out = await tool.execute({ action: 'reminisce', mode: 'overview' }, context);
+    expect(out.success).toBe(true);
+    // totalMessages reflects the FULL archive, not the compacted view.
+    expect(out.result.totalMessages).toBe(10);
+    // A messageId from the original archive must still resolve via around.
+    const aroundOut = await tool.execute(
+      { action: 'reminisce', mode: 'around', messageId: 'msg_0005', before: 1, after: 1 },
+      context
+    );
+    expect(aroundOut.result.targetFound).toBe(true);
+    expect(aroundOut.result.messages.some(m => m.messageId === 'msg_0005')).toBe(true);
+  });
+
+  test('bookmark stability across simulated conversation growth', async () => {
+    // An agent bookmarks msg_0005 in turn 1. Conversation grows to 200
+    // messages over many turns. reminisce still resolves the bookmark.
+    const messages = makeMessages(20);
+    const bookmark = 'msg_0005';
+    const agent = { id: 'a', conversations: { full: { messages } } };
+    const tool = new MemoryTool({}, createMockLogger());
+    const context = { agentId: 'a', agentPool: { getAgent: () => Promise.resolve(agent) } };
+
+    // Simulate archive growth: append 180 more messages.
+    for (let i = 20; i < 200; i++) {
+      messages.push({
+        id: `msg_${String(i).padStart(4, '0')}`,
+        role: 'assistant',
+        content: `later message ${i}`,
+        createdAt: new Date(Date.UTC(2026, 0, 2, 0, 0, i)).toISOString(),
+        tokenUsage: { totalTokens: 10 },
+        toolExecutions: [],
+      });
+    }
+
+    const out = await tool.execute(
+      { action: 'reminisce', mode: 'around', messageId: bookmark, before: 2, after: 2 },
+      context
+    );
+    expect(out.result.targetFound).toBe(true);
+    expect(out.result.center).toBe(bookmark);
+  });
+});
+
+describe('memoryTool — reminisce registered as a valid action', () => {
+  test('getSupportedActions includes reminisce', () => {
+    const tool = new MemoryTool({}, createMockLogger());
+    expect(tool.getSupportedActions()).toContain('reminisce');
+  });
+
+  test('customValidateParameters accepts action=reminisce without error', () => {
+    const tool = new MemoryTool({}, createMockLogger());
+    const result = tool.customValidateParameters({ action: 'reminisce' });
+    expect(result.valid).toBe(true);
+  });
+
+  test('getParameterSchema enum includes reminisce', () => {
+    const tool = new MemoryTool({}, createMockLogger());
+    const schema = tool.getParameterSchema();
+    expect(schema.properties.action.enum).toContain('reminisce');
+  });
+
+  test('getParameterSchema advertises every reminisce-specific parameter', () => {
+    // Without this, the model invoking memory via OpenAI function calling
+    // can't know what fields are legal for action=reminisce and will either
+    // omit them or hallucinate wrong names. Locked tight.
+    const schema = new MemoryTool({}, createMockLogger()).getParameterSchema();
+    const props = schema.properties;
+    const required = [
+      'mode', 'messageId',
+      'from', 'to', 'offset', 'limit', 'maxResults', 'role', 'cursor', 'toolId',
+      'before', 'after',
+      'lineFrom', 'lineTo', 'contentFrom', 'contentTo',
+      'detail',
+    ];
+    for (const field of required) {
+      expect(props[field]).toBeDefined();
+      expect(typeof props[field].description).toBe('string');
+    }
+    // mode enum must carry all six sub-modes
+    expect(props.mode.enum).toEqual(
+      expect.arrayContaining(['overview', 'range', 'search', 'around', 'byTool', 'read'])
+    );
+  });
+
+  test('getDescription teaches the agent about reminisce + pointer stability', () => {
+    const desc = new MemoryTool({}, createMockLogger()).getDescription();
+    expect(desc).toMatch(/REMINISCE/i);
+    expect(desc).toMatch(/messageId/);
+    // All six sub-modes should be present by name.
+    expect(desc).toMatch(/overview/);
+    expect(desc).toMatch(/search/);
+    expect(desc).toMatch(/around/);
+    expect(desc).toMatch(/byTool/);
+    expect(desc).toMatch(/\bread\b/);
+    // Documents that search scope excludes tool results.
+    expect(desc).toMatch(/does NOT match tool results|tool-call arguments/i);
+    // Around explicitly documents its unit = messages.
+    expect(desc).toMatch(/count MESSAGES/);
+    // Read documents sub-message granularity — lines AND chars.
+    expect(desc).toMatch(/lineFrom/);
+    expect(desc).toMatch(/contentFrom/);
+  });
+});

package/src/tools/__tests__/memoryTool.test.js

@@ -56,9 +56,9 @@ describe('MemoryTool', () => {
     expect(desc).toContain('stats');
   });
 
-  test('getSupportedActions returns all 7 actions', () => {
+  test('getSupportedActions returns all 8 actions', () => {
     expect(tool.getSupportedActions()).toEqual(
-      ['add', 'update', 'delete', 'list', 'read', 'search', 'stats']
+      ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce']
     );
   });
 

package/src/tools/__tests__/openaiFunctionSchemas.memoryReminisce.test.js

@@ -0,0 +1,84 @@
+/**
+ * Contract test for the `memory` function's OpenAI schema — specifically
+ * that it advertises the `reminisce` action and its sub-mode params.
+ *
+ * Why this exists: the OpenAI function schema is what the model sees on
+ * the Chat Completions path. If `reminisce` is missing from the enum or
+ * the reminisce-specific params are absent, the model can't invoke it
+ * correctly regardless of what memoryTool's own validators say. This
+ * tripwire catches that class of drift without booting the full CLI.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { OPENAI_FUNCTION_SCHEMAS } from '../openaiFunctionSchemas.js';
+
+const memory = OPENAI_FUNCTION_SCHEMAS.find(s => s.name === 'memory');
+
+describe('OPENAI_FUNCTION_SCHEMAS — memory function', () => {
+  test('memory function schema exists', () => {
+    expect(memory).toBeDefined();
+    expect(memory.type).toBe('function');
+    expect(memory.parameters?.type).toBe('object');
+  });
+
+  test('action enum includes reminisce', () => {
+    const actions = memory.parameters.properties.action.enum;
+    expect(actions).toContain('reminisce');
+  });
+
+  test('action enum covers every sanctioned action (incl. stats)', () => {
+    const actions = memory.parameters.properties.action.enum;
+    for (const a of ['add', 'update', 'delete', 'read', 'list', 'search', 'stats', 'reminisce']) {
+      expect(actions).toContain(a);
+    }
+  });
+
+  test('mode field is present and enumerates the six sub-modes', () => {
+    const mode = memory.parameters.properties.mode;
+    expect(mode).toBeDefined();
+    expect(mode.enum).toEqual(
+      expect.arrayContaining(['overview', 'range', 'search', 'around', 'byTool', 'read'])
+    );
+  });
+
+  test('every reminisce-specific parameter is documented in the schema', () => {
+    // The model can only pass what the schema advertises. If one of these
+    // is missing, the feature silently loses that capability on the Chat
+    // Completions path.
+    const required = [
+      'mode',
+      'messageId',
+      'from', 'to',
+      'offset', 'limit', 'maxResults',
+      'role', 'cursor', 'toolId',
+      'before', 'after',
+      'lineFrom', 'lineTo', 'contentFrom', 'contentTo',
+      'detail',
+    ];
+    for (const field of required) {
+      const prop = memory.parameters.properties[field];
+      expect(prop).toBeDefined();
+      expect(typeof prop.description).toBe('string');
+      expect(prop.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  test('around before/after descriptions say MESSAGES (not chars/lines)', () => {
+    const before = memory.parameters.properties.before.description;
+    const after = memory.parameters.properties.after.description;
+    expect(before).toMatch(/MESSAGES/);
+    expect(after).toMatch(/MESSAGES/);
+  });
+
+  test('read line/char params describe their index convention and cap', () => {
+    const p = memory.parameters.properties;
+    expect(p.lineFrom.description).toMatch(/1-indexed/);
+    expect(p.lineTo.description).toMatch(/500 lines/);
+    expect(p.contentFrom.description).toMatch(/0-indexed/);
+    expect(p.contentTo.description).toMatch(/16000 chars|16 000 chars/);
+  });
+
+  test('top-level description mentions reminisce so the model knows the tool does both', () => {
+    expect(memory.description.toLowerCase()).toMatch(/reminisce|archive/);
+  });
+});

package/src/tools/__tests__/taskManagerTool.lifecycleGuidance.test.js

@@ -0,0 +1,71 @@
+/**
+ * Contract test for the TaskManager tool's lifecycle guidance surface.
+ *
+ * The agent follows the workflow described in the tool's `getDescription()`
+ * output verbatim (it's part of the system prompt at every turn). If that
+ * text accidentally regresses — a "simplification" PR that flattens the
+ * four phases back into the old "list → work → complete" stub — the
+ * agent immediately reverts to creating tasks one-at-a-time at the start,
+ * burning tool calls and cluttering the transcript.
+ *
+ * These tests lock the lifecycle keywords into place. They're a tripwire,
+ * not a style guide: the exact wording can evolve, but all four phases
+ * must remain named, `sync` must be positioned as the first-call tool,
+ * and the `in_progress` → `completed` per-step pattern must be present.
+ *
+ * If someone legitimately reworks the description (different phase names,
+ * different order, etc.), they update this test AND confirm the agent
+ * instruction in agentScheduler.js is in lockstep.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import TaskManagerTool from '../taskManagerTool.js';
+
+describe('TaskManagerTool.getDescription — lifecycle guidance contract', () => {
+  const desc = new TaskManagerTool({}).getDescription();
+  // Case-insensitive match for resilience against rephrasing.
+  const has = (needle) => expect(desc).toMatch(new RegExp(needle, 'i'));
+
+  test('names the four lifecycle phases', () => {
+    has('Phase 1 — Plan');
+    has('Phase 2 — Execute');
+    has('Phase 3 — Refine');
+    has('Phase 4 — Finish');
+  });
+
+  test('Phase 1 tells the agent to sync the whole plan in ONE call', () => {
+    // Plan phase must mention sync + "one call" concept + discourage per-task create at start.
+    has('sync');
+    has('ONE call');
+    // The exact wording that discourages per-task create is free to evolve;
+    // what matters is that "one-by-one" (or equivalent) and the word create
+    // both appear in the Plan phase area.
+    has('one-by-one|one at a time');
+  });
+
+  test('Phase 2 describes the in_progress → work → completed per-step pattern', () => {
+    has('in_progress');
+    has('completed');
+    has('one at a time|one task at a time|per step');
+  });
+
+  test('Phase 3 covers mid-flight refinement (both single-task create and resync)', () => {
+    has('create');
+    has('sync');
+    // warns against per-turn sync spam
+    has("Don't `sync` every turn");
+  });
+
+  test('Phase 4 points at jobdone when everything is completed', () => {
+    has('jobdone');
+  });
+
+  test('preserves the loop-forever warning (operational guard)', () => {
+    has('MANDATORY');
+    has('loop forever');
+  });
+
+  test('preserves memory-integration guidance (unrelated feature must survive)', () => {
+    has('memory:');
+  });
+});