@vellumai/assistant 0.3.4 → 0.3.6

package/src/__tests__/channel-readiness-service.test.ts

@@ -0,0 +1,324 @@
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { ChannelReadinessService, REMOTE_TTL_MS } from '../runtime/channel-readiness-service.js';
+import type { ChannelId } from '../channels/types.js';
+import type { ChannelProbe, ReadinessCheckResult } from '../runtime/channel-readiness-types.js';
+
+// ── Test helpers ────────────────────────────────────────────────────────────
+
+function makeProbe(
+  channel: ChannelId,
+  localResults: ReadinessCheckResult[],
+  remoteResults?: ReadinessCheckResult[],
+): ChannelProbe & { localCallCount: number; remoteCallCount: number } {
+  const probe = {
+    channel,
+    localCallCount: 0,
+    remoteCallCount: 0,
+    runLocalChecks(): ReadinessCheckResult[] {
+      probe.localCallCount++;
+      return localResults;
+    },
+    ...(remoteResults !== undefined
+      ? {
+          async runRemoteChecks(): Promise<ReadinessCheckResult[]> {
+            probe.remoteCallCount++;
+            return remoteResults;
+          },
+        }
+      : {}),
+  };
+  return probe;
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('ChannelReadinessService', () => {
+  let service: ChannelReadinessService;
+
+  beforeEach(() => {
+    service = new ChannelReadinessService();
+  });
+
+  test('local checks run on every call (no caching of local results)', async () => {
+    const probe = makeProbe('sms', [
+      { name: 'creds', passed: true, message: 'ok' },
+    ]);
+    service.registerProbe(probe);
+
+    await service.getReadiness('sms');
+    await service.getReadiness('sms');
+
+    expect(probe.localCallCount).toBe(2);
+  });
+
+  test('cache miss runs local checks and returns snapshot', async () => {
+    const probe = makeProbe('sms', [
+      { name: 'creds', passed: true, message: 'ok' },
+      { name: 'phone', passed: false, message: 'missing' },
+    ]);
+    service.registerProbe(probe);
+
+    const [snapshot] = await service.getReadiness('sms');
+
+    expect(probe.localCallCount).toBe(1);
+    expect(snapshot.channel).toBe('sms');
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.localChecks).toHaveLength(2);
+    expect(snapshot.reasons).toEqual([
+      { code: 'phone', text: 'missing' },
+    ]);
+  });
+
+  test('includeRemote=true runs remote checks on cache miss', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: true, message: 'remote ok' }],
+    );
+    service.registerProbe(probe);
+
+    const [snapshot] = await service.getReadiness('sms', true);
+
+    expect(probe.remoteCallCount).toBe(1);
+    expect(snapshot.remoteChecks).toHaveLength(1);
+    expect(snapshot.remoteChecks![0].passed).toBe(true);
+  });
+
+  test('cached remote checks reused within TTL', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: true, message: 'remote ok' }],
+    );
+    service.registerProbe(probe);
+
+    // First call populates cache
+    await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(1);
+
+    // Second call within TTL should reuse cache
+    const [snapshot] = await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(1);
+    expect(snapshot.remoteChecks).toHaveLength(1);
+  });
+
+  test('stale cache triggers remote check re-run', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: true, message: 'remote ok' }],
+    );
+    service.registerProbe(probe);
+
+    // First call
+    await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(1);
+
+    // Manually age the cached snapshot beyond TTL
+    const cached = (service as unknown as { snapshots: Map<string, { checkedAt: number }> }).snapshots.get('sms::__default__')!;
+    cached.checkedAt = Date.now() - REMOTE_TTL_MS - 1;
+
+    // Second call should re-run remote checks
+    await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(2);
+  });
+
+  test('invalidateChannel clears cache for specific channel', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: true, message: 'remote ok' }],
+    );
+    service.registerProbe(probe);
+
+    await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(1);
+
+    service.invalidateChannel('sms');
+
+    // After invalidation, remote checks should run again
+    await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(2);
+  });
+
+  test('invalidateAll clears all cached snapshots', async () => {
+    const smsProbe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api', passed: true, message: 'ok' }],
+    );
+    const telegramProbe = makeProbe(
+      'telegram',
+      [{ name: 'token', passed: true, message: 'ok' }],
+      [{ name: 'webhook', passed: true, message: 'ok' }],
+    );
+    service.registerProbe(smsProbe);
+    service.registerProbe(telegramProbe);
+
+    await service.getReadiness(undefined, true);
+    expect(smsProbe.remoteCallCount).toBe(1);
+    expect(telegramProbe.remoteCallCount).toBe(1);
+
+    service.invalidateAll();
+
+    await service.getReadiness(undefined, true);
+    expect(smsProbe.remoteCallCount).toBe(2);
+    expect(telegramProbe.remoteCallCount).toBe(2);
+  });
+
+  test('unknown channel returns unsupported_channel reason', async () => {
+    // Cast to exercise runtime handling of an unrecognized channel value
+    const [snapshot] = await service.getReadiness('carrier_pigeon' as ChannelId);
+
+    expect(snapshot.channel).toBe('carrier_pigeon' as ChannelId);
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.reasons).toEqual([
+      { code: 'unsupported_channel', text: 'Channel carrier_pigeon is not supported' },
+    ]);
+    expect(snapshot.localChecks).toHaveLength(0);
+  });
+
+  test('all checks passing yields ready=true', async () => {
+    const probe = makeProbe('telegram', [
+      { name: 'a', passed: true, message: 'ok' },
+      { name: 'b', passed: true, message: 'ok' },
+    ]);
+    service.registerProbe(probe);
+
+    const [snapshot] = await service.getReadiness('telegram');
+
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.reasons).toHaveLength(0);
+  });
+
+  test('getReadiness with no channel returns all registered channels', async () => {
+    service.registerProbe(makeProbe('sms', [{ name: 'a', passed: true, message: 'ok' }]));
+    service.registerProbe(makeProbe('telegram', [{ name: 'b', passed: true, message: 'ok' }]));
+
+    const snapshots = await service.getReadiness();
+
+    expect(snapshots).toHaveLength(2);
+    const channels = snapshots.map((s) => s.channel).sort();
+    expect(channels).toEqual(['sms', 'telegram']);
+  });
+
+  test('cached remote checks preserve original checkedAt (TTL not reset on reuse)', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: true, message: 'remote ok' }],
+    );
+    service.registerProbe(probe);
+
+    // First call populates cache with freshly fetched remote checks
+    const [first] = await service.getReadiness('sms', true);
+    const originalCheckedAt = first.checkedAt;
+    expect(probe.remoteCallCount).toBe(1);
+
+    // Second call within TTL reuses cache — checkedAt must stay at the original value
+    const [second] = await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(1);
+    expect(second.checkedAt).toBe(originalCheckedAt);
+  });
+
+  test('includeRemote runs remote checks when cache exists without remote data', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: true, message: 'remote ok' }],
+    );
+    service.registerProbe(probe);
+
+    // First call without includeRemote — cache has no remote data
+    await service.getReadiness('sms', false);
+    expect(probe.remoteCallCount).toBe(0);
+
+    // Second call with includeRemote — should run remote checks even though
+    // the cached snapshot exists (because it has no remoteChecks)
+    const [snapshot] = await service.getReadiness('sms', true);
+    expect(probe.remoteCallCount).toBe(1);
+    expect(snapshot.remoteChecks).toHaveLength(1);
+    expect(snapshot.remoteChecks![0].passed).toBe(true);
+  });
+
+  test('failed remote check makes channel not ready', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: false, message: 'API unreachable' }],
+    );
+    service.registerProbe(probe);
+
+    const [snapshot] = await service.getReadiness('sms', true);
+
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.reasons).toEqual([
+      { code: 'api_check', text: 'API unreachable' },
+    ]);
+  });
+
+  test('fresh cached remote failures do not affect local-only readiness', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: false, message: 'API unreachable' }],
+    );
+    service.registerProbe(probe);
+
+    // Prime remote cache with a failing check
+    await service.getReadiness('sms', true);
+
+    // Immediately call with includeRemote=false (cache is still fresh within TTL).
+    // The cached remote failure should be surfaced for visibility but must NOT
+    // affect readiness when the caller explicitly opted out of remote checks.
+    const [snapshot] = await service.getReadiness('sms', false);
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.reasons).toEqual([]);
+    // Remote checks are still visible for informational purposes
+    expect(snapshot.remoteChecks).toHaveLength(1);
+    expect(snapshot.remoteChecks![0].passed).toBe(false);
+  });
+
+  test('stale cached remote failures do not affect local-only readiness', async () => {
+    const probe = makeProbe(
+      'sms',
+      [{ name: 'creds', passed: true, message: 'ok' }],
+      [{ name: 'api_check', passed: false, message: 'API unreachable' }],
+    );
+    service.registerProbe(probe);
+
+    // Prime remote cache with a failing check
+    await service.getReadiness('sms', true);
+
+    // Age snapshot beyond TTL so remote checks are stale
+    const cached = (service as unknown as { snapshots: Map<string, { checkedAt: number }> }).snapshots.get('sms::__default__')!;
+    cached.checkedAt = Date.now() - REMOTE_TTL_MS - 1;
+
+    // Local-only call should not be blocked by stale remote failure
+    const [snapshot] = await service.getReadiness('sms', false);
+    expect(snapshot.stale).toBe(true);
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.reasons).toEqual([]);
+  });
+
+  test('remote cache is scoped per assistantId', async () => {
+    const remoteCalls: Record<string, number> = {};
+    const probe: ChannelProbe = {
+      channel: 'sms',
+      runLocalChecks: () => [{ name: 'local', passed: true, message: 'ok' }],
+      async runRemoteChecks(context) {
+        const key = context?.assistantId ?? '__default__';
+        remoteCalls[key] = (remoteCalls[key] ?? 0) + 1;
+        return [{ name: 'remote', passed: true, message: `ok-${key}` }];
+      },
+    };
+    service.registerProbe(probe);
+
+    await service.getReadiness('sms', true, 'ast-alpha');
+    await service.getReadiness('sms', true, 'ast-beta');
+    await service.getReadiness('sms', true, 'ast-alpha');
+
+    expect(remoteCalls['ast-alpha']).toBe(1);
+    expect(remoteCalls['ast-beta']).toBe(1);
+  });
+});

package/src/__tests__/checker.test.ts

@@ -1,7 +1,6 @@
 // Smoke command (run all security test files together):
 // bun test src/__tests__/checker.test.ts src/__tests__/trust-store.test.ts src/__tests__/session-skill-tools.test.ts src/__tests__/skill-script-runner-host.test.ts
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { describe, test, expect, beforeAll, beforeEach, afterEach, mock } from 'bun:test';
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync, symlinkSync, realpathSync } from 'node:fs';
 import { tmpdir, homedir } from 'node:os';
@@ -39,9 +38,16 @@ mock.module('../util/logger.js', () => ({
 
 // Mutable config object so tests can switch permissions.mode between
 // 'legacy', 'strict', and 'workspace' without re-registering the mock.
-const testConfig: Record<string, any> = {
-  permissions: { mode: 'legacy' as 'legacy' | 'strict' | 'workspace' },
-  skills: { load: { extraDirs: [] as string[] } },
+interface TestConfig {
+  permissions: { mode: 'legacy' | 'strict' | 'workspace' };
+  skills: { load: { extraDirs: string[] } };
+  sandbox: { enabled: boolean };
+  [key: string]: unknown;
+}
+
+const testConfig: TestConfig = {
+  permissions: { mode: 'legacy' },
+  skills: { load: { extraDirs: [] } },
   sandbox: { enabled: true },
 };
 
@@ -58,6 +64,7 @@ mock.module('../config/loader.js', () => ({
 
 import { classifyRisk, check, generateAllowlistOptions, generateScopeOptions, _resetLegacyDeprecationWarning } from '../permissions/checker.js';
 import { RiskLevel } from '../permissions/types.js';
+import type { TrustRule } from '../permissions/types.js';
 import { addRule, clearCache, findHighestPriorityRule } from '../permissions/trust-store.js';
 import { getDefaultRuleTemplates } from '../permissions/defaults.js';
 import { registerTool, getTool } from '../tools/registry.js';
@@ -2353,13 +2360,13 @@ describe('Permission Checker', () => {
       const trustDir = dirnameFn(trustPath);
       if (!existsSync(trustDir)) mkdirSyncFs(trustDir, { recursive: true });
 
-      let currentRules: any[] = [];
+      let currentRules: TrustRule[] = [];
       try {
         const raw = readFileSync(trustPath, 'utf-8');
         currentRules = JSON.parse(raw).rules ?? [];
       } catch { /* first run */ }
 
-      currentRules = currentRules.filter((r: any) => r.id !== opts.id);
+      currentRules = currentRules.filter((r: TrustRule) => r.id !== opts.id);
       currentRules.push({
         ...opts,
         createdAt: Date.now(),
@@ -2486,7 +2493,7 @@ describe('Permission Checker', () => {
         // Write the executionTarget field directly (addVersionBoundRule doesn't support it)
         const trustPath = join(checkerTestDir, 'protected', 'trust.json');
         const raw = JSON.parse((await import('node:fs')).readFileSync(trustPath, 'utf-8'));
-        const rule = raw.rules.find((r: any) => r.id === 'inv4-target-scoped');
+        const rule = raw.rules.find((r: TrustRule) => r.id === 'inv4-target-scoped');
         rule.executionTarget = '/usr/local/bin/node';
         (await import('node:fs')).writeFileSync(trustPath, JSON.stringify(raw, null, 2));
         clearCache();

package/src/__tests__/clarification-resolver.test.ts

@@ -6,33 +6,53 @@ let llmResolution: 'keep_existing' | 'keep_candidate' | 'merge' | 'still_unclear
 let llmResolvedStatement = '';
 let llmExplanation = 'Unclear response from user.';
 
-mock.module('@anthropic-ai/sdk', () => ({
-  default: class MockAnthropic {
-    messages = {
-      create: async (_body: unknown, opts?: { signal?: AbortSignal }) => {
-        llmCallCount += 1;
-        if (llmDelayMs > 0) {
-          await new Promise((resolve, reject) => {
-            const timer = setTimeout(resolve, llmDelayMs);
-            opts?.signal?.addEventListener('abort', () => {
-              clearTimeout(timer);
-              reject(new Error('Request was aborted.'));
-            });
+mock.module('../providers/provider-send-message.js', () => ({
+  getConfiguredProvider: () => ({
+    sendMessage: async (
+      _messages: unknown,
+      _tools: unknown,
+      _system: unknown,
+      opts?: { signal?: AbortSignal },
+    ) => {
+      llmCallCount += 1;
+      if (llmDelayMs > 0) {
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(resolve, llmDelayMs);
+          opts?.signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new Error('Request was aborted.'));
           });
-        }
-        return {
-          content: [{
-            type: 'tool_use',
-            input: {
-              resolution: llmResolution,
-              resolved_statement: llmResolvedStatement,
-              explanation: llmExplanation,
-            },
-          }],
-        };
-      },
+        });
+      }
+      return {
+        content: [{
+          type: 'tool_use' as const,
+          id: 'test-tool-use-id',
+          name: 'resolve_conflict',
+          input: {
+            resolution: llmResolution,
+            resolved_statement: llmResolvedStatement,
+            explanation: llmExplanation,
+          },
+        }],
+        model: 'claude-haiku-4-5-20251001',
+        stopReason: 'tool_use',
+        usage: { inputTokens: 0, outputTokens: 0 },
+      };
+    },
+  }),
+  createTimeout: (ms: number) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ms);
+    return {
+      signal: controller.signal,
+      cleanup: () => clearTimeout(timer),
     };
   },
+  extractToolUse: (response: { content: Array<{ type: string }> }) => {
+    return response.content.find((b: { type: string }) => b.type === 'tool_use');
+  },
+  userMessage: (text: string) => ({ role: 'user', content: [{ type: 'text', text }] }),
 }));
 
 mock.module('../config/loader.js', () => ({

package/src/__tests__/commit-message-enrichment-service.test.ts

@@ -308,25 +308,30 @@ describe('CommitEnrichmentService', () => {
   });
 
   test('job timeout triggers retry with backoff then fails after max retries', async () => {
-    // Use a very short timeout so the real git notes write times out
     const service = new CommitEnrichmentService({
       maxQueueSize: 10,
       maxConcurrency: 1,
-      jobTimeoutMs: 1, // 1ms timeout — will always time out
+      jobTimeoutMs: 10, // short timeout
       maxRetries: 2,
     });
 
     const commitHash = await createCommit();
+
+    // Use a slow gitService so the timeout always wins the race.
+    // A 1ms timeout against a real git write is flaky on fast CI runners.
+    const slowGitService = new WorkspaceGitService(testDir);
+    await slowGitService.ensureInitialized();
+    slowGitService.writeNote = () => new Promise<void>(() => {});
+
     service.enqueue({
       workspaceDir: testDir,
       commitHash,
       context: makeContext(),
-      gitService,
+      gitService: slowGitService,
     });
 
     // Wait for all retries to complete (initial + 2 retries, with backoff)
     // Backoff: 1s after attempt 1, 2s after attempt 2 = ~3s total
-    // But since the job itself is very fast to time out, total time is dominated by backoff
     await waitForDrain(service, 10000);
     await service.shutdown();
 

package/src/__tests__/computer-use-session-working-dir.test.ts

@@ -8,6 +8,13 @@ mock.module('../util/logger.js', () => ({
   getLogger: () => new Proxy({} as Record<string, unknown>, {
     get: () => () => {},
   }),
+  getCliLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+  isDebug: () => false,
+  truncateForLog: (value: string, maxLen = 500) => value.length > maxLen ? value.slice(0, maxLen) + '...' : value,
+  initLogger: () => {},
+  pruneOldLogFiles: () => 0,
 }));
 
 mock.module('../util/platform.js', () => ({
@@ -38,6 +45,7 @@ mock.module('../util/platform.js', () => ({
   isMacOS: () => false,
   isLinux: () => true,
   isWindows: () => false,
+  readHttpToken: () => null,
 }));
 
 mock.module('../tools/executor.js', () => ({

package/src/__tests__/config-schema.test.ts

@@ -74,9 +74,9 @@ describe('AssistantConfigSchema', () => {
     const result = AssistantConfigSchema.parse({});
     expect(result.provider).toBe('anthropic');
     expect(result.model).toBe('claude-opus-4-6');
-    expect(result.maxTokens).toBe(64000);
+    expect(result.maxTokens).toBe(16000);
     expect(result.apiKeys).toEqual({});
-    expect(result.thinking).toEqual({ enabled: false, budgetTokens: 10000 });
+    expect(result.thinking).toEqual({ enabled: false, budgetTokens: 10000, streamThinking: false });
     expect(result.contextWindow).toEqual({
       enabled: true,
       maxInputTokens: 180000,
@@ -206,6 +206,7 @@ describe('AssistantConfigSchema', () => {
       maxEdges: 40,
       neighborScoreMultiplier: 0.7,
       maxDepth: 3,
+      depthDecay: true,
     });
   });
 
@@ -681,7 +682,7 @@ describe('AssistantConfigSchema', () => {
       userConsultTimeoutSeconds: 120,
       disclosure: {
         enabled: true,
-        text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.',
+        text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".',
       },
       safety: {
         denyCategories: [],
@@ -706,6 +707,11 @@ describe('AssistantConfigSchema', () => {
       callerIdentity: {
         allowPerCallOverride: true,
       },
+      verification: {
+        enabled: false,
+        maxAttempts: 3,
+        codeLength: 6,
+      },
     });
   });
 
@@ -1187,8 +1193,8 @@ describe('loadConfig with schema validation', () => {
     const config = loadConfig();
     expect(config.provider).toBe('anthropic');
     expect(config.model).toBe('claude-opus-4-6');
-    expect(config.maxTokens).toBe(64000);
-    expect(config.thinking).toEqual({ enabled: false, budgetTokens: 10000 });
+    expect(config.maxTokens).toBe(16000);
+    expect(config.thinking).toEqual({ enabled: false, budgetTokens: 10000, streamThinking: false });
     expect(config.contextWindow).toEqual({
       enabled: true,
       maxInputTokens: 180000,
@@ -1209,7 +1215,7 @@ describe('loadConfig with schema validation', () => {
   test('falls back to default for invalid maxTokens', () => {
     writeConfig({ maxTokens: -100 });
     const config = loadConfig();
-    expect(config.maxTokens).toBe(64000);
+    expect(config.maxTokens).toBe(16000);
   });
 
   test('falls back to defaults for invalid nested values', () => {
@@ -1234,13 +1240,13 @@ describe('loadConfig with schema validation', () => {
     expect(config.model).toBe('gpt-4');
     expect(config.thinking.enabled).toBe(true);
     expect(config.thinking.budgetTokens).toBe(5000);
-    expect(config.maxTokens).toBe(64000);
+    expect(config.maxTokens).toBe(16000);
   });
 
   test('handles no config file', () => {
     const config = loadConfig();
     expect(config.provider).toBe('anthropic');
-    expect(config.maxTokens).toBe(64000);
+    expect(config.maxTokens).toBe(16000);
   });
 
   test('partial nested objects get defaults for missing fields', () => {

package/src/__tests__/context-window-manager.test.ts

@@ -287,7 +287,7 @@ describe('ContextWindowManager', () => {
     expect(getSummaryFromContextMessage(userMessage)).toBeNull();
   });
 
-  test('skips compaction during cooldown when projected gain is too low', async () => {
+  test('skips compaction during cooldown', async () => {
     const provider = createProvider(() => {
       throw new Error('summarizer should not be called while cooldown skip is active');
     });
@@ -307,7 +307,7 @@ describe('ContextWindowManager', () => {
       lastCompactedAt: Date.now() - 30_000,
     });
     expect(result.compacted).toBe(false);
-    expect(result.reason).toBe('compaction cooldown active with low projected gain');
+    expect(result.reason).toBe('compaction cooldown active');
   });
 
   test('ignores cooldown and compacts under severe token pressure', async () => {
@@ -338,6 +338,34 @@ describe('ContextWindowManager', () => {
     expect(result.reason).toBeUndefined();
   });
 
+  test('force=true bypasses cooldown for context-too-large recovery', async () => {
+    const provider = createProvider(() => ({
+      content: [{ type: 'text', text: '## Goals\n- forced compaction' }],
+      model: 'mock-model',
+      usage: { inputTokens: 60, outputTokens: 12 },
+      stopReason: 'end_turn',
+    }));
+    const manager = new ContextWindowManager(
+      provider,
+      'system prompt',
+      makeConfig({ maxInputTokens: 260, targetInputTokens: 180, preserveRecentUserTurns: 1 }),
+    );
+    const long = 'c'.repeat(220);
+    const history: Message[] = [
+      message('user', `u1 ${long}`),
+      message('assistant', `a1 ${long}`),
+      message('user', `u2 ${long}`),
+    ];
+
+    // Same setup as the cooldown test, but with force=true — should compact.
+    const result = await manager.maybeCompact(history, undefined, {
+      lastCompactedAt: Date.now() - 30_000,
+      force: true,
+    });
+    expect(result.compacted).toBe(true);
+    expect(result.reason).toBeUndefined();
+  });
+
   test('image-heavy payload is no longer underestimated as below-threshold', async () => {
     const provider = createProvider(() => ({
       content: [{ type: 'text', text: '## Goals\n- compacted image-heavy history' }],