onbuzz 4.8.3 → 4.9.1

package/src/tools/__tests__/skillsTool.search.test.js

@@ -0,0 +1,164 @@
+/**
+ * skillsTool tests for search + backfill-search-index.
+ *
+ * Pins the wiring contracts only — SkillsIndexer's internals are
+ * covered by its own suite. We test:
+ *   - search dispatches to indexer when enabled
+ *   - search falls back to substring over service.listSkills() when disabled
+ *   - missing query → clean error
+ *   - backfill walks listSkills + readSkill for each + calls indexer.backfill
+ *   - backfill is resilient when readSkill fails for one (uses metadata only)
+ *
+ * Mocks: SKILLS_ACTIONS enum (already extended), SkillsIndexer, and the
+ * underlying skills service the tool consumes.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+const mockIndexerInstance = {
+  isEnabled: true,
+  indexOne:  jest.fn().mockResolvedValue({ indexed: true }),
+  deleteOne: jest.fn().mockResolvedValue({ deleted: true }),
+  backfill:  jest.fn().mockResolvedValue({ ok: true, indexed: 2, skipped: 0, failed: 0 }),
+  search:    jest.fn().mockResolvedValue({ enabled: true, hits: [] }),
+  stats:     jest.fn().mockResolvedValue({ count: 2, enabled: true }),
+};
+const MockSkillsIndexer = jest.fn(() => mockIndexerInstance);
+jest.unstable_mockModule('../../services/embeddings/indexers/skillsIndexer.js', () => ({
+  SkillsIndexer: MockSkillsIndexer,
+  skillToText: () => '',
+}));
+
+// Mock the skills service. Needs `.initialize()` because the tool calls
+// it via `_ensureSkillsService()` before dispatching.
+const mockSkillsService = {
+  initialize:   jest.fn().mockResolvedValue(undefined),
+  listSkills:   jest.fn(),
+  readSkill:    jest.fn(),
+  describeSkill: jest.fn(),
+};
+jest.unstable_mockModule('../../services/skillsService.js', () => ({
+  getSkillsService: () => mockSkillsService,
+}));
+
+const { default: SkillsTool } = await import('../skillsTool.js');
+
+function makeTool({ embeddingsEnabled = true } = {}) {
+  const tool = new SkillsTool();
+  mockIndexerInstance.isEnabled = embeddingsEnabled;
+  mockIndexerInstance.search.mockClear();
+  mockIndexerInstance.backfill.mockClear();
+  MockSkillsIndexer.mockClear();
+  mockSkillsService.listSkills.mockClear();
+  mockSkillsService.readSkill.mockClear();
+  tool.aiService = { getEmbeddingService: () => ({ isEnabled: embeddingsEnabled }) };
+  tool._skillsIndexer = null;
+  return tool;
+}
+
+const skillList = [
+  { name: 'git-rebase-recovery',    description: 'Recover from a broken rebase' },
+  { name: 'docker-build-debug',     description: 'Debug docker build failures' },
+  { name: 'react-hook-deps',        description: 'Fix exhaustive-deps warnings' },
+];
+
+describe('skillsTool — search wiring', () => {
+  test('missing query → clean error', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'search' });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/query/i);
+  });
+
+  test('disabled embeddings → substring fallback over service.listSkills', async () => {
+    const tool = makeTool({ embeddingsEnabled: false });
+    mockSkillsService.listSkills.mockResolvedValue(skillList);
+    const r = await tool.execute({ action: 'search', query: 'rebase' });
+    expect(mockIndexerInstance.search).not.toHaveBeenCalled();
+    expect(r.result.mode).toBe('substring-fallback');
+    expect(r.result.hits.some(s => s.name === 'git-rebase-recovery')).toBe(true);
+  });
+
+  test('enabled embeddings → forwards query + topK + hybrid to indexer', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.search.mockResolvedValue({ enabled: true, hits: [] });
+    await tool.execute({ action: 'search', query: 'rebase', topK: 3, hybrid: false });
+    expect(mockIndexerInstance.search).toHaveBeenCalledWith('rebase', { topK: 3, hybrid: false });
+  });
+
+  test('enabled embeddings → returns hits in result', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.search.mockResolvedValue({
+      enabled: true,
+      hits: [
+        { id: 'git-rebase-recovery', score: 0.9, metadata: { description: 'Recover...' } },
+      ],
+    });
+    const r = await tool.execute({ action: 'search', query: 'rebase' });
+    expect(r.success).toBe(true);
+    expect(r.result.mode).toBe('hybrid');
+    expect(r.result.hits[0].id).toBe('git-rebase-recovery');
+  });
+
+  test('indexer error surfaces in result', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.search.mockResolvedValue({ enabled: true, hits: [], error: 'rate-limited' });
+    const r = await tool.execute({ action: 'search', query: 'q' });
+    expect(r.success).toBe(false);
+    expect(r.result.error).toBe('rate-limited');
+  });
+});
+
+describe('skillsTool — backfill-search-index wiring', () => {
+  test('disabled → clean error', async () => {
+    const tool = makeTool({ embeddingsEnabled: false });
+    const r = await tool.execute({ action: 'backfill-search-index' });
+    expect(r.success).toBe(false);
+    expect(r.message).toMatch(/not enabled/i);
+    expect(mockIndexerInstance.backfill).not.toHaveBeenCalled();
+  });
+
+  test('walks listSkills + readSkill for each + calls indexer.backfill', async () => {
+    const tool = makeTool();
+    mockSkillsService.listSkills.mockResolvedValue(skillList);
+    mockSkillsService.readSkill
+      .mockResolvedValueOnce({ content: 'rebase step 1...' })
+      .mockResolvedValueOnce({ content: 'docker tip 1...' })
+      .mockResolvedValueOnce({ content: 'react fix 1...' });
+
+    const r = await tool.execute({ action: 'backfill-search-index' });
+
+    expect(mockSkillsService.listSkills).toHaveBeenCalled();
+    expect(mockSkillsService.readSkill).toHaveBeenCalledTimes(3);
+    const passed = mockIndexerInstance.backfill.mock.calls[0][0];
+    expect(passed).toHaveLength(3);
+    expect(passed[0]).toMatchObject({ name: 'git-rebase-recovery', content: 'rebase step 1...' });
+    expect(r.success).toBe(true);
+    expect(r.result.indexed).toBe(2);   // from the stub return
+  });
+
+  test('readSkill failure on one skill falls back to metadata only', async () => {
+    const tool = makeTool();
+    mockSkillsService.listSkills.mockResolvedValue([skillList[0], skillList[1]]);
+    mockSkillsService.readSkill
+      .mockRejectedValueOnce(new Error('file gone'))
+      .mockResolvedValueOnce({ content: 'docker tip' });
+
+    await tool.execute({ action: 'backfill-search-index' });
+    const passed = mockIndexerInstance.backfill.mock.calls[0][0];
+    expect(passed).toHaveLength(2);
+    // First skill made it in without content (failed-read fallback).
+    expect(passed[0]).toMatchObject({ name: 'git-rebase-recovery' });
+    expect(passed[0].content).toBeUndefined();
+    // Second one has its content.
+    expect(passed[1].content).toBe('docker tip');
+  });
+
+  test('listSkills throw → clean error', async () => {
+    const tool = makeTool();
+    mockSkillsService.listSkills.mockRejectedValue(new Error('disk full'));
+    const r = await tool.execute({ action: 'backfill-search-index' });
+    expect(r.success).toBe(false);
+    expect(r.message).toMatch(/listSkills failed/);
+  });
+});

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

@@ -0,0 +1,137 @@
+/**
+ * Tests for the TASK DISCIPLINE signal — `currentFocus` returned on
+ * every taskmanager response — and the OPERATING POSTURE guideline
+ * that pairs with it.
+ *
+ * Production observation (scripts/memory-bench/live-v2-*,
+ * agent-agent-v2-v2-s2-multi-topic-1779570320941): Kimi-K2.6 and gpt-5.4
+ * lost task focus after cascading tool errors and silently reverted
+ * to a prior task instead of completing the current one. The fix is
+ * two-pronged:
+ *   1. Surface `currentFocus` on every taskmanager response so the
+ *      anchor stays visible across error cascades.
+ *   2. OPERATING POSTURE explicitly tells the agent: only one task
+ *      in_progress at a time, transition before working, finish or
+ *      release before switching.
+ */
+import { describe, test, expect } from '@jest/globals';
+import TaskManagerTool from '../taskManagerTool.js';
+import { BaseTool, ToolsRegistry } from '../baseTool.js';
+
+const SILENT_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+function makeTool() {
+  const tool = new TaskManagerTool({ description: 'test' });
+  tool.logger = SILENT_LOGGER;
+  return tool;
+}
+
+describe('_buildCurrentFocus — task-discipline signal', () => {
+  test('ok=true when exactly one task is in_progress', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'Polish README', description: 'Rewrite intro', status: 'in_progress' },
+      { id: 'task-2', title: 'Other thing',   description: '...',           status: 'pending' },
+    ]);
+    expect(focus.ok).toBe(true);
+    expect(focus.inProgressCount).toBe(1);
+    expect(focus.current).toMatchObject({
+      taskId: 'task-1', title: 'Polish README', description: 'Rewrite intro',
+    });
+    expect(focus.warning).toBeUndefined();
+  });
+
+  test('ok=false with warning when 0 tasks are in_progress', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'X', description: '...', status: 'pending' },
+      { id: 'task-2', title: 'Y', description: '...', status: 'completed' },
+    ]);
+    expect(focus.ok).toBe(false);
+    expect(focus.inProgressCount).toBe(0);
+    expect(focus.current).toBeNull();
+    expect(focus.warning).toMatch(/in_progress/);
+    expect(focus.warning).toMatch(/BEFORE/);
+  });
+
+  test('ok=false with warning when 2+ tasks are in_progress', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'A', description: '...', status: 'in_progress' },
+      { id: 'task-2', title: 'B', description: '...', status: 'in_progress' },
+      { id: 'task-3', title: 'C', description: '...', status: 'pending' },
+    ]);
+    expect(focus.ok).toBe(false);
+    expect(focus.inProgressCount).toBe(2);
+    expect(Array.isArray(focus.current)).toBe(true);
+    expect(focus.current).toHaveLength(2);
+    expect(focus.warning).toMatch(/Multiple tasks/);
+  });
+
+  test('empty task list reports 0 in_progress with warning', () => {
+    const focus = makeTool()._buildCurrentFocus([]);
+    expect(focus.ok).toBe(false);
+    expect(focus.inProgressCount).toBe(0);
+    expect(focus.current).toBeNull();
+  });
+
+  test('null/undefined input handled gracefully (no crash)', () => {
+    expect(() => makeTool()._buildCurrentFocus(null)).not.toThrow();
+    expect(() => makeTool()._buildCurrentFocus(undefined)).not.toThrow();
+    const f = makeTool()._buildCurrentFocus(null);
+    expect(f.inProgressCount).toBe(0);
+  });
+
+  test('long descriptions are truncated to 140 chars', () => {
+    const long = 'x'.repeat(500);
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'T', description: long, status: 'in_progress' },
+    ]);
+    expect(focus.current.description.length).toBeLessThanOrEqual(141);
+    expect(focus.current.description.endsWith('…')).toBe(true);
+  });
+
+  test('non-string description is coerced to empty (no crash)', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'T', description: null, status: 'in_progress' },
+    ]);
+    expect(focus.current.description).toBe('');
+  });
+});
+
+describe('OPERATING POSTURE — TASK DISCIPLINE section', () => {
+  // The OPERATING POSTURE block lives in baseTool.js and is built per
+  // agent based on its capabilities. We construct a BaseTool-derived
+  // tool registry stub and verify the block content directly.
+  function buildOperatingPosture(capabilities) {
+    // Use the real ToolsRegistry — it's the class that owns
+    // generateToolDescriptionsForPrompt. Register fake tools matching
+    // the capability list so the block emits its sections.
+    const reg = new ToolsRegistry(SILENT_LOGGER);
+    for (const id of capabilities) {
+      reg.tools.set(id, { id, getDescription: () => `# ${id}` });
+    }
+    return reg.generateToolDescriptionsForPrompt(capabilities);
+  }
+
+  test('section appears when taskmanager capability is present', () => {
+    const block = buildOperatingPosture(['memory', 'taskmanager']);
+    expect(block).toMatch(/TASK DISCIPLINE/);
+    expect(block).toMatch(/ONE.*task.*in_progress/);
+    expect(block).toMatch(/Transition first, then work/);
+    expect(block).toMatch(/Finish or release/);
+    expect(block).toMatch(/Anchor on tool failures/);
+    expect(block).toMatch(/currentFocus/);
+  });
+
+  test('section does NOT appear without taskmanager capability', () => {
+    const block = buildOperatingPosture(['memory']);
+    expect(block).not.toMatch(/TASK DISCIPLINE/);
+  });
+
+  test('section guidance is descriptive of cognitive effort, not bureaucratic checklist', () => {
+    // The aim is "task list reflects actual work", not "fill in fields".
+    const block = buildOperatingPosture(['memory', 'taskmanager']);
+    expect(block).toMatch(/cognitive effort/);
+    // Should describe what to do on tool failures — that's the main
+    // failure mode we observed.
+    expect(block).toMatch(/tool.*fail/i);
+  });
+});

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

@@ -0,0 +1,143 @@
+/**
+ * taskManagerTool tests for search + backfill-search-index.
+ *
+ * Pins the wiring contracts only — the TaskIndexer's internals have
+ * their own dedicated suite. We test:
+ *   - search dispatches to indexer when embeddings are enabled
+ *   - search falls back to substring-on-title/description when disabled
+ *   - status filter forwards correctly
+ *   - missing query → clean error
+ *   - hits hydrate back to live tasks from agent.taskList
+ *   - backfill walks agent.taskList.tasks + reports counts
+ *
+ * Mocks: stub TaskIndexer at the module boundary.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+const mockIndexerInstance = {
+  isEnabled: true,
+  indexOne:  jest.fn().mockResolvedValue({ indexed: true }),
+  deleteOne: jest.fn().mockResolvedValue({ deleted: true }),
+  backfill:  jest.fn().mockResolvedValue({ ok: true, indexed: 0, skipped: 0, failed: 0 }),
+  search:    jest.fn().mockResolvedValue({ enabled: true, hits: [] }),
+};
+const MockTaskIndexer = jest.fn(() => mockIndexerInstance);
+jest.unstable_mockModule('../../services/embeddings/indexers/taskIndexer.js', () => ({
+  TaskIndexer: MockTaskIndexer,
+  taskToText: () => '',
+}));
+
+const { default: TaskManagerTool } = await import('../taskManagerTool.js');
+
+function makeAgent(tasks = []) {
+  return {
+    id: 'agent-1',
+    taskList: { tasks },
+    status: 'active',
+  };
+}
+
+function makeTool({ embeddingsEnabled = true } = {}) {
+  const tool = new TaskManagerTool();
+  mockIndexerInstance.isEnabled = embeddingsEnabled;
+  mockIndexerInstance.search.mockClear();
+  mockIndexerInstance.backfill.mockClear();
+  MockTaskIndexer.mockClear();
+  tool.aiService = { getEmbeddingService: () => ({ isEnabled: embeddingsEnabled }) };
+  tool._taskIndexer = null;
+  return tool;
+}
+
+const tasks = [
+  { id: 't1', title: 'Refactor auth flow',       description: 'Move to OAuth 2.1',   status: 'pending',     priority: 'high'   },
+  { id: 't2', title: 'Investigate Telegram dedup', description: 'Why are we flooding?', status: 'in_progress', priority: 'high'   },
+  { id: 't3', title: 'Update README',             description: 'Add embeddings docs', status: 'completed',   priority: 'medium' },
+];
+
+describe('taskManagerTool — search wiring', () => {
+  test('missing query → clean error', async () => {
+    const tool = makeTool();
+    const r = await tool.searchTasks(makeAgent(tasks), {});
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/query/i);
+  });
+
+  test('disabled embeddings → substring fallback over title/description', async () => {
+    const tool = makeTool({ embeddingsEnabled: false });
+    const r = await tool.searchTasks(makeAgent(tasks), { query: 'telegram' });
+    expect(mockIndexerInstance.search).not.toHaveBeenCalled();
+    expect(r.mode).toBe('substring-fallback');
+    expect(r.results.some(t => t.id === 't2')).toBe(true);
+  });
+
+  test('disabled fallback respects status filter', async () => {
+    const tool = makeTool({ embeddingsEnabled: false });
+    const r = await tool.searchTasks(makeAgent(tasks), { query: 'auth', status: 'pending' });
+    expect(r.results.every(t => t.status === 'pending')).toBe(true);
+  });
+
+  test('enabled embeddings → forwards query + topK + hybrid + statusFilter to indexer', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.search.mockResolvedValue({ enabled: true, hits: [] });
+    await tool.searchTasks(makeAgent(tasks), {
+      query: 'telegram', topK: 3, hybrid: false, status: 'in_progress',
+    });
+    expect(mockIndexerInstance.search).toHaveBeenCalledWith(
+      'agent-1', 'telegram',
+      { topK: 3, hybrid: false, statusFilter: 'in_progress' },
+    );
+  });
+
+  test('enabled embeddings → hydrates hits back to live tasks', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.search.mockResolvedValue({
+      enabled: true,
+      hits: [
+        { id: 't2', score: 0.9, metadata: { title: 'snap', status: 'in_progress' } },
+        { id: 'gone', score: 0.5, metadata: { title: 'archived', status: 'pending' } },
+      ],
+    });
+    const r = await tool.searchTasks(makeAgent(tasks), { query: 'q' });
+    expect(r.results[0]).toMatchObject({ id: 't2', title: 'Investigate Telegram dedup', score: 0.9 });
+    expect(r.results[1]).toMatchObject({ id: 'gone', missing: true });
+  });
+
+  test('indexer error surfaces in result', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.search.mockResolvedValue({ enabled: true, hits: [], error: 'rate-limited' });
+    const r = await tool.searchTasks(makeAgent(tasks), { query: 'q' });
+    expect(r.success).toBe(false);
+    expect(r.error).toBe('rate-limited');
+  });
+});
+
+describe('taskManagerTool — backfill-search-index wiring', () => {
+  test('disabled → clean error', async () => {
+    const tool = makeTool({ embeddingsEnabled: false });
+    const r = await tool.backfillTasksSearchIndex(makeAgent(tasks));
+    expect(r.success).toBe(false);
+    expect(r.message).toMatch(/not enabled/i);
+    expect(mockIndexerInstance.backfill).not.toHaveBeenCalled();
+  });
+
+  test('enabled → walks agent.taskList.tasks + calls indexer.backfill', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.backfill.mockResolvedValue({ ok: true, indexed: 3, skipped: 0, failed: 0 });
+    const r = await tool.backfillTasksSearchIndex(makeAgent(tasks));
+    expect(mockIndexerInstance.backfill).toHaveBeenCalledWith('agent-1', tasks);
+    expect(r.success).toBe(true);
+    expect(r.indexed).toBe(3);
+  });
+
+  test('reports failure counts honestly', async () => {
+    const tool = makeTool();
+    mockIndexerInstance.backfill.mockResolvedValue({
+      ok: false, indexed: 0, skipped: 0, failed: 3, error: 'rate-limited',
+    });
+    const r = await tool.backfillTasksSearchIndex(makeAgent(tasks));
+    expect(r.success).toBe(false);
+    expect(r.failed).toBe(3);
+    expect(r.error).toBe('rate-limited');
+  });
+});

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

@@ -0,0 +1,236 @@
+/**
+ * Tests for updateTask's status-transition handler.
+ *
+ * Covers the in_progress entry handler that:
+ *   - Auto-loads `[memory:mem-...]` referenced memory into result.attachedMemory
+ *   - Emits result.memoryNudge when no memory is attached
+ *   - Surfaces a not-found error when the referenced memory was deleted
+ *   - Does nothing on non-transitioning updates (already in_progress)
+ *   - Does nothing for transitions to other statuses (e.g. blocked)
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+const mockLoadMemories = jest.fn();
+const mockInitialize = jest.fn().mockResolvedValue(undefined);
+const mockAddMemory = jest.fn();
+jest.unstable_mockModule('../../services/memoryService.js', () => ({
+  getMemoryService: jest.fn(() => ({
+    initialize: mockInitialize,
+    addMemory: mockAddMemory,
+    loadMemories: mockLoadMemories,
+  })),
+}));
+
+let uuidCounter = 0;
+jest.unstable_mockModule('uuid', () => ({
+  v4: jest.fn(() => `mock-uuid-${++uuidCounter}`),
+}));
+
+const { default: TaskManagerTool } = await import('../taskManagerTool.js');
+
+function makeTool() {
+  const tool = new TaskManagerTool({ description: 'test' });
+  tool.logger = createMockLogger();
+  return tool;
+}
+
+function makeContext({ taskList } = {}) {
+  const agent = {
+    id: 'agent-1',
+    name: 'Trans Test',
+    capabilities: ['memory', 'tools'],
+    taskList: taskList || { tasks: [], lastUpdated: new Date().toISOString() },
+  };
+  return {
+    agent,
+    context: {
+      agentId: 'agent-1',
+      agentName: 'Trans Test',
+      agent,
+      agentPool: {
+        getAgent: jest.fn().mockResolvedValue(agent),
+        persistAgentState: jest.fn().mockResolvedValue(undefined),
+      },
+      projectDir: '/tmp/test',
+    },
+  };
+}
+
+function makeTask(overrides = {}) {
+  return {
+    id: 'task-1',
+    title: 'Demo task',
+    description: 'No reference here',
+    status: 'pending',
+    priority: 'medium',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  uuidCounter = 0;
+  mockLoadMemories.mockReset();
+  mockInitialize.mockReset();
+  mockInitialize.mockResolvedValue(undefined);
+  mockAddMemory.mockReset();
+});
+
+describe('TaskManagerTool — updateTask in_progress transition handler', () => {
+  test('auto-loads attached memory when task description has [memory:mem-...] marker', async () => {
+    mockLoadMemories.mockResolvedValueOnce([
+      { id: 'mem-abc', title: 'Task plan', content: 'step 1: ...' },
+    ]);
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: '[memory:mem-abc] short summary' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeDefined();
+    expect(res.result.attachedMemory.id).toBe('mem-abc');
+    expect(res.result.attachedMemory.content).toBe('step 1: ...');
+    expect(res.result.attachedMemory._hint).toMatch(/memory append/);
+    expect(res.result.memoryNudge).toBeUndefined();
+  });
+
+  test('LOXIA_MEMORY_NUDGE_VARIANT=descriptive falls back to the older wording (for A/B validation)', async () => {
+    const prev = process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+    process.env.LOXIA_MEMORY_NUDGE_VARIANT = 'descriptive';
+    try {
+      const tool = makeTool();
+      const { agent, context } = makeContext();
+      agent.taskList.tasks = [makeTask({ description: 'Plain task with no marker' })];
+
+      const res = await tool.execute(
+        { action: 'update', taskId: 'task-1', status: 'in_progress' },
+        context
+      );
+
+      expect(res.success).toBe(true);
+      // Descriptive wording, NOT the imperative "VERY NEXT" phrasing.
+      expect(res.result.memoryNudge).toMatch(/Scan the.*AGENT MEMORY/);
+      expect(res.result.memoryNudge).not.toMatch(/VERY NEXT/);
+    } finally {
+      if (prev === undefined) delete process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+      else process.env.LOXIA_MEMORY_NUDGE_VARIANT = prev;
+    }
+  });
+
+  test('LOXIA_MEMORY_NUDGE_VARIANT unset OR =directive emits the directive wording', async () => {
+    const prev = process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+    delete process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+    try {
+      const tool = makeTool();
+      const { agent, context } = makeContext();
+      agent.taskList.tasks = [makeTask({ description: 'Plain task with no marker' })];
+
+      const res = await tool.execute(
+        { action: 'update', taskId: 'task-1', status: 'in_progress' },
+        context
+      );
+
+      expect(res.result.memoryNudge).toMatch(/VERY NEXT tool call/);
+      expect(res.result.memoryNudge).toMatch(/memory list/);
+    } finally {
+      if (prev === undefined) delete process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+      else process.env.LOXIA_MEMORY_NUDGE_VARIANT = prev;
+    }
+  });
+
+  test('emits memoryNudge when transitioning to in_progress without any [memory:] marker', async () => {
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: 'Plain task with no marker' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    // Directive wording (post-optimization, 2026-05-19): the
+    // descriptive earlier nudge ("Scan the catalog...") scored 22% in
+    // the live multi-turn memory bench. Switching to "Your VERY NEXT
+    // tool call MUST be `memory list`" doubled it to 44%. See
+    // scripts/memory-bench/.
+    expect(res.result.memoryNudge).toMatch(/memory list/);
+    expect(res.result.memoryNudge).toMatch(/VERY NEXT tool call/);
+    expect(res.result.memoryNudge).toMatch(/memory add/);
+    expect(mockLoadMemories).not.toHaveBeenCalled();
+  });
+
+  test('surfaces error when [memory:] marker points at a deleted memory', async () => {
+    mockLoadMemories.mockResolvedValueOnce([]); // memory not found
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: '[memory:mem-ghost] gone' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeDefined();
+    expect(res.result.attachedMemory.id).toBe('mem-ghost');
+    expect(res.result.attachedMemory.error).toMatch(/not found/i);
+    expect(res.result.attachedMemory.content).toBeUndefined();
+  });
+
+  test('does NOT trigger handler when task was already in_progress (no transition)', async () => {
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ status: 'in_progress', description: '[memory:mem-xyz] x' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    expect(res.result.memoryNudge).toBeUndefined();
+    expect(mockLoadMemories).not.toHaveBeenCalled();
+  });
+
+  test('does NOT trigger handler for transitions to non-in_progress statuses', async () => {
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ status: 'pending', description: '[memory:mem-xyz] x' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'blocked' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    expect(res.result.memoryNudge).toBeUndefined();
+    expect(mockLoadMemories).not.toHaveBeenCalled();
+  });
+
+  test('handler errors are swallowed (does not break update)', async () => {
+    mockLoadMemories.mockRejectedValueOnce(new Error('disk on fire'));
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: '[memory:mem-abc] x' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    expect(res.result.memoryNudge).toBeUndefined();
+  });
+});