github-issue-tower-defence-management 1.69.4 → 1.69.6

package/src/adapter/entry-points/cli/index.test.ts

@@ -350,6 +350,108 @@ codexHomeCandidates:
         '.codex-main',
       ]);
     });
+
+    it('should not warn when only known top-level keys are present', () => {
+      const readme = `<details>
+<summary>config</summary>
+defaultAgentName: 'agent'
+maximumPreparingIssuesCount: 5
+</details>`;
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+      const result = parseProjectReadmeConfig(
+        readme,
+        'https://github.com/orgs/example/projects/1',
+      );
+
+      expect(result.defaultAgentName).toBe('agent');
+      expect(result.maximumPreparingIssuesCount).toBe(5);
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('should warn for each unknown top-level key with project URL', () => {
+      const readme = `<details>
+<summary>config</summary>
+unknownOne: 'value-one'
+unknownTwo: 42
+</details>`;
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+      parseProjectReadmeConfig(
+        readme,
+        'https://github.com/orgs/example/projects/1',
+      );
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'Unknown key "unknownOne" in project README config section (project URL: https://github.com/orgs/example/projects/1)',
+      );
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'Unknown key "unknownTwo" in project README config section (project URL: https://github.com/orgs/example/projects/1)',
+      );
+      expect(consoleWarnSpy).toHaveBeenCalledTimes(2);
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('should warn only for unknown keys in a mixed config', () => {
+      const readme = `<details>
+<summary>config</summary>
+defaultAgentName: 'agent'
+unexpectedKey: 'oops'
+</details>`;
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+      const result = parseProjectReadmeConfig(
+        readme,
+        'https://github.com/orgs/example/projects/2',
+      );
+
+      expect(result.defaultAgentName).toBe('agent');
+      expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'Unknown key "unexpectedKey" in project README config section (project URL: https://github.com/orgs/example/projects/2)',
+      );
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('should warn for a typo of a known key (maximumPreparingIssueCount missing trailing s)', () => {
+      const readme = `<details>
+<summary>config</summary>
+maximumPreparingIssueCount: 9
+</details>`;
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+      const result = parseProjectReadmeConfig(
+        readme,
+        'https://github.com/orgs/example/projects/3',
+      );
+
+      expect(result.maximumPreparingIssuesCount).toBeUndefined();
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'Unknown key "maximumPreparingIssueCount" in project README config section (project URL: https://github.com/orgs/example/projects/3)',
+      );
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('should warn without project URL suffix when projectUrl is not provided', () => {
+      const readme = `<details>
+<summary>config</summary>
+mysteryKey: 'value'
+</details>`;
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+      parseProjectReadmeConfig(readme);
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'Unknown key "mysteryKey" in project README config section',
+      );
+
+      consoleWarnSpy.mockRestore();
+    });
   });
 
   describe('mergeConfigs', () => {

package/src/adapter/entry-points/cli/index.ts

@@ -161,7 +161,7 @@ program
     if (tempProjectUrl) {
       const readme = await fetchProjectReadme(tempProjectUrl, token);
       if (readme) {
-        readmeOverrides = parseProjectReadmeConfig(readme);
+        readmeOverrides = parseProjectReadmeConfig(readme, tempProjectUrl);
       }
     }
 
@@ -348,7 +348,7 @@ program
     if (tempProjectUrl) {
       const readme = await fetchProjectReadme(tempProjectUrl, token);
       if (readme) {
-        readmeOverrides = parseProjectReadmeConfig(readme);
+        readmeOverrides = parseProjectReadmeConfig(readme, tempProjectUrl);
       }
     }
 

package/src/adapter/entry-points/cli/projectConfig.ts

@@ -58,6 +58,23 @@ const getStringArrayValue = (
 export const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
+const knownProjectReadmeConfigKeys = [
+  'defaultAgentName',
+  'defaultLlmModelName',
+  'defaultLlmAgentName',
+  'maximumPreparingIssuesCount',
+  'allowIssueCacheMinutes',
+  'utilizationPercentageThreshold',
+  'allowedIssueAuthors',
+  'thresholdForAutoReject',
+  'workflowBlockerResolvedWebhookUrl',
+  'preparationProcessCheckCommand',
+  'codexHomeCandidates',
+  'claudeCodeOauthTokenListJsonPath',
+  'awLogDirectoryPath',
+  'awLogStaleThresholdMinutes',
+] as const;
+
 export const loadConfigFile = (configFilePath: string): ConfigFile => {
   try {
     const content = fs.readFileSync(configFilePath, 'utf-8');
@@ -111,7 +128,10 @@ export const loadConfigFile = (configFilePath: string): ConfigFile => {
   }
 };
 
-export const parseProjectReadmeConfig = (readme: string): ConfigFile => {
+export const parseProjectReadmeConfig = (
+  readme: string,
+  projectUrl?: string,
+): ConfigFile => {
   const detailsRegex =
     /<details>\s*<summary>config<\/summary>([\s\S]*?)<\/details>/i;
   const match = detailsRegex.exec(readme);
@@ -127,6 +147,15 @@ export const parseProjectReadmeConfig = (readme: string): ConfigFile => {
     if (!isRecord(parsed)) {
       return {};
     }
+    const knownKeySet = new Set<string>(knownProjectReadmeConfigKeys);
+    const projectUrlSuffix = projectUrl ? ` (project URL: ${projectUrl})` : '';
+    for (const key of Object.keys(parsed)) {
+      if (!knownKeySet.has(key)) {
+        console.warn(
+          `Unknown key "${key}" in project README config section${projectUrlSuffix}`,
+        );
+      }
+    }
     return {
       defaultAgentName: getStringValue(parsed, 'defaultAgentName'),
       defaultLlmModelName: getStringValue(parsed, 'defaultLlmModelName'),

package/src/adapter/entry-points/handlers/HandleScheduledEventUseCaseHandler.test.ts

@@ -457,4 +457,98 @@ claudeCodeOauthTokenListJsonPath: /readme/tokens.json
       );
     });
   });
+
+  describe('effective config logging', () => {
+    let consoleLogSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should log the effective values with configFile source when only the YAML config sets them', async () => {
+      const configWithPreparation = {
+        ...validConfig,
+        startPreparation: {
+          defaultAgentName: 'yaml-agent',
+          defaultLlmModelName: 'yaml-model',
+          configFilePath: './config.yml',
+          maximumPreparingIssuesCount: 10,
+        },
+      };
+      mockFetchReturningReadme(null);
+      jest
+        .mocked(fs.readFileSync)
+        .mockReturnValue(YAML.stringify(configWithPreparation));
+
+      const handler = new HandleScheduledEventUseCaseHandler();
+      await handler.handle('config.yml', false);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective maximumPreparingIssuesCount: 10 (source: configFile)',
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective defaultLlmModelName: yaml-model (source: configFile)',
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective defaultAgentName: yaml-agent (source: configFile)',
+      );
+    });
+
+    it('should log the effective values with readmeOverride source when the README config overrides them', async () => {
+      const readmeContent = `<details>
+<summary>config</summary>
+maximumPreparingIssuesCount: 3
+defaultLlmModelName: readme-model
+defaultAgentName: readme-agent
+</details>`;
+      mockFetchReturningReadme(readmeContent);
+      const configWithPreparation = {
+        ...validConfig,
+        startPreparation: {
+          defaultAgentName: 'yaml-agent',
+          defaultLlmModelName: 'yaml-model',
+          configFilePath: './config.yml',
+          maximumPreparingIssuesCount: 10,
+        },
+      };
+      jest
+        .mocked(fs.readFileSync)
+        .mockReturnValue(YAML.stringify(configWithPreparation));
+
+      const handler = new HandleScheduledEventUseCaseHandler();
+      await handler.handle('config.yml', false);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective maximumPreparingIssuesCount: 3 (source: readmeOverride)',
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective defaultLlmModelName: readme-model (source: readmeOverride)',
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective defaultAgentName: readme-agent (source: readmeOverride)',
+      );
+    });
+
+    it('should log null with unset (default) source when neither README nor config provides the value', async () => {
+      mockFetchReturningReadme(null);
+      jest.mocked(fs.readFileSync).mockReturnValue(YAML.stringify(validConfig));
+
+      const handler = new HandleScheduledEventUseCaseHandler();
+      await handler.handle('config.yml', false);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective maximumPreparingIssuesCount: null (source: unset (default))',
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective defaultLlmModelName: null (source: unset (default))',
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Effective defaultAgentName: null (source: unset (default))',
+      );
+    });
+  });
 });

package/src/adapter/entry-points/handlers/HandleScheduledEventUseCaseHandler.ts

@@ -94,7 +94,9 @@ export class HandleScheduledEventUseCaseHandler {
 
     const managerToken = input.credentials.manager.github.token;
     const readme = await fetchProjectReadme(input.projectUrl, managerToken);
-    const readmeConfig = readme ? parseProjectReadmeConfig(readme) : {};
+    const readmeConfig = readme
+      ? parseProjectReadmeConfig(readme, input.projectUrl)
+      : {};
 
     const mergedInput = {
       ...input,
@@ -139,6 +141,50 @@ export class HandleScheduledEventUseCaseHandler {
         : input.startPreparation,
     };
 
+    type EffectiveConfigValue = string | number | null | undefined;
+
+    const resolveConfigSource = (
+      readmeValue: EffectiveConfigValue,
+      configFileValue: EffectiveConfigValue,
+    ): 'readmeOverride' | 'configFile' | 'unset (default)' => {
+      if (readmeValue !== undefined && readmeValue !== null) {
+        return 'readmeOverride';
+      }
+      if (configFileValue !== undefined && configFileValue !== null) {
+        return 'configFile';
+      }
+      return 'unset (default)';
+    };
+
+    const formatEffectiveConfig = (
+      value: EffectiveConfigValue,
+      readmeValue: EffectiveConfigValue,
+      configFileValue: EffectiveConfigValue,
+    ): string =>
+      `${value ?? 'null'} (source: ${resolveConfigSource(readmeValue, configFileValue)})`;
+
+    console.log(
+      `Effective maximumPreparingIssuesCount: ${formatEffectiveConfig(
+        mergedInput.startPreparation?.maximumPreparingIssuesCount,
+        readmeConfig.maximumPreparingIssuesCount,
+        input.startPreparation?.maximumPreparingIssuesCount,
+      )}`,
+    );
+    console.log(
+      `Effective defaultLlmModelName: ${formatEffectiveConfig(
+        mergedInput.startPreparation?.defaultLlmModelName,
+        readmeConfig.defaultLlmModelName,
+        input.startPreparation?.defaultLlmModelName,
+      )}`,
+    );
+    console.log(
+      `Effective defaultAgentName: ${formatEffectiveConfig(
+        mergedInput.startPreparation?.defaultAgentName,
+        readmeConfig.defaultAgentName,
+        input.startPreparation?.defaultAgentName,
+      )}`,
+    );
+
     const systemDateRepository = new SystemDateRepository();
     const localStorageRepository = new LocalStorageRepository();
     const googleSpreadsheetRepository = new GoogleSpreadsheetRepository(

package/src/adapter/proxy/RateLimitCache.test.ts

@@ -218,6 +218,49 @@ describe('RateLimitCache', () => {
       const snapshot = readRateLimit(token);
       expect(snapshot?.modelWeeklyLimits).toEqual({});
     });
+
+    it('should expose ts as lastUpdatedEpoch in the snapshot', () => {
+      const token = 'ts-snapshot-token';
+      const before = Date.now() / 1000;
+      writeRateLimit(token, {
+        'anthropic-ratelimit-unified-status': 'allowed',
+        'anthropic-ratelimit-unified-5h-status': 'allowed',
+        'anthropic-ratelimit-unified-5h-reset': '1700000000',
+        'anthropic-ratelimit-unified-5h-utilization': '10',
+        'anthropic-ratelimit-unified-7d-status': 'allowed',
+        'anthropic-ratelimit-unified-7d-reset': '1700100000',
+        'anthropic-ratelimit-unified-7d-utilization': '5',
+      });
+      const after = Date.now() / 1000;
+      const snapshot = readRateLimit(token);
+      expect(snapshot).not.toBeNull();
+      if (snapshot === null) return;
+      expect(snapshot.lastUpdatedEpoch).toBeGreaterThanOrEqual(before);
+      expect(snapshot.lastUpdatedEpoch).toBeLessThanOrEqual(after);
+    });
+
+    it('should default lastUpdatedEpoch to 0 when the stored payload has no ts field', () => {
+      const token = 'no-ts-token';
+      fs.mkdirSync(cacheDir(), { recursive: true });
+      fs.writeFileSync(
+        cachePathForToken(token),
+        JSON.stringify({
+          headers: {
+            'anthropic-ratelimit-unified-status': 'allowed',
+            'anthropic-ratelimit-unified-5h-status': 'allowed',
+            'anthropic-ratelimit-unified-5h-reset': '1700000000',
+            'anthropic-ratelimit-unified-5h-utilization': '10',
+            'anthropic-ratelimit-unified-7d-status': 'allowed',
+            'anthropic-ratelimit-unified-7d-reset': '1700100000',
+            'anthropic-ratelimit-unified-7d-utilization': '5',
+          },
+        }),
+      );
+      const snapshot = readRateLimit(token);
+      expect(snapshot).not.toBeNull();
+      if (snapshot === null) return;
+      expect(snapshot.lastUpdatedEpoch).toBe(0);
+    });
   });
 
   describe('writeRateLimit stores all anthropic-ratelimit-* headers', () => {

package/src/adapter/proxy/RateLimitCache.ts

@@ -19,6 +19,7 @@ export interface RateLimitSnapshot {
   fiveHourRejected: boolean;
   sevenDayRejected: boolean;
   modelWeeklyLimits: Record<string, ModelWeeklyLimit>;
+  lastUpdatedEpoch: number;
 }
 
 export const PROXY_PORT = 8787;
@@ -183,6 +184,8 @@ export const readRateLimit = (token: string): RateLimitSnapshot | null => {
     const unifiedRejected = status === 'rejected';
     const fiveHourRejected = fiveHourStatus === 'rejected';
     const sevenDayRejected = sevenDayStatus === 'rejected';
+    const storedTs = parsed.ts;
+    const lastUpdatedEpoch = typeof storedTs === 'number' ? storedTs : 0;
     return {
       fiveHourUtilization: num('anthropic-ratelimit-unified-5h-utilization'),
       fiveHourReset: num('anthropic-ratelimit-unified-5h-reset'),
@@ -197,6 +200,7 @@ export const readRateLimit = (token: string): RateLimitSnapshot | null => {
       fiveHourRejected,
       sevenDayRejected,
       modelWeeklyLimits: readModelWeeklyLimits(parsed),
+      lastUpdatedEpoch,
     };
   } catch {
     return null;

package/src/adapter/repositories/ProxyRateLimitCacheRepository.test.ts

@@ -37,8 +37,9 @@ describe('ProxyRateLimitCacheRepository', () => {
     });
 
     const futureReset = Math.floor(Date.now() / 1000) + 3600;
+    const recentEpoch = Math.floor(Date.now() / 1000) - 60;
 
-    it('should return fiveHourReset as unifiedReset for a token with a cached snapshot', () => {
+    it('should return fiveHourReset as unifiedReset and ts as lastProbeEpoch for a token with a cached snapshot', () => {
       mockLoadTokens.mockReturnValue(['token-a']);
       mockReadRateLimit.mockReturnValue({
         fiveHourUtilization: 42,
@@ -51,22 +52,31 @@ describe('ProxyRateLimitCacheRepository', () => {
         fiveHourRejected: false,
         sevenDayRejected: false,
         modelWeeklyLimits: {},
+        lastUpdatedEpoch: recentEpoch,
       });
       const repository = new ProxyRateLimitCacheRepository('/tokens.json');
 
       const result = repository.getTokenRateLimitCaches();
 
-      expect(result).toEqual([{ token: 'token-a', unifiedReset: futureReset }]);
+      expect(result).toEqual([
+        {
+          token: 'token-a',
+          unifiedReset: futureReset,
+          lastProbeEpoch: recentEpoch,
+        },
+      ]);
     });
 
-    it('should return unifiedReset of 0 when no snapshot exists for a token', () => {
+    it('should return unifiedReset of 0 and lastProbeEpoch of 0 when no snapshot exists for a token', () => {
       mockLoadTokens.mockReturnValue(['token-a']);
       mockReadRateLimit.mockReturnValue(null);
       const repository = new ProxyRateLimitCacheRepository('/tokens.json');
 
       const result = repository.getTokenRateLimitCaches();
 
-      expect(result).toEqual([{ token: 'token-a', unifiedReset: 0 }]);
+      expect(result).toEqual([
+        { token: 'token-a', unifiedReset: 0, lastProbeEpoch: 0 },
+      ]);
     });
 
     it('should return entries for all tokens in the list', () => {
@@ -84,6 +94,7 @@ describe('ProxyRateLimitCacheRepository', () => {
             fiveHourRejected: false,
             sevenDayRejected: false,
             modelWeeklyLimits: {},
+            lastUpdatedEpoch: recentEpoch,
           };
         }
         return null;
@@ -93,8 +104,12 @@ describe('ProxyRateLimitCacheRepository', () => {
       const result = repository.getTokenRateLimitCaches();
 
       expect(result).toEqual([
-        { token: 'token-a', unifiedReset: futureReset },
-        { token: 'token-b', unifiedReset: 0 },
+        {
+          token: 'token-a',
+          unifiedReset: futureReset,
+          lastProbeEpoch: recentEpoch,
+        },
+        { token: 'token-b', unifiedReset: 0, lastProbeEpoch: 0 },
       ]);
     });
   });

package/src/adapter/repositories/ProxyRateLimitCacheRepository.ts

@@ -29,7 +29,8 @@ export class ProxyRateLimitCacheRepository implements RateLimitCacheRepository {
     return tokens.map((token) => {
       const snapshot = readRateLimit(token);
       const unifiedReset = snapshot !== null ? snapshot.fiveHourReset : 0;
-      return { token, unifiedReset };
+      const lastProbeEpoch = snapshot !== null ? snapshot.lastUpdatedEpoch : 0;
+      return { token, unifiedReset, lastProbeEpoch };
     });
   };
 

package/src/domain/usecases/UpdateRateLimitCacheUseCase.test.ts

@@ -12,10 +12,14 @@ describe('UpdateRateLimitCacheUseCase', () => {
   });
 
   it('should probe a token whose unifiedReset is in the past', async () => {
-    const pastReset = 1000000000;
     const nowEpochSeconds = 1000000100;
+    const pastReset = 1000000000;
     mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
-      { token: 'token-expired', unifiedReset: pastReset },
+      {
+        token: 'token-expired',
+        unifiedReset: pastReset,
+        lastProbeEpoch: nowEpochSeconds,
+      },
     ]);
     mockRateLimitCacheRepository.probeToken.mockResolvedValue(undefined);
 
@@ -26,11 +30,16 @@ describe('UpdateRateLimitCacheUseCase', () => {
     );
   });
 
-  it('should not probe a token whose unifiedReset is in the future', async () => {
-    const futureReset = 9999999999;
+  it('should not probe a token whose unifiedReset is in the future and was probed within the last hour', async () => {
     const nowEpochSeconds = 1000000000;
+    const futureReset = nowEpochSeconds + 1800;
+    const tenMinutesAgo = nowEpochSeconds - 600;
     mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
-      { token: 'token-active', unifiedReset: futureReset },
+      {
+        token: 'token-active',
+        unifiedReset: futureReset,
+        lastProbeEpoch: tenMinutesAgo,
+      },
     ]);
 
     await useCase.run({ nowEpochSeconds });
@@ -39,12 +48,20 @@ describe('UpdateRateLimitCacheUseCase', () => {
   });
 
   it('should probe only tokens with expired reset when mixed tokens exist', async () => {
-    const pastReset = 1000000000;
-    const futureReset = 9999999999;
     const nowEpochSeconds = 1000000100;
+    const pastReset = 1000000000;
+    const futureReset = nowEpochSeconds + 1800;
     mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
-      { token: 'token-expired', unifiedReset: pastReset },
-      { token: 'token-active', unifiedReset: futureReset },
+      {
+        token: 'token-expired',
+        unifiedReset: pastReset,
+        lastProbeEpoch: nowEpochSeconds,
+      },
+      {
+        token: 'token-active',
+        unifiedReset: futureReset,
+        lastProbeEpoch: nowEpochSeconds,
+      },
     ]);
     mockRateLimitCacheRepository.probeToken.mockResolvedValue(undefined);
 
@@ -57,10 +74,14 @@ describe('UpdateRateLimitCacheUseCase', () => {
   });
 
   it('should update the cache after probing by relying on the repository side effect', async () => {
-    const pastReset = 1000000000;
     const nowEpochSeconds = 1000000100;
+    const pastReset = 1000000000;
     mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
-      { token: 'token-expired', unifiedReset: pastReset },
+      {
+        token: 'token-expired',
+        unifiedReset: pastReset,
+        lastProbeEpoch: nowEpochSeconds,
+      },
     ]);
     mockRateLimitCacheRepository.probeToken.mockResolvedValue(undefined);
 
@@ -78,4 +99,80 @@ describe('UpdateRateLimitCacheUseCase', () => {
 
     expect(mockRateLimitCacheRepository.probeToken).not.toHaveBeenCalled();
   });
+
+  it('should probe a token whose last probe was 61 minutes ago even when unifiedReset is in the future', async () => {
+    const nowEpochSeconds = 1000000000;
+    const futureReset = nowEpochSeconds + 7200;
+    const sixtyOneMinutesAgo = nowEpochSeconds - 61 * 60;
+    mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
+      {
+        token: 'token-stale-probe',
+        unifiedReset: futureReset,
+        lastProbeEpoch: sixtyOneMinutesAgo,
+      },
+    ]);
+    mockRateLimitCacheRepository.probeToken.mockResolvedValue(undefined);
+
+    await useCase.run({ nowEpochSeconds });
+
+    expect(mockRateLimitCacheRepository.probeToken).toHaveBeenCalledWith(
+      'token-stale-probe',
+    );
+  });
+
+  it('should not probe a token whose last probe was 10 minutes ago', async () => {
+    const nowEpochSeconds = 1000000000;
+    const futureReset = nowEpochSeconds + 7200;
+    const tenMinutesAgo = nowEpochSeconds - 10 * 60;
+    mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
+      {
+        token: 'token-fresh-probe',
+        unifiedReset: futureReset,
+        lastProbeEpoch: tenMinutesAgo,
+      },
+    ]);
+
+    await useCase.run({ nowEpochSeconds });
+
+    expect(mockRateLimitCacheRepository.probeToken).not.toHaveBeenCalled();
+  });
+
+  it('should probe a token with unifiedReset in the past regardless of last probe time', async () => {
+    const nowEpochSeconds = 1000000000;
+    const pastReset = nowEpochSeconds - 60;
+    const oneMinuteAgo = nowEpochSeconds - 60;
+    mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
+      {
+        token: 'token-expired-recent-probe',
+        unifiedReset: pastReset,
+        lastProbeEpoch: oneMinuteAgo,
+      },
+    ]);
+    mockRateLimitCacheRepository.probeToken.mockResolvedValue(undefined);
+
+    await useCase.run({ nowEpochSeconds });
+
+    expect(mockRateLimitCacheRepository.probeToken).toHaveBeenCalledWith(
+      'token-expired-recent-probe',
+    );
+  });
+
+  it('should probe a token that has never been probed even when unifiedReset is in the future', async () => {
+    const nowEpochSeconds = 1000000000;
+    const futureReset = nowEpochSeconds + 7200;
+    mockRateLimitCacheRepository.getTokenRateLimitCaches.mockReturnValue([
+      {
+        token: 'token-never-probed',
+        unifiedReset: futureReset,
+        lastProbeEpoch: 0,
+      },
+    ]);
+    mockRateLimitCacheRepository.probeToken.mockResolvedValue(undefined);
+
+    await useCase.run({ nowEpochSeconds });
+
+    expect(mockRateLimitCacheRepository.probeToken).toHaveBeenCalledWith(
+      'token-never-probed',
+    );
+  });
 });

package/src/domain/usecases/UpdateRateLimitCacheUseCase.ts

@@ -1,5 +1,7 @@
 import { RateLimitCacheRepository } from './adapter-interfaces/RateLimitCacheRepository';
 
+const HOURLY_PROBE_INTERVAL_SECONDS = 3600;
+
 export class UpdateRateLimitCacheUseCase {
   constructor(
     private readonly rateLimitCacheRepository: RateLimitCacheRepository,
@@ -8,7 +10,11 @@ export class UpdateRateLimitCacheUseCase {
   run = async (params: { nowEpochSeconds: number }): Promise<void> => {
     const caches = this.rateLimitCacheRepository.getTokenRateLimitCaches();
     for (const cache of caches) {
-      if (cache.unifiedReset < params.nowEpochSeconds) {
+      const unifiedResetExpired = cache.unifiedReset < params.nowEpochSeconds;
+      const hourlyProbeDue =
+        params.nowEpochSeconds - cache.lastProbeEpoch >=
+        HOURLY_PROBE_INTERVAL_SECONDS;
+      if (unifiedResetExpired || hourlyProbeDue) {
         await this.rateLimitCacheRepository.probeToken(cache.token);
       }
     }

package/src/domain/usecases/adapter-interfaces/RateLimitCacheRepository.ts

@@ -1,6 +1,7 @@
 export interface TokenRateLimitCache {
   token: string;
   unifiedReset: number;
+  lastProbeEpoch: number;
 }
 
 export interface RateLimitCacheRepository {