onbuzz 4.8.3 → 4.9.1

package/src/core/__tests__/agentScheduler.autoRecall.test.js

@@ -0,0 +1,215 @@
+/**
+ * agentScheduler — auto-recall injection wiring (Phase 6d.2).
+ *
+ * The auto-recall primitive + the aiService.augmentSystemPrompt helper
+ * are tested elsewhere (autoRecall.test.js, aiService.embed.test.js).
+ * This suite pins the WIRING contract: the scheduler calls the helper
+ * with the right arguments under the right conditions, and never lets
+ * a failure block the turn.
+ *
+ * Pins:
+ *   - Fires when memory capability is present AND lastUserMsg has content.
+ *   - Skipped when memory capability is absent (no point).
+ *   - Skipped when there's no user message (e.g. an agent-initiated turn).
+ *   - Skipped when augmentSystemPrompt is undefined (older aiService builds).
+ *   - Errors from augmentSystemPrompt are swallowed; the turn continues
+ *     with the un-augmented prompt.
+ *   - The augmented prompt is what reaches aiService.sendMessage.
+ *
+ * Strategy: build a minimal "scheduler-shaped" object with just the
+ * methods we need, then call into the same code path. Avoids dragging
+ * the full constructor + every dependency into the test.
+ */
+
+import { describe, test, expect, jest, beforeEach } from '@jest/globals';
+
+/**
+ * The auto-recall wiring lives inside _getAIResponse-adjacent code in
+ * agentScheduler. Rather than firing the whole scheduler, we extract
+ * the wiring into a tiny reusable helper here that mirrors EXACTLY the
+ * shape inserted in the scheduler. The contract is identical:
+ *   if agent has 'memory' capability AND aiService.augmentSystemPrompt
+ *   AND there's a non-empty lastUserMsg.content → call the helper.
+ *
+ * This is a "shape-match" test: it catches regressions on the gating
+ * logic + argument passing without coupling to the whole scheduler.
+ */
+async function runAutoRecallStep({
+  agent,
+  conversationHistory,
+  aiService,
+  logger,
+  enhancedSystemPrompt,
+}) {
+  const lastUserMsg = [...conversationHistory].reverse().find(m => m.role === 'user');
+  if (
+    Array.isArray(agent.capabilities) &&
+    agent.capabilities.includes('memory') &&
+    typeof aiService?.augmentSystemPrompt === 'function'
+  ) {
+    try {
+      const recentText = typeof lastUserMsg?.content === 'string' ? lastUserMsg.content : '';
+      if (recentText) {
+        enhancedSystemPrompt = await aiService.augmentSystemPrompt(
+          enhancedSystemPrompt, agent.id, recentText,
+        );
+      }
+    } catch (err) {
+      logger.warn?.(`Auto-recall injection failed for agent ${agent.id} (continuing without)`, {
+        error: err?.message,
+      });
+    }
+  }
+  return enhancedSystemPrompt;
+}
+
+function makeLogger() {
+  return { warn: jest.fn(), info: jest.fn(), error: jest.fn(), debug: jest.fn() };
+}
+
+describe('agentScheduler — auto-recall wiring (Phase 6d.2)', () => {
+  let aiService, logger;
+
+  beforeEach(() => {
+    aiService = {
+      augmentSystemPrompt: jest.fn(async (prompt) => prompt + '\n\n## RELEVANT CONTEXT (auto-recalled)\n\nmocked'),
+    };
+    logger = makeLogger();
+  });
+
+  test('fires when memory capability + user message + helper are all present', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory', 'terminal'] },
+      conversationHistory: [
+        { role: 'system', content: 'sys' },
+        { role: 'user',   content: 'how do we throttle telegram?' },
+      ],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).toHaveBeenCalledTimes(1);
+    expect(aiService.augmentSystemPrompt).toHaveBeenCalledWith(
+      'BASE',
+      'a1',
+      'how do we throttle telegram?',
+    );
+    expect(out).toContain('## RELEVANT CONTEXT (auto-recalled)');
+  });
+
+  test('uses the MOST RECENT user message (not an older one)', async () => {
+    await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [
+        { role: 'user',      content: 'first question'  },
+        { role: 'assistant', content: 'first answer'    },
+        { role: 'user',      content: 'second question' },
+        { role: 'assistant', content: 'second answer'   },
+        { role: 'user',      content: 'latest question' },
+      ],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).toHaveBeenCalledWith(
+      'BASE', 'a1', 'latest question',
+    );
+  });
+
+  test('skipped when agent lacks memory capability', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['terminal'] },          // no memory
+      conversationHistory: [{ role: 'user', content: 'hi' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');                                    // unchanged
+  });
+
+  test('skipped when capabilities is missing or non-array', async () => {
+    for (const caps of [undefined, null, 'memory', 42]) {
+      aiService.augmentSystemPrompt.mockClear();
+      const out = await runAutoRecallStep({
+        agent: { id: 'a1', capabilities: caps },
+        conversationHistory: [{ role: 'user', content: 'hi' }],
+        aiService, logger,
+        enhancedSystemPrompt: 'BASE',
+      });
+      expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+      expect(out).toBe('BASE');
+    }
+  });
+
+  test('skipped when there is no user message at all', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'system', content: 'sys' }],   // no user msg
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');
+  });
+
+  test('skipped when the latest user message has empty content', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: '' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');
+  });
+
+  test('skipped when user message content is non-string (array form)', async () => {
+    // Some history entries have content as [{type:'text', text:'...'}]. The
+    // wiring intentionally requires plain string content — array form is
+    // handled by the embedding service\'s own packing if it gets there.
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: [{ type: 'text', text: 'array form' }] }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');
+  });
+
+  test('older aiService without augmentSystemPrompt → no-op (forward-compat)', async () => {
+    const oldService = {};   // no augmentSystemPrompt at all
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: 'hi' }],
+      aiService: oldService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(out).toBe('BASE');
+  });
+
+  test('errors from augmentSystemPrompt are swallowed; turn continues with un-augmented prompt', async () => {
+    aiService.augmentSystemPrompt = jest.fn(async () => {
+      throw new Error('embedding service exploded');
+    });
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: 'hi' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(out).toBe('BASE');
+    expect(logger.warn).toHaveBeenCalled();
+  });
+
+  test('returned prompt is what aiService.augmentSystemPrompt produced', async () => {
+    aiService.augmentSystemPrompt = jest.fn(async () =>
+      'BASE\n\n## RELEVANT CONTEXT (auto-recalled)\n\nremembered thing'
+    );
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: 'q' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(out).toBe('BASE\n\n## RELEVANT CONTEXT (auto-recalled)\n\nremembered thing');
+  });
+});

package/src/core/__tests__/agentScheduler.codebaseKnowledge.test.js

@@ -0,0 +1,65 @@
+/**
+ * Contract tests for the `## CODEBASE KNOWLEDGE` injection in
+ * agentScheduler. Like the sibling tests for task-list and operating-
+ * posture, we source-grep rather than instantiating the heavy
+ * scheduler graph — the contract is: the injection block exists, sits
+ * in the right place, sources from the singleton service, and is
+ * wrapped in a graceful-degrade try/catch.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC = readFileSync(join(__dirname, '../agentScheduler.js'), 'utf-8');
+
+describe('agentScheduler — CODEBASE KNOWLEDGE injection', () => {
+  test('source contains the injection block', () => {
+    expect(SRC).toMatch(/Auto-inject CODEBASE KNOWLEDGE/);
+  });
+
+  test('injection sources from codebaseKnowledgeService singleton', () => {
+    expect(SRC).toMatch(/codebaseKnowledgeService/);
+    expect(SRC).toMatch(/getCodebaseKnowledgeService/);
+    expect(SRC).toMatch(/buildIndexBlock\(agentId\)/);
+  });
+
+  test('injection follows the CURRENT TASK LIST block (stable ordering for prompt cache)', () => {
+    const taskIdx = SRC.indexOf('CURRENT TASK LIST');
+    const cbIdx = SRC.indexOf('CODEBASE KNOWLEDGE');
+    expect(taskIdx).toBeGreaterThan(-1);
+    expect(cbIdx).toBeGreaterThan(-1);
+    expect(cbIdx).toBeGreaterThan(taskIdx);
+  });
+
+  test('graceful degrade: wrapped in try/catch with a `continuing without` warning', () => {
+    const block = SRC.slice(
+      SRC.indexOf('Auto-inject CODEBASE KNOWLEDGE'),
+      SRC.indexOf('Check if streaming is enabled'),
+    );
+    expect(block).toMatch(/try\s*\{/);
+    expect(block).toMatch(/catch\s*\(/);
+    expect(block).toMatch(/continuing without/);
+  });
+
+  test('REGRESSION: injection is GATED on the agent having code-map in capabilities', () => {
+    // Non-coder agents (chat-only, marketing agents, etc.) must not
+    // pay the per-turn service-lookup cost. The cache is only
+    // populated by code-map results — agents without code-map have
+    // nothing to surface.
+    const block = SRC.slice(
+      SRC.indexOf('Auto-inject CODEBASE KNOWLEDGE'),
+      SRC.indexOf('Check if streaming is enabled'),
+    );
+    // Must check capabilities for 'code-map' before doing anything.
+    expect(block).toMatch(/agent\.capabilities/);
+    expect(block).toMatch(/includes\(['"]code-map['"]\)/);
+    // The whole try-block should sit INSIDE that conditional, not
+    // outside it (otherwise the gate doesn't actually skip the work).
+    const guardIdx = block.indexOf('includes(\'code-map\')');
+    const tryIdx   = block.indexOf('try {');
+    expect(guardIdx).toBeGreaterThan(-1);
+    expect(tryIdx).toBeGreaterThan(guardIdx);
+  });
+});

package/src/core/__tests__/agentScheduler.errorCategorisation.test.js

@@ -0,0 +1,169 @@
+/**
+ * Tests for handleAIServiceFailure's error categorisation + broadcast policy.
+ *
+ * Behavioural contract:
+ *   • PERSISTENT failures (auth, unknown) → broadcast `agent_error`
+ *     so the UI banner / Telegram fanout reach the user.
+ *   • TRANSIENT failures (rate-limit, provider-overload, gateway, network)
+ *     → silent. They self-heal; broadcasting them every retry cycle was
+ *     the source of the Telegram floods.
+ *   • Token-limit → handled by the compaction path (early return),
+ *     never broadcasts directly from this function.
+ *
+ * The classification regexes are the most likely source of regression —
+ * cover the named status codes (401/403/429/503/504/529) plus the common
+ * textual variants we saw in production logs.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+const mockShouldAgentBeActive = jest.fn(() => ({ active: false, reason: 'idle' }));
+const mockGetActiveAgents = jest.fn(() => []);
+const mockShouldSkipIteration = jest.fn(() => false);
+jest.unstable_mockModule('../../services/agentActivityService.js', () => ({
+  shouldAgentBeActive: mockShouldAgentBeActive,
+  getActiveAgents: mockGetActiveAgents,
+  shouldSkipIteration: mockShouldSkipIteration,
+}));
+
+const { default: AgentScheduler } = await import('../agentScheduler.js');
+
+function makeScheduler() {
+  const logger = createMockLogger();
+  const agent = { id: 'a1', name: 'TestAgent', sessionId: 'sess-1' };
+  const agentPool = {
+    getAgent: jest.fn().mockResolvedValue(agent),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    addToolResult: jest.fn().mockResolvedValue(undefined),
+  };
+  const broadcasts = [];
+  const webSocketManager = {
+    broadcastToSession: jest.fn((sessionId, payload) => broadcasts.push({ sessionId, payload })),
+  };
+  const aiService = { abortRequest: jest.fn(), getActiveRequest: () => null };
+  const scheduler = new AgentScheduler(agentPool, {}, aiService, logger);
+  scheduler.webSocketManager = webSocketManager;
+  scheduler.broadcastAgentStateUpdate = jest.fn().mockResolvedValue(undefined);
+  scheduler.getAgentSession = jest.fn(() => 'sess-1');
+  return { scheduler, agentPool, broadcasts, agent };
+}
+
+const errorClasses = [
+  // -- TRANSIENT (no broadcast) --
+  { name: 'rate-limit text',         msg: 'Rate limit exceeded', expectBroadcast: false, label: 'rate-limit' },
+  { name: 'rate-limit 429',          msg: 'HTTP 429 Too Many Requests', expectBroadcast: false, label: 'rate-limit' },
+  { name: 'provider overload 529',   msg: 'HTTP 529 Overloaded',  expectBroadcast: false, label: 'provider-overload' },
+  { name: 'provider overload text',  msg: 'The model is overloaded with requests', expectBroadcast: false, label: 'provider-overload' },
+  { name: 'server is busy',          msg: 'Sorry, the server is busy. Please try again.', expectBroadcast: false, label: 'provider-overload' },
+  { name: 'capacity error',          msg: 'Provider returned a capacity error', expectBroadcast: false, label: 'provider-overload' },
+  { name: 'gateway 503',             msg: 'HTTP 503 Service Unavailable', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'gateway 504',             msg: '504 Gateway Timeout from upstream', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'bad gateway',             msg: 'Got a bad gateway response', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'upstream',                msg: 'Upstream connect error', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'network ECONNREFUSED',    msg: 'ECONNREFUSED 127.0.0.1', expectBroadcast: false, label: 'network-error' },
+  { name: 'network ETIMEDOUT',       msg: 'connect ETIMEDOUT', expectBroadcast: false, label: 'network-error' },
+  { name: 'network ENOTFOUND',       msg: 'getaddrinfo ENOTFOUND api.foo', expectBroadcast: false, label: 'network-error' },
+  { name: 'fetch failed',            msg: 'fetch failed', expectBroadcast: false, label: 'network-error' },
+  // -- PERSISTENT (broadcast) --
+  { name: 'auth: API key',           msg: 'Invalid API key provided',           expectBroadcast: true, label: 'api-key-error' },
+  { name: 'auth: 401',               msg: 'HTTP 401 Unauthorized',              expectBroadcast: true, label: 'api-key-error' },
+  { name: 'auth: 403',               msg: 'HTTP 403 Forbidden',                  expectBroadcast: true, label: 'api-key-error' },
+  { name: 'unknown: random 500',     msg: 'Random 500 Internal Server Error from the AI', expectBroadcast: true, label: 'server-error' },
+  { name: 'unknown: weird shape',    msg: 'Provider returned malformed JSON',   expectBroadcast: true, label: 'server-error' },
+];
+
+describe('handleAIServiceFailure: error categorisation', () => {
+  describe.each(errorClasses)('%s', (tc) => {
+    let scheduler, broadcasts;
+    beforeEach(() => {
+      jest.clearAllMocks();
+      ({ scheduler, broadcasts } = makeScheduler());
+    });
+
+    test(`"${tc.msg}" → broadcast=${tc.expectBroadcast}, state="${tc.label}"`, async () => {
+      await scheduler.handleAIServiceFailure('a1', new Error(tc.msg));
+
+      const agentErrorBroadcasts = broadcasts.filter(b => b.payload?.type === 'agent_error');
+      if (tc.expectBroadcast) {
+        expect(agentErrorBroadcasts.length).toBe(1);
+        expect(agentErrorBroadcasts[0].payload.data.error).toBe(tc.msg);
+      } else {
+        expect(agentErrorBroadcasts.length).toBe(0);
+      }
+      // Every branch must publish an agent-state hint so the UI shows the
+      // right pause reason; verify the label we expect.
+      expect(scheduler.broadcastAgentStateUpdate).toHaveBeenCalledWith('a1', tc.label);
+    });
+  });
+});
+
+describe('handleAIServiceFailure: gateway 503 takes the network delay, not the rate-limit delay', () => {
+  test('uses NETWORK_ERROR_DELAY_MS for 503 errors', async () => {
+    const { scheduler, agentPool, agent } = makeScheduler();
+    const beforeMs = Date.now();
+    await scheduler.handleAIServiceFailure('a1', new Error('HTTP 503 Service Unavailable'));
+
+    // delayEndTime is in agent.delayEndTime as ISO; should be ~30s out.
+    const elapsedMs = new Date(agent.delayEndTime).getTime() - beforeMs;
+    // Use a generous range to tolerate test-machine drift.
+    expect(elapsedMs).toBeGreaterThanOrEqual(20 * 1000);
+    expect(elapsedMs).toBeLessThanOrEqual(90 * 1000);
+    expect(agentPool.persistAgentState).toHaveBeenCalledWith('a1');
+  });
+});
+
+describe('handleAIServiceFailure: token-limit path early-returns without broadcasting', () => {
+  test('does not call broadcastToSession for token-limit errors', async () => {
+    const { scheduler, broadcasts } = makeScheduler();
+    // Stub the token-limit handler so we don't fall into its compaction logic.
+    scheduler.handleTokenLimitError = jest.fn().mockResolvedValue(undefined);
+    scheduler.isTokenLimitError = jest.fn().mockReturnValue(true);
+
+    await scheduler.handleAIServiceFailure('a1', new Error('Context length exceeded'));
+
+    expect(scheduler.handleTokenLimitError).toHaveBeenCalledWith('a1', expect.any(Object), expect.any(Error));
+    // Importantly: no agent_error broadcast from this path.
+    expect(broadcasts.filter(b => b.payload?.type === 'agent_error').length).toBe(0);
+  });
+});
+
+describe('isTokenLimitError: regex-free implementation preserves all original patterns', () => {
+  // The original implementation matched these literal substrings plus a
+  // `/maximum.*exceeded/` regex. The refactored version replaces the
+  // regex with a two-indexOf check. Cover both halves explicitly.
+  const positives = [
+    'prompt is too long for this model',
+    'too many tokens for the model',
+    'context length exceeded the limit',
+    'context window exceeded',
+    'maximum context size reached',
+    'token limit reached for this request',
+    'max_tokens is set too high',
+    'context_length_exceeded: request had 200000 tokens',
+    // The 'maximum.*exceeded' case — "maximum" appears before "exceeded".
+    'maximum response limit exceeded for input',
+    'maximum 100k context length exceeded by 5k tokens',
+  ];
+  const negatives = [
+    'rate limit exceeded',
+    'connection timed out',
+    'maximum retries reached',         // has "maximum" but no "exceeded" after it
+    'something exceeded the maximum',  // "exceeded" appears BEFORE "maximum" — old regex required maximum→exceeded order
+    'random unrelated error',
+  ];
+
+  describe.each(positives)('positive: %s', (msg) => {
+    test('classifies as token-limit', () => {
+      const { scheduler } = makeScheduler();
+      expect(scheduler.isTokenLimitError(msg.toLowerCase())).toBe(true);
+    });
+  });
+
+  describe.each(negatives)('negative: %s', (msg) => {
+    test('does not classify as token-limit', () => {
+      const { scheduler } = makeScheduler();
+      expect(scheduler.isTokenLimitError(msg.toLowerCase())).toBe(false);
+    });
+  });
+});

package/src/core/__tests__/agentScheduler.memoryInjection.test.js

@@ -0,0 +1,78 @@
+/**
+ * Contract tests for the `## AGENT MEMORY` catalog injection and
+ * post-compaction nudge inside agentScheduler. We source-grep — the
+ * contracts are:
+ *   - The catalog injection block exists, is gated on the `memory`
+ *     capability, calls memoryService.getCatalog, lists `id  title`
+ *     compactly, and is wrapped in try/catch.
+ *   - The post-compaction nudge is a one-shot flag-driven block
+ *     keyed off `_postCompactionNudgePending`, and the flag is set
+ *     after the compaction step succeeds.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC = readFileSync(join(__dirname, '../agentScheduler.js'), 'utf-8');
+
+describe('agentScheduler — AGENT MEMORY catalog injection', () => {
+  test('source contains the AGENT MEMORY catalog injection header', () => {
+    expect(SRC).toMatch(/AGENT MEMORY \(catalog/);
+  });
+
+  test('injection sources from memoryService.getCatalog', () => {
+    expect(SRC).toMatch(/getMemoryService/);
+    expect(SRC).toMatch(/getCatalog\(agentId/);
+  });
+
+  test('injection is gated on the `memory` capability', () => {
+    const start = SRC.indexOf('Auto-inject AGENT MEMORY');
+    const block = SRC.slice(start, start + 1500);
+    expect(block).toMatch(/capabilities\.includes\(['"]memory['"]\)/);
+  });
+
+  test('injection follows the CODEBASE KNOWLEDGE block (stable ordering for prompt cache)', () => {
+    const cbIdx = SRC.indexOf('Auto-inject CODEBASE KNOWLEDGE');
+    const memIdx = SRC.indexOf('Auto-inject AGENT MEMORY');
+    expect(cbIdx).toBeGreaterThan(-1);
+    expect(memIdx).toBeGreaterThan(-1);
+    expect(memIdx).toBeGreaterThan(cbIdx);
+  });
+
+  test('graceful degrade: wrapped in try/catch', () => {
+    const start = SRC.indexOf('AGENT MEMORY');
+    const block = SRC.slice(Math.max(0, start - 600), start + 800);
+    expect(block).toMatch(/try\s*\{/);
+    expect(block).toMatch(/catch\s*\(/);
+  });
+});
+
+describe('agentScheduler — POST-COMPACTION NUDGE', () => {
+  test('source contains the POST-COMPACTION NUDGE block', () => {
+    expect(SRC).toMatch(/POST-COMPACTION NUDGE/);
+  });
+
+  test('nudge is driven by the _postCompactionNudgePending flag (one-shot)', () => {
+    expect(SRC).toMatch(/_postCompactionNudgePending/);
+    const block = SRC.slice(
+      SRC.indexOf('POST-COMPACTION NUDGE') - 200,
+      SRC.indexOf('POST-COMPACTION NUDGE') + 600,
+    );
+    // The flag is consumed (set false) after emission.
+    expect(block).toMatch(/_postCompactionNudgePending\s*=\s*false/);
+  });
+
+  test('the flag is set after the compaction step', () => {
+    // Look for a place that flips the flag to true (not false).
+    expect(SRC).toMatch(/_postCompactionNudgePending\s*=\s*true/);
+  });
+
+  test('nudge references AGENT MEMORY so the agent knows where to look', () => {
+    const start = SRC.indexOf('POST-COMPACTION NUDGE');
+    const block = SRC.slice(start, start + 1200);
+    expect(block).toMatch(/AGENT MEMORY/);
+    expect(block).toMatch(/memory read/);
+  });
+});

package/src/core/agentPool.js

@@ -889,6 +889,16 @@ class AgentPool {
       }
     }
 
+    // Clear codebase-knowledge cache for this agent — bytes live in
+    // the service's in-memory map; without this the per-agent entry
+    // would persist until the next process restart.
+    try {
+      const { getCodebaseKnowledgeService } = await import('../services/codebaseKnowledgeService.js');
+      getCodebaseKnowledgeService(this.logger).clear(agentId);
+    } catch (e) {
+      this.logger.debug?.('codebase-knowledge clear failed on agent delete', { agentId, error: e.message });
+    }
+
     // Clean up visual editor instance
     try {
       const visualEditorBridge = getVisualEditorBridge();