github-issue-tower-defence-management 1.194.2 → 1.196.0

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

@@ -67,13 +67,15 @@ describe('loadLiveSessionOauthTokenSelectionSettings', () => {
     );
   });
 
-  it('reads both tuning numbers from the fleet config file', () => {
+  it('reads all tuning numbers from the fleet config file', () => {
     const fleetConfigFilePath = writeFleetConfig(
       [
         'inTmuxLauncherCommand: cl',
         'liveSessionOauthTokenSelection:',
         '  maxConcurrentSessionCount: 16',
         '  fullSpeedFiveHourFreeRatio: 0.4',
+        '  minFiveHourFreeRatio: 0.7',
+        '  minSevenDayFreeRatio: 0.2',
       ].join('\n'),
     );
 
@@ -82,6 +84,8 @@ describe('loadLiveSessionOauthTokenSelectionSettings', () => {
     ).toEqual({
       maxConcurrentSessionCount: 16,
       fullSpeedFiveHourFreeRatio: 0.4,
+      minFiveHourFreeRatio: 0.7,
+      minSevenDayFreeRatio: 0.2,
     });
   });
 
@@ -99,6 +103,10 @@ describe('loadLiveSessionOauthTokenSelectionSettings', () => {
       maxConcurrentSessionCount: 16,
       fullSpeedFiveHourFreeRatio:
         DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.fullSpeedFiveHourFreeRatio,
+      minFiveHourFreeRatio:
+        DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.minFiveHourFreeRatio,
+      minSevenDayFreeRatio:
+        DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.minSevenDayFreeRatio,
     });
   });
 
@@ -152,6 +160,30 @@ describe('loadLiveSessionOauthTokenSelectionSettings', () => {
     ).toThrow('fullSpeedFiveHourFreeRatio');
   });
 
+  it('throws when the minimum five hour free ratio is above one', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      ['liveSessionOauthTokenSelection:', '  minFiveHourFreeRatio: 1.5'].join(
+        '\n',
+      ),
+    );
+
+    expect(() =>
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toThrow('minFiveHourFreeRatio');
+  });
+
+  it('throws when the minimum seven day free ratio is above one', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      ['liveSessionOauthTokenSelection:', '  minSevenDayFreeRatio: 1.5'].join(
+        '\n',
+      ),
+    );
+
+    expect(() =>
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toThrow('minSevenDayFreeRatio');
+  });
+
   it('throws when a tuning number is written as a string', () => {
     const fleetConfigFilePath = writeFleetConfig(
       [

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

@@ -105,5 +105,21 @@ export const loadLiveSessionOauthTokenSelectionSettings = (
       (value) => value > 0 && value <= 1,
       'above 0 and at most 1',
     ),
+    minFiveHourFreeRatio: readBoundedNumber(
+      section,
+      'minFiveHourFreeRatio',
+      fleetConfigFilePath,
+      DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.minFiveHourFreeRatio,
+      (value) => value > 0 && value <= 1,
+      'above 0 and at most 1',
+    ),
+    minSevenDayFreeRatio: readBoundedNumber(
+      section,
+      'minSevenDayFreeRatio',
+      fleetConfigFilePath,
+      DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.minSevenDayFreeRatio,
+      (value) => value > 0 && value <= 1,
+      'above 0 and at most 1',
+    ),
   };
 };

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

@@ -394,6 +394,84 @@ describe('OauthTokenSelectHandler', () => {
     expect(Number(drawWeightMatch?.[1])).toBeGreaterThan(0);
   });
 
+  it('excludes a token whose 5h window has only 59% free (CL script threshold is 60%)', () => {
+    writeTokenList([{ name: 'low5h', token: 'fake-low5h' }]);
+    writeCache('fake-low5h', {
+      fiveHourUtilization: 0.41,
+      fiveHourReset: NOW + HOUR,
+      sevenDayUtilization: 0.1,
+      sevenDayReset: NOW + DAY,
+    });
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedToken).toBeNull();
+    expect(output.diagnostics.join('\n')).toContain('5h window');
+  });
+
+  it('treats exactly 60% 5h free as eligible in the handler (CL script boundary)', () => {
+    writeTokenList([{ name: 'boundary5h', token: 'fake-boundary5h' }]);
+    writeCache('fake-boundary5h', {
+      fiveHourUtilization: 0.4,
+      fiveHourReset: NOW + HOUR,
+      sevenDayUtilization: 0.1,
+      sevenDayReset: NOW + DAY,
+    });
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedName).toBe('boundary5h');
+  });
+
+  it('excludes a token whose 7d window has only 13% free (CL script threshold is 14%)', () => {
+    writeTokenList([{ name: 'low7d', token: 'fake-low7d' }]);
+    writeCache('fake-low7d', {
+      fiveHourUtilization: 0.1,
+      fiveHourReset: NOW + HOUR,
+      sevenDayUtilization: 0.87,
+      sevenDayReset: NOW + DAY,
+    });
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedToken).toBeNull();
+    expect(output.diagnostics.join('\n')).toContain('7d window');
+  });
+
+  it('treats exactly 14% 7d free as eligible in the handler (CL script boundary)', () => {
+    writeTokenList([{ name: 'boundary7d', token: 'fake-boundary7d' }]);
+    writeCache('fake-boundary7d', {
+      fiveHourUtilization: 0.1,
+      fiveHourReset: NOW + HOUR,
+      sevenDayUtilization: 0.86,
+      sevenDayReset: NOW + DAY,
+    });
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedName).toBe('boundary7d');
+  });
+
   describe('resolveTokenListJsonPath', () => {
     it('prefers the explicit path over the environment variable', () => {
       process.env.CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH = '/from/env.json';

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

@@ -1,4 +1,5 @@
 import {
+  CL_SCRIPT_OAUTH_TOKEN_SELECTION_THRESHOLDS,
   DEFAULT_SELECTION_WEIGHT,
   type OauthTokenCandidate,
   type OauthTokenSelectResult,
@@ -118,6 +119,7 @@ export class OauthTokenSelectHandler {
       candidates,
       input.nowEpochSeconds,
       this.random,
+      CL_SCRIPT_OAUTH_TOKEN_SELECTION_THRESHOLDS,
     );
 
     return {

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

@@ -145,11 +145,11 @@ describe('LiveSessionOauthTokenSelectUseCase', () => {
     expect(result.selected?.name).toBe('distantResetIdle');
   });
 
-  it('keeps the full concurrent session limit on a nearly used seven day window so the expiring allowance is drained', () => {
+  it('excludes a seven day window that has fallen below the minimum free ratio even when sessions are below the concurrent limit', () => {
     const result = useCase.run(
       [
         candidate(
-          'soonResetNearlyUsedSevenDay',
+          'nearlyUsedSevenDay',
           snapshot({
             sevenDayReset: NOW + 3 * DAY,
             sevenDayUtilization: 0.9,
@@ -160,29 +160,27 @@ describe('LiveSessionOauthTokenSelectUseCase', () => {
           snapshot({ sevenDayReset: NOW + 6 * DAY }),
         ),
       ],
-      sessionsFor('soonResetNearlyUsedSevenDay', 5),
+      sessionsFor('nearlyUsedSevenDay', 5),
       NOW,
       SETTINGS,
     );
 
     const nearlyUsed = result.metrics.find(
-      (m) => m.name === 'soonResetNearlyUsedSevenDay',
+      (m) => m.name === 'nearlyUsedSevenDay',
     );
-    expect(nearlyUsed?.concurrentSessionLimit).toBe(
-      MAX_CONCURRENT_SESSION_COUNT,
-    );
-    expect(result.selected?.name).toBe('soonResetNearlyUsedSevenDay');
+    expect(nearlyUsed?.eligible).toBe(false);
+    expect(nearlyUsed?.exclusionReason).toContain('7d window');
+    expect(result.selected?.name).toBe('distantResetIdle');
   });
 
-  it('keeps the full concurrent session limit on a seven day window that resets within the hour while its five hour window is still half free', () => {
+  it('excludes a token whose seven day window is below the minimum even when it resets within the hour', () => {
     const result = useCase.run(
       [
         candidate(
-          'aboutToResetHalfFreeFiveHour',
+          'aboutToResetNearlyUsedSevenDay',
           snapshot({
             sevenDayReset: NOW + HOUR,
             sevenDayUtilization: 0.9,
-            fiveHourUtilization: 0.5,
           }),
         ),
         candidate(
@@ -190,18 +188,16 @@ describe('LiveSessionOauthTokenSelectUseCase', () => {
           snapshot({ sevenDayReset: NOW + 6 * DAY }),
         ),
       ],
-      sessionsFor('aboutToResetHalfFreeFiveHour', 5),
+      sessionsFor('aboutToResetNearlyUsedSevenDay', 5),
       NOW,
       SETTINGS,
     );
 
     const aboutToReset = result.metrics.find(
-      (m) => m.name === 'aboutToResetHalfFreeFiveHour',
+      (m) => m.name === 'aboutToResetNearlyUsedSevenDay',
     );
-    expect(aboutToReset?.concurrentSessionLimit).toBe(
-      MAX_CONCURRENT_SESSION_COUNT,
-    );
-    expect(result.selected?.name).toBe('aboutToResetHalfFreeFiveHour');
+    expect(aboutToReset?.eligible).toBe(false);
+    expect(result.selected?.name).toBe('distantResetIdle');
   });
 
   it('still throttles a seven day window that resets within the hour once its five hour window falls below half free', () => {
@@ -509,6 +505,130 @@ describe('LiveSessionOauthTokenCandidateMetrics selectionWeight', () => {
   });
 });
 
+describe('LiveSessionOauthTokenSelectUseCase minimum free ratio thresholds', () => {
+  const useCase = new LiveSessionOauthTokenSelectUseCase();
+
+  it('excludes a token whose five hour window has less than the minimum free ratio', () => {
+    const result = useCase.run(
+      [
+        candidate('narrowFiveHourMin', snapshot({ fiveHourUtilization: 0.5 })),
+        candidate('freeFiveHourMin', snapshot({})),
+      ],
+      [],
+      NOW,
+      SETTINGS,
+    );
+
+    const narrow = result.metrics.find((m) => m.name === 'narrowFiveHourMin');
+    expect(narrow?.eligible).toBe(false);
+    expect(narrow?.exclusionReason).toContain('5h window');
+    expect(result.selected?.name).toBe('freeFiveHourMin');
+  });
+
+  it('excludes a token whose seven day window has less than the minimum free ratio', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'nearlyUsedSevenDayMin',
+          snapshot({ sevenDayUtilization: 0.9 }),
+        ),
+        candidate('freeSevenDayMin', snapshot({})),
+      ],
+      [],
+      NOW,
+      SETTINGS,
+    );
+
+    const nearlyUsed = result.metrics.find(
+      (m) => m.name === 'nearlyUsedSevenDayMin',
+    );
+    expect(nearlyUsed?.eligible).toBe(false);
+    expect(nearlyUsed?.exclusionReason).toContain('7d window');
+    expect(result.selected?.name).toBe('freeSevenDayMin');
+  });
+
+  it('selects a token whose ratios are at exactly the minimum free ratio thresholds', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'atThreshold',
+          snapshot({ fiveHourUtilization: 0.4, sevenDayUtilization: 0.86 }),
+        ),
+      ],
+      [],
+      NOW,
+      SETTINGS,
+    );
+
+    const atThreshold = result.metrics.find((m) => m.name === 'atThreshold');
+    expect(atThreshold?.eligible).toBe(true);
+    expect(result.selected?.name).toBe('atThreshold');
+  });
+
+  it('honours a fleet supplied minimum five hour free ratio', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'narrowForFleetFiveHour',
+          snapshot({ fiveHourUtilization: 0.15 }),
+        ),
+        candidate('freeForFleetFiveHour', snapshot({})),
+      ],
+      [],
+      NOW,
+      settingsWith({ minFiveHourFreeRatio: 0.9 }),
+    );
+
+    const narrow = result.metrics.find(
+      (m) => m.name === 'narrowForFleetFiveHour',
+    );
+    expect(narrow?.eligible).toBe(false);
+    expect(narrow?.exclusionReason).toContain('5h window');
+    expect(result.selected?.name).toBe('freeForFleetFiveHour');
+  });
+
+  it('honours a fleet supplied minimum seven day free ratio', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'narrowForFleetSevenDay',
+          snapshot({ sevenDayUtilization: 0.5 }),
+        ),
+        candidate('freeForFleetSevenDay', snapshot({})),
+      ],
+      [],
+      NOW,
+      settingsWith({ minSevenDayFreeRatio: 0.6 }),
+    );
+
+    const narrow = result.metrics.find(
+      (m) => m.name === 'narrowForFleetSevenDay',
+    );
+    expect(narrow?.eligible).toBe(false);
+    expect(narrow?.exclusionReason).toContain('7d window');
+    expect(result.selected?.name).toBe('freeForFleetSevenDay');
+  });
+
+  it('reports the five hour window exclusion reason when both windows are below their minimums', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'bothNarrow',
+          snapshot({ fiveHourUtilization: 0.5, sevenDayUtilization: 0.9 }),
+        ),
+      ],
+      [],
+      NOW,
+      SETTINGS,
+    );
+
+    const bothNarrow = result.metrics.find((m) => m.name === 'bothNarrow');
+    expect(bothNarrow?.eligible).toBe(false);
+    expect(bothNarrow?.exclusionReason).toContain('5h window');
+    expect(bothNarrow?.exclusionReason).not.toContain('7d window');
+  });
+});
+
 describe('liveSessionConcurrentLimitOf', () => {
   it('gives the full limit while the five hour window is at or above the full speed free ratio', () => {
     expect(liveSessionConcurrentLimitOf(1, 1, SETTINGS)).toBe(

package/src/domain/usecases/LiveSessionOauthTokenSelectUseCase.ts

@@ -8,12 +8,16 @@ import {
 export type LiveSessionOauthTokenSelectionSettings = {
   maxConcurrentSessionCount: number;
   fullSpeedFiveHourFreeRatio: number;
+  minFiveHourFreeRatio: number;
+  minSevenDayFreeRatio: number;
 };
 
 export const DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS: LiveSessionOauthTokenSelectionSettings =
   {
     maxConcurrentSessionCount: 10,
     fullSpeedFiveHourFreeRatio: 0.5,
+    minFiveHourFreeRatio: 0.6,
+    minSevenDayFreeRatio: 0.14,
   };
 
 export const liveSessionConcurrentLimitOf = (
@@ -80,6 +84,12 @@ export class LiveSessionOauthTokenSelectUseCase {
         selectionWeightOf(candidate),
         settings,
       );
+      const exclusionReason = this.liveSessionExclusionReason(
+        rateLimitMetric.exclusionReason,
+        rateLimitMetric.fiveHourFreeRatio,
+        rateLimitMetric.sevenDayFreeRatio,
+        settings,
+      );
       return {
         candidate,
         metric: {
@@ -90,8 +100,8 @@ export class LiveSessionOauthTokenSelectUseCase {
           liveSessionCount,
           concurrentSessionLimit,
           hasConcurrencyHeadroom: liveSessionCount < concurrentSessionLimit,
-          eligible: rateLimitMetric.eligible,
-          exclusionReason: rateLimitMetric.exclusionReason,
+          eligible: exclusionReason === null,
+          exclusionReason,
           selectionWeight: selectionWeightOf(candidate),
         },
       };
@@ -113,6 +123,24 @@ export class LiveSessionOauthTokenSelectUseCase {
     return { selected: selected.candidate, metrics };
   };
 
+  private liveSessionExclusionReason = (
+    rateLimitExclusionReason: string | null,
+    fiveHourFreeRatio: number,
+    sevenDayFreeRatio: number,
+    settings: LiveSessionOauthTokenSelectionSettings,
+  ): string | null => {
+    if (rateLimitExclusionReason !== null) {
+      return rateLimitExclusionReason;
+    }
+    if (fiveHourFreeRatio < settings.minFiveHourFreeRatio) {
+      return `5h window only ${Math.round(fiveHourFreeRatio * 100)}% free (requires >= ${Math.round(settings.minFiveHourFreeRatio * 100)}% for live session selection)`;
+    }
+    if (sevenDayFreeRatio < settings.minSevenDayFreeRatio) {
+      return `7d window only ${Math.round(sevenDayFreeRatio * 100)}% free (requires >= ${Math.round(settings.minSevenDayFreeRatio * 100)}% for live session selection)`;
+    }
+    return null;
+  };
+
   private preferred = (
     candidateMetric: LiveSessionOauthTokenCandidateMetrics,
     incumbentMetric: LiveSessionOauthTokenCandidateMetrics,